/ Hex Artifact Content
Login

Artifact 7ef021d74ac7d4004c784a16ad015508f171c4bf:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 64 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a  ed to operate..*
04e0: 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66  *.** The name of
04f0: 20 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72   this file under
0500: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d   configuration m
0510: 61 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71  anagement is "sq
0520: 6c 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54  lite.h.in"..** T
0530: 68 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65  he makefile make
0540: 73 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61  s some minor cha
0550: 6e 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c  nges to this fil
0560: 65 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72  e (such as inser
0570: 74 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73  ting.** the vers
0580: 69 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20  ion number) and 
0590: 63 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65  changes its name
05a0: 20 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20   to "sqlite3.h" 
05b0: 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68  as.** part of th
05c0: 65 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e  e build process.
05d0: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  .*/.#ifndef SQLI
05e0: 54 45 33 5f 48 0a 23 64 65 66 69 6e 65 20 53 51  TE3_H.#define SQ
05f0: 4c 49 54 45 33 5f 48 0a 23 69 6e 63 6c 75 64 65  LITE3_H.#include
0600: 20 3c 73 74 64 61 72 67 2e 68 3e 20 20 20 20 20   <stdarg.h>     
0610: 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72 20 74 68  /* Needed for th
0620: 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 66 20  e definition of 
0630: 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a  va_list */../*.*
0640: 2a 20 4d 61 6b 65 20 73 75 72 65 20 77 65 20 63  * Make sure we c
0650: 61 6e 20 63 61 6c 6c 20 74 68 69 73 20 73 74 75  an call this stu
0660: 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a  ff from C++..*/.
0670: 23 69 66 64 65 66 20 5f 5f 63 70 6c 75 73 70 6c  #ifdef __cpluspl
0680: 75 73 0a 65 78 74 65 72 6e 20 22 43 22 20 7b 0a  us.extern "C" {.
0690: 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 50  #endif.../*.** P
06a0: 72 6f 76 69 64 65 20 74 68 65 20 61 62 69 6c 69  rovide the abili
06b0: 74 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 6c  ty to override l
06c0: 69 6e 6b 61 67 65 20 66 65 61 74 75 72 65 73 20  inkage features 
06d0: 6f 66 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  of the interface
06e0: 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c  ..*/.#ifndef SQL
06f0: 49 54 45 5f 45 58 54 45 52 4e 0a 23 20 64 65 66  ITE_EXTERN.# def
0700: 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 54 45 52  ine SQLITE_EXTER
0710: 4e 20 65 78 74 65 72 6e 0a 23 65 6e 64 69 66 0a  N extern.#endif.
0720: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 41  #ifndef SQLITE_A
0730: 50 49 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  PI.# define SQLI
0740: 54 45 5f 41 50 49 0a 23 65 6e 64 69 66 0a 23 69  TE_API.#endif.#i
0750: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 43 44 45  fndef SQLITE_CDE
0760: 43 4c 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  CL.# define SQLI
0770: 54 45 5f 43 44 45 43 4c 0a 23 65 6e 64 69 66 0a  TE_CDECL.#endif.
0780: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 41  #ifndef SQLITE_A
0790: 50 49 43 41 4c 4c 0a 23 20 64 65 66 69 6e 65 20  PICALL.# define 
07a0: 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a 23  SQLITE_APICALL.#
07b0: 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51  endif.#ifndef SQ
07c0: 4c 49 54 45 5f 53 54 44 43 41 4c 4c 0a 23 20 64  LITE_STDCALL.# d
07d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 44  efine SQLITE_STD
07e0: 43 41 4c 4c 20 53 51 4c 49 54 45 5f 41 50 49 43  CALL SQLITE_APIC
07f0: 41 4c 4c 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64  ALL.#endif.#ifnd
0800: 65 66 20 53 51 4c 49 54 45 5f 43 41 4c 4c 42 41  ef SQLITE_CALLBA
0810: 43 4b 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  CK.# define SQLI
0820: 54 45 5f 43 41 4c 4c 42 41 43 4b 0a 23 65 6e 64  TE_CALLBACK.#end
0830: 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  if.#ifndef SQLIT
0840: 45 5f 53 59 53 41 50 49 0a 23 20 64 65 66 69 6e  E_SYSAPI.# defin
0850: 65 20 53 51 4c 49 54 45 5f 53 59 53 41 50 49 0a  e SQLITE_SYSAPI.
0860: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68  #endif../*.** Th
0870: 65 73 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73  ese no-op macros
0880: 20 61 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f   are used in fro
0890: 6e 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73  nt of interfaces
08a0: 20 74 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a   to mark those.*
08b0: 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 73 20  * interfaces as 
08c0: 65 69 74 68 65 72 20 64 65 70 72 65 63 61 74 65  either deprecate
08d0: 64 20 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61  d or experimenta
08e0: 6c 2e 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74  l.  New applicat
08f0: 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e  ions.** should n
0900: 6f 74 20 75 73 65 20 64 65 70 72 65 63 61 74 65  ot use deprecate
0910: 64 20 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74  d interfaces - t
0920: 68 65 79 20 61 72 65 20 73 75 70 70 6f 72 74 65  hey are supporte
0930: 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a  d for backwards.
0940: 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ** compatibility
0950: 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69 63 61 74   only.  Applicat
0960: 69 6f 6e 20 77 72 69 74 65 72 73 20 73 68 6f 75  ion writers shou
0970: 6c 64 20 62 65 20 61 77 61 72 65 20 74 68 61 74  ld be aware that
0980: 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e 74 61 6c  .** experimental
0990: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
09a0: 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
09b0: 65 20 69 6e 20 70 6f 69 6e 74 20 72 65 6c 65 61  e in point relea
09c0: 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ses..**.** These
09d0: 20 6d 61 63 72 6f 73 20 75 73 65 64 20 74 6f 20   macros used to 
09e0: 72 65 73 6f 6c 76 65 20 74 6f 20 76 61 72 69 6f  resolve to vario
09f0: 75 73 20 6b 69 6e 64 73 20 6f 66 20 63 6f 6d 70  us kinds of comp
0a00: 69 6c 65 72 20 6d 61 67 69 63 20 74 68 61 74 0a  iler magic that.
0a10: 2a 2a 20 77 6f 75 6c 64 20 67 65 6e 65 72 61 74  ** would generat
0a20: 65 20 77 61 72 6e 69 6e 67 20 6d 65 73 73 61 67  e warning messag
0a30: 65 73 20 77 68 65 6e 20 74 68 65 79 20 77 65 72  es when they wer
0a40: 65 20 75 73 65 64 2e 20 20 42 75 74 20 74 68 61  e used.  But tha
0a50: 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72 20 6d 61  t.** compiler ma
0a60: 67 69 63 20 65 6e 64 65 64 20 75 70 20 67 65 6e  gic ended up gen
0a70: 65 72 61 74 69 6e 67 20 73 75 63 68 20 61 20 66  erating such a f
0a80: 6c 75 72 72 79 20 6f 66 20 62 75 67 20 72 65 70  lurry of bug rep
0a90: 6f 72 74 73 0a 2a 2a 20 74 68 61 74 20 77 65 20  orts.** that we 
0aa0: 68 61 76 65 20 74 61 6b 65 6e 20 69 74 20 61 6c  have taken it al
0ab0: 6c 20 6f 75 74 20 61 6e 64 20 67 6f 6e 65 20 62  l out and gone b
0ac0: 61 63 6b 20 74 6f 20 75 73 69 6e 67 20 73 69 6d  ack to using sim
0ad0: 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72  ple.** noop macr
0ae0: 6f 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  os..*/.#define S
0af0: 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
0b00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
0b10: 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a  EXPERIMENTAL../*
0b20: 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68 65 73 65  .** Ensure these
0b30: 20 73 79 6d 62 6f 6c 73 20 77 65 72 65 20 6e 6f   symbols were no
0b40: 74 20 64 65 66 69 6e 65 64 20 62 79 20 73 6f 6d  t defined by som
0b50: 65 20 70 72 65 76 69 6f 75 73 20 68 65 61 64 65  e previous heade
0b60: 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65  r file..*/.#ifde
0b70: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0b80: 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f  .# undef SQLITE_
0b90: 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69 66 0a 23  VERSION.#endif.#
0ba0: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52  ifdef SQLITE_VER
0bb0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 20 75 6e  SION_NUMBER.# un
0bc0: 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49  def SQLITE_VERSI
0bd0: 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e 64 69 66  ON_NUMBER.#endif
0be0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
0bf0: 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 4c  : Compile-Time L
0c00: 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e  ibrary Version N
0c10: 75 6d 62 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54  umbers.**.** ^(T
0c20: 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  he [SQLITE_VERSI
0c30: 4f 4e 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  ON] C preprocess
0c40: 6f 72 20 6d 61 63 72 6f 20 69 6e 20 74 68 65 20  or macro in the 
0c50: 73 71 6c 69 74 65 33 2e 68 20 68 65 61 64 65 72  sqlite3.h header
0c60: 0a 2a 2a 20 65 76 61 6c 75 61 74 65 73 20 74 6f  .** evaluates to
0c70: 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
0c80: 6c 20 74 68 61 74 20 69 73 20 74 68 65 20 53 51  l that is the SQ
0c90: 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 69 6e 20  Lite version in 
0ca0: 74 68 65 0a 2a 2a 20 66 6f 72 6d 61 74 20 22 58  the.** format "X
0cb0: 2e 59 2e 5a 22 20 77 68 65 72 65 20 58 20 69 73  .Y.Z" where X is
0cc0: 20 74 68 65 20 6d 61 6a 6f 72 20 76 65 72 73 69   the major versi
0cd0: 6f 6e 20 6e 75 6d 62 65 72 20 28 61 6c 77 61 79  on number (alway
0ce0: 73 20 33 20 66 6f 72 0a 2a 2a 20 53 51 4c 69 74  s 3 for.** SQLit
0cf0: 65 33 29 20 61 6e 64 20 59 20 69 73 20 74 68 65  e3) and Y is the
0d00: 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f 6e 20 6e   minor version n
0d10: 75 6d 62 65 72 20 61 6e 64 20 5a 20 69 73 20 74  umber and Z is t
0d20: 68 65 20 72 65 6c 65 61 73 65 20 6e 75 6d 62 65  he release numbe
0d30: 72 2e 29 5e 0a 2a 2a 20 5e 28 54 68 65 20 5b 53  r.)^.** ^(The [S
0d40: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
0d50: 4d 42 45 52 5d 20 43 20 70 72 65 70 72 6f 63 65  MBER] C preproce
0d60: 73 73 6f 72 20 6d 61 63 72 6f 20 72 65 73 6f 6c  ssor macro resol
0d70: 76 65 73 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ves to an intege
0d80: 72 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 76 61  r.** with the va
0d90: 6c 75 65 20 28 58 2a 31 30 30 30 30 30 30 20 2b  lue (X*1000000 +
0da0: 20 59 2a 31 30 30 30 20 2b 20 5a 29 20 77 68 65   Y*1000 + Z) whe
0db0: 72 65 20 58 2c 20 59 2c 20 61 6e 64 20 5a 20 61  re X, Y, and Z a
0dc0: 72 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 6e  re the same.** n
0dd0: 75 6d 62 65 72 73 20 75 73 65 64 20 69 6e 20 5b  umbers used in [
0de0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2e  SQLITE_VERSION].
0df0: 29 5e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  )^.** The SQLITE
0e00: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20  _VERSION_NUMBER 
0e10: 66 6f 72 20 61 6e 79 20 67 69 76 65 6e 20 72 65  for any given re
0e20: 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20  lease of SQLite 
0e30: 77 69 6c 6c 20 61 6c 73 6f 0a 2a 2a 20 62 65 20  will also.** be 
0e40: 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20  larger than the 
0e50: 72 65 6c 65 61 73 65 20 66 72 6f 6d 20 77 68 69  release from whi
0e60: 63 68 20 69 74 20 69 73 20 64 65 72 69 76 65 64  ch it is derived
0e70: 2e 20 20 45 69 74 68 65 72 20 59 20 77 69 6c 6c  .  Either Y will
0e80: 0a 2a 2a 20 62 65 20 68 65 6c 64 20 63 6f 6e 73  .** be held cons
0e90: 74 61 6e 74 20 61 6e 64 20 5a 20 77 69 6c 6c 20  tant and Z will 
0ea0: 62 65 20 69 6e 63 72 65 6d 65 6e 74 65 64 20 6f  be incremented o
0eb0: 72 20 65 6c 73 65 20 59 20 77 69 6c 6c 20 62 65  r else Y will be
0ec0: 20 69 6e 63 72 65 6d 65 6e 74 65 64 0a 2a 2a 20   incremented.** 
0ed0: 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 72 65  and Z will be re
0ee0: 73 65 74 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a  set to zero..**.
0ef0: 2a 2a 20 53 69 6e 63 65 20 5b 76 65 72 73 69 6f  ** Since [versio
0f00: 6e 20 33 2e 36 2e 31 38 5d 20 28 5b 64 61 74 65  n 3.6.18] ([date
0f10: 6f 66 3a 33 2e 36 2e 31 38 5d 29 2c 20 0a 2a 2a  of:3.6.18]), .**
0f20: 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 63   SQLite source c
0f30: 6f 64 65 20 68 61 73 20 62 65 65 6e 20 73 74 6f  ode has been sto
0f40: 72 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 3c 61  red in the.** <a
0f50: 20 68 72 65 66 3d 22 68 74 74 70 3a 2f 2f 77 77   href="http://ww
0f60: 77 2e 66 6f 73 73 69 6c 2d 73 63 6d 2e 6f 72 67  w.fossil-scm.org
0f70: 2f 22 3e 46 6f 73 73 69 6c 20 63 6f 6e 66 69 67  /">Fossil config
0f80: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65  uration manageme
0f90: 6e 74 0a 2a 2a 20 73 79 73 74 65 6d 3c 2f 61 3e  nt.** system</a>
0fa0: 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 53  .  ^The SQLITE_S
0fb0: 4f 55 52 43 45 5f 49 44 20 6d 61 63 72 6f 20 65  OURCE_ID macro e
0fc0: 76 61 6c 75 61 74 65 73 20 74 6f 0a 2a 2a 20 61  valuates to.** a
0fd0: 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 64   string which id
0fe0: 65 6e 74 69 66 69 65 73 20 61 20 70 61 72 74 69  entifies a parti
0ff0: 63 75 6c 61 72 20 63 68 65 63 6b 2d 69 6e 20 6f  cular check-in o
1000: 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 74 68  f SQLite.** with
1010: 69 6e 20 69 74 73 20 63 6f 6e 66 69 67 75 72 61  in its configura
1020: 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20  tion management 
1030: 73 79 73 74 65 6d 2e 20 20 5e 54 68 65 20 53 51  system.  ^The SQ
1040: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 0a 2a  LITE_SOURCE_ID.*
1050: 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e  * string contain
1060: 73 20 74 68 65 20 64 61 74 65 20 61 6e 64 20 74  s the date and t
1070: 69 6d 65 20 6f 66 20 74 68 65 20 63 68 65 63 6b  ime of the check
1080: 2d 69 6e 20 28 55 54 43 29 20 61 6e 64 20 61 6e  -in (UTC) and an
1090: 20 53 48 41 31 0a 2a 2a 20 68 61 73 68 20 6f 66   SHA1.** hash of
10a0: 20 74 68 65 20 65 6e 74 69 72 65 20 73 6f 75 72   the entire sour
10b0: 63 65 20 74 72 65 65 2e 0a 2a 2a 0a 2a 2a 20 53  ce tree..**.** S
10c0: 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
10d0: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 5d 2c  3_libversion()],
10e0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62  .** [sqlite3_lib
10f0: 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29  version_number()
1100: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6f 75 72  ], [sqlite3_sour
1110: 63 65 69 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  ceid()],.** [sql
1120: 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d 20 61  ite_version()] a
1130: 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75 72 63  nd [sqlite_sourc
1140: 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66  e_id()]..*/.#def
1150: 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49  ine SQLITE_VERSI
1160: 4f 4e 20 20 20 20 20 20 20 20 22 2d 2d 56 45 52  ON        "--VER
1170: 53 2d 2d 22 0a 23 64 65 66 69 6e 65 20 53 51 4c  S--".#define SQL
1180: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
1190: 45 52 20 2d 2d 56 45 52 53 49 4f 4e 2d 4e 55 4d  ER --VERSION-NUM
11a0: 42 45 52 2d 2d 0a 23 64 65 66 69 6e 65 20 53 51  BER--.#define SQ
11b0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 20  LITE_SOURCE_ID  
11c0: 20 20 20 20 22 2d 2d 53 4f 55 52 43 45 2d 49 44      "--SOURCE-ID
11d0: 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  --"../*.** CAPI3
11e0: 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69  REF: Run-Time Li
11f0: 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75  brary Version Nu
1200: 6d 62 65 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  mbers.** KEYWORD
1210: 53 3a 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69  S: sqlite3_versi
1220: 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 73 6f 75 72  on, sqlite3_sour
1230: 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ceid.**.** These
1240: 20 69 6e 74 65 72 66 61 63 65 73 20 70 72 6f 76   interfaces prov
1250: 69 64 65 20 74 68 65 20 73 61 6d 65 20 69 6e 66  ide the same inf
1260: 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74 68 65 20  ormation as the 
1270: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d  [SQLITE_VERSION]
1280: 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52  ,.** [SQLITE_VER
1290: 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2c 20 61 6e  SION_NUMBER], an
12a0: 64 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43 45  d [SQLITE_SOURCE
12b0: 5f 49 44 5d 20 43 20 70 72 65 70 72 6f 63 65 73  _ID] C preproces
12c0: 73 6f 72 20 6d 61 63 72 6f 73 0a 2a 2a 20 62 75  sor macros.** bu
12d0: 74 20 61 72 65 20 61 73 73 6f 63 69 61 74 65 64  t are associated
12e0: 20 77 69 74 68 20 74 68 65 20 6c 69 62 72 61 72   with the librar
12f0: 79 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65  y instead of the
1300: 20 68 65 61 64 65 72 20 66 69 6c 65 2e 20 20 5e   header file.  ^
1310: 28 43 61 75 74 69 6f 75 73 0a 2a 2a 20 70 72 6f  (Cautious.** pro
1320: 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 69  grammers might i
1330: 6e 63 6c 75 64 65 20 61 73 73 65 72 74 28 29 20  nclude assert() 
1340: 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68  statements in th
1350: 65 69 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  eir application 
1360: 74 6f 0a 2a 2a 20 76 65 72 69 66 79 20 74 68 61  to.** verify tha
1370: 74 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65  t values returne
1380: 64 20 62 79 20 74 68 65 73 65 20 69 6e 74 65 72  d by these inter
1390: 66 61 63 65 73 20 6d 61 74 63 68 20 74 68 65 20  faces match the 
13a0: 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a 20 74 68 65  macros in.** the
13b0: 20 68 65 61 64 65 72 2c 20 61 6e 64 20 74 68 75   header, and thu
13c0: 73 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  s ensure that th
13d0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73  e application is
13e0: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  .** compiled wit
13f0: 68 20 6d 61 74 63 68 69 6e 67 20 6c 69 62 72 61  h matching libra
1400: 72 79 20 61 6e 64 20 68 65 61 64 65 72 20 66 69  ry and header fi
1410: 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  les..**.** <bloc
1420: 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1430: 61 73 73 65 72 74 28 20 73 71 6c 69 74 65 33 5f  assert( sqlite3_
1440: 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65  libversion_numbe
1450: 72 28 29 3d 3d 53 51 4c 49 54 45 5f 56 45 52 53  r()==SQLITE_VERS
1460: 49 4f 4e 5f 4e 55 4d 42 45 52 20 29 3b 0a 2a 2a  ION_NUMBER );.**
1470: 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70 28   assert( strcmp(
1480: 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64  sqlite3_sourceid
1490: 28 29 2c 53 51 4c 49 54 45 5f 53 4f 55 52 43 45  (),SQLITE_SOURCE
14a0: 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73  _ID)==0 );.** as
14b0: 73 65 72 74 28 20 73 74 72 63 6d 70 28 73 71 6c  sert( strcmp(sql
14c0: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
14d0: 29 2c 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  ),SQLITE_VERSION
14e0: 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65  )==0 );.** </pre
14f0: 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e  ></blockquote>)^
1500: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1510: 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74  te3_version[] st
1520: 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f  ring constant co
1530: 6e 74 61 69 6e 73 20 74 68 65 20 74 65 78 74 20  ntains the text 
1540: 6f 66 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  of [SQLITE_VERSI
1550: 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e  ON].** macro.  ^
1560: 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76  The sqlite3_libv
1570: 65 72 73 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f  ersion() functio
1580: 6e 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  n returns a poin
1590: 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 74 6f  ter to the.** to
15a0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72   the sqlite3_ver
15b0: 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f  sion[] string co
15c0: 6e 73 74 61 6e 74 2e 20 20 54 68 65 20 73 71 6c  nstant.  The sql
15d0: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
15e0: 29 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73  ).** function is
15f0: 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20 75 73   provided for us
1600: 65 20 69 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20  e in DLLs since 
1610: 44 4c 4c 20 75 73 65 72 73 20 75 73 75 61 6c 6c  DLL users usuall
1620: 79 20 64 6f 20 6e 6f 74 20 68 61 76 65 0a 2a 2a  y do not have.**
1630: 20 64 69 72 65 63 74 20 61 63 63 65 73 73 20 74   direct access t
1640: 6f 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  o string constan
1650: 74 73 20 77 69 74 68 69 6e 20 74 68 65 20 44 4c  ts within the DL
1660: 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69  L.  ^The.** sqli
1670: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
1680: 75 6d 62 65 72 28 29 20 66 75 6e 63 74 69 6f 6e  umber() function
1690: 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65   returns an inte
16a0: 67 65 72 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20  ger equal to.** 
16b0: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f  [SQLITE_VERSION_
16c0: 4e 55 4d 42 45 52 5d 2e 20 20 5e 54 68 65 20 73  NUMBER].  ^The s
16d0: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28  qlite3_sourceid(
16e0: 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ) function retur
16f0: 6e 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72  ns .** a pointer
1700: 20 74 6f 20 61 20 73 74 72 69 6e 67 20 63 6f 6e   to a string con
1710: 73 74 61 6e 74 20 77 68 6f 73 65 20 76 61 6c 75  stant whose valu
1720: 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73  e is the same as
1730: 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45   the .** [SQLITE
1740: 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72  _SOURCE_ID] C pr
1750: 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
1760: 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
1770: 3a 20 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f  : [sqlite_versio
1780: 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
1790: 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a  _source_id()]..*
17a0: 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20  /.SQLITE_EXTERN 
17b0: 63 6f 6e 73 74 20 63 68 61 72 20 73 71 6c 69 74  const char sqlit
17c0: 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b 0a 63 6f  e3_version[];.co
17d0: 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
17e0: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 76 6f 69  3_libversion(voi
17f0: 64 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  d);.const char *
1800: 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64  sqlite3_sourceid
1810: 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69  (void);.int sqli
1820: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
1830: 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a 0a 2f 2a  umber(void);../*
1840: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75  .** CAPI3REF: Ru
1850: 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 43  n-Time Library C
1860: 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70 74 69 6f  ompilation Optio
1870: 6e 73 20 44 69 61 67 6e 6f 73 74 69 63 73 0a 2a  ns Diagnostics.*
1880: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1890: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
18a0: 75 73 65 64 28 29 20 66 75 6e 63 74 69 6f 6e 20  used() function 
18b0: 72 65 74 75 72 6e 73 20 30 20 6f 72 20 31 20 0a  returns 0 or 1 .
18c0: 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 77 68  ** indicating wh
18d0: 65 74 68 65 72 20 74 68 65 20 73 70 65 63 69 66  ether the specif
18e0: 69 65 64 20 6f 70 74 69 6f 6e 20 77 61 73 20 64  ied option was d
18f0: 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a 20 63 6f  efined at .** co
1900: 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20 5e 54 68  mpile time.  ^Th
1910: 65 20 53 51 4c 49 54 45 5f 20 70 72 65 66 69 78  e SQLITE_ prefix
1920: 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 65 64 20   may be omitted 
1930: 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20 6f 70 74  from the .** opt
1940: 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73 65 64 20  ion name passed 
1950: 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  to sqlite3_compi
1960: 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 2e  leoption_used().
1970: 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71    .**.** ^The sq
1980: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1990: 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e 63 74 69  ion_get() functi
19a0: 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65 72 61 74  on allows iterat
19b0: 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20  ing.** over the 
19c0: 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f 6e 73 20  list of options 
19d0: 74 68 61 74 20 77 65 72 65 20 64 65 66 69 6e 65  that were define
19e0: 64 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d  d at compile tim
19f0: 65 20 62 79 0a 2a 2a 20 72 65 74 75 72 6e 69 6e  e by.** returnin
1a00: 67 20 74 68 65 20 4e 2d 74 68 20 63 6f 6d 70 69  g the N-th compi
1a10: 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f 6e 20 73  le time option s
1a20: 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e 20 69 73  tring.  ^If N is
1a30: 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 0a 2a   out of range,.*
1a40: 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  * sqlite3_compil
1a50: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 72 65  eoption_get() re
1a60: 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
1a70: 6e 74 65 72 2e 20 20 5e 54 68 65 20 53 51 4c 49  nter.  ^The SQLI
1a80: 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69 78 20 69  TE_ .** prefix i
1a90: 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 61  s omitted from a
1aa0: 6e 79 20 73 74 72 69 6e 67 73 20 72 65 74 75 72  ny strings retur
1ab0: 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74  ned by .** sqlit
1ac0: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
1ad0: 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 53  _get()..**.** ^S
1ae0: 75 70 70 6f 72 74 20 66 6f 72 20 74 68 65 20 64  upport for the d
1af0: 69 61 67 6e 6f 73 74 69 63 20 66 75 6e 63 74 69  iagnostic functi
1b00: 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  ons sqlite3_comp
1b10: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
1b20: 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  .** and sqlite3_
1b30: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65  compileoption_ge
1b40: 74 28 29 20 6d 61 79 20 62 65 20 6f 6d 69 74 74  t() may be omitt
1b50: 65 64 20 62 79 20 73 70 65 63 69 66 79 69 6e 67  ed by specifying
1b60: 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45   the .** [SQLITE
1b70: 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54  _OMIT_COMPILEOPT
1b80: 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70 74 69 6f  ION_DIAGS] optio
1b90: 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d  n at compile tim
1ba0: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
1bb0: 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  o: SQL functions
1bc0: 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65   [sqlite_compile
1bd0: 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 5d 20 61  option_used()] a
1be0: 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 63 6f  nd.** [sqlite_co
1bf0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
1c00: 29 5d 20 61 6e 64 20 74 68 65 20 5b 63 6f 6d 70  )] and the [comp
1c10: 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70 72 61 67  ile_options prag
1c20: 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20  ma]..*/.#ifndef 
1c30: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50  SQLITE_OMIT_COMP
1c40: 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 0a  ILEOPTION_DIAGS.
1c50: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  int sqlite3_comp
1c60: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 63  ileoption_used(c
1c70: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f 70 74 4e  onst char *zOptN
1c80: 61 6d 65 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  ame);.const char
1c90: 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c   *sqlite3_compil
1ca0: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 69 6e 74 20  eoption_get(int 
1cb0: 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  N);.#endif../*.*
1cc0: 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 73 74  * CAPI3REF: Test
1cd0: 20 54 6f 20 53 65 65 20 49 66 20 54 68 65 20 4c   To See If The L
1ce0: 69 62 72 61 72 79 20 49 73 20 54 68 72 65 61 64  ibrary Is Thread
1cf0: 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  safe.**.** ^The 
1d00: 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61  sqlite3_threadsa
1d10: 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  fe() function re
1d20: 74 75 72 6e 73 20 7a 65 72 6f 20 69 66 20 61 6e  turns zero if an
1d30: 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 53 51 4c  d only if.** SQL
1d40: 69 74 65 20 77 61 73 20 63 6f 6d 70 69 6c 65 64  ite was compiled
1d50: 20 77 69 74 68 20 6d 75 74 65 78 69 6e 67 20 63   with mutexing c
1d60: 6f 64 65 20 6f 6d 69 74 74 65 64 20 64 75 65 20  ode omitted due 
1d70: 74 6f 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  to the.** [SQLIT
1d80: 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 63 6f  E_THREADSAFE] co
1d90: 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
1da0: 6e 20 62 65 69 6e 67 20 73 65 74 20 74 6f 20 30  n being set to 0
1db0: 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63  ..**.** SQLite c
1dc0: 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77  an be compiled w
1dd0: 69 74 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d  ith or without m
1de0: 75 74 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a  utexes.  When.**
1df0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
1e00: 45 41 44 53 41 46 45 5d 20 43 20 70 72 65 70 72  EADSAFE] C prepr
1e10: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 73  ocessor macro is
1e20: 20 31 20 6f 72 20 32 2c 20 6d 75 74 65 78 65 73   1 or 2, mutexes
1e30: 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20  .** are enabled 
1e40: 61 6e 64 20 53 51 4c 69 74 65 20 69 73 20 74 68  and SQLite is th
1e50: 72 65 61 64 73 61 66 65 2e 20 20 57 68 65 6e 20  readsafe.  When 
1e60: 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54  the.** [SQLITE_T
1e70: 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f  HREADSAFE] macro
1e80: 20 69 73 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d   is 0, .** the m
1e90: 75 74 65 78 65 73 20 61 72 65 20 6f 6d 69 74 74  utexes are omitt
1ea0: 65 64 2e 20 20 57 69 74 68 6f 75 74 20 74 68 65  ed.  Without the
1eb0: 20 6d 75 74 65 78 65 73 2c 20 69 74 20 69 73 20   mutexes, it is 
1ec0: 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75  not safe.** to u
1ed0: 73 65 20 53 51 4c 69 74 65 20 63 6f 6e 63 75 72  se SQLite concur
1ee0: 72 65 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65  rently from more
1ef0: 20 74 68 61 6e 20 6f 6e 65 20 74 68 72 65 61 64   than one thread
1f00: 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67  ..**.** Enabling
1f10: 20 6d 75 74 65 78 65 73 20 69 6e 63 75 72 73 20   mutexes incurs 
1f20: 61 20 6d 65 61 73 75 72 61 62 6c 65 20 70 65 72  a measurable per
1f30: 66 6f 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79  formance penalty
1f40: 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70 65 65 64  ..** So if speed
1f50: 20 69 73 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d   is of utmost im
1f60: 70 6f 72 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b  portance, it mak
1f70: 65 73 20 73 65 6e 73 65 20 74 6f 20 64 69 73 61  es sense to disa
1f80: 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78  ble.** the mutex
1f90: 65 73 2e 20 20 42 75 74 20 66 6f 72 20 6d 61 78  es.  But for max
1fa0: 69 6d 75 6d 20 73 61 66 65 74 79 2c 20 6d 75 74  imum safety, mut
1fb0: 65 78 65 73 20 73 68 6f 75 6c 64 20 62 65 20 65  exes should be e
1fc0: 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  nabled..** ^The 
1fd0: 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72  default behavior
1fe0: 20 69 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20   is for mutexes 
1ff0: 74 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a  to be enabled..*
2000: 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66  *.** This interf
2010: 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ace can be used 
2020: 62 79 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  by an applicatio
2030: 6e 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74  n to make sure t
2040: 68 61 74 20 74 68 65 0a 2a 2a 20 76 65 72 73 69  hat the.** versi
2050: 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20 74 68 61  on of SQLite tha
2060: 74 20 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20  t it is linking 
2070: 61 67 61 69 6e 73 74 20 77 61 73 20 63 6f 6d 70  against was comp
2080: 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
2090: 20 64 65 73 69 72 65 64 20 73 65 74 74 69 6e 67   desired setting
20a0: 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   of the [SQLITE_
20b0: 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72  THREADSAFE] macr
20c0: 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  o..**.** This in
20d0: 74 65 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 70  terface only rep
20e0: 6f 72 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70  orts on the comp
20f0: 69 6c 65 2d 74 69 6d 65 20 6d 75 74 65 78 20 73  ile-time mutex s
2100: 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65  etting.** of the
2110: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
2120: 41 46 45 5d 20 66 6c 61 67 2e 20 20 49 66 20 53  AFE] flag.  If S
2130: 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
2140: 64 20 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45  d with.** SQLITE
2150: 5f 54 48 52 45 41 44 53 41 46 45 3d 31 20 6f 72  _THREADSAFE=1 or
2160: 20 3d 32 20 74 68 65 6e 20 6d 75 74 65 78 65 73   =2 then mutexes
2170: 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20   are enabled by 
2180: 64 65 66 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63  default but.** c
2190: 61 6e 20 62 65 20 66 75 6c 6c 79 20 6f 72 20 70  an be fully or p
21a0: 61 72 74 69 61 6c 6c 79 20 64 69 73 61 62 6c 65  artially disable
21b0: 64 20 75 73 69 6e 67 20 61 20 63 61 6c 6c 20 74  d using a call t
21c0: 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
21d0: 67 28 29 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65  g()].** with the
21e0: 20 76 65 72 62 73 20 5b 53 51 4c 49 54 45 5f 43   verbs [SQLITE_C
21f0: 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
2200: 41 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  AD], [SQLITE_CON
2210: 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d  FIG_MULTITHREAD]
2220: 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ,.** or [SQLITE_
2230: 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
2240: 44 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72  D].  ^(The retur
2250: 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a  n value of the.*
2260: 2a 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64  * sqlite3_thread
2270: 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  safe() function 
2280: 73 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63  shows only the c
2290: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74  ompile-time sett
22a0: 69 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64  ing of.** thread
22b0: 20 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79   safety, not any
22c0: 20 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65   run-time change
22d0: 73 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e  s to that settin
22e0: 67 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c  g made by.** sql
22f0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49  ite3_config(). I
2300: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
2310: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
2320: 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72  from sqlite3_thr
2330: 65 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20  eadsafe().** is 
2340: 75 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c  unchanged by cal
2350: 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
2360: 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20  nfig().)^.**.** 
2370: 53 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69  See the [threadi
2380: 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e  ng mode] documen
2390: 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74  tation for addit
23a0: 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
23b0: 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  n..*/.int sqlite
23c0: 33 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69  3_threadsafe(voi
23d0: 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  d);../*.** CAPI3
23e0: 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f  REF: Database Co
23f0: 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a  nnection Handle.
2400: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61  ** KEYWORDS: {da
2410: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2420: 6e 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e  n} {database con
2430: 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20  nections}.**.** 
2440: 45 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65  Each open SQLite
2450: 20 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70   database is rep
2460: 72 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f  resented by a po
2470: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
2480: 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f  ance of.** the o
2490: 70 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20  paque structure 
24a0: 6e 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e  named "sqlite3".
24b0: 20 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74    It is useful t
24c0: 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71  o think of an sq
24d0: 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72  lite3.** pointer
24e0: 20 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20   as an object.  
24f0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  The [sqlite3_ope
2500: 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
2510: 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a  pen16()], and.**
2520: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
2530: 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20  2()] interfaces 
2540: 61 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63  are its construc
2550: 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74  tors, and [sqlit
2560: 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61  e3_close()].** a
2570: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  nd [sqlite3_clos
2580: 65 5f 76 32 28 29 5d 20 61 72 65 20 69 74 73 20  e_v2()] are its 
2590: 64 65 73 74 72 75 63 74 6f 72 73 2e 20 20 54 68  destructors.  Th
25a0: 65 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68  ere are many oth
25b0: 65 72 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  er.** interfaces
25c0: 20 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71   (such as.** [sq
25d0: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
25e0: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72  ()], [sqlite3_cr
25f0: 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
2600: 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
2610: 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29  3_busy_timeout()
2620: 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68  ] to name but th
2630: 72 65 65 29 20 74 68 61 74 20 61 72 65 20 6d 65  ree) that are me
2640: 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73  thods on an.** s
2650: 71 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a  qlite3 object..*
2660: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
2670: 20 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33   sqlite3 sqlite3
2680: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2690: 46 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65  F: 64-Bit Intege
26a0: 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f  r Types.** KEYWO
26b0: 52 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36  RDS: sqlite_int6
26c0: 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a  4 sqlite_uint64.
26d0: 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68  **.** Because th
26e0: 65 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d  ere is no cross-
26f0: 70 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20  platform way to 
2700: 73 70 65 63 69 66 79 20 36 34 2d 62 69 74 20 69  specify 64-bit i
2710: 6e 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20  nteger types.** 
2720: 53 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20  SQLite includes 
2730: 74 79 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d  typedefs for 64-
2740: 62 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75  bit signed and u
2750: 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73  nsigned integers
2760: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
2770: 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71  te3_int64 and sq
2780: 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65  lite3_uint64 are
2790: 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74   the preferred t
27a0: 79 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e  ype definitions.
27b0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69  .** The sqlite_i
27c0: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f  nt64 and sqlite_
27d0: 75 69 6e 74 36 34 20 74 79 70 65 73 20 61 72 65  uint64 types are
27e0: 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62   supported for b
27f0: 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70  ackwards.** comp
2800: 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a  atibility only..
2810: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2820: 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  e3_int64 and sql
2830: 69 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20  ite_int64 types 
2840: 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65  can store intege
2850: 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77  r values.** betw
2860: 65 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38  een -92233720368
2870: 35 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32  54775808 and +92
2880: 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30  2337203685477580
2890: 37 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54  7 inclusive.  ^T
28a0: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69  he.** sqlite3_ui
28b0: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f  nt64 and sqlite_
28c0: 75 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e  uint64 types can
28d0: 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76   store integer v
28e0: 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65  alues .** betwee
28f0: 6e 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34  n 0 and +1844674
2900: 34 30 37 33 37 30 39 35 35 31 36 31 35 20 69 6e  4073709551615 in
2910: 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64  clusive..*/.#ifd
2920: 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f  ef SQLITE_INT64_
2930: 54 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 53  TYPE.  typedef S
2940: 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45  QLITE_INT64_TYPE
2950: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20   sqlite_int64;. 
2960: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65   typedef unsigne
2970: 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  d SQLITE_INT64_T
2980: 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  YPE sqlite_uint6
2990: 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64  4;.#elif defined
29a0: 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65  (_MSC_VER) || de
29b0: 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43  fined(__BORLANDC
29c0: 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f  __).  typedef __
29d0: 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74  int64 sqlite_int
29e0: 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e  64;.  typedef un
29f0: 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73  signed __int64 s
2a00: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65  qlite_uint64;.#e
2a10: 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f  lse.  typedef lo
2a20: 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69  ng long int sqli
2a30: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
2a40: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e  def unsigned lon
2a50: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
2a60: 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66  e_uint64;.#endif
2a70: 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f  .typedef sqlite_
2a80: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e  int64 sqlite3_in
2a90: 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c  t64;.typedef sql
2aa0: 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74  ite_uint64 sqlit
2ab0: 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a  e3_uint64;../*.*
2ac0: 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66  * If compiling f
2ad0: 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74  or a processor t
2ae0: 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69  hat lacks floati
2af0: 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74  ng point support
2b00: 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20  ,.** substitute 
2b10: 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61  integer for floa
2b20: 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23  ting-point..*/.#
2b30: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49  ifdef SQLITE_OMI
2b40: 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54  T_FLOATING_POINT
2b50: 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65  .# define double
2b60: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23   sqlite3_int64.#
2b70: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
2b80: 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41  I3REF: Closing A
2b90: 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
2ba0: 74 69 6f 6e 0a 2a 2a 20 44 45 53 54 52 55 43 54  tion.** DESTRUCT
2bb0: 4f 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OR: sqlite3.**.*
2bc0: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
2bd0: 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74  lose() and sqlit
2be0: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 6f  e3_close_v2() ro
2bf0: 75 74 69 6e 65 73 20 61 72 65 20 64 65 73 74 72  utines are destr
2c00: 75 63 74 6f 72 73 0a 2a 2a 20 66 6f 72 20 74 68  uctors.** for th
2c10: 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
2c20: 63 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f  ct..** ^Calls to
2c30: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
2c40: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f   and sqlite3_clo
2c50: 73 65 5f 76 32 28 29 20 72 65 74 75 72 6e 20 5b  se_v2() return [
2c60: 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 0a 2a 2a  SQLITE_OK] if.**
2c70: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
2c80: 62 6a 65 63 74 20 69 73 20 73 75 63 63 65 73 73  bject is success
2c90: 66 75 6c 6c 79 20 64 65 73 74 72 6f 79 65 64 20  fully destroyed 
2ca0: 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63 69 61 74  and all associat
2cb0: 65 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20  ed.** resources 
2cc0: 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e  are deallocated.
2cd0: 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64  .**.** ^If the d
2ce0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2cf0: 6f 6e 20 69 73 20 61 73 73 6f 63 69 61 74 65 64  on is associated
2d00: 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65   with unfinalize
2d10: 64 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  d prepared.** st
2d20: 61 74 65 6d 65 6e 74 73 20 6f 72 20 75 6e 66 69  atements or unfi
2d30: 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62  nished sqlite3_b
2d40: 61 63 6b 75 70 20 6f 62 6a 65 63 74 73 20 74 68  ackup objects th
2d50: 65 6e 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  en sqlite3_close
2d60: 28 29 0a 2a 2a 20 77 69 6c 6c 20 6c 65 61 76 65  ().** will leave
2d70: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2d80: 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 20 61 6e  nnection open an
2d90: 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  d return [SQLITE
2da0: 5f 42 55 53 59 5d 2e 0a 2a 2a 20 5e 49 66 20 73  _BUSY]..** ^If s
2db0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
2dc0: 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68  ) is called with
2dd0: 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65   unfinalized pre
2de0: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
2df0: 0a 2a 2a 20 61 6e 64 2f 6f 72 20 75 6e 66 69 6e  .** and/or unfin
2e00: 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61  ished sqlite3_ba
2e10: 63 6b 75 70 73 2c 20 74 68 65 6e 20 74 68 65 20  ckups, then the 
2e20: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2e30: 69 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 61  ion becomes.** a
2e40: 6e 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d 62  n unusable "zomb
2e50: 69 65 22 20 77 68 69 63 68 20 77 69 6c 6c 20 61  ie" which will a
2e60: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65 20  utomatically be 
2e70: 64 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e  deallocated when
2e80: 20 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72 65   the.** last pre
2e90: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2ea0: 69 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72 20  is finalized or 
2eb0: 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33  the last sqlite3
2ec0: 5f 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66 69  _backup is.** fi
2ed0: 6e 69 73 68 65 64 2e 20 20 54 68 65 20 73 71 6c  nished.  The sql
2ee0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
2ef0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e 74  interface is int
2f00: 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 77 69  ended for use wi
2f10: 74 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 75  th.** host langu
2f20: 61 67 65 73 20 74 68 61 74 20 61 72 65 20 67 61  ages that are ga
2f30: 72 62 61 67 65 20 63 6f 6c 6c 65 63 74 65 64 2c  rbage collected,
2f40: 20 61 6e 64 20 77 68 65 72 65 20 74 68 65 20 6f   and where the o
2f50: 72 64 65 72 20 69 6e 20 77 68 69 63 68 0a 2a 2a  rder in which.**
2f60: 20 64 65 73 74 72 75 63 74 6f 72 73 20 61 72 65   destructors are
2f70: 20 63 61 6c 6c 65 64 20 69 73 20 61 72 62 69 74   called is arbit
2f80: 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c  rary..**.** Appl
2f90: 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
2fa0: 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2fb0: 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c  e | finalize] al
2fc0: 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  l [prepared stat
2fd0: 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71 6c  ements],.** [sql
2fe0: 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20  ite3_blob_close 
2ff0: 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c  | close] all [BL
3000: 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64  OB handles], and
3010: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61   .** [sqlite3_ba
3020: 63 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20 66 69  ckup_finish | fi
3030: 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 74  nish] all [sqlit
3040: 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63  e3_backup] objec
3050: 74 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a  ts associated.**
3060: 20 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74   with the [sqlit
3070: 65 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f 72  e3] object prior
3080: 20 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 20 74   to attempting t
3090: 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65  o close the obje
30a0: 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c 69  ct.  ^If.** sqli
30b0: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69  te3_close_v2() i
30c0: 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64  s called on a [d
30d0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
30e0: 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68  on] that still h
30f0: 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e  as.** outstandin
3100: 67 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  g [prepared stat
3110: 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68  ements], [BLOB h
3120: 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a  andles], and/or.
3130: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b  ** [sqlite3_back
3140: 75 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e  up] objects then
3150: 20 69 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c   it returns [SQL
3160: 49 54 45 5f 4f 4b 5d 20 61 6e 64 20 74 68 65 20  ITE_OK] and the 
3170: 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  deallocation.** 
3180: 6f 66 20 72 65 73 6f 75 72 63 65 73 20 69 73 20  of resources is 
3190: 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61  deferred until a
31a0: 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ll [prepared sta
31b0: 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20  tements], [BLOB 
31c0: 68 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64  handles],.** and
31d0: 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70   [sqlite3_backup
31e0: 5d 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c  ] objects are al
31f0: 73 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a  so destroyed..**
3200: 0a 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69  .** ^If an [sqli
3210: 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64  te3] object is d
3220: 65 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61  estroyed while a
3230: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
3240: 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61  open,.** the tra
3250: 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f  nsaction is auto
3260: 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64  matically rolled
3270: 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   back..**.** The
3280: 20 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   C parameter to 
3290: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43  [sqlite3_close(C
32a0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
32b0: 63 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20  close_v2(C)].** 
32c0: 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61  must be either a
32d0: 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72   NULL.** pointer
32e0: 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d   or an [sqlite3]
32f0: 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20   object pointer 
3300: 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d  obtained.** from
3310: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
3320: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
3330: 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71  16()], or.** [sq
3340: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
3350: 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f  , and not previo
3360: 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20  usly closed..** 
3370: 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33  ^Calling sqlite3
3380: 5f 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69  _close() or sqli
3390: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77  te3_close_v2() w
33a0: 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ith a NULL point
33b0: 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69  er.** argument i
33c0: 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  s a harmless no-
33d0: 6f 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  op..*/.int sqlit
33e0: 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33  e3_close(sqlite3
33f0: 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
3400: 63 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65 33  close_v2(sqlite3
3410: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74  *);../*.** The t
3420: 79 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61  ype for a callba
3430: 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20  ck function..** 
3440: 54 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61  This is legacy a
3450: 6e 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20  nd deprecated.  
3460: 49 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66  It is included f
3470: 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a  or historical.**
3480: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61   compatibility a
3490: 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65  nd is not docume
34a0: 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  nted..*/.typedef
34b0: 20 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63   int (*sqlite3_c
34c0: 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69  allback)(void*,i
34d0: 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a  nt,char**, char*
34e0: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
34f0: 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75  REF: One-Step Qu
3500: 65 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e  ery Execution In
3510: 74 65 72 66 61 63 65 0a 2a 2a 20 4d 45 54 48 4f  terface.** METHO
3520: 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
3530: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   The sqlite3_exe
3540: 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  c() interface is
3550: 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77   a convenience w
3560: 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a  rapper around.**
3570: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
3580: 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v2()], [sqlite
3590: 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b  3_step()], and [
35a0: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
35b0: 28 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c  ()],.** that all
35c0: 6f 77 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69  ows an applicati
35d0: 6f 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70  on to run multip
35e0: 6c 65 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66  le statements of
35f0: 20 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20   SQL.** without 
3600: 68 61 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20  having to use a 
3610: 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a  lot of C code. .
3620: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
3630: 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66  e3_exec() interf
3640: 61 63 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72  ace runs zero or
3650: 20 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f   more UTF-8 enco
3660: 64 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f  ded,.** semicolo
3670: 6e 2d 73 65 70 61 72 61 74 65 20 53 51 4c 20 73  n-separate SQL s
3680: 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64  tatements passed
3690: 20 69 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72   into its 2nd ar
36a0: 67 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68  gument,.** in th
36b0: 65 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65  e context of the
36c0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
36d0: 63 74 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e  ction] passed in
36e0: 20 61 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61   as its 1st.** a
36f0: 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68  rgument.  ^If th
3700: 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
3710: 69 6f 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61  ion of the 3rd a
3720: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71  rgument to.** sq
3730: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
3740: 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69  not NULL, then i
3750: 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72  t is invoked for
3760: 20 65 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77   each result row
3770: 0a 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f  .** coming out o
3780: 66 20 74 68 65 20 65 76 61 6c 75 61 74 65 64 20  f the evaluated 
3790: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20  SQL statements. 
37a0: 20 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65   ^The 4th argume
37b0: 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  nt to.** sqlite3
37c0: 5f 65 78 65 63 28 29 20 69 73 20 72 65 6c 61 79  _exec() is relay
37d0: 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68  ed through to th
37e0: 65 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f  e 1st argument o
37f0: 66 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61  f each.** callba
3800: 63 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20  ck invocation.  
3810: 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ^If the callback
3820: 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69   pointer to sqli
3830: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73  te3_exec().** is
3840: 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63   NULL, then no c
3850: 61 6c 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20  allback is ever 
3860: 69 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75  invoked and resu
3870: 6c 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69  lt rows are.** i
3880: 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  gnored..**.** ^I
3890: 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  f an error occur
38a0: 73 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69  s while evaluati
38b0: 6e 67 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  ng the SQL state
38c0: 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74  ments passed int
38d0: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
38e0: 63 28 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74  c(), then execut
38f0: 69 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65  ion of the curre
3900: 6e 74 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f  nt statement sto
3910: 70 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71  ps and.** subseq
3920: 75 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20  uent statements 
3930: 61 72 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49  are skipped.  ^I
3940: 66 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  f the 5th parame
3950: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3960: 78 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20  xec().** is not 
3970: 4e 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72  NULL then any er
3980: 72 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20 77  ror message is w
3990: 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f  ritten into memo
39a0: 72 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  ry obtained.** f
39b0: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
39c0: 6c 6f 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65  loc()] and passe
39d0: 64 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74  d back through t
39e0: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
39f0: 2e 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65  ..** To avoid me
3a00: 6d 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20  mory leaks, the 
3a10: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
3a20: 6c 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74  ld invoke [sqlit
3a30: 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e  e3_free()].** on
3a40: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
3a50: 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
3a60: 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20  through the 5th 
3a70: 70 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20  parameter of.** 
3a80: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61  sqlite3_exec() a
3a90: 66 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d  fter the error m
3aa0: 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73  essage string is
3ab0: 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65   no longer neede
3ac0: 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74  d..** ^If the 5t
3ad0: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
3ae0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3af0: 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f   not NULL and no
3b00: 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72   errors.** occur
3b10: 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65  , then sqlite3_e
3b20: 78 65 63 28 29 20 73 65 74 73 20 74 68 65 20 70  xec() sets the p
3b30: 6f 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74  ointer in its 5t
3b40: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  h parameter to.*
3b50: 2a 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65  * NULL before re
3b60: 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e  turning..**.** ^
3b70: 49 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78  If an sqlite3_ex
3b80: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65  ec() callback re
3b90: 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
3ba0: 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  the sqlite3_exec
3bb0: 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65  ().** routine re
3bc0: 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f  turns SQLITE_ABO
3bd0: 52 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b  RT without invok
3be0: 69 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ing the callback
3bf0: 20 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69   again and.** wi
3c00: 74 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e  thout running an
3c10: 79 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c  y subsequent SQL
3c20: 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
3c30: 2a 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75  ** ^The 2nd argu
3c40: 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69  ment to the sqli
3c50: 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62  te3_exec() callb
3c60: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ack function is 
3c70: 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
3c80: 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
3c90: 72 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72  result.  ^The 3r
3ca0: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  d argument to th
3cb0: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3cc0: 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  .** callback is 
3cd0: 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
3ce0: 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20  ters to strings 
3cf0: 6f 62 74 61 69 6e 65 64 20 61 73 20 69 66 20 66  obtained as if f
3d00: 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  rom.** [sqlite3_
3d10: 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20  column_text()], 
3d20: 6f 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c  one for each col
3d30: 75 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65  umn.  ^If an ele
3d40: 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73  ment of a.** res
3d50: 75 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20  ult row is NULL 
3d60: 74 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70  then the corresp
3d70: 6f 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f  onding string po
3d80: 69 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a  inter for the.**
3d90: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3da0: 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55  callback is a NU
3db0: 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68  LL pointer.  ^Th
3dc0: 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74  e 4th argument t
3dd0: 6f 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33  o the.** sqlite3
3de0: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
3df0: 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20   is an array of 
3e00: 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69  pointers to stri
3e10: 6e 67 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a  ngs where each.*
3e20: 2a 20 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e  * entry represen
3e30: 74 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63  ts the name of c
3e40: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73  orresponding res
3e50: 75 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62  ult column as ob
3e60: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
3e70: 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
3e80: 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ame()]..**.** ^I
3e90: 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  f the 2nd parame
3ea0: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3eb0: 78 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20  xec() is a NULL 
3ec0: 70 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74  pointer, a point
3ed0: 65 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74  er.** to an empt
3ee0: 79 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70  y string, or a p
3ef0: 6f 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74  ointer that cont
3f00: 61 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73  ains only whites
3f10: 70 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20  pace and/or .** 
3f20: 53 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68  SQL comments, th
3f30: 65 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d  en no SQL statem
3f40: 65 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74  ents are evaluat
3f50: 65 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62  ed and the datab
3f60: 61 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68  ase.** is not ch
3f70: 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73  anged..**.** Res
3f80: 74 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a  trictions:.**.**
3f90: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68   <ul>.** <li> Th
3fa0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
3fb0: 73 74 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  st ensure that t
3fc0: 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72  he 1st parameter
3fd0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
3fe0: 28 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20  ().**      is a 
3ff0: 76 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b  valid and open [
4000: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
4010: 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  ion]..** <li> Th
4020: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
4030: 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65  st not close the
4040: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
4050: 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64  ction] specified
4060: 20 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20   by.**      the 
4070: 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  1st parameter to
4080: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
4090: 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78  while sqlite3_ex
40a0: 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e  ec() is running.
40b0: 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70  .** <li> The app
40c0: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
40d0: 74 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c  t modify the SQL
40e0: 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
40f0: 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20  passed into.**  
4100: 20 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 61      the 2nd para
4110: 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33  meter of sqlite3
4120: 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71  _exec() while sq
4130: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
4140: 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c  running..** </ul
4150: 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  >.*/.int sqlite3
4160: 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33  _exec(.  sqlite3
4170: 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  *,              
4180: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4190: 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64      /* An open d
41a0: 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e  atabase */.  con
41b0: 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20  st char *sql,   
41c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41d0: 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74          /* SQL t
41e0: 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a  o be evaluated *
41f0: 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61  /.  int (*callba
4200: 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68  ck)(void*,int,ch
4210: 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f  ar**,char**),  /
4220: 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  * Callback funct
4230: 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c  ion */.  void *,
4240: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4250: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4260: 20 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d      /* 1st argum
4270: 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20  ent to callback 
4280: 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d  */.  char **errm
4290: 73 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20  sg              
42a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
42b0: 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69  /* Error msg wri
42c0: 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a  tten here */.);.
42d0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
42e0: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a   Result Codes.**
42f0: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75   KEYWORDS: {resu
4300: 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69  lt code definiti
4310: 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20  ons}.**.** Many 
4320: 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73  SQLite functions
4330: 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67   return an integ
4340: 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66  er result code f
4350: 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77  rom the set show
4360: 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64  n.** here in ord
4370: 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73  er to indicate s
4380: 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72  uccess or failur
4390: 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72  e..**.** New err
43a0: 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20  or codes may be 
43b0: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
43c0: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
43d0: 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  te..**.** See al
43e0: 73 6f 3a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  so: [extended re
43f0: 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69  sult code defini
4400: 74 69 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e  tions].*/.#defin
4410: 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20  e SQLITE_OK     
4420: 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63        0   /* Suc
4430: 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a  cessful result *
4440: 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f  /./* beginning-o
4450: 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f  f-error-codes */
4460: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4470: 45 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20  ERROR        1  
4480: 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72   /* SQL error or
4490: 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62 61 73   missing databas
44a0: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
44b0: 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20  ITE_INTERNAL    
44c0: 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c   2   /* Internal
44d0: 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20   logic error in 
44e0: 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e  SQLite */.#defin
44f0: 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20  e SQLITE_PERM   
4500: 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63        3   /* Acc
4510: 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64  ess permission d
4520: 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  enied */.#define
4530: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20   SQLITE_ABORT   
4540: 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c       4   /* Call
4550: 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71  back routine req
4560: 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20  uested an abort 
4570: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4580: 45 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35  E_BUSY         5
4590: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61     /* The databa
45a0: 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65  se file is locke
45b0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
45c0: 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20  ITE_LOCKED      
45d0: 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20   6   /* A table 
45e0: 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  in the database 
45f0: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
4600: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45  fine SQLITE_NOME
4610: 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20  M        7   /* 
4620: 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65  A malloc() faile
4630: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4640: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20  ITE_READONLY    
4650: 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20   8   /* Attempt 
4660: 74 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f  to write a reado
4670: 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  nly database */.
4680: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4690: 4e 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20  NTERRUPT    9   
46a0: 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72  /* Operation ter
46b0: 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74  minated by sqlit
46c0: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f  e3_interrupt()*/
46d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
46e0: 49 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20  IOERR       10  
46f0: 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66   /* Some kind of
4700: 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20   disk I/O error 
4710: 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66  occurred */.#def
4720: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55  ine SQLITE_CORRU
4730: 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54  PT     11   /* T
4740: 68 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b  he database disk
4750: 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72   image is malfor
4760: 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  med */.#define S
4770: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20  QLITE_NOTFOUND  
4780: 20 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77    12   /* Unknow
4790: 6e 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69  n opcode in sqli
47a0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
47b0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
47c0: 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20  LITE_FULL       
47d0: 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69   13   /* Inserti
47e0: 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73  on failed becaus
47f0: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75  e database is fu
4800: 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ll */.#define SQ
4810: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20  LITE_CANTOPEN   
4820: 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20   14   /* Unable 
4830: 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61  to open the data
4840: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65  base file */.#de
4850: 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54  fine SQLITE_PROT
4860: 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20  OCOL    15   /* 
4870: 44 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72  Database lock pr
4880: 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a  otocol error */.
4890: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45  #define SQLITE_E
48a0: 4d 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20  MPTY       16   
48b0: 2f 2a 20 44 61 74 61 62 61 73 65 20 69 73 20 65  /* Database is e
48c0: 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  mpty */.#define 
48d0: 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20  SQLITE_SCHEMA   
48e0: 20 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64     17   /* The d
48f0: 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63  atabase schema c
4900: 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e  hanged */.#defin
4910: 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20  e SQLITE_TOOBIG 
4920: 20 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72       18   /* Str
4930: 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65  ing or BLOB exce
4940: 65 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a  eds size limit *
4950: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4960: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20  _CONSTRAINT  19 
4970: 20 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74    /* Abort due t
4980: 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  o constraint vio
4990: 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e  lation */.#defin
49a0: 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43  e SQLITE_MISMATC
49b0: 48 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74  H    20   /* Dat
49c0: 61 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20  a type mismatch 
49d0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
49e0: 45 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31  E_MISUSE      21
49f0: 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73     /* Library us
4a00: 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a  ed incorrectly *
4a10: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4a20: 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20  _NOLFS       22 
4a30: 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61    /* Uses OS fea
4a40: 74 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72  tures not suppor
4a50: 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23  ted on host */.#
4a60: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55  define SQLITE_AU
4a70: 54 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f  TH        23   /
4a80: 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20  * Authorization 
4a90: 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e  denied */.#defin
4aa0: 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20  e SQLITE_FORMAT 
4ab0: 20 20 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78       24   /* Aux
4ac0: 69 6c 69 61 72 79 20 64 61 74 61 62 61 73 65 20  iliary database 
4ad0: 66 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a  format error */.
4ae0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
4af0: 41 4e 47 45 20 20 20 20 20 20 20 32 35 20 20 20  ANGE       25   
4b00: 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  /* 2nd parameter
4b10: 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
4b20: 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f   out of range */
4b30: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4b40: 4e 4f 54 41 44 42 20 20 20 20 20 20 32 36 20 20  NOTADB      26  
4b50: 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20   /* File opened 
4b60: 74 68 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61  that is not a da
4b70: 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23  tabase file */.#
4b80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
4b90: 54 49 43 45 20 20 20 20 20 20 32 37 20 20 20 2f  TICE      27   /
4ba0: 2a 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 73 20  * Notifications 
4bb0: 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67  from sqlite3_log
4bc0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
4bd0: 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 20 20 20  LITE_WARNING    
4be0: 20 32 38 20 20 20 2f 2a 20 57 61 72 6e 69 6e 67   28   /* Warning
4bf0: 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c  s from sqlite3_l
4c00: 6f 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  og() */.#define 
4c10: 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20  SQLITE_ROW      
4c20: 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74     100  /* sqlit
4c30: 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e  e3_step() has an
4c40: 6f 74 68 65 72 20 72 6f 77 20 72 65 61 64 79 20  other row ready 
4c50: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4c60: 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30  E_DONE        10
4c70: 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74  1  /* sqlite3_st
4c80: 65 70 28 29 20 68 61 73 20 66 69 6e 69 73 68 65  ep() has finishe
4c90: 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f  d executing */./
4ca0: 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63  * end-of-error-c
4cb0: 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  odes */../*.** C
4cc0: 41 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65  API3REF: Extende
4cd0: 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a  d Result Codes.*
4ce0: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74  * KEYWORDS: {ext
4cf0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
4d00: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a  e definitions}.*
4d10: 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61  *.** In its defa
4d20: 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
4d30: 6e 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f  n, SQLite API ro
4d40: 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e  utines return on
4d50: 65 20 6f 66 20 33 30 20 69 6e 74 65 67 65 72 0a  e of 30 integer.
4d60: 2a 2a 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73  ** [result codes
4d70: 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70  ].  However, exp
4d80: 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77  erience has show
4d90: 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a  n that many of.*
4da0: 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63  * these result c
4db0: 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61  odes are too coa
4dc0: 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68  rse-grained.  Th
4dd0: 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64  ey do not provid
4de0: 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66  e as.** much inf
4df0: 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70  ormation about p
4e00: 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72  roblems as progr
4e10: 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b  ammers might lik
4e20: 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74  e.  In an effort
4e30: 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74   to.** address t
4e40: 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69  his, newer versi
4e50: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76  ons of SQLite (v
4e60: 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 5b 64 61  ersion 3.3.8 [da
4e70: 74 65 6f 66 3a 33 2e 33 2e 38 5d 0a 2a 2a 20 61  teof:3.3.8].** a
4e80: 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64  nd later) includ
4e90: 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72  e.** support for
4ea0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75   additional resu
4eb0: 6c 74 20 63 6f 64 65 73 20 74 68 61 74 20 70 72  lt codes that pr
4ec0: 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69  ovide more detai
4ed0: 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a  led information.
4ee0: 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e  ** about errors.
4ef0: 20 54 68 65 73 65 20 5b 65 78 74 65 6e 64 65 64   These [extended
4f00: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 61   result codes] a
4f10: 72 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69  re enabled or di
4f20: 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70  sabled.** on a p
4f30: 65 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  er database conn
4f40: 65 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69  ection basis usi
4f50: 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
4f60: 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
4f70: 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e  lt_codes()] API.
4f80: 20 20 4f 72 2c 20 74 68 65 20 65 78 74 65 6e 64    Or, the extend
4f90: 65 64 20 63 6f 64 65 20 66 6f 72 0a 2a 2a 20 74  ed code for.** t
4fa0: 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65  he most recent e
4fb0: 72 72 6f 72 20 63 61 6e 20 62 65 20 6f 62 74 61  rror can be obta
4fc0: 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  ined using.** [s
4fd0: 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
4fe0: 65 72 72 63 6f 64 65 28 29 5d 2e 0a 2a 2f 0a 23  errcode()]..*/.#
4ff0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5000: 45 52 52 5f 52 45 41 44 20 20 20 20 20 20 20 20  ERR_READ        
5010: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5020: 45 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  ERR | (1<<8)).#d
5030: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5040: 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20  RR_SHORT_READ   
5050: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5060: 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  RR | (2<<8)).#de
5070: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5080: 52 5f 57 52 49 54 45 20 20 20 20 20 20 20 20 20  R_WRITE         
5090: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
50a0: 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66  R | (3<<8)).#def
50b0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
50c0: 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 20  _FSYNC          
50d0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
50e0: 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69   | (4<<8)).#defi
50f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5100: 44 49 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20  DIR_FSYNC       
5110: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5120: 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (5<<8)).#defin
5130: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54  e SQLITE_IOERR_T
5140: 52 55 4e 43 41 54 45 20 20 20 20 20 20 20 20 20  RUNCATE         
5150: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
5160: 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (6<<8)).#define
5170: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53   SQLITE_IOERR_FS
5180: 54 41 54 20 20 20 20 20 20 20 20 20 20 20 20 20  TAT             
5190: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
51a0: 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (7<<8)).#define 
51b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c  SQLITE_IOERR_UNL
51c0: 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 28  OCK            (
51d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
51e0: 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  8<<8)).#define S
51f0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f  QLITE_IOERR_RDLO
5200: 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53  CK            (S
5210: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39  QLITE_IOERR | (9
5220: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5230: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54  LITE_IOERR_DELET
5240: 45 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  E            (SQ
5250: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 30  LITE_IOERR | (10
5260: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5270: 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
5280: 45 44 20 20 20 20 20 20 20 20 20 20 20 28 53 51  ED           (SQ
5290: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 31  LITE_IOERR | (11
52a0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
52b0: 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d  LITE_IOERR_NOMEM
52c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
52d0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 32  LITE_IOERR | (12
52e0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
52f0: 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53  LITE_IOERR_ACCES
5300: 53 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  S            (SQ
5310: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 33  LITE_IOERR | (13
5320: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5330: 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b  LITE_IOERR_CHECK
5340: 52 45 53 45 52 56 45 44 4c 4f 43 4b 20 28 53 51  RESERVEDLOCK (SQ
5350: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 34  LITE_IOERR | (14
5360: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5370: 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20  LITE_IOERR_LOCK 
5380: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
5390: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 35  LITE_IOERR | (15
53a0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
53b0: 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45  LITE_IOERR_CLOSE
53c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
53d0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 36  LITE_IOERR | (16
53e0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
53f0: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43  LITE_IOERR_DIR_C
5400: 4c 4f 53 45 20 20 20 20 20 20 20 20 20 28 53 51  LOSE         (SQ
5410: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 37  LITE_IOERR | (17
5420: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5430: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4f 50  LITE_IOERR_SHMOP
5440: 45 4e 20 20 20 20 20 20 20 20 20 20 20 28 53 51  EN           (SQ
5450: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 38  LITE_IOERR | (18
5460: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5470: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 53 49  LITE_IOERR_SHMSI
5480: 5a 45 20 20 20 20 20 20 20 20 20 20 20 28 53 51  ZE           (SQ
5490: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 39  LITE_IOERR | (19
54a0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
54b0: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f  LITE_IOERR_SHMLO
54c0: 43 4b 20 20 20 20 20 20 20 20 20 20 20 28 53 51  CK           (SQ
54d0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 30  LITE_IOERR | (20
54e0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
54f0: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4d 41  LITE_IOERR_SHMMA
5500: 50 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  P            (SQ
5510: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 31  LITE_IOERR | (21
5520: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5530: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 45 45 4b 20  LITE_IOERR_SEEK 
5540: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
5550: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 32  LITE_IOERR | (22
5560: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5570: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54  LITE_IOERR_DELET
5580: 45 5f 4e 4f 45 4e 54 20 20 20 20 20 20 28 53 51  E_NOENT      (SQ
5590: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 33  LITE_IOERR | (23
55a0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
55b0: 4c 49 54 45 5f 49 4f 45 52 52 5f 4d 4d 41 50 20  LITE_IOERR_MMAP 
55c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
55d0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 34  LITE_IOERR | (24
55e0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
55f0: 4c 49 54 45 5f 49 4f 45 52 52 5f 47 45 54 54 45  LITE_IOERR_GETTE
5600: 4d 50 50 41 54 48 20 20 20 20 20 20 20 28 53 51  MPPATH       (SQ
5610: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 35  LITE_IOERR | (25
5620: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5630: 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4f 4e 56 50  LITE_IOERR_CONVP
5640: 41 54 48 20 20 20 20 20 20 20 20 20 20 28 53 51  ATH          (SQ
5650: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 36  LITE_IOERR | (26
5660: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5670: 4c 49 54 45 5f 49 4f 45 52 52 5f 56 4e 4f 44 45  LITE_IOERR_VNODE
5680: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
5690: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 37  LITE_IOERR | (27
56a0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
56b0: 4c 49 54 45 5f 49 4f 45 52 52 5f 41 55 54 48 20  LITE_IOERR_AUTH 
56c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
56d0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 38  LITE_IOERR | (28
56e0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
56f0: 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52  LITE_LOCKED_SHAR
5700: 45 44 43 41 43 48 45 20 20 20 20 20 20 28 53 51  EDCACHE      (SQ
5710: 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 20 28  LITE_LOCKED |  (
5720: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5730: 51 4c 49 54 45 5f 42 55 53 59 5f 52 45 43 4f 56  QLITE_BUSY_RECOV
5740: 45 52 59 20 20 20 20 20 20 20 20 20 20 20 28 53  ERY           (S
5750: 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20  QLITE_BUSY   |  
5760: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
5770: 53 51 4c 49 54 45 5f 42 55 53 59 5f 53 4e 41 50  SQLITE_BUSY_SNAP
5780: 53 48 4f 54 20 20 20 20 20 20 20 20 20 20 20 28  SHOT           (
5790: 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c 20  SQLITE_BUSY   | 
57a0: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
57b0: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e   SQLITE_CANTOPEN
57c0: 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20 20 20 20  _NOTEMPDIR      
57d0: 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  (SQLITE_CANTOPEN
57e0: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
57f0: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  ne SQLITE_CANTOP
5800: 45 4e 5f 49 53 44 49 52 20 20 20 20 20 20 20 20  EN_ISDIR        
5810: 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50    (SQLITE_CANTOP
5820: 45 4e 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  EN | (2<<8)).#de
5830: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54  fine SQLITE_CANT
5840: 4f 50 45 4e 5f 46 55 4c 4c 50 41 54 48 20 20 20  OPEN_FULLPATH   
5850: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54      (SQLITE_CANT
5860: 4f 50 45 4e 20 7c 20 28 33 3c 3c 38 29 29 0a 23  OPEN | (3<<8)).#
5870: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
5880: 4e 54 4f 50 45 4e 5f 43 4f 4e 56 50 41 54 48 20  NTOPEN_CONVPATH 
5890: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
58a0: 4e 54 4f 50 45 4e 20 7c 20 28 34 3c 3c 38 29 29  NTOPEN | (4<<8))
58b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
58c0: 43 4f 52 52 55 50 54 5f 56 54 41 42 20 20 20 20  CORRUPT_VTAB    
58d0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
58e0: 43 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c 38 29  CORRUPT | (1<<8)
58f0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5900: 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45  _READONLY_RECOVE
5910: 52 59 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  RY       (SQLITE
5920: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c  _READONLY | (1<<
5930: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5940: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54  TE_READONLY_CANT
5950: 4c 4f 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49  LOCK       (SQLI
5960: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32  TE_READONLY | (2
5970: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5980: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 4f  LITE_READONLY_RO
5990: 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 28 53 51  LLBACK       (SQ
59a0: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20  LITE_READONLY | 
59b0: 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (3<<8)).#define 
59c0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f  SQLITE_READONLY_
59d0: 44 42 4d 4f 56 45 44 20 20 20 20 20 20 20 20 28  DBMOVED        (
59e0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
59f0: 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (4<<8)).#defin
5a00: 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52  e SQLITE_ABORT_R
5a10: 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 20 20  OLLBACK         
5a20: 20 28 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c   (SQLITE_ABORT |
5a30: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
5a40: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5a50: 4e 54 5f 43 48 45 43 4b 20 20 20 20 20 20 20 20  NT_CHECK        
5a60: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5a70: 4e 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  NT | (1<<8)).#de
5a80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5a90: 54 52 41 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f  TRAINT_COMMITHOO
5aa0: 4b 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53  K   (SQLITE_CONS
5ab0: 54 52 41 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29  TRAINT | (2<<8))
5ac0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5ad0: 43 4f 4e 53 54 52 41 49 4e 54 5f 46 4f 52 45 49  CONSTRAINT_FOREI
5ae0: 47 4e 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f  GNKEY   (SQLITE_
5af0: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 33 3c  CONSTRAINT | (3<
5b00: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5b10: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46  ITE_CONSTRAINT_F
5b20: 55 4e 43 54 49 4f 4e 20 20 20 20 20 28 53 51 4c  UNCTION     (SQL
5b30: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5b40: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (4<<8)).#define
5b50: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5b60: 4e 54 5f 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20  NT_NOTNULL      
5b70: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5b80: 4e 54 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65  NT | (5<<8)).#de
5b90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5ba0: 54 52 41 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45  TRAINT_PRIMARYKE
5bb0: 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53  Y   (SQLITE_CONS
5bc0: 54 52 41 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29  TRAINT | (6<<8))
5bd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5be0: 43 4f 4e 53 54 52 41 49 4e 54 5f 54 52 49 47 47  CONSTRAINT_TRIGG
5bf0: 45 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  ER      (SQLITE_
5c00: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 37 3c  CONSTRAINT | (7<
5c10: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5c20: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55  ITE_CONSTRAINT_U
5c30: 4e 49 51 55 45 20 20 20 20 20 20 20 28 53 51 4c  NIQUE       (SQL
5c40: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5c50: 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (8<<8)).#define
5c60: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5c70: 4e 54 5f 56 54 41 42 20 20 20 20 20 20 20 20 20  NT_VTAB         
5c80: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5c90: 4e 54 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65  NT | (9<<8)).#de
5ca0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5cb0: 54 52 41 49 4e 54 5f 52 4f 57 49 44 20 20 20 20  TRAINT_ROWID    
5cc0: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
5cd0: 54 52 41 49 4e 54 20 7c 28 31 30 3c 3c 38 29 29  TRAINT |(10<<8))
5ce0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5cf0: 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45 52 5f 57  NOTICE_RECOVER_W
5d00: 41 4c 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  AL      (SQLITE_
5d10: 4e 4f 54 49 43 45 20 7c 20 28 31 3c 3c 38 29 29  NOTICE | (1<<8))
5d20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5d30: 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45 52 5f 52  NOTICE_RECOVER_R
5d40: 4f 4c 4c 42 41 43 4b 20 28 53 51 4c 49 54 45 5f  OLLBACK (SQLITE_
5d50: 4e 4f 54 49 43 45 20 7c 20 28 32 3c 3c 38 29 29  NOTICE | (2<<8))
5d60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5d70: 57 41 52 4e 49 4e 47 5f 41 55 54 4f 49 4e 44 45  WARNING_AUTOINDE
5d80: 58 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  X       (SQLITE_
5d90: 57 41 52 4e 49 4e 47 20 7c 20 28 31 3c 3c 38 29  WARNING | (1<<8)
5da0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5db0: 5f 41 55 54 48 5f 55 53 45 52 20 20 20 20 20 20  _AUTH_USER      
5dc0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5dd0: 5f 41 55 54 48 20 7c 20 28 31 3c 3c 38 29 29 0a  _AUTH | (1<<8)).
5de0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5df0: 4b 5f 4c 4f 41 44 5f 50 45 52 4d 41 4e 45 4e 54  K_LOAD_PERMANENT
5e00: 4c 59 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4f  LY     (SQLITE_O
5e10: 4b 20 7c 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a  K | (1<<8))../*.
5e20: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
5e30: 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e  gs For File Open
5e40: 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a   Operations.**.*
5e50: 2a 20 54 68 65 73 65 20 62 69 74 20 76 61 6c 75  * These bit valu
5e60: 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  es are intended 
5e70: 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a  for use in the.*
5e80: 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  * 3rd parameter 
5e90: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
5ea0: 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72  open_v2()] inter
5eb0: 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74  face and.** in t
5ec0: 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
5ed0: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
5ee0: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
5ef0: 6f 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  od..*/.#define S
5f00: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
5f10: 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30  NLY         0x00
5f20: 30 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f  000001  /* Ok fo
5f30: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5f40: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5f50: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
5f60: 52 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30  RITE        0x00
5f70: 30 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f  000002  /* Ok fo
5f80: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5f90: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5fa0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
5fb0: 45 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30  E           0x00
5fc0: 30 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f  000004  /* Ok fo
5fd0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5fe0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5ff0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
6000: 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30  EONCLOSE    0x00
6010: 30 30 30 30 30 38 20 20 2f 2a 20 56 46 53 20 6f  000008  /* VFS o
6020: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6030: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
6040: 53 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30  SIVE        0x00
6050: 30 30 30 30 31 30 20 20 2f 2a 20 56 46 53 20 6f  000010  /* VFS o
6060: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6070: 51 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50  QLITE_OPEN_AUTOP
6080: 52 4f 58 59 20 20 20 20 20 20 20 20 30 78 30 30  ROXY        0x00
6090: 30 30 30 30 32 30 20 20 2f 2a 20 56 46 53 20 6f  000020  /* VFS o
60a0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
60b0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20  QLITE_OPEN_URI  
60c0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
60d0: 30 30 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f  000040  /* Ok fo
60e0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
60f0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
6100: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52  QLITE_OPEN_MEMOR
6110: 59 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30  Y           0x00
6120: 30 30 30 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f  000080  /* Ok fo
6130: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
6140: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
6150: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
6160: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30  DB          0x00
6170: 30 30 30 31 30 30 20 20 2f 2a 20 56 46 53 20 6f  000100  /* VFS o
6180: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6190: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
61a0: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30  DB          0x00
61b0: 30 30 30 32 30 30 20 20 2f 2a 20 56 46 53 20 6f  000200  /* VFS o
61c0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
61d0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53  QLITE_OPEN_TRANS
61e0: 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30  IENT_DB     0x00
61f0: 30 30 30 34 30 30 20 20 2f 2a 20 56 46 53 20 6f  000400  /* VFS o
6200: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6210: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
6220: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30  JOURNAL     0x00
6230: 30 30 30 38 30 30 20 20 2f 2a 20 56 46 53 20 6f  000800  /* VFS o
6240: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6250: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
6260: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30  JOURNAL     0x00
6270: 30 30 31 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  001000  /* VFS o
6280: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6290: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f  QLITE_OPEN_SUBJO
62a0: 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30  URNAL       0x00
62b0: 30 30 32 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  002000  /* VFS o
62c0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
62d0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45  QLITE_OPEN_MASTE
62e0: 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30  R_JOURNAL   0x00
62f0: 30 30 34 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  004000  /* VFS o
6300: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6310: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
6320: 45 58 20 20 20 20 20 20 20 20 20 20 30 78 30 30  EX          0x00
6330: 30 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  008000  /* Ok fo
6340: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
6350: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
6360: 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
6370: 55 54 45 58 20 20 20 20 20 20 20 20 30 78 30 30  UTEX        0x00
6380: 30 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  010000  /* Ok fo
6390: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
63a0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
63b0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
63c0: 44 43 41 43 48 45 20 20 20 20 20 20 30 78 30 30  DCACHE      0x00
63d0: 30 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  020000  /* Ok fo
63e0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
63f0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
6400: 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
6410: 54 45 43 41 43 48 45 20 20 20 20 20 30 78 30 30  TECACHE     0x00
6420: 30 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  040000  /* Ok fo
6430: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
6440: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
6450: 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20  QLITE_OPEN_WAL  
6460: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6470: 30 38 30 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  080000  /* VFS o
6480: 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72  nly */../* Reser
6490: 76 65 64 3a 20 20 20 20 20 20 20 20 20 20 20 20  ved:            
64a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
64b0: 30 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a  0F00000 */../*.*
64c0: 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69  * CAPI3REF: Devi
64d0: 63 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69  ce Characteristi
64e0: 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65  cs.**.** The xDe
64f0: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
6500: 69 63 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  ics method of th
6510: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
6520: 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74  thods].** object
6530: 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65   returns an inte
6540: 67 65 72 20 77 68 69 63 68 20 69 73 20 61 20 76  ger which is a v
6550: 65 63 74 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a  ector of these.*
6560: 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 70  * bit values exp
6570: 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72  ressing I/O char
6580: 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 74  acteristics of t
6590: 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a  he mass storage.
65a0: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 68  ** device that h
65b0: 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 68  olds the file th
65c0: 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  at the [sqlite3_
65d0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72  io_methods].** r
65e0: 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20  efers to..**.** 
65f0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
6600: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79  _ATOMIC property
6610: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20   means that all 
6620: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79  writes of.** any
6630: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63   size are atomic
6640: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
6650: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61  CAP_ATOMICnnn va
6660: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61  lues.** mean tha
6670: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63  t writes of bloc
6680: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20  ks that are nnn 
6690: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
66a0: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64  d.** are aligned
66b0: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77   to an address w
66c0: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67  hich is an integ
66d0: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a  er multiple of.*
66e0: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63  * nnn are atomic
66f0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
6700: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
6710: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74  value means.** t
6720: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73  hat when data is
6730: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66   appended to a f
6740: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73  ile, the data is
6750: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72   appended.** fir
6760: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65  st then the size
6770: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   of the file is 
6780: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20  extended, never 
6790: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79  the other.** way
67a0: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51   around.  The SQ
67b0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
67c0: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d  NTIAL property m
67d0: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66  eans that.** inf
67e0: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74  ormation is writ
67f0: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74  ten to disk in t
6800: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73  he same order as
6810: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72   calls.** to xWr
6820: 69 74 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49  ite().  The SQLI
6830: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41  TE_IOCAP_POWERSA
6840: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f  FE_OVERWRITE pro
6850: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
6860: 0a 2a 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74  .** after reboot
6870: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61   following a cra
6880: 73 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73  sh or power loss
6890: 2c 20 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73  , the only bytes
68a0: 20 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68   in a.** file th
68b0: 61 74 20 77 65 72 65 20 77 72 69 74 74 65 6e 20  at were written 
68c0: 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  at the applicati
68d0: 6f 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68  on level might h
68e0: 61 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61  ave changed.** a
68f0: 6e 64 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74  nd that adjacent
6900: 20 62 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74   bytes, even byt
6910: 65 73 20 77 69 74 68 69 6e 20 74 68 65 20 73 61  es within the sa
6920: 6d 65 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a  me sector are.**
6930: 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62   guaranteed to b
6940: 65 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68  e unchanged.  Th
6950: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55  e SQLITE_IOCAP_U
6960: 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f  NDELETABLE_WHEN_
6970: 4f 50 45 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e 64  OPEN.** flag ind
6980: 69 63 61 74 65 20 74 68 61 74 20 61 20 66 69 6c  icate that a fil
6990: 65 20 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65  e cannot be dele
69a0: 74 65 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20  ted when open.  
69b0: 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f  The.** SQLITE_IO
69c0: 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c  CAP_IMMUTABLE fl
69d0: 61 67 20 69 6e 64 69 63 61 74 65 73 20 74 68 61  ag indicates tha
69e0: 74 20 74 68 65 20 66 69 6c 65 20 69 73 20 6f 6e  t the file is on
69f0: 0a 2a 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65  .** read-only me
6a00: 64 69 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62  dia and cannot b
6a10: 65 20 63 68 61 6e 67 65 64 20 65 76 65 6e 20 62  e changed even b
6a20: 79 20 70 72 6f 63 65 73 73 65 73 20 77 69 74 68  y processes with
6a30: 0a 2a 2a 20 65 6c 65 76 61 74 65 64 20 70 72 69  .** elevated pri
6a40: 76 69 6c 65 67 65 73 2e 0a 2a 2f 0a 23 64 65 66  vileges..*/.#def
6a50: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6a60: 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20  _ATOMIC         
6a70: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6a80: 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  01.#define SQLIT
6a90: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31  E_IOCAP_ATOMIC51
6aa0: 32 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  2              0
6ab0: 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e  x00000002.#defin
6ac0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6ad0: 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 20  TOMIC1K         
6ae0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
6af0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6b00: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20  IOCAP_ATOMIC2K  
6b10: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6b20: 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20  0000008.#define 
6b30: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6b40: 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20 20 20  MIC4K           
6b50: 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23      0x00000010.#
6b60: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6b70: 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20  CAP_ATOMIC8K    
6b80: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6b90: 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51  00020.#define SQ
6ba0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6bb0: 43 31 36 4b 20 20 20 20 20 20 20 20 20 20 20 20  C16K            
6bc0: 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 65    0x00000040.#de
6bd0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6be0: 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20  P_ATOMIC32K     
6bf0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6c00: 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  080.#define SQLI
6c10: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36  TE_IOCAP_ATOMIC6
6c20: 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  4K              
6c30: 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69  0x00000100.#defi
6c40: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6c50: 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20  SAFE_APPEND     
6c60: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30         0x0000020
6c70: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6c80: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
6c90: 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78  L             0x
6ca0: 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65  00000400.#define
6cb0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e   SQLITE_IOCAP_UN
6cc0: 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f  DELETABLE_WHEN_O
6cd0: 50 45 4e 20 20 30 78 30 30 30 30 30 38 30 30 0a  PEN  0x00000800.
6ce0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6cf0: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
6d00: 56 45 52 57 52 49 54 45 20 20 20 20 30 78 30 30  VERWRITE    0x00
6d10: 30 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53  001000.#define S
6d20: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55  QLITE_IOCAP_IMMU
6d30: 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20  TABLE           
6d40: 20 20 20 30 78 30 30 30 30 32 30 30 30 0a 0a 2f     0x00002000../
6d50: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
6d60: 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65  ile Locking Leve
6d70: 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  ls.**.** SQLite 
6d80: 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73  uses one of thes
6d90: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
6da0: 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a   as the second.*
6db0: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61  * argument to ca
6dc0: 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20  lls it makes to 
6dd0: 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20  the xLock() and 
6de0: 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64  xUnlock() method
6df0: 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69  s.** of an [sqli
6e00: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
6e10: 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69  object..*/.#defi
6e20: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e  ne SQLITE_LOCK_N
6e30: 4f 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a 23  ONE          0.#
6e40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
6e50: 43 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20 20  CK_SHARED       
6e60: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
6e70: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20  E_LOCK_RESERVED 
6e80: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
6e90: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
6ea0: 4e 47 20 20 20 20 20 20 20 33 0a 23 64 65 66 69  NG       3.#defi
6eb0: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  ne SQLITE_LOCK_E
6ec0: 58 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a  XCLUSIVE     4..
6ed0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
6ee0: 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20  Synchronization 
6ef0: 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a  Type Flags.**.**
6f00: 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76   When SQLite inv
6f10: 6f 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28 29  okes the xSync()
6f20: 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a   method of an.**
6f30: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
6f40: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20  hods] object it 
6f50: 75 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69  uses a combinati
6f60: 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69  on of.** these i
6f70: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73  nteger values as
6f80: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
6f90: 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  ment..**.** When
6fa0: 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   the SQLITE_SYNC
6fb0: 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69  _DATAONLY flag i
6fc0: 73 20 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73  s used, it means
6fd0: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e   that the.** syn
6fe0: 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79  c operation only
6ff0: 20 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20   needs to flush 
7000: 64 61 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f  data to mass sto
7010: 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20  rage.  Inode.** 
7020: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64  information need
7030: 20 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e   not be flushed.
7040: 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f   If the lower fo
7050: 75 72 20 62 69 74 73 20 6f 66 20 74 68 65 20 66  ur bits of the f
7060: 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c  lag.** equal SQL
7070: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c  ITE_SYNC_NORMAL,
7080: 20 74 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 75   that means to u
7090: 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28  se normal fsync(
70a0: 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20  ) semantics..** 
70b0: 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75  If the lower fou
70c0: 72 20 62 69 74 73 20 65 71 75 61 6c 20 53 51 4c  r bits equal SQL
70d0: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74  ITE_SYNC_FULL, t
70e0: 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20  hat means.** to 
70f0: 75 73 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79  use Mac OS X sty
7100: 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74  le fullsync inst
7110: 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a  ead of fsync()..
7120: 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e  **.** Do not con
7130: 66 75 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f  fuse the SQLITE_
7140: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20  SYNC_NORMAL and 
7150: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
7160: 20 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20 74   flags.** with t
7170: 68 65 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  he [PRAGMA synch
7180: 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61  ronous]=NORMAL a
7190: 6e 64 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  nd [PRAGMA synch
71a0: 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20  ronous]=FULL.** 
71b0: 73 65 74 74 69 6e 67 73 2e 20 20 54 68 65 20 5b  settings.  The [
71c0: 73 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61 67  synchronous prag
71d0: 6d 61 5d 20 64 65 74 65 72 6d 69 6e 65 73 20 77  ma] determines w
71e0: 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  hen calls to the
71f0: 0a 2a 2a 20 78 53 79 6e 63 20 56 46 53 20 6d 65  .** xSync VFS me
7200: 74 68 6f 64 20 6f 63 63 75 72 20 61 6e 64 20 61  thod occur and a
7210: 70 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79  pplies uniformly
7220: 20 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74   across all plat
7230: 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51  forms..** The SQ
7240: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
7250: 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43   and SQLITE_SYNC
7260: 5f 46 55 4c 4c 20 66 6c 61 67 73 20 64 65 74 65  _FULL flags dete
7270: 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65  rmine how.** ene
7280: 72 67 65 74 69 63 20 6f 72 20 72 69 67 6f 72 6f  rgetic or rigoro
7290: 75 73 20 6f 72 20 66 6f 72 63 65 66 75 6c 20 74  us or forceful t
72a0: 68 65 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f  he sync operatio
72b0: 6e 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e  ns are and.** on
72c0: 6c 79 20 6d 61 6b 65 20 61 20 64 69 66 66 65 72  ly make a differ
72d0: 65 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20  ence on Mac OSX 
72e0: 66 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74 20  for the default 
72f0: 53 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20  SQLite code..** 
7300: 28 54 68 69 72 64 2d 70 61 72 74 79 20 56 46 53  (Third-party VFS
7310: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
7320: 20 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65   might also make
7330: 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e   the distinction
7340: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49  .** between SQLI
7350: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61  TE_SYNC_NORMAL a
7360: 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  nd SQLITE_SYNC_F
7370: 55 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74  ULL, but among t
7380: 68 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20  he.** operating 
7390: 73 79 73 74 65 6d 73 20 6e 61 74 69 76 65 6c 79  systems natively
73a0: 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51   supported by SQ
73b0: 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f  Lite, only Mac O
73c0: 53 58 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f 75  SX.** cares abou
73d0: 74 20 74 68 65 20 64 69 66 66 65 72 65 6e 63 65  t the difference
73e0: 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  .).*/.#define SQ
73f0: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
7400: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a          0x00002.
7410: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
7420: 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  YNC_FULL        
7430: 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e    0x00003.#defin
7440: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
7450: 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30  TAONLY      0x00
7460: 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  010../*.** CAPI3
7470: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
7480: 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64  e Open File Hand
7490: 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c  le.**.** An [sql
74a0: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
74b0: 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  t represents an 
74c0: 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65  open file in the
74d0: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66   .** [sqlite3_vf
74e0: 73 20 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65  s | OS interface
74f0: 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69   layer].  Indivi
7500: 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63  dual OS interfac
7510: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
7520: 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e  ions will.** wan
7530: 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68  t to subclass th
7540: 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70  is object by app
7550: 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61  ending additiona
7560: 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20  l fields.** for 
7570: 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20  their own use.  
7580: 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74  The pMethods ent
7590: 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ry is a pointer 
75a0: 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65  to an.** [sqlite
75b0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
75c0: 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65  ject that define
75d0: 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65  s methods for pe
75e0: 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20  rforming.** I/O 
75f0: 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68  operations on th
7600: 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a  e open file..*/.
7610: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
7620: 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69  qlite3_file sqli
7630: 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74  te3_file;.struct
7640: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a   sqlite3_file {.
7650: 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73    const struct s
7660: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7670: 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a  s *pMethods;  /*
7680: 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20   Methods for an 
7690: 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a  open file */.};.
76a0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
76b0: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69   OS Interface Fi
76c0: 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f  le Virtual Metho
76d0: 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  ds Object.**.** 
76e0: 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65  Every file opene
76f0: 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
7700: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74  3_vfs.xOpen] met
7710: 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e  hod populates an
7720: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
7730: 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d  e] object (or, m
7740: 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20  ore commonly, a 
7750: 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a  subclass of the.
7760: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
7770: 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61  ] object) with a
7780: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
7790: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
77a0: 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20  object..** This 
77b0: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
77c0: 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20  he methods used 
77d0: 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f  to perform vario
77e0: 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a  us operations.**
77f0: 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65   against the ope
7800: 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74  n file represent
7810: 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
7820: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e  e3_file] object.
7830: 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73  .**.** If the [s
7840: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
7850: 5d 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68  ] method sets th
7860: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
7870: 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20  Methods element 
7880: 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c  .** to a non-NUL
7890: 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
78a0: 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  the sqlite3_io_m
78b0: 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65  ethods.xClose me
78c0: 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69  thod.** may be i
78d0: 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74  nvoked even if t
78e0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
78f0: 78 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65 64 20  xOpen] reported 
7900: 74 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20  that it failed. 
7910: 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79   The.** only way
7920: 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61   to prevent a ca
7930: 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c  ll to xClose fol
7940: 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20  lowing a failed 
7950: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
7960: 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68  en].** is for th
7970: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
7980: 4f 70 65 6e 5d 20 74 6f 20 73 65 74 20 74 68 65  Open] to set the
7990: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
79a0: 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a  ethods element.*
79b0: 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  * to NULL..**.**
79c0: 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   The flags argum
79d0: 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79  ent to xSync may
79e0: 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   be one of [SQLI
79f0: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20  TE_SYNC_NORMAL] 
7a00: 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59  or.** [SQLITE_SY
7a10: 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66  NC_FULL].  The f
7a20: 69 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74  irst choice is t
7a30: 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28  he normal fsync(
7a40: 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  )..** The second
7a50: 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63   choice is a Mac
7a60: 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c   OS X style full
7a70: 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49  sync.  The [SQLI
7a80: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
7a90: 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65  ].** flag may be
7aa0: 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69   ORed in to indi
7ab0: 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74  cate that only t
7ac0: 68 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66  he data of the f
7ad0: 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69  ile.** and not i
7ae0: 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74  ts inode needs t
7af0: 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a  o be synced..**.
7b00: 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76  ** The integer v
7b10: 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29  alues to xLock()
7b20: 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61   and xUnlock() a
7b30: 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c  re one of.** <ul
7b40: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
7b50: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a  E_LOCK_NONE],.**
7b60: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
7b70: 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c  CK_SHARED],.** <
7b80: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
7b90: 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c  _RESERVED],.** <
7ba0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
7bb0: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a  _PENDING], or.**
7bc0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
7bd0: 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a  CK_EXCLUSIVE]..*
7be0: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b  * </ul>.** xLock
7bf0: 28 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65  () increases the
7c00: 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29   lock. xUnlock()
7c10: 20 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c   decreases the l
7c20: 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65  ock..** The xChe
7c30: 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29  ckReservedLock()
7c40: 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77   method checks w
7c50: 68 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62  hether any datab
7c60: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a  ase connection,.
7c70: 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69  ** either in thi
7c80: 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20  s process or in 
7c90: 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65  some other proce
7ca0: 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ss, is holding a
7cb0: 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45   RESERVED,.** PE
7cc0: 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53  NDING, or EXCLUS
7cd0: 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20  IVE lock on the 
7ce0: 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e  file.  It return
7cf0: 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63  s true.** if suc
7d00: 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20  h a lock exists 
7d10: 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77  and false otherw
7d20: 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ise..**.** The x
7d30: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65  FileControl() me
7d40: 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69  thod is a generi
7d50: 63 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  c interface that
7d60: 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a   allows custom.*
7d70: 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  * VFS implementa
7d80: 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c  tions to directl
7d90: 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65  y control an ope
7da0: 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65  n file using the
7db0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
7dc0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74  e_control()] int
7dd0: 65 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63  erface.  The sec
7de0: 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e  ond "op" argumen
7df0: 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67  t is an.** integ
7e00: 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20  er opcode.  The 
7e10: 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
7e20: 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e  s a generic poin
7e30: 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a  ter intended to.
7e40: 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74  ** point to a st
7e50: 72 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79  ructure that may
7e60: 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e   contain argumen
7e70: 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77  ts or space in w
7e80: 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65  hich to.** write
7e90: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20   return values. 
7ea0: 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20   Potential uses 
7eb0: 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  for xFileControl
7ec0: 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66  () might be.** f
7ed0: 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62  unctions to enab
7ee0: 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b  le blocking lock
7ef0: 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c  s with timeouts,
7f00: 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a   to change the.*
7f10: 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65  * locking strate
7f20: 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  gy (for example 
7f30: 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20  to use dot-file 
7f40: 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69  locks), to inqui
7f50: 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20  re.** about the 
7f60: 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b  status of a lock
7f70: 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74  , or to break st
7f80: 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20  ale locks.  The 
7f90: 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72  SQLite.** core r
7fa0: 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f  eserves all opco
7fb0: 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30  des less than 10
7fc0: 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73  0 for its own us
7fd0: 65 2e 0a 2a 2a 20 41 20 5b 66 69 6c 65 20 63 6f  e..** A [file co
7fe0: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 7c 20  ntrol opcodes | 
7ff0: 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d  list of opcodes]
8000: 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 69   less than 100 i
8010: 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20  s available..** 
8020: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
8030: 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f  t define a custo
8040: 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  m xFileControl m
8050: 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65  ethod should use
8060: 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61   opcodes.** grea
8070: 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20  ter than 100 to 
8080: 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e  avoid conflicts.
8090: 20 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61    VFS implementa
80a0: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20  tions should.** 
80b0: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e  return [SQLITE_N
80c0: 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c  OTFOUND] for fil
80d0: 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65  e control opcode
80e0: 73 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e  s that they do n
80f0: 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e  ot.** recognize.
8100: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74  .**.** The xSect
8110: 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20  orSize() method 
8120: 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63 74  returns the sect
8130: 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a  or size of the.*
8140: 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75 6e  * device that un
8150: 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65  derlies the file
8160: 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73 69  .  The sector si
8170: 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e  ze is the.** min
8180: 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74 20  imum write that 
8190: 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64  can be performed
81a0: 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72 62   without disturb
81b0: 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74  ing.** other byt
81c0: 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20  es in the file. 
81d0: 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72   The xDeviceChar
81e0: 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a  acteristics().**
81f0: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
8200: 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65 73  a bit vector des
8210: 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72  cribing behavior
8220: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65  s of the.** unde
8230: 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a  rlying device:.*
8240: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
8250: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8260: 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20  ATOMIC].** <li> 
8270: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
8280: 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC512].** <li>
8290: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
82a0: 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC1K].** <li>
82b0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
82c0: 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC2K].** <li>
82d0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
82e0: 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC4K].** <li>
82f0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8300: 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC8K].** <li>
8310: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8320: 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC16K].** <li
8330: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8340: 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC32K].** <l
8350: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
8360: 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c  _ATOMIC64K].** <
8370: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
8380: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a  P_SAFE_APPEND].*
8390: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
83a0: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d  OCAP_SEQUENTIAL]
83b0: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
83c0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
83d0: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79  _ATOMIC property
83e0: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20   means that all 
83f0: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79  writes of.** any
8400: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63   size are atomic
8410: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
8420: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61  CAP_ATOMICnnn va
8430: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61  lues.** mean tha
8440: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63  t writes of bloc
8450: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20  ks that are nnn 
8460: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
8470: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64  d.** are aligned
8480: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77   to an address w
8490: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67  hich is an integ
84a0: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a  er multiple of.*
84b0: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63  * nnn are atomic
84c0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
84d0: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
84e0: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74  value means.** t
84f0: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73  hat when data is
8500: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66   appended to a f
8510: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73  ile, the data is
8520: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72   appended.** fir
8530: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65  st then the size
8540: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   of the file is 
8550: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20  extended, never 
8560: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79  the other.** way
8570: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51   around.  The SQ
8580: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
8590: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d  NTIAL property m
85a0: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66  eans that.** inf
85b0: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74  ormation is writ
85c0: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74  ten to disk in t
85d0: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73  he same order as
85e0: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72   calls.** to xWr
85f0: 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ite()..**.** If 
8600: 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73 20  xRead() returns 
8610: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f  SQLITE_IOERR_SHO
8620: 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20  RT_READ it must 
8630: 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20  also fill.** in 
8640: 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69  the unread porti
8650: 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66 65  ons of the buffe
8660: 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41  r with zeros.  A
8670: 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69   VFS that.** fai
8680: 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20  ls to zero-fill 
8690: 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68  short reads migh
86a0: 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20  t seem to work. 
86b0: 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69   However,.** fai
86c0: 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c  lure to zero-fil
86d0: 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77 69  l short reads wi
86e0: 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65  ll eventually le
86f0: 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73  ad to.** databas
8700: 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f  e corruption..*/
8710: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
8720: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
8730: 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ds sqlite3_io_me
8740: 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
8750: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
8760: 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
8770: 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73  n;.  int (*xClos
8780: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
8790: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64  );.  int (*xRead
87a0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
87b0: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74   void*, int iAmt
87c0: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
87d0: 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a  iOfst);.  int (*
87e0: 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f  xWrite)(sqlite3_
87f0: 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  file*, const voi
8800: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71  d*, int iAmt, sq
8810: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
8820: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75  t);.  int (*xTru
8830: 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66  ncate)(sqlite3_f
8840: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
8850: 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74  t64 size);.  int
8860: 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65   (*xSync)(sqlite
8870: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61  3_file*, int fla
8880: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  gs);.  int (*xFi
8890: 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f  leSize)(sqlite3_
88a0: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
88b0: 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20  nt64 *pSize);.  
88c0: 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c  int (*xLock)(sql
88d0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29  ite3_file*, int)
88e0: 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63  ;.  int (*xUnloc
88f0: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
8900: 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a  , int);.  int (*
8910: 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f  xCheckReservedLo
8920: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
8930: 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29  *, int *pResOut)
8940: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43  ;.  int (*xFileC
8950: 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f  ontrol)(sqlite3_
8960: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76  file*, int op, v
8970: 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e  oid *pArg);.  in
8980: 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29  t (*xSectorSize)
8990: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
89a0: 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65  .  int (*xDevice
89b0: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 29  Characteristics)
89c0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
89d0: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62  .  /* Methods ab
89e0: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f  ove are valid fo
89f0: 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20  r version 1 */. 
8a00: 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29 28   int (*xShmMap)(
8a10: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8a20: 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73 7a  nt iPg, int pgsz
8a30: 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61  , int, void vola
8a40: 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28  tile**);.  int (
8a50: 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74  *xShmLock)(sqlit
8a60: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66  e3_file*, int of
8a70: 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74  fset, int n, int
8a80: 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64 20   flags);.  void 
8a90: 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28 73  (*xShmBarrier)(s
8aa0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
8ab0: 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70   int (*xShmUnmap
8ac0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8ad0: 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67 29   int deleteFlag)
8ae0: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
8af0: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
8b00: 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a  or version 2 */.
8b10: 20 20 69 6e 74 20 28 2a 78 46 65 74 63 68 29 28    int (*xFetch)(
8b20: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
8b30: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
8b40: 73 74 2c 20 69 6e 74 20 69 41 6d 74 2c 20 76 6f  st, int iAmt, vo
8b50: 69 64 20 2a 2a 70 70 29 3b 0a 20 20 69 6e 74 20  id **pp);.  int 
8b60: 28 2a 78 55 6e 66 65 74 63 68 29 28 73 71 6c 69  (*xUnfetch)(sqli
8b70: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
8b80: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20  e3_int64 iOfst, 
8b90: 76 6f 69 64 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d  void *p);.  /* M
8ba0: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
8bb0: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69   valid for versi
8bc0: 6f 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20 41 64 64  on 3 */.  /* Add
8bd0: 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20  itional methods 
8be0: 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
8bf0: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
8c00: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
8c10: 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20  I3REF: Standard 
8c20: 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63  File Control Opc
8c30: 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  odes.** KEYWORDS
8c40: 3a 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  : {file control 
8c50: 6f 70 63 6f 64 65 73 7d 20 7b 66 69 6c 65 20 63  opcodes} {file c
8c60: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 7d 0a 2a  ontrol opcode}.*
8c70: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67  *.** These integ
8c80: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  er constants are
8c90: 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65   opcodes for the
8ca0: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
8cb0: 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  thod.** of the [
8cc0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
8cd0: 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66  ds] object and f
8ce0: 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  or the [sqlite3_
8cf0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a  file_control()].
8d00: 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  ** interface..**
8d10: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
8d20: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c  [[SQLITE_FCNTL_L
8d30: 4f 43 4b 53 54 41 54 45 5d 5d 0a 2a 2a 20 54 68  OCKSTATE]].** Th
8d40: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
8d50: 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64  LOCKSTATE] opcod
8d60: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65  e is used for de
8d70: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a  bugging.  This.*
8d80: 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20  * opcode causes 
8d90: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
8da0: 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65   method to write
8db0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
8dc0: 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63  te of.** the loc
8dd0: 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  k (one of [SQLIT
8de0: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53  E_LOCK_NONE], [S
8df0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
8e00: 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c  D],.** [SQLITE_L
8e10: 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b  OCK_RESERVED], [
8e20: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
8e30: 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  ING], or [SQLITE
8e40: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d  _LOCK_EXCLUSIVE]
8e50: 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74  ).** into an int
8e60: 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41  eger that the pA
8e70: 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  rg argument poin
8e80: 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61  ts to. This capa
8e90: 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65  bility.** is use
8ea0: 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67  d during testing
8eb0: 20 61 6e 64 20 69 73 20 6f 6e 6c 79 20 61 76 61   and is only ava
8ec0: 69 6c 61 62 6c 65 20 77 68 65 6e 20 74 68 65 20  ilable when the 
8ed0: 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 63  SQLITE_TEST.** c
8ee0: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
8ef0: 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  on is used..**.*
8f00: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
8f10: 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d  CNTL_SIZE_HINT]]
8f20: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
8f30: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d  FCNTL_SIZE_HINT]
8f40: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
8f50: 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67 69 76  by SQLite to giv
8f60: 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79  e the VFS.** lay
8f70: 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68 6f 77  er a hint of how
8f80: 20 6c 61 72 67 65 20 74 68 65 20 64 61 74 61 62   large the datab
8f90: 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 67 72  ase file will gr
8fa0: 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e 67 20  ow to be during 
8fb0: 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74  the.** current t
8fc0: 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68 69  ransaction.  Thi
8fd0: 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20 67 75  s hint is not gu
8fe0: 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 61  aranteed to be a
8ff0: 63 63 75 72 61 74 65 20 62 75 74 20 69 74 0a 2a  ccurate but it.*
9000: 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65  * is often close
9010: 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e  .  The underlyin
9020: 67 20 56 46 53 20 6d 69 67 68 74 20 63 68 6f 6f  g VFS might choo
9030: 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74  se to preallocat
9040: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  e database.** fi
9050: 6c 65 20 73 70 61 63 65 20 62 61 73 65 64 20 6f  le space based o
9060: 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e 20 6f  n this hint in o
9070: 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77 72 69  rder to help wri
9080: 74 65 73 20 74 6f 20 74 68 65 20 64 61 74 61 62  tes to the datab
9090: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20  ase.** file run 
90a0: 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  faster..**.** <l
90b0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
90c0: 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a  _CHUNK_SIZE]].**
90d0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
90e0: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f  TL_CHUNK_SIZE] o
90f0: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
9100: 20 72 65 71 75 65 73 74 20 74 68 61 74 20 74 68   request that th
9110: 65 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73  e VFS.** extends
9120: 20 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74   and truncates t
9130: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
9140: 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20   in chunks of a 
9150: 73 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a  size specified.*
9160: 2a 20 62 79 20 74 68 65 20 75 73 65 72 2e 20 54  * by the user. T
9170: 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
9180: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  nt to [sqlite3_f
9190: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73  ile_control()] s
91a0: 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20  hould .** point 
91b0: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74  to an integer (t
91c0: 79 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e  ype int) contain
91d0: 69 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e  ing the new chun
91e0: 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a  k-size to use.**
91f0: 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74   for the nominat
9200: 65 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c  ed database. All
9210: 6f 63 61 74 69 6e 67 20 64 61 74 61 62 61 73 65  ocating database
9220: 20 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c   file space in l
9230: 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28  arge.** chunks (
9240: 73 61 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d  say 1MB at a tim
9250: 65 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66  e), may reduce f
9260: 69 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d  ile-system fragm
9270: 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20  entation and.** 
9280: 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61  improve performa
9290: 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74  nce on some syst
92a0: 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ems..**.** <li>[
92b0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49  [SQLITE_FCNTL_FI
92c0: 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20  LE_POINTER]].** 
92d0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
92e0: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20  L_FILE_POINTER] 
92f0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
9300: 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74  o obtain a point
9310: 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  er.** to the [sq
9320: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
9330: 63 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ct associated wi
9340: 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  th a particular 
9350: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
9360: 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 61 6c 73  ection.  See als
9370: 6f 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  o [SQLITE_FCNTL_
9380: 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d  JOURNAL_POINTER]
9390: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
93a0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e  LITE_FCNTL_JOURN
93b0: 41 4c 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20  AL_POINTER]].** 
93c0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
93d0: 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45  L_JOURNAL_POINTE
93e0: 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  R] opcode is use
93f0: 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f  d to obtain a po
9400: 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
9410: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
9420: 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 64  bject associated
9430: 20 77 69 74 68 20 74 68 65 20 6a 6f 75 72 6e 61   with the journa
9440: 6c 20 66 69 6c 65 20 28 65 69 74 68 65 72 0a 2a  l file (either.*
9450: 2a 20 74 68 65 20 5b 72 6f 6c 6c 62 61 63 6b 20  * the [rollback 
9460: 6a 6f 75 72 6e 61 6c 5d 20 6f 72 20 74 68 65 20  journal] or the 
9470: 5b 77 72 69 74 65 2d 61 68 65 61 64 20 6c 6f 67  [write-ahead log
9480: 5d 29 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  ]) for a particu
9490: 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  lar database.** 
94a0: 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65  connection.  See
94b0: 20 61 6c 73 6f 20 5b 53 51 4c 49 54 45 5f 46 43   also [SQLITE_FC
94c0: 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52  NTL_FILE_POINTER
94d0: 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  ]..**.** <li>[[S
94e0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
94f0: 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20 4e 6f  _OMITTED]].** No
9500: 20 6c 6f 6e 67 65 72 20 69 6e 20 75 73 65 2e 0a   longer in use..
9510: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9520: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 5d 0a  TE_FCNTL_SYNC]].
9530: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
9540: 43 4e 54 4c 5f 53 59 4e 43 5d 20 6f 70 63 6f 64  CNTL_SYNC] opcod
9550: 65 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 69  e is generated i
9560: 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c  nternally by SQL
9570: 69 74 65 20 61 6e 64 0a 2a 2a 20 73 65 6e 74 20  ite and.** sent 
9580: 74 6f 20 74 68 65 20 56 46 53 20 69 6d 6d 65 64  to the VFS immed
9590: 69 61 74 65 6c 79 20 62 65 66 6f 72 65 20 74 68  iately before th
95a0: 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 69  e xSync method i
95b0: 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 0a 2a  s invoked on a.*
95c0: 2a 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  * database file 
95d0: 64 65 73 63 72 69 70 74 6f 72 2e 20 4f 72 2c 20  descriptor. Or, 
95e0: 69 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74  if the xSync met
95f0: 68 6f 64 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b  hod is not invok
9600: 65 64 20 0a 2a 2a 20 62 65 63 61 75 73 65 20 74  ed .** because t
9610: 68 65 20 75 73 65 72 20 68 61 73 20 63 6f 6e 66  he user has conf
9620: 69 67 75 72 65 64 20 53 51 4c 69 74 65 20 77 69  igured SQLite wi
9630: 74 68 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 73  th .** [PRAGMA s
9640: 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41  ynchronous | PRA
9650: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d  GMA synchronous=
9660: 4f 46 46 5d 20 69 74 20 69 73 20 69 6e 76 6f 6b  OFF] it is invok
9670: 65 64 20 69 6e 20 70 6c 61 63 65 20 0a 2a 2a 20  ed in place .** 
9680: 6f 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74  of the xSync met
9690: 68 6f 64 2e 20 49 6e 20 6d 6f 73 74 20 63 61 73  hod. In most cas
96a0: 65 73 2c 20 74 68 65 20 70 6f 69 6e 74 65 72 20  es, the pointer 
96b0: 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20  argument passed 
96c0: 77 69 74 68 0a 2a 2a 20 74 68 69 73 20 66 69 6c  with.** this fil
96d0: 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 4e 55 4c  e-control is NUL
96e0: 4c 2e 20 48 6f 77 65 76 65 72 2c 20 69 66 20 74  L. However, if t
96f0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
9700: 20 69 73 20 62 65 69 6e 67 20 73 79 6e 63 65 64   is being synced
9710: 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 61  .** as part of a
9720: 20 6d 75 6c 74 69 2d 64 61 74 61 62 61 73 65 20   multi-database 
9730: 63 6f 6d 6d 69 74 2c 20 74 68 65 20 61 72 67 75  commit, the argu
9740: 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 20 61  ment points to a
9750: 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a   nul-terminated.
9760: 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69  ** string contai
9770: 6e 69 6e 67 20 74 68 65 20 74 72 61 6e 73 61 63  ning the transac
9780: 74 69 6f 6e 73 20 6d 61 73 74 65 72 2d 6a 6f 75  tions master-jou
9790: 72 6e 61 6c 20 66 69 6c 65 20 6e 61 6d 65 2e 20  rnal file name. 
97a0: 56 46 53 65 73 20 74 68 61 74 20 0a 2a 2a 20 64  VFSes that .** d
97b0: 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20  o not need this 
97c0: 73 69 67 6e 61 6c 20 73 68 6f 75 6c 64 20 73 69  signal should si
97d0: 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68  lently ignore th
97e0: 69 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69  is opcode. Appli
97f0: 63 61 74 69 6f 6e 73 20 0a 2a 2a 20 73 68 6f 75  cations .** shou
9800: 6c 64 20 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c  ld not call [sql
9810: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
9820: 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f  l()] with this o
9830: 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73  pcode as doing s
9840: 6f 20 6d 61 79 20 0a 2a 2a 20 64 69 73 72 75 70  o may .** disrup
9850: 74 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20  t the operation 
9860: 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a  of the specializ
9870: 65 64 20 56 46 53 65 73 20 74 68 61 74 20 64 6f  ed VFSes that do
9880: 20 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a   require it.  .*
9890: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
98a0: 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50  E_FCNTL_COMMIT_P
98b0: 48 41 53 45 54 57 4f 5d 5d 0a 2a 2a 20 54 68 65  HASETWO]].** The
98c0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43   [SQLITE_FCNTL_C
98d0: 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 20  OMMIT_PHASETWO] 
98e0: 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61  opcode is genera
98f0: 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62  ted internally b
9900: 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20  y SQLite.** and 
9910: 73 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20  sent to the VFS 
9920: 61 66 74 65 72 20 61 20 74 72 61 6e 73 61 63 74  after a transact
9930: 69 6f 6e 20 68 61 73 20 62 65 65 6e 20 63 6f 6d  ion has been com
9940: 6d 69 74 74 65 64 20 69 6d 6d 65 64 69 61 74 65  mitted immediate
9950: 6c 79 0a 2a 2a 20 62 75 74 20 62 65 66 6f 72 65  ly.** but before
9960: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
9970: 20 75 6e 6c 6f 63 6b 65 64 2e 20 56 46 53 65 73   unlocked. VFSes
9980: 20 74 68 61 74 20 64 6f 20 6e 6f 74 20 6e 65 65   that do not nee
9990: 64 20 74 68 69 73 20 73 69 67 6e 61 6c 0a 2a 2a  d this signal.**
99a0: 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79   should silently
99b0: 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63   ignore this opc
99c0: 6f 64 65 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e  ode. Application
99d0: 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c  s should not cal
99e0: 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  l.** [sqlite3_fi
99f0: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69  le_control()] wi
9a00: 74 68 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61  th this opcode a
9a10: 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64  s doing so may d
9a20: 69 73 72 75 70 74 20 74 68 65 20 0a 2a 2a 20 6f  isrupt the .** o
9a30: 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  peration of the 
9a40: 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65  specialized VFSe
9a50: 73 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72  s that do requir
9a60: 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c  e it.  .**.** <l
9a70: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
9a80: 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d  _WIN32_AV_RETRY]
9a90: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
9aa0: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56  E_FCNTL_WIN32_AV
9ab0: 5f 52 45 54 52 59 5d 20 6f 70 63 6f 64 65 20 69  _RETRY] opcode i
9ac0: 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67  s used to config
9ad0: 75 72 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a  ure automatic.**
9ae0: 20 72 65 74 72 79 20 63 6f 75 6e 74 73 20 61 6e   retry counts an
9af0: 64 20 69 6e 74 65 72 76 61 6c 73 20 66 6f 72 20  d intervals for 
9b00: 63 65 72 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f  certain disk I/O
9b10: 20 6f 70 65 72 61 74 69 6f 6e 73 20 66 6f 72 20   operations for 
9b20: 74 68 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b  the.** windows [
9b30: 56 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f  VFS] in order to
9b40: 20 70 72 6f 76 69 64 65 20 72 6f 62 75 73 74 6e   provide robustn
9b50: 65 73 73 20 69 6e 20 74 68 65 20 70 72 65 73 65  ess in the prese
9b60: 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76  nce of.** anti-v
9b70: 69 72 75 73 20 70 72 6f 67 72 61 6d 73 2e 20 20  irus programs.  
9b80: 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20  By default, the 
9b90: 77 69 6e 64 6f 77 73 20 56 46 53 20 77 69 6c 6c  windows VFS will
9ba0: 20 72 65 74 72 79 20 66 69 6c 65 20 72 65 61 64   retry file read
9bb0: 2c 0a 2a 2a 20 66 69 6c 65 20 77 72 69 74 65 2c  ,.** file write,
9bc0: 20 61 6e 64 20 66 69 6c 65 20 64 65 6c 65 74 65   and file delete
9bd0: 20 6f 70 65 72 61 74 69 6f 6e 73 20 75 70 20 74   operations up t
9be0: 6f 20 31 30 20 74 69 6d 65 73 2c 20 77 69 74 68  o 10 times, with
9bf0: 20 61 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32   a delay.** of 2
9c00: 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62  5 milliseconds b
9c10: 65 66 6f 72 65 20 74 68 65 20 66 69 72 73 74 20  efore the first 
9c20: 72 65 74 72 79 20 61 6e 64 20 77 69 74 68 20 74  retry and with t
9c30: 68 65 20 64 65 6c 61 79 20 69 6e 63 72 65 61 73  he delay increas
9c40: 69 6e 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64  ing.** by an add
9c50: 69 74 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69  itional 25 milli
9c60: 73 65 63 6f 6e 64 73 20 77 69 74 68 20 65 61 63  seconds with eac
9c70: 68 20 73 75 62 73 65 71 75 65 6e 74 20 72 65 74  h subsequent ret
9c80: 72 79 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63  ry.  This.** opc
9c90: 6f 64 65 20 61 6c 6c 6f 77 73 20 74 68 65 73 65  ode allows these
9ca0: 20 74 77 6f 20 76 61 6c 75 65 73 20 28 31 30 20   two values (10 
9cb0: 72 65 74 72 69 65 73 20 61 6e 64 20 32 35 20 6d  retries and 25 m
9cc0: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 64  illiseconds of d
9cd0: 65 6c 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61  elay).** to be a
9ce0: 64 6a 75 73 74 65 64 2e 20 20 54 68 65 20 76 61  djusted.  The va
9cf0: 6c 75 65 73 20 61 72 65 20 63 68 61 6e 67 65 64  lues are changed
9d00: 20 66 6f 72 20 61 6c 6c 20 64 61 74 61 62 61 73   for all databas
9d10: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a  e connections.**
9d20: 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65   within the same
9d30: 20 70 72 6f 63 65 73 73 2e 20 20 54 68 65 20 61   process.  The a
9d40: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
9d50: 6e 74 65 72 20 74 6f 20 61 6e 20 61 72 72 61 79  nter to an array
9d60: 20 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67   of two.** integ
9d70: 65 72 73 20 77 68 65 72 65 20 74 68 65 20 66 69  ers where the fi
9d80: 72 73 74 20 69 6e 74 65 67 65 72 20 69 20 74 68  rst integer i th
9d90: 65 20 6e 65 77 20 72 65 74 72 79 20 63 6f 75 6e  e new retry coun
9da0: 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  t and the second
9db0: 0a 2a 2a 20 69 6e 74 65 67 65 72 20 69 73 20 74  .** integer is t
9dc0: 68 65 20 64 65 6c 61 79 2e 20 20 49 66 20 65 69  he delay.  If ei
9dd0: 74 68 65 72 20 69 6e 74 65 67 65 72 20 69 73 20  ther integer is 
9de0: 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74  negative, then t
9df0: 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73  he setting.** is
9e00: 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 62 75 74   not changed but
9e10: 20 69 6e 73 74 65 61 64 20 74 68 65 20 70 72 69   instead the pri
9e20: 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74  or value of that
9e30: 20 73 65 74 74 69 6e 67 20 69 73 20 77 72 69 74   setting is writ
9e40: 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20  ten.** into the 
9e50: 61 72 72 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c  array entry, all
9e60: 6f 77 69 6e 67 20 74 68 65 20 63 75 72 72 65 6e  owing the curren
9e70: 74 20 72 65 74 72 79 20 73 65 74 74 69 6e 67 73  t retry settings
9e80: 20 74 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72   to be.** interr
9e90: 6f 67 61 74 65 64 2e 20 20 54 68 65 20 7a 44 62  ogated.  The zDb
9ea0: 4e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69  Name parameter i
9eb0: 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a  s ignored..**.**
9ec0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
9ed0: 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d  NTL_PERSIST_WAL]
9ee0: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
9ef0: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
9f00: 57 41 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  WAL] opcode is u
9f10: 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75  sed to set or qu
9f20: 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69  ery the.** persi
9f30: 73 74 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69  stent [WAL | Wri
9f40: 74 65 20 41 68 65 61 64 20 4c 6f 67 5d 20 73 65  te Ahead Log] se
9f50: 74 74 69 6e 67 2e 20 20 42 79 20 64 65 66 61 75  tting.  By defau
9f60: 6c 74 2c 20 74 68 65 20 61 75 78 69 6c 69 61 72  lt, the auxiliar
9f70: 79 0a 2a 2a 20 77 72 69 74 65 20 61 68 65 61 64  y.** write ahead
9f80: 20 6c 6f 67 20 61 6e 64 20 73 68 61 72 65 64 20   log and shared 
9f90: 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 75 73 65  memory files use
9fa0: 64 20 66 6f 72 20 74 72 61 6e 73 61 63 74 69 6f  d for transactio
9fb0: 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65  n control.** are
9fc0: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64   automatically d
9fd0: 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65 20  eleted when the 
9fe0: 6c 61 74 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f  latest connectio
9ff0: 6e 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  n to the databas
a000: 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65  e.** closes.  Se
a010: 74 74 69 6e 67 20 70 65 72 73 69 73 74 65 6e 74  tting persistent
a020: 20 57 41 4c 20 6d 6f 64 65 20 63 61 75 73 65 73   WAL mode causes
a030: 20 74 68 6f 73 65 20 66 69 6c 65 73 20 74 6f 20   those files to 
a040: 70 65 72 73 69 73 74 20 61 66 74 65 72 0a 2a 2a  persist after.**
a050: 20 63 6c 6f 73 65 2e 20 20 50 65 72 73 69 73 74   close.  Persist
a060: 69 6e 67 20 74 68 65 20 66 69 6c 65 73 20 69 73  ing the files is
a070: 20 75 73 65 66 75 6c 20 77 68 65 6e 20 6f 74 68   useful when oth
a080: 65 72 20 70 72 6f 63 65 73 73 65 73 20 74 68 61  er processes tha
a090: 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65  t do not.** have
a0a0: 20 77 72 69 74 65 20 70 65 72 6d 69 73 73 69 6f   write permissio
a0b0: 6e 20 6f 6e 20 74 68 65 20 64 69 72 65 63 74 6f  n on the directo
a0c0: 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  ry containing th
a0d0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
a0e0: 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20  want.** to read 
a0f0: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
a100: 65 2c 20 61 73 20 74 68 65 20 57 41 4c 20 61 6e  e, as the WAL an
a110: 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20  d shared memory 
a120: 66 69 6c 65 73 20 6d 75 73 74 20 65 78 69 73 74  files must exist
a130: 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f 72  .** in order for
a140: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74 6f   the database to
a150: 20 62 65 20 72 65 61 64 61 62 6c 65 2e 20 20 54   be readable.  T
a160: 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
a170: 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ter to.** [sqlit
a180: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
a190: 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f  )] for this opco
a1a0: 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70  de should be a p
a1b0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
a1c0: 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e  eger..** That in
a1d0: 74 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69  teger is 0 to di
a1e0: 73 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74  sable persistent
a1f0: 20 57 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74   WAL mode or 1 t
a200: 6f 20 65 6e 61 62 6c 65 20 70 65 72 73 69 73 74  o enable persist
a210: 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e  ent.** WAL mode.
a220: 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72    If the integer
a230: 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20   is -1, then it 
a240: 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77  is overwritten w
a250: 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a  ith the current.
a260: 2a 2a 20 57 41 4c 20 70 65 72 73 69 73 74 65 6e  ** WAL persisten
a270: 63 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a  ce setting..**.*
a280: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
a290: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f  CNTL_POWERSAFE_O
a2a0: 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54  VERWRITE]].** ^T
a2b0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
a2c0: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
a2d0: 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20  RITE] opcode is 
a2e0: 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71  used to set or q
a2f0: 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73  uery the.** pers
a300: 69 73 74 65 6e 74 20 22 70 6f 77 65 72 73 61 66  istent "powersaf
a310: 65 2d 6f 76 65 72 77 72 69 74 65 22 20 6f 72 20  e-overwrite" or 
a320: 22 50 53 4f 57 22 20 73 65 74 74 69 6e 67 2e 20  "PSOW" setting. 
a330: 20 54 68 65 20 50 53 4f 57 20 73 65 74 74 69 6e   The PSOW settin
a340: 67 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73 20  g.** determines 
a350: 74 68 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  the [SQLITE_IOCA
a360: 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  P_POWERSAFE_OVER
a370: 57 52 49 54 45 5d 20 62 69 74 20 6f 66 20 74 68  WRITE] bit of th
a380: 65 0a 2a 2a 20 78 44 65 76 69 63 65 43 68 61 72  e.** xDeviceChar
a390: 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68  acteristics meth
a3a0: 6f 64 73 2e 20 54 68 65 20 66 6f 75 72 74 68 20  ods. The fourth 
a3b0: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
a3c0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
a3d0: 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69  ntrol()] for thi
a3e0: 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20  s opcode should 
a3f0: 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  be a pointer to 
a400: 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54  an integer..** T
a410: 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30  hat integer is 0
a420: 20 74 6f 20 64 69 73 61 62 6c 65 20 7a 65 72 6f   to disable zero
a430: 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20  -damage mode or 
a440: 31 20 74 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f  1 to enable zero
a450: 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e  -damage.** mode.
a460: 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72    If the integer
a470: 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20   is -1, then it 
a480: 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77  is overwritten w
a490: 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a  ith the current.
a4a0: 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d  ** zero-damage m
a4b0: 6f 64 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a  ode setting..**.
a4c0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
a4d0: 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d  FCNTL_OVERWRITE]
a4e0: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
a4f0: 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54  E_FCNTL_OVERWRIT
a500: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6e 76  E] opcode is inv
a510: 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 61  oked by SQLite a
a520: 66 74 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20  fter opening.** 
a530: 61 20 77 72 69 74 65 20 74 72 61 6e 73 61 63 74  a write transact
a540: 69 6f 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20  ion to indicate 
a550: 74 68 61 74 2c 20 75 6e 6c 65 73 73 20 69 74 20  that, unless it 
a560: 69 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66  is rolled back f
a570: 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f  or some.** reaso
a580: 6e 2c 20 74 68 65 20 65 6e 74 69 72 65 20 64 61  n, the entire da
a590: 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c  tabase file will
a5a0: 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20   be overwritten 
a5b0: 62 79 20 74 68 65 20 63 75 72 72 65 6e 74 20 0a  by the current .
a5c0: 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20  ** transaction. 
a5d0: 54 68 69 73 20 69 73 20 75 73 65 64 20 62 79 20  This is used by 
a5e0: 56 41 43 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e  VACUUM operation
a5f0: 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  s..**.** <li>[[S
a600: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e  QLITE_FCNTL_VFSN
a610: 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  AME]].** ^The [S
a620: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e  QLITE_FCNTL_VFSN
a630: 41 4d 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20  AME] opcode can 
a640: 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  be used to obtai
a650: 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a  n the names of.*
a660: 2a 20 61 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e  * all [VFSes] in
a670: 20 74 68 65 20 56 46 53 20 73 74 61 63 6b 2e 20   the VFS stack. 
a680: 20 54 68 65 20 6e 61 6d 65 73 20 61 72 65 20 6f   The names are o
a690: 66 20 61 6c 6c 20 56 46 53 20 73 68 69 6d 73 20  f all VFS shims 
a6a0: 61 6e 64 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c  and the.** final
a6b0: 20 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46   bottom-level VF
a6c0: 53 20 61 72 65 20 77 72 69 74 74 65 6e 20 69 6e  S are written in
a6d0: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
a6e0: 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c  ed from .** [sql
a6f0: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61  ite3_malloc()] a
a700: 6e 64 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  nd the result is
a710: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20 63   stored in the c
a720: 68 61 72 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a  har* variable.**
a730: 20 74 68 61 74 20 74 68 65 20 66 6f 75 72 74 68   that the fourth
a740: 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 5b 73   parameter of [s
a750: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
a760: 72 6f 6c 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f  rol()] points to
a770: 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 65 72 20  ..** The caller 
a780: 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
a790: 6f 72 20 66 72 65 65 69 6e 67 20 74 68 65 20 6d  or freeing the m
a7a0: 65 6d 6f 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e  emory when done.
a7b0: 20 20 41 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c    As with.** all
a7c0: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63   file-control ac
a7d0: 74 69 6f 6e 73 2c 20 74 68 65 72 65 20 69 73 20  tions, there is 
a7e0: 6e 6f 20 67 75 61 72 61 6e 74 65 65 20 74 68 61  no guarantee tha
a7f0: 74 20 74 68 69 73 20 77 69 6c 6c 20 61 63 74 75  t this will actu
a800: 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68  ally.** do anyth
a810: 69 6e 67 2e 20 20 43 61 6c 6c 65 72 73 20 73 68  ing.  Callers sh
a820: 6f 75 6c 64 20 69 6e 69 74 69 61 6c 69 7a 65 20  ould initialize 
a830: 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62  the char* variab
a840: 6c 65 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20  le to a NULL.** 
a850: 70 6f 69 6e 74 65 72 20 69 6e 20 63 61 73 65 20  pointer in case 
a860: 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  this file-contro
a870: 6c 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65  l is not impleme
a880: 6e 74 65 64 2e 20 20 54 68 69 73 20 66 69 6c 65  nted.  This file
a890: 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69  -control.** is i
a8a0: 6e 74 65 6e 64 65 64 20 66 6f 72 20 64 69 61 67  ntended for diag
a8b0: 6e 6f 73 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e  nostic use only.
a8c0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
a8d0: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f  ITE_FCNTL_VFS_PO
a8e0: 49 4e 54 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20  INTER]].** ^The 
a8f0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46  [SQLITE_FCNTL_VF
a900: 53 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64  S_POINTER] opcod
a910: 65 20 66 69 6e 64 73 20 61 20 70 6f 69 6e 74 65  e finds a pointe
a920: 72 20 74 6f 20 74 68 65 20 74 6f 70 2d 6c 65 76  r to the top-lev
a930: 65 6c 0a 2a 2a 20 5b 56 46 53 65 73 5d 20 63 75  el.** [VFSes] cu
a940: 72 72 65 6e 74 6c 79 20 69 6e 20 75 73 65 2e 20  rrently in use. 
a950: 20 5e 28 54 68 65 20 61 72 67 75 6d 65 6e 74 20   ^(The argument 
a960: 58 20 69 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  X in.** sqlite3_
a970: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 64 62 2c  file_control(db,
a980: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53  SQLITE_FCNTL_VFS
a990: 5f 50 4f 49 4e 54 45 52 2c 58 29 20 6d 75 73 74  _POINTER,X) must
a9a0: 20 62 65 0a 2a 2a 20 6f 66 20 74 79 70 65 20 22   be.** of type "
a9b0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 2a 2a  [sqlite3_vfs] **
a9c0: 22 2e 20 20 54 68 69 73 20 6f 70 63 6f 64 65 73  ".  This opcodes
a9d0: 20 77 69 6c 6c 20 73 65 74 20 2a 58 0a 2a 2a 20   will set *X.** 
a9e0: 74 6f 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  to a pointer to 
a9f0: 74 68 65 20 74 6f 70 2d 6c 65 76 65 6c 20 56 46  the top-level VF
aa00: 53 2e 29 5e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68  S.)^.** ^When th
aa10: 65 72 65 20 61 72 65 20 6d 75 6c 74 69 70 6c 65  ere are multiple
aa20: 20 56 46 53 20 73 68 69 6d 73 20 69 6e 20 74 68   VFS shims in th
aa30: 65 20 73 74 61 63 6b 2c 20 74 68 69 73 20 6f 70  e stack, this op
aa40: 63 6f 64 65 20 66 69 6e 64 73 20 74 68 65 0a 2a  code finds the.*
aa50: 2a 20 75 70 70 65 72 2d 6d 6f 73 74 20 73 68 69  * upper-most shi
aa60: 6d 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  m only..**.** <l
aa70: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
aa80: 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68  _PRAGMA]].** ^Wh
aa90: 65 6e 65 76 65 72 20 61 20 5b 50 52 41 47 4d 41  enever a [PRAGMA
aaa0: 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 70  ] statement is p
aab0: 61 72 73 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54  arsed, an [SQLIT
aac0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
aad0: 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  .** file control
aae0: 20 69 73 20 73 65 6e 74 20 74 6f 20 74 68 65 20   is sent to the 
aaf0: 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  open [sqlite3_fi
ab00: 6c 65 5d 20 6f 62 6a 65 63 74 20 63 6f 72 72 65  le] object corre
ab10: 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74  sponding.** to t
ab20: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
ab30: 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 70 72   to which the pr
ab40: 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 72  agma statement r
ab50: 65 66 65 72 73 2e 20 5e 54 68 65 20 61 72 67 75  efers. ^The argu
ab60: 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  ment.** to the [
ab70: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
ab80: 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  GMA] file contro
ab90: 6c 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  l is an array of
aba0: 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  .** pointers to 
abb0: 73 74 72 69 6e 67 73 20 28 63 68 61 72 2a 2a 29  strings (char**)
abc0: 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 73 65   in which the se
abd0: 63 6f 6e 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20  cond element of 
abe0: 74 68 65 20 61 72 72 61 79 0a 2a 2a 20 69 73 20  the array.** is 
abf0: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
ac00: 70 72 61 67 6d 61 20 61 6e 64 20 74 68 65 20 74  pragma and the t
ac10: 68 69 72 64 20 65 6c 65 6d 65 6e 74 20 69 73 20  hird element is 
ac20: 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  the argument to 
ac30: 74 68 65 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72  the.** pragma or
ac40: 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 70 72 61   NULL if the pra
ac50: 67 6d 61 20 68 61 73 20 6e 6f 20 61 72 67 75 6d  gma has no argum
ac60: 65 6e 74 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c  ent.  ^The handl
ac70: 65 72 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51  er for an.** [SQ
ac80: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
ac90: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A] file control 
aca0: 63 61 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d  can optionally m
acb0: 61 6b 65 20 74 68 65 20 66 69 72 73 74 20 65 6c  ake the first el
acc0: 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20  ement.** of the 
acd0: 63 68 61 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20  char** argument 
ace0: 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e  point to a strin
acf0: 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  g obtained from 
ad00: 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  [sqlite3_mprintf
ad10: 28 29 5d 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71  ()].** or the eq
ad20: 75 69 76 61 6c 65 6e 74 20 61 6e 64 20 74 68 61  uivalent and tha
ad30: 74 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65  t string will be
ad40: 63 6f 6d 65 20 74 68 65 20 72 65 73 75 6c 74 20  come the result 
ad50: 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 6f 72  of the pragma or
ad60: 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 6d 65  .** the error me
ad70: 73 73 61 67 65 20 69 66 20 74 68 65 20 70 72 61  ssage if the pra
ad80: 67 6d 61 20 66 61 69 6c 73 2e 20 5e 49 66 20 74  gma fails. ^If t
ad90: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43  he.** [SQLITE_FC
ada0: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65  NTL_PRAGMA] file
adb0: 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73   control returns
adc0: 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e   [SQLITE_NOTFOUN
add0: 44 5d 2c 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20  D], then normal 
ade0: 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f  .** [PRAGMA] pro
adf0: 63 65 73 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65  cessing continue
ae00: 73 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c  s.  ^If the [SQL
ae10: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
ae20: 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f  ].** file contro
ae30: 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  l returns [SQLIT
ae40: 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20  E_OK], then the 
ae50: 70 61 72 73 65 72 20 61 73 73 75 6d 65 73 20 74  parser assumes t
ae60: 68 61 74 20 74 68 65 0a 2a 2a 20 56 46 53 20 68  hat the.** VFS h
ae70: 61 73 20 68 61 6e 64 6c 65 64 20 74 68 65 20 50  as handled the P
ae80: 52 41 47 4d 41 20 69 74 73 65 6c 66 20 61 6e 64  RAGMA itself and
ae90: 20 74 68 65 20 70 61 72 73 65 72 20 67 65 6e 65   the parser gene
aea0: 72 61 74 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a  rates a no-op.**
aeb0: 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
aec0: 65 6e 74 20 69 66 20 72 65 73 75 6c 74 20 73 74  ent if result st
aed0: 72 69 6e 67 20 69 73 20 4e 55 4c 4c 2c 20 6f 72  ring is NULL, or
aee0: 20 74 68 61 74 20 72 65 74 75 72 6e 73 20 61 20   that returns a 
aef0: 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 72  copy.** of the r
af00: 65 73 75 6c 74 20 73 74 72 69 6e 67 20 69 66 20  esult string if 
af10: 74 68 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f  the string is no
af20: 6e 2d 4e 55 4c 4c 2e 0a 2a 2a 20 5e 49 66 20 74  n-NULL..** ^If t
af30: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
af40: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
af50: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 0a 2a 2a  ntrol returns.**
af60: 20 61 6e 79 20 72 65 73 75 6c 74 20 63 6f 64 65   any result code
af70: 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
af80: 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49  ITE_OK] or [SQLI
af90: 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68  TE_NOTFOUND], th
afa0: 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  at means.** that
afb0: 20 74 68 65 20 56 46 53 20 65 6e 63 6f 75 6e 74   the VFS encount
afc0: 65 72 65 64 20 61 6e 20 65 72 72 6f 72 20 77 68  ered an error wh
afd0: 69 6c 65 20 68 61 6e 64 6c 69 6e 67 20 74 68 65  ile handling the
afe0: 20 5b 50 52 41 47 4d 41 5d 20 61 6e 64 20 74 68   [PRAGMA] and th
aff0: 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74 69 6f 6e  e.** compilation
b000: 20 6f 66 20 74 68 65 20 50 52 41 47 4d 41 20 66   of the PRAGMA f
b010: 61 69 6c 73 20 77 69 74 68 20 61 6e 20 65 72 72  ails with an err
b020: 6f 72 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54  or.  ^The [SQLIT
b030: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a  E_FCNTL_PRAGMA].
b040: 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  ** file control 
b050: 6f 63 63 75 72 73 20 61 74 20 74 68 65 20 62 65  occurs at the be
b060: 67 69 6e 6e 69 6e 67 20 6f 66 20 70 72 61 67 6d  ginning of pragm
b070: 61 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 61 6c  a statement anal
b080: 79 73 69 73 20 61 6e 64 20 73 6f 0a 2a 2a 20 69  ysis and so.** i
b090: 74 20 69 73 20 61 62 6c 65 20 74 6f 20 6f 76 65  t is able to ove
b0a0: 72 72 69 64 65 20 62 75 69 6c 74 2d 69 6e 20 5b  rride built-in [
b0b0: 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e  PRAGMA] statemen
b0c0: 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ts..**.** <li>[[
b0d0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53  SQLITE_FCNTL_BUS
b0e0: 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54  YHANDLER]].** ^T
b0f0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
b100: 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 0a 2a 2a  _BUSYHANDLER].**
b110: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61   file-control ma
b120: 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 62 79 20  y be invoked by 
b130: 53 51 4c 69 74 65 20 6f 6e 20 74 68 65 20 64 61  SQLite on the da
b140: 74 61 62 61 73 65 20 66 69 6c 65 20 68 61 6e 64  tabase file hand
b150: 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c 79 20 61 66  le.** shortly af
b160: 74 65 72 20 69 74 20 69 73 20 6f 70 65 6e 65 64  ter it is opened
b170: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f   in order to pro
b180: 76 69 64 65 20 61 20 63 75 73 74 6f 6d 20 56 46  vide a custom VF
b190: 53 20 77 69 74 68 20 61 63 63 65 73 73 0a 2a 2a  S with access.**
b1a0: 20 74 6f 20 74 68 65 20 63 6f 6e 6e 65 63 74 69   to the connecti
b1b0: 6f 6e 73 20 62 75 73 79 2d 68 61 6e 64 6c 65 72  ons busy-handler
b1c0: 20 63 61 6c 6c 62 61 63 6b 2e 20 54 68 65 20 61   callback. The a
b1d0: 72 67 75 6d 65 6e 74 20 69 73 20 6f 66 20 74 79  rgument is of ty
b1e0: 70 65 20 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20  pe (void **).** 
b1f0: 2d 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77  - an array of tw
b200: 6f 20 28 76 6f 69 64 20 2a 29 20 76 61 6c 75 65  o (void *) value
b210: 73 2e 20 54 68 65 20 66 69 72 73 74 20 28 76 6f  s. The first (vo
b220: 69 64 20 2a 29 20 61 63 74 75 61 6c 6c 79 20 70  id *) actually p
b230: 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 61 20 66 75  oints.** to a fu
b240: 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 28  nction of type (
b250: 69 6e 74 20 28 2a 29 28 76 6f 69 64 20 2a 29 29  int (*)(void *))
b260: 2e 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e  . In order to in
b270: 76 6f 6b 65 20 74 68 65 20 63 6f 6e 6e 65 63 74  voke the connect
b280: 69 6f 6e 73 0a 2a 2a 20 62 75 73 79 2d 68 61 6e  ions.** busy-han
b290: 64 6c 65 72 2c 20 74 68 69 73 20 66 75 6e 63 74  dler, this funct
b2a0: 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 69 6e  ion should be in
b2b0: 76 6f 6b 65 64 20 77 69 74 68 20 74 68 65 20 73  voked with the s
b2c0: 65 63 6f 6e 64 20 28 76 6f 69 64 20 2a 29 20 69  econd (void *) i
b2d0: 6e 0a 2a 2a 20 74 68 65 20 61 72 72 61 79 20 61  n.** the array a
b2e0: 73 20 74 68 65 20 6f 6e 6c 79 20 61 72 67 75 6d  s the only argum
b2f0: 65 6e 74 2e 20 49 66 20 69 74 20 72 65 74 75 72  ent. If it retur
b300: 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
b310: 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a  n the operation.
b320: 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74  ** should be ret
b330: 72 69 65 64 2e 20 49 66 20 69 74 20 72 65 74 75  ried. If it retu
b340: 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20 63 75  rns zero, the cu
b350: 73 74 6f 6d 20 56 46 53 20 73 68 6f 75 6c 64 20  stom VFS should 
b360: 61 62 61 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20 63  abandon the.** c
b370: 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e  urrent operation
b380: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
b390: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46  LITE_FCNTL_TEMPF
b3a0: 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70  ILENAME]].** ^Ap
b3b0: 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 69 6e  plication can in
b3c0: 76 6f 6b 65 20 74 68 65 20 5b 53 51 4c 49 54 45  voke the [SQLITE
b3d0: 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e  _FCNTL_TEMPFILEN
b3e0: 41 4d 45 5d 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  AME] file-contro
b3f0: 6c 0a 2a 2a 20 74 6f 20 68 61 76 65 20 53 51 4c  l.** to have SQL
b400: 69 74 65 20 67 65 6e 65 72 61 74 65 20 61 0a 2a  ite generate a.*
b410: 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  * temporary file
b420: 6e 61 6d 65 20 75 73 69 6e 67 20 74 68 65 20 73  name using the s
b430: 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 74 68  ame algorithm th
b440: 61 74 20 69 73 20 66 6f 6c 6c 6f 77 65 64 20 74  at is followed t
b450: 6f 20 67 65 6e 65 72 61 74 65 0a 2a 2a 20 74 65  o generate.** te
b460: 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65  mporary filename
b470: 73 20 66 6f 72 20 54 45 4d 50 20 74 61 62 6c 65  s for TEMP table
b480: 73 20 61 6e 64 20 6f 74 68 65 72 20 69 6e 74 65  s and other inte
b490: 72 6e 61 6c 20 75 73 65 73 2e 20 20 54 68 65 0a  rnal uses.  The.
b4a0: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  ** argument shou
b4b0: 6c 64 20 62 65 20 61 20 63 68 61 72 2a 2a 20 77  ld be a char** w
b4c0: 68 69 63 68 20 77 69 6c 6c 20 62 65 20 66 69 6c  hich will be fil
b4d0: 6c 65 64 20 77 69 74 68 20 74 68 65 20 66 69 6c  led with the fil
b4e0: 65 6e 61 6d 65 0a 2a 2a 20 77 72 69 74 74 65 6e  ename.** written
b4f0: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
b500: 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
b510: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20  te3_malloc()].  
b520: 54 68 65 20 63 61 6c 6c 65 72 20 73 68 6f 75 6c  The caller shoul
b530: 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20 5b 73 71 6c  d.** invoke [sql
b540: 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20  ite3_free()] on 
b550: 74 68 65 20 72 65 73 75 6c 74 20 74 6f 20 61 76  the result to av
b560: 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61  oid a memory lea
b570: 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  k..**.** <li>[[S
b580: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50  QLITE_FCNTL_MMAP
b590: 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  _SIZE]].** The [
b5a0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41  SQLITE_FCNTL_MMA
b5b0: 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e  P_SIZE] file con
b5c0: 74 72 6f 6c 20 69 73 20 75 73 65 64 20 74 6f 20  trol is used to 
b5d0: 71 75 65 72 79 20 6f 72 20 73 65 74 20 74 68 65  query or set the
b5e0: 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  .** maximum numb
b5f0: 65 72 20 6f 66 20 62 79 74 65 73 20 74 68 61 74  er of bytes that
b600: 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 66 6f   will be used fo
b610: 72 20 6d 65 6d 6f 72 79 2d 6d 61 70 70 65 64 20  r memory-mapped 
b620: 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75  I/O..** The argu
b630: 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
b640: 72 20 74 6f 20 61 20 76 61 6c 75 65 20 6f 66 20  r to a value of 
b650: 74 79 70 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  type sqlite3_int
b660: 36 34 20 74 68 61 74 0a 2a 2a 20 69 73 20 61 6e  64 that.** is an
b670: 20 61 64 76 69 73 6f 72 79 20 6d 61 78 69 6d 75   advisory maximu
b680: 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  m number of byte
b690: 73 20 69 6e 20 74 68 65 20 66 69 6c 65 20 74 6f  s in the file to
b6a0: 20 6d 65 6d 6f 72 79 20 6d 61 70 2e 20 20 54 68   memory map.  Th
b6b0: 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 73 20  e.** pointer is 
b6c0: 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68  overwritten with
b6d0: 20 74 68 65 20 6f 6c 64 20 76 61 6c 75 65 2e 20   the old value. 
b6e0: 20 54 68 65 20 6c 69 6d 69 74 20 69 73 20 6e 6f   The limit is no
b6f0: 74 20 63 68 61 6e 67 65 64 20 69 66 0a 2a 2a 20  t changed if.** 
b700: 74 68 65 20 76 61 6c 75 65 20 6f 72 69 67 69 6e  the value origin
b710: 61 6c 6c 79 20 70 6f 69 6e 74 65 64 20 74 6f 20  ally pointed to 
b720: 69 73 20 6e 65 67 61 74 69 76 65 2c 20 61 6e 64  is negative, and
b730: 20 73 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20   so the current 
b740: 6c 69 6d 69 74 20 0a 2a 2a 20 63 61 6e 20 62 65  limit .** can be
b750: 20 71 75 65 72 69 65 64 20 62 79 20 70 61 73 73   queried by pass
b760: 69 6e 67 20 69 6e 20 61 20 70 6f 69 6e 74 65 72  ing in a pointer
b770: 20 74 6f 20 61 20 6e 65 67 61 74 69 76 65 20 6e   to a negative n
b780: 75 6d 62 65 72 2e 20 20 54 68 69 73 0a 2a 2a 20  umber.  This.** 
b790: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20  file-control is 
b7a0: 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  used internally 
b7b0: 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 50 52  to implement [PR
b7c0: 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 2e  AGMA mmap_size].
b7d0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
b7e0: 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d  ITE_FCNTL_TRACE]
b7f0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
b800: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 66 69  _FCNTL_TRACE] fi
b810: 6c 65 20 63 6f 6e 74 72 6f 6c 20 70 72 6f 76 69  le control provi
b820: 64 65 73 20 61 64 76 69 73 6f 72 79 20 69 6e 66  des advisory inf
b830: 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74  ormation.** to t
b840: 68 65 20 56 46 53 20 61 62 6f 75 74 20 77 68 61  he VFS about wha
b850: 74 20 74 68 65 20 68 69 67 68 65 72 20 6c 61 79  t the higher lay
b860: 65 72 73 20 6f 66 20 74 68 65 20 53 51 4c 69 74  ers of the SQLit
b870: 65 20 73 74 61 63 6b 20 61 72 65 20 64 6f 69 6e  e stack are doin
b880: 67 2e 0a 2a 2a 20 54 68 69 73 20 66 69 6c 65 20  g..** This file 
b890: 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20  control is used 
b8a0: 62 79 20 73 6f 6d 65 20 56 46 53 20 61 63 74 69  by some VFS acti
b8b0: 76 69 74 79 20 74 72 61 63 69 6e 67 20 5b 73 68  vity tracing [sh
b8c0: 69 6d 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 72 67  ims]..** The arg
b8d0: 75 6d 65 6e 74 20 69 73 20 61 20 7a 65 72 6f 2d  ument is a zero-
b8e0: 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
b8f0: 67 2e 20 20 48 69 67 68 65 72 20 6c 61 79 65 72  g.  Higher layer
b900: 73 20 69 6e 20 74 68 65 0a 2a 2a 20 53 51 4c 69  s in the.** SQLi
b910: 74 65 20 73 74 61 63 6b 20 6d 61 79 20 67 65 6e  te stack may gen
b920: 65 72 61 74 65 20 69 6e 73 74 61 6e 63 65 73 20  erate instances 
b930: 6f 66 20 74 68 69 73 20 66 69 6c 65 20 63 6f 6e  of this file con
b940: 74 72 6f 6c 20 69 66 0a 2a 2a 20 74 68 65 20 5b  trol if.** the [
b950: 53 51 4c 49 54 45 5f 55 53 45 5f 46 43 4e 54 4c  SQLITE_USE_FCNTL
b960: 5f 54 52 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d  _TRACE] compile-
b970: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65  time option is e
b980: 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  nabled..**.** <l
b990: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
b9a0: 5f 48 41 53 5f 4d 4f 56 45 44 5d 5d 0a 2a 2a 20  _HAS_MOVED]].** 
b9b0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
b9c0: 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 20 66 69 6c  L_HAS_MOVED] fil
b9d0: 65 20 63 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70  e control interp
b9e0: 72 65 74 73 20 69 74 73 20 61 72 67 75 6d 65 6e  rets its argumen
b9f0: 74 20 61 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65  t as a.** pointe
ba00: 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  r to an integer 
ba10: 61 6e 64 20 69 74 20 77 72 69 74 65 73 20 61 20  and it writes a 
ba20: 62 6f 6f 6c 65 61 6e 20 69 6e 74 6f 20 74 68 61  boolean into tha
ba30: 74 20 69 6e 74 65 67 65 72 20 64 65 70 65 6e 64  t integer depend
ba40: 69 6e 67 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65  ing.** on whethe
ba50: 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 66 69 6c  r or not the fil
ba60: 65 20 68 61 73 20 62 65 65 6e 20 72 65 6e 61 6d  e has been renam
ba70: 65 64 2c 20 6d 6f 76 65 64 2c 20 6f 72 20 64 65  ed, moved, or de
ba80: 6c 65 74 65 64 20 73 69 6e 63 65 20 69 74 0a 2a  leted since it.*
ba90: 2a 20 77 61 73 20 66 69 72 73 74 20 6f 70 65 6e  * was first open
baa0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ed..**.** <li>[[
bab0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
bac0: 33 32 5f 47 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a  32_GET_HANDLE]].
bad0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
bae0: 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48  CNTL_WIN32_GET_H
baf0: 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 65 20 63 61  ANDLE] opcode ca
bb00: 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74  n be used to obt
bb10: 61 69 6e 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72  ain the.** under
bb20: 6c 79 69 6e 67 20 6e 61 74 69 76 65 20 66 69 6c  lying native fil
bb30: 65 20 68 61 6e 64 6c 65 20 61 73 73 6f 63 69 61  e handle associa
bb40: 74 65 64 20 77 69 74 68 20 61 20 66 69 6c 65 20  ted with a file 
bb50: 68 61 6e 64 6c 65 2e 20 20 54 68 69 73 20 66 69  handle.  This fi
bb60: 6c 65 0a 2a 2a 20 63 6f 6e 74 72 6f 6c 20 69 6e  le.** control in
bb70: 74 65 72 70 72 65 74 73 20 69 74 73 20 61 72 67  terprets its arg
bb80: 75 6d 65 6e 74 20 61 73 20 61 20 70 6f 69 6e 74  ument as a point
bb90: 65 72 20 74 6f 20 61 20 6e 61 74 69 76 65 20 66  er to a native f
bba0: 69 6c 65 20 68 61 6e 64 6c 65 20 61 6e 64 0a 2a  ile handle and.*
bbb0: 2a 20 77 72 69 74 65 73 20 74 68 65 20 72 65 73  * writes the res
bbc0: 75 6c 74 69 6e 67 20 76 61 6c 75 65 20 74 68 65  ulting value the
bbd0: 72 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  re..**.** <li>[[
bbe0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
bbf0: 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a  32_SET_HANDLE]].
bc00: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
bc10: 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48  CNTL_WIN32_SET_H
bc20: 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 65 20 69 73  ANDLE] opcode is
bc30: 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67 67   used for debugg
bc40: 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70  ing.  This.** op
bc50: 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65 20  code causes the 
bc60: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
bc70: 68 6f 64 20 74 6f 20 73 77 61 70 20 74 68 65 20  hod to swap the 
bc80: 66 69 6c 65 20 68 61 6e 64 6c 65 20 77 69 74 68  file handle with
bc90: 20 74 68 65 20 6f 6e 65 0a 2a 2a 20 70 6f 69 6e   the one.** poin
bca0: 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 70 41  ted to by the pA
bcb0: 72 67 20 61 72 67 75 6d 65 6e 74 2e 20 20 54 68  rg argument.  Th
bcc0: 69 73 20 63 61 70 61 62 69 6c 69 74 79 20 69 73  is capability is
bcd0: 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73   used during tes
bce0: 74 69 6e 67 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79  ting.** and only
bcf0: 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75 70   needs to be sup
bd00: 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49  ported when SQLI
bd10: 54 45 5f 54 45 53 54 20 69 73 20 64 65 66 69 6e  TE_TEST is defin
bd20: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ed..**.** <li>[[
bd30: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c  SQLITE_FCNTL_WAL
bd40: 5f 42 4c 4f 43 4b 5d 5d 0a 2a 2a 20 54 68 65 20  _BLOCK]].** The 
bd50: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41  [SQLITE_FCNTL_WA
bd60: 4c 5f 42 4c 4f 43 4b 5d 20 69 73 20 61 20 73 69  L_BLOCK] is a si
bd70: 67 6e 61 6c 20 74 6f 20 74 68 65 20 56 46 53 20  gnal to the VFS 
bd80: 6c 61 79 65 72 20 74 68 61 74 20 69 74 20 6d 69  layer that it mi
bd90: 67 68 74 0a 2a 2a 20 62 65 20 61 64 76 61 6e 74  ght.** be advant
bda0: 61 67 65 6f 75 73 20 74 6f 20 62 6c 6f 63 6b 20  ageous to block 
bdb0: 6f 6e 20 74 68 65 20 6e 65 78 74 20 57 41 4c 20  on the next WAL 
bdc0: 6c 6f 63 6b 20 69 66 20 74 68 65 20 6c 6f 63 6b  lock if the lock
bdd0: 20 69 73 20 6e 6f 74 20 69 6d 6d 65 64 69 61 74   is not immediat
bde0: 65 6c 79 0a 2a 2a 20 61 76 61 69 6c 61 62 6c 65  ely.** available
bdf0: 2e 20 20 54 68 65 20 57 41 4c 20 73 75 62 73 79  .  The WAL subsy
be00: 73 74 65 6d 20 69 73 73 75 65 73 20 74 68 69 73  stem issues this
be10: 20 73 69 67 6e 61 6c 20 64 75 72 69 6e 67 20 72   signal during r
be20: 61 72 65 0a 2a 2a 20 63 69 72 63 75 6d 73 74 61  are.** circumsta
be30: 6e 63 65 73 20 69 6e 20 6f 72 64 65 72 20 74 6f  nces in order to
be40: 20 66 69 78 20 61 20 70 72 6f 62 6c 65 6d 20 77   fix a problem w
be50: 69 74 68 20 70 72 69 6f 72 69 74 79 20 69 6e 76  ith priority inv
be60: 65 72 73 69 6f 6e 2e 0a 2a 2a 20 41 70 70 6c 69  ersion..** Appli
be70: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 3c  cations should <
be80: 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20 75 73 65 20  em>not</em> use 
be90: 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  this file-contro
bea0: 6c 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  l..**.** <li>[[S
beb0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56  QLITE_FCNTL_ZIPV
bec0: 46 53 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  FS]].** The [SQL
bed0: 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53  ITE_FCNTL_ZIPVFS
bee0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6d 70 6c  ] opcode is impl
bef0: 65 6d 65 6e 74 65 64 20 62 79 20 7a 69 70 76 66  emented by zipvf
bf00: 73 20 6f 6e 6c 79 2e 20 41 6c 6c 20 6f 74 68 65  s only. All othe
bf10: 72 0a 2a 2a 20 56 46 53 20 73 68 6f 75 6c 64 20  r.** VFS should 
bf20: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f  return SQLITE_NO
bf30: 54 46 4f 55 4e 44 20 66 6f 72 20 74 68 69 73 20  TFOUND for this 
bf40: 6f 70 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  opcode..**.** <l
bf50: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
bf60: 5f 52 42 55 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  _RBU]].** The [S
bf70: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d  QLITE_FCNTL_RBU]
bf80: 20 6f 70 63 6f 64 65 20 69 73 20 69 6d 70 6c 65   opcode is imple
bf90: 6d 65 6e 74 65 64 20 62 79 20 74 68 65 20 73 70  mented by the sp
bfa0: 65 63 69 61 6c 20 56 46 53 20 75 73 65 64 20 62  ecial VFS used b
bfb0: 79 0a 2a 2a 20 74 68 65 20 52 42 55 20 65 78 74  y.** the RBU ext
bfc0: 65 6e 73 69 6f 6e 20 6f 6e 6c 79 2e 20 20 41 6c  ension only.  Al
bfd0: 6c 20 6f 74 68 65 72 20 56 46 53 20 73 68 6f 75  l other VFS shou
bfe0: 6c 64 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  ld return SQLITE
bff0: 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f 72 0a 2a 2a  _NOTFOUND for.**
c000: 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 20 0a   this opcode.  .
c010: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </ul>.*/.#def
c020: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c030: 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20  _LOCKSTATE      
c040: 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69           1.#defi
c050: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c060: 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  GET_LOCKPROXYFIL
c070: 45 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e  E       2.#defin
c080: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  e SQLITE_FCNTL_S
c090: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
c0a0: 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
c0b0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41   SQLITE_FCNTL_LA
c0c0: 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20  ST_ERRNO        
c0d0: 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20        4.#define 
c0e0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
c0f0: 45 5f 48 49 4e 54 20 20 20 20 20 20 20 20 20 20  E_HINT          
c100: 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53       5.#define S
c110: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e  QLITE_FCNTL_CHUN
c120: 4b 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 20  K_SIZE          
c130: 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51      6.#define SQ
c140: 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f  LITE_FCNTL_FILE_
c150: 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 20  POINTER         
c160: 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c     7.#define SQL
c170: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f  ITE_FCNTL_SYNC_O
c180: 4d 49 54 54 45 44 20 20 20 20 20 20 20 20 20 20  MITTED          
c190: 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    8.#define SQLI
c1a0: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41  TE_FCNTL_WIN32_A
c1b0: 56 5f 52 45 54 52 59 20 20 20 20 20 20 20 20 20  V_RETRY         
c1c0: 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   9.#define SQLIT
c1d0: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
c1e0: 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 31  WAL            1
c1f0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
c200: 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45  _FCNTL_OVERWRITE
c210: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 31                11
c220: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c230: 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20  FCNTL_VFSNAME   
c240: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 32 0a               12.
c250: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c260: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f  CNTL_POWERSAFE_O
c270: 56 45 52 57 52 49 54 45 20 20 20 20 31 33 0a 23  VERWRITE    13.#
c280: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
c290: 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20 20 20 20  NTL_PRAGMA      
c2a0: 20 20 20 20 20 20 20 20 20 20 20 31 34 0a 23 64             14.#d
c2b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
c2c0: 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 20 20  TL_BUSYHANDLER  
c2d0: 20 20 20 20 20 20 20 20 20 20 31 35 0a 23 64 65            15.#de
c2e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c2f0: 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 20 20  L_TEMPFILENAME  
c300: 20 20 20 20 20 20 20 20 20 31 36 0a 23 64 65 66           16.#def
c310: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c320: 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 20 20  _MMAP_SIZE      
c330: 20 20 20 20 20 20 20 20 31 38 0a 23 64 65 66 69          18.#defi
c340: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c350: 54 52 41 43 45 20 20 20 20 20 20 20 20 20 20 20  TRACE           
c360: 20 20 20 20 20 20 20 31 39 0a 23 64 65 66 69 6e         19.#defin
c370: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48  e SQLITE_FCNTL_H
c380: 41 53 5f 4d 4f 56 45 44 20 20 20 20 20 20 20 20  AS_MOVED        
c390: 20 20 20 20 20 20 32 30 0a 23 64 65 66 69 6e 65        20.#define
c3a0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59   SQLITE_FCNTL_SY
c3b0: 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20  NC              
c3c0: 20 20 20 20 20 32 31 0a 23 64 65 66 69 6e 65 20       21.#define 
c3d0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d  SQLITE_FCNTL_COM
c3e0: 4d 49 54 5f 50 48 41 53 45 54 57 4f 20 20 20 20  MIT_PHASETWO    
c3f0: 20 20 20 20 32 32 0a 23 64 65 66 69 6e 65 20 53      22.#define S
c400: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
c410: 32 5f 53 45 54 5f 48 41 4e 44 4c 45 20 20 20 20  2_SET_HANDLE    
c420: 20 20 20 32 33 0a 23 64 65 66 69 6e 65 20 53 51     23.#define SQ
c430: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42  LITE_FCNTL_WAL_B
c440: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20  LOCK            
c450: 20 20 32 34 0a 23 64 65 66 69 6e 65 20 53 51 4c    24.#define SQL
c460: 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53  ITE_FCNTL_ZIPVFS
c470: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
c480: 20 32 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   25.#define SQLI
c490: 54 45 5f 46 43 4e 54 4c 5f 52 42 55 20 20 20 20  TE_FCNTL_RBU    
c4a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
c4b0: 32 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  26.#define SQLIT
c4c0: 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e  E_FCNTL_VFS_POIN
c4d0: 54 45 52 20 20 20 20 20 20 20 20 20 20 20 20 32  TER            2
c4e0: 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  7.#define SQLITE
c4f0: 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50  _FCNTL_JOURNAL_P
c500: 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 32 38  OINTER        28
c510: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c520: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f  FCNTL_WIN32_GET_
c530: 48 41 4e 44 4c 45 20 20 20 20 20 20 20 32 39 0a  HANDLE       29.
c540: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c550: 43 4e 54 4c 5f 50 44 42 20 20 20 20 20 20 20 20  CNTL_PDB        
c560: 20 20 20 20 20 20 20 20 20 20 20 20 33 30 0a 0a              30..
c570: 2f 2a 20 64 65 70 72 65 63 61 74 65 64 20 6e 61  /* deprecated na
c580: 6d 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  mes */.#define S
c590: 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52  QLITE_GET_LOCKPR
c5a0: 4f 58 59 46 49 4c 45 20 20 20 20 20 20 53 51 4c  OXYFILE      SQL
c5b0: 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f  ITE_FCNTL_GET_LO
c5c0: 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 66  CKPROXYFILE.#def
c5d0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c  ine SQLITE_SET_L
c5e0: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20  OCKPROXYFILE    
c5f0: 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53    SQLITE_FCNTL_S
c600: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
c610: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c620: 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20  LAST_ERRNO      
c630: 20 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43         SQLITE_FC
c640: 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 0a 0a  NTL_LAST_ERRNO..
c650: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
c660: 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a   Mutex Handle.**
c670: 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f  .** The mutex mo
c680: 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69  dule within SQLi
c690: 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69  te defines [sqli
c6a0: 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65  te3_mutex] to be
c6b0: 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20   an.** abstract 
c6c0: 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78  type for a mutex
c6d0: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51   object.  The SQ
c6e0: 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20  Lite core never 
c6f0: 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20  looks.** at the 
c700: 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65  internal represe
c710: 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73  ntation of an [s
c720: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20  qlite3_mutex].  
c730: 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73  It only.** deals
c740: 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74   with pointers t
c750: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  o the [sqlite3_m
c760: 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  utex] object..**
c770: 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20  .** Mutexes are 
c780: 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73  created using [s
c790: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c  qlite3_mutex_all
c7a0: 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65  oc()]..*/.typede
c7b0: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
c7c0: 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d  _mutex sqlite3_m
c7d0: 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  utex;../*.** CAP
c7e0: 49 33 52 45 46 3a 20 4c 6f 61 64 61 62 6c 65 20  I3REF: Loadable 
c7f0: 45 78 74 65 6e 73 69 6f 6e 20 54 68 75 6e 6b 0a  Extension Thunk.
c800: 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20  **.** A pointer 
c810: 74 6f 20 74 68 65 20 6f 70 61 71 75 65 20 73 71  to the opaque sq
c820: 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e  lite3_api_routin
c830: 65 73 20 73 74 72 75 63 74 75 72 65 20 69 73 20  es structure is 
c840: 70 61 73 73 65 64 20 61 73 0a 2a 2a 20 74 68 65  passed as.** the
c850: 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
c860: 20 74 6f 20 65 6e 74 72 79 20 70 6f 69 6e 74 73   to entry points
c870: 20 6f 66 20 5b 6c 6f 61 64 61 62 6c 65 20 65 78   of [loadable ex
c880: 74 65 6e 73 69 6f 6e 73 5d 2e 20 20 54 68 69 73  tensions].  This
c890: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 6d 75  .** structure mu
c8a0: 73 74 20 62 65 20 74 79 70 65 64 65 66 65 64 20  st be typedefed 
c8b0: 69 6e 20 6f 72 64 65 72 20 74 6f 20 77 6f 72 6b  in order to work
c8c0: 20 61 72 6f 75 6e 64 20 63 6f 6d 70 69 6c 65 72   around compiler
c8d0: 20 77 61 72 6e 69 6e 67 73 0a 2a 2a 20 6f 6e 20   warnings.** on 
c8e0: 73 6f 6d 65 20 70 6c 61 74 66 6f 72 6d 73 2e 0a  some platforms..
c8f0: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
c900: 74 20 73 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f  t sqlite3_api_ro
c910: 75 74 69 6e 65 73 20 73 71 6c 69 74 65 33 5f 61  utines sqlite3_a
c920: 70 69 5f 72 6f 75 74 69 6e 65 73 3b 0a 0a 2f 2a  pi_routines;../*
c930: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
c940: 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63   Interface Objec
c950: 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  t.**.** An insta
c960: 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74  nce of the sqlit
c970: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65  e3_vfs object de
c980: 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66  fines the interf
c990: 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74  ace between.** t
c9a0: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61  he SQLite core a
c9b0: 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  nd the underlyin
c9c0: 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  g operating syst
c9d0: 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a  em.  The "vfs".*
c9e0: 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  * in the name of
c9f0: 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e   the object stan
ca00: 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20  ds for "virtual 
ca10: 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 20 20 53  file system".  S
ca20: 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c  ee.** the [VFS |
ca30: 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 61 74 69   VFS documentati
ca40: 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 65 72 20  on] for further 
ca50: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
ca60: 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20  ** The value of 
ca70: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65  the iVersion fie
ca80: 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20  ld is initially 
ca90: 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72  1 but may be lar
caa0: 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65  ger in.** future
cab0: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
cac0: 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c  ite.  Additional
cad0: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61   fields may be a
cae0: 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a  ppended to this.
caf0: 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74  ** object when t
cb00: 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75  he iVersion valu
cb10: 65 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e 20  e is increased. 
cb20: 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 73   Note that the s
cb30: 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74  tructure.** of t
cb40: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  he sqlite3_vfs o
cb50: 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69 6e  bject changes in
cb60: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
cb70: 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69   between.** SQLi
cb80: 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39  te version 3.5.9
cb90: 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20 79   and 3.6.0 and y
cba0: 65 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  et the iVersion 
cbb0: 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a  field was not.**
cbc0: 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a   modified..**.**
cbd0: 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69   The szOsFile fi
cbe0: 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65 20  eld is the size 
cbf0: 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 73 65  of the subclasse
cc00: 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  d [sqlite3_file]
cc10: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75 73  .** structure us
cc20: 65 64 20 62 79 20 74 68 69 73 20 56 46 53 2e 20  ed by this VFS. 
cc30: 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74   mxPathname is t
cc40: 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
cc50: 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61  h of.** a pathna
cc60: 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a  me in this VFS..
cc70: 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64  **.** Registered
cc80: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a   sqlite3_vfs obj
cc90: 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f 6e  ects are kept on
cca0: 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66   a linked list f
ccb0: 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20  ormed by.** the 
ccc0: 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20  pNext pointer.  
ccd0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  The [sqlite3_vfs
cce0: 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20  _register()].** 
ccf0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  and [sqlite3_vfs
cd00: 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69  _unregister()] i
cd10: 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65  nterfaces manage
cd20: 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e   this list.** in
cd30: 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 20 77   a thread-safe w
cd40: 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  ay.  The [sqlite
cd50: 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e  3_vfs_find()] in
cd60: 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63  terface.** searc
cd70: 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20 4e  hes the list.  N
cd80: 65 69 74 68 65 72 20 74 68 65 20 61 70 70 6c 69  either the appli
cd90: 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20  cation code nor 
cda0: 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65  the VFS.** imple
cdb0: 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64  mentation should
cdc0: 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 20 70   use the pNext p
cdd0: 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  ointer..**.** Th
cde0: 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73  e pNext field is
cdf0: 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20   the only field 
ce00: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  in the sqlite3_v
ce10: 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  fs.** structure 
ce20: 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
ce30: 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53   ever modify.  S
ce40: 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20  QLite will only 
ce50: 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64  access.** or mod
ce60: 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 20 77  ify this field w
ce70: 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70  hile holding a p
ce80: 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 69 63  articular static
ce90: 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61   mutex..** The a
cea0: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
ceb0: 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61  d never modify a
cec0: 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74  nything within t
ced0: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a  he sqlite3_vfs.*
cee0: 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68  * object once th
cef0: 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65  e object has bee
cf00: 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a  n registered..**
cf10: 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69  .** The zName fi
cf20: 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61  eld holds the na
cf30: 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f  me of the VFS mo
cf40: 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20  dule.  The name 
cf50: 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75  must.** be uniqu
cf60: 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53  e across all VFS
cf70: 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20   modules..**.** 
cf80: 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f  [[sqlite3_vfs.xO
cf90: 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65  pen]].** ^SQLite
cfa0: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
cfb0: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70   the zFilename p
cfc0: 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65  arameter to xOpe
cfd0: 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 61  n.** is either a
cfe0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72   NULL pointer or
cff0: 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64   string obtained
d000: 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61  .** from xFullPa
d010: 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20 61 6e  thname() with an
d020: 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66 69 78   optional suffix
d030: 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61   added..** ^If a
d040: 20 73 75 66 66 69 78 20 69 73 20 61 64 64 65 64   suffix is added
d050: 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d   to the zFilenam
d060: 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69 74 20  e parameter, it 
d070: 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20  will.** consist 
d080: 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d 22 20  of a single "-" 
d090: 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77  character follow
d0a0: 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68  ed by no more th
d0b0: 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e 75  an.** 11 alphanu
d0c0: 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22  meric and/or "-"
d0d0: 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20   characters..** 
d0e0: 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65 72 20  ^SQLite further 
d0f0: 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a  guarantees that.
d100: 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77 69  ** the string wi
d110: 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20  ll be valid and 
d120: 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20  unchanged until 
d130: 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63  xClose() is.** c
d140: 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20 6f  alled. Because o
d150: 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73  f the previous s
d160: 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20  entence,.** the 
d170: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63  [sqlite3_file] c
d180: 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65 20  an safely store 
d190: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
d1a0: 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20  .** filename if 
d1b0: 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65  it needs to reme
d1c0: 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d  mber the filenam
d1d0: 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f  e for some reaso
d1e0: 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69  n..** If the zFi
d1f0: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
d200: 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 20 4e   to xOpen is a N
d210: 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
d220: 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69   xOpen.** must i
d230: 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74 65  nvent its own te
d240: 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f 72  mporary name for
d250: 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57 68 65   the file.  ^Whe
d260: 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 46  never the .** xF
d270: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
d280: 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c  r is NULL it wil
d290: 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63 61  l also be the ca
d2a0: 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 66  se that the.** f
d2b0: 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 77  lags parameter w
d2c0: 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c  ill include [SQL
d2d0: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
d2e0: 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54  NCLOSE]..**.** T
d2f0: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
d300: 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63  t to xOpen() inc
d310: 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73  ludes all bits s
d320: 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61  et in.** the fla
d330: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b  gs argument to [
d340: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
d350: 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69  )].  Or if [sqli
d360: 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f  te3_open()].** o
d370: 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  r [sqlite3_open1
d380: 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68  6()] is used, th
d390: 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65  en flags include
d3a0: 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53  s at least.** [S
d3b0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
d3c0: 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f  RITE] | [SQLITE_
d3d0: 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a  OPEN_CREATE]. .*
d3e0: 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65  * If xOpen() ope
d3f0: 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f  ns a file read-o
d400: 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74 73  nly then it sets
d410: 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a   *pOutFlags to.*
d420: 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54  * include [SQLIT
d430: 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d  E_OPEN_READONLY]
d440: 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e  .  Other bits in
d450: 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20   *pOutFlags may 
d460: 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28  be set..**.** ^(
d470: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f  SQLite will also
d480: 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20   add one of the 
d490: 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20  following flags 
d4a0: 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a  to the xOpen().*
d4b0: 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e  * call, dependin
d4c0: 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20  g on the object 
d4d0: 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a  being opened:.**
d4e0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
d4f0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
d500: 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  AIN_DB].** <li> 
d510: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
d520: 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  IN_JOURNAL].** <
d530: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
d540: 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c  N_TEMP_DB].** <l
d550: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
d560: 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  _TEMP_JOURNAL].*
d570: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
d580: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44  OPEN_TRANSIENT_D
d590: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  B].** <li>  [SQL
d5a0: 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52  ITE_OPEN_SUBJOUR
d5b0: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
d5c0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45  QLITE_OPEN_MASTE
d5d0: 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  R_JOURNAL].** <l
d5e0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
d5f0: 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e  _WAL].** </ul>)^
d600: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20  .**.** The file 
d610: 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  I/O implementati
d620: 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f  on can use the o
d630: 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67 73  bject type flags
d640: 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68   to.** change th
d650: 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20 77  e way it deals w
d660: 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20  ith files.  For 
d670: 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c  example, an appl
d680: 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20  ication.** that 
d690: 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62  does not care ab
d6a0: 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76 65  out crash recove
d6b0: 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d  ry or rollback m
d6c0: 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65  ight make.** the
d6d0: 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e   open of a journ
d6e0: 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e  al file a no-op.
d6f0: 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 69 73    Writes to this
d700: 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a   journal would.*
d710: 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73  * also be no-ops
d720: 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d 70  , and any attemp
d730: 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f  t to read the jo
d740: 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 75  urnal would retu
d750: 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45  rn.** SQLITE_IOE
d760: 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70 6c  RR.  Or the impl
d770: 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74  ementation might
d780: 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74 20   recognize that 
d790: 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  a database.** fi
d7a0: 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67  le will be doing
d7b0: 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 65   page-aligned se
d7c0: 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20 77  ctor reads and w
d7d0: 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64 6f  rites in a rando
d7e0: 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20 73  m.** order and s
d7f0: 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73 75  et up its I/O su
d800: 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69 6e  bsystem accordin
d810: 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  gly..**.** SQLit
d820: 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64  e might also add
d830: 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
d840: 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74  owing flags to t
d850: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a  he xOpen method:
d860: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
d870: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  li> [SQLITE_OPEN
d880: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a  _DELETEONCLOSE].
d890: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
d8a0: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a  OPEN_EXCLUSIVE].
d8b0: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54  ** </ul>.**.** T
d8c0: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
d8d0: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66  DELETEONCLOSE] f
d8e0: 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69  lag means the fi
d8f0: 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  le should be.** 
d900: 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20  deleted when it 
d910: 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65  is closed.  ^The
d920: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
d930: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20  LETEONCLOSE].** 
d940: 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20  will be set for 
d950: 54 45 4d 50 20 64 61 74 61 62 61 73 65 73 20 61  TEMP databases a
d960: 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c  nd their journal
d970: 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20  s, transient.** 
d980: 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64 20 73  databases, and s
d990: 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a  ubjournals..**.*
d9a0: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  * ^The [SQLITE_O
d9b0: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66  PEN_EXCLUSIVE] f
d9c0: 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20 75 73  lag is always us
d9d0: 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f  ed in conjunctio
d9e0: 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53  n.** with the [S
d9f0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
da00: 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20 61  E] flag, which a
da10: 72 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c 79  re both directly
da20: 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f  .** analogous to
da30: 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20   the O_EXCL and 
da40: 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f 66  O_CREAT flags of
da50: 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e 28   the POSIX open(
da60: 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 53  ).** API.  The S
da70: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
da80: 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e 20  SIVE flag, when 
da90: 70 61 69 72 65 64 20 77 69 74 68 20 74 68 65 20  paired with the 
daa0: 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  .** SQLITE_OPEN_
dab0: 43 52 45 41 54 45 2c 20 69 73 20 75 73 65 64 20  CREATE, is used 
dac0: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  to indicate that
dad0: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77   file should alw
dae0: 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 65  ays.** be create
daf0: 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20 69  d, and that it i
db00: 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69 74  s an error if it
db10: 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 73 2e   already exists.
db20: 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74  .** It is <i>not
db30: 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e 64  </i> used to ind
db40: 69 63 61 74 65 20 74 68 65 20 66 69 6c 65 20 73  icate the file s
db50: 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 20  hould be opened 
db60: 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76  .** for exclusiv
db70: 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20  e access..**.** 
db80: 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69  ^At least szOsFi
db90: 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  le bytes of memo
dba0: 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64  ry are allocated
dbb0: 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f   by SQLite.** to
dbc0: 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69   hold the  [sqli
dbd0: 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74  te3_file] struct
dbe0: 75 72 65 20 70 61 73 73 65 64 20 61 73 20 74 68  ure passed as th
dbf0: 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d  e third.** argum
dc00: 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54  ent to xOpen.  T
dc10: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20  he xOpen method 
dc20: 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f  does not have to
dc30: 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65  .** allocate the
dc40: 20 73 74 72 75 63 74 75 72 65 3b 20 69 74 20 73   structure; it s
dc50: 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20  hould just fill 
dc60: 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61  it in.  Note tha
dc70: 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d  t.** the xOpen m
dc80: 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20 74  ethod must set t
dc90: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
dca0: 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74 68  pMethods to eith
dcb0: 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73  er.** a valid [s
dcc0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
dcd0: 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20  s] object or to 
dce0: 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73  NULL.  xOpen mus
dcf0: 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65  t do.** this eve
dd00: 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66 61  n if the open fa
dd10: 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78 70  ils.  SQLite exp
dd20: 65 63 74 73 20 74 68 61 74 20 74 68 65 20 73 71  ects that the sq
dd30: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
dd40: 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77  ods.** element w
dd50: 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66 74  ill be valid aft
dd60: 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e 73  er xOpen returns
dd70: 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74   regardless of t
dd80: 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72  he success.** or
dd90: 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65 20   failure of the 
dda0: 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a  xOpen call..**.*
ddb0: 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  * [[sqlite3_vfs.
ddc0: 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68  xAccess]].** ^Th
ddd0: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
dde0: 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61   to xAccess() ma
ddf0: 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43  y be [SQLITE_ACC
de00: 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74  ESS_EXISTS].** t
de10: 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 20 65  o test for the e
de20: 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69  xistence of a fi
de30: 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41  le, or [SQLITE_A
de40: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d  CCESS_READWRITE]
de50: 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74   to.** test whet
de60: 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 72 65  her a file is re
de70: 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61  adable and writa
de80: 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ble, or [SQLITE_
de90: 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20  ACCESS_READ].** 
dea0: 74 6f 20 74 65 73 74 20 77 68 65 74 68 65 72 20  to test whether 
deb0: 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61  a file is at lea
dec0: 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20 54  st readable.   T
ded0: 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20 61  he file can be a
dee0: 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a  .** directory..*
def0: 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  *.** ^SQLite wil
df00: 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74  l always allocat
df10: 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74  e at least mxPat
df20: 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f  hname+1 bytes fo
df30: 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20  r the.** output 
df40: 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68  buffer xFullPath
df50: 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63 74  name.  The exact
df60: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74   size of the out
df70: 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73  put buffer.** is
df80: 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20   also passed as 
df90: 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62  a parameter to b
dfa0: 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 66  oth  methods. If
dfb0: 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66   the output buff
dfc0: 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72  er.** is not lar
dfd0: 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49  ge enough, [SQLI
dfe0: 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f  TE_CANTOPEN] sho
dff0: 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e  uld be returned.
e000: 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a   Since this is.*
e010: 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66  * handled as a f
e020: 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51  atal error by SQ
e030: 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d  Lite, vfs implem
e040: 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  entations should
e050: 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20   endeavor.** to 
e060: 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 20  prevent this by 
e070: 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61  setting mxPathna
e080: 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 65  me to a sufficie
e090: 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65  ntly large value
e0a0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e  ..**.** The xRan
e0b0: 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65  domness(), xSlee
e0c0: 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69 6d  p(), xCurrentTim
e0d0: 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e  e(), and xCurren
e0e0: 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20  tTimeInt64().** 
e0f0: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 6e  interfaces are n
e100: 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20 70 61  ot strictly a pa
e110: 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79  rt of the filesy
e120: 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61  stem, but they a
e130: 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69  re.** included i
e140: 6e 20 74 68 65 20 56 46 53 20 73 74 72 75 63 74  n the VFS struct
e150: 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65  ure for complete
e160: 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61  ness..** The xRa
e170: 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74  ndomness() funct
e180: 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ion attempts to 
e190: 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79  return nBytes by
e1a0: 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71  tes.** of good-q
e1b0: 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73  uality randomnes
e1c0: 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68  s into zOut.  Th
e1d0: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69  e return value i
e1e0: 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20  s.** the actual 
e1f0: 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
e200: 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62  of randomness ob
e210: 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78  tained..** The x
e220: 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63  Sleep() method c
e230: 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e  auses the callin
e240: 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65  g thread to slee
e250: 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73  p for at.** leas
e260: 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
e270: 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76  microseconds giv
e280: 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72 65  en.  ^The xCurre
e290: 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68  ntTime().** meth
e2a0: 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c  od returns a Jul
e2b0: 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66  ian Day Number f
e2c0: 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  or the current d
e2d0: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73 0a  ate and time as.
e2e0: 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f  ** a floating po
e2f0: 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54  int value..** ^T
e300: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  he xCurrentTimeI
e310: 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72 65  nt64() method re
e320: 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e 74  turns, as an int
e330: 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61 6e  eger, the Julian
e340: 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20 6d  .** Day Number m
e350: 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38 36 34  ultiplied by 864
e360: 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62 65  00000 (the numbe
e370: 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  r of millisecond
e380: 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f  s in .** a 24-ho
e390: 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53  ur day).  .** ^S
e3a0: 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74  QLite will use t
e3b0: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  he xCurrentTimeI
e3c0: 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74 6f  nt64() method to
e3d0: 20 67 65 74 20 74 68 65 20 63 75 72 72 65 6e 74   get the current
e3e0: 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69 6d  .** date and tim
e3f0: 65 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f 64  e if that method
e400: 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28 69   is available (i
e410: 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32 20  f iVersion is 2 
e420: 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20 61  or .** greater a
e430: 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  nd the function 
e440: 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e  pointer is not N
e450: 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66 61  ULL) and will fa
e460: 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43  ll back.** to xC
e470: 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66 20  urrentTime() if 
e480: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
e490: 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61 62  4() is unavailab
e4a0: 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78  le..**.** ^The x
e4b0: 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c  SetSystemCall(),
e4c0: 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 28   xGetSystemCall(
e4d0: 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73 74  ), and xNestSyst
e4e0: 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66 61  emCall() interfa
e4f0: 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 75  ces.** are not u
e500: 73 65 64 20 62 79 20 74 68 65 20 53 51 4c 69 74  sed by the SQLit
e510: 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20 6f  e core.  These o
e520: 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61 63  ptional interfac
e530: 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 0a  es are provided.
e540: 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65 73  ** by some VFSes
e550: 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20 74   to facilitate t
e560: 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56 46  esting of the VF
e570: 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72 72  S code. By overr
e580: 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65 6d  iding .** system
e590: 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e 63   calls with func
e5a0: 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73 20  tions under its 
e5b0: 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74 20  control, a test 
e5c0: 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 73  program can.** s
e5d0: 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20 61  imulate faults a
e5e0: 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74 69  nd error conditi
e5f0: 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20 6f  ons that would o
e600: 74 68 65 72 77 69 73 65 20 62 65 20 64 69 66 66  therwise be diff
e610: 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f  icult.** or impo
e620: 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63 65  ssible to induce
e630: 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20 73 79  .  The set of sy
e640: 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74 20  stem calls that 
e650: 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65  can be overridde
e660: 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f 6d  n.** varies from
e670: 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f 74   one VFS to anot
e680: 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f 6e  her, and from on
e690: 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65  e version of the
e6a0: 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68 65   same VFS to the
e6b0: 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c 69  .** next.  Appli
e6c0: 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65  cations that use
e6d0: 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
e6e0: 73 20 6d 75 73 74 20 62 65 20 70 72 65 70 61 72  s must be prepar
e6f0: 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72  ed for any.** or
e700: 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69 6e   all of these in
e710: 74 65 72 66 61 63 65 73 20 74 6f 20 62 65 20 4e  terfaces to be N
e720: 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69 72  ULL or for their
e730: 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68 61   behavior to cha
e740: 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20  nge.** from one 
e750: 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20 6e  release to the n
e760: 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ext.  Applicatio
e770: 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74 65  ns must not atte
e780: 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a 2a  mpt to access.**
e790: 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d 65   any of these me
e7a0: 74 68 6f 64 73 20 69 66 20 74 68 65 20 69 56 65  thods if the iVe
e7b0: 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46 53  rsion of the VFS
e7c0: 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33 2e   is less than 3.
e7d0: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
e7e0: 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73  ct sqlite3_vfs s
e7f0: 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70 65  qlite3_vfs;.type
e800: 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74  def void (*sqlit
e810: 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 28  e3_syscall_ptr)(
e820: 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73 71  void);.struct sq
e830: 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e  lite3_vfs {.  in
e840: 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20  t iVersion;     
e850: 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74         /* Struct
e860: 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62  ure version numb
e870: 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33 29  er (currently 3)
e880: 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69   */.  int szOsFi
e890: 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f  le;            /
e8a0: 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61  * Size of subcla
e8b0: 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c  ssed sqlite3_fil
e8c0: 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74  e */.  int mxPat
e8d0: 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20  hname;          
e8e0: 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20  /* Maximum file 
e8f0: 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20  pathname length 
e900: 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73  */.  sqlite3_vfs
e910: 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a   *pNext;      /*
e920: 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65 64   Next registered
e930: 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20   VFS */.  const 
e940: 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20  char *zName;    
e950: 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68     /* Name of th
e960: 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20  is virtual file 
e970: 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64  system */.  void
e980: 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20   *pAppData;     
e990: 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20       /* Pointer 
e9a0: 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73  to application-s
e9b0: 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a  pecific data */.
e9c0: 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73    int (*xOpen)(s
e9d0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
e9e0: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
e9f0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20  sqlite3_file*,. 
ea00: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e                in
ea10: 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f  t flags, int *pO
ea20: 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20  utFlags);.  int 
ea30: 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74  (*xDelete)(sqlit
ea40: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
ea50: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
ea60: 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20  syncDir);.  int 
ea70: 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69 74  (*xAccess)(sqlit
ea80: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
ea90: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
eaa0: 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73  flags, int *pRes
eab0: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  Out);.  int (*xF
eac0: 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c  ullPathname)(sql
ead0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
eae0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
eaf0: 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f  t nOut, char *zO
eb00: 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78  ut);.  void *(*x
eb10: 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f  DlOpen)(sqlite3_
eb20: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
eb30: 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20   *zFilename);.  
eb40: 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29  void (*xDlError)
eb50: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
eb60: 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a  nt nByte, char *
eb70: 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64  zErrMsg);.  void
eb80: 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c   (*(*xDlSym)(sql
eb90: 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c  ite3_vfs*,void*,
eba0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79   const char *zSy
ebb0: 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20  mbol))(void);.  
ebc0: 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29  void (*xDlClose)
ebd0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76  (sqlite3_vfs*, v
ebe0: 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  oid*);.  int (*x
ebf0: 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69  Randomness)(sqli
ec00: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42  te3_vfs*, int nB
ec10: 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29  yte, char *zOut)
ec20: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70  ;.  int (*xSleep
ec30: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
ec40: 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73  int microseconds
ec50: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72  );.  int (*xCurr
ec60: 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33  entTime)(sqlite3
ec70: 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b  _vfs*, double*);
ec80: 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73  .  int (*xGetLas
ec90: 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f  tError)(sqlite3_
eca0: 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20  vfs*, int, char 
ecb0: 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68  *);.  /*.  ** Th
ecc0: 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  e methods above 
ecd0: 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20 31  are in version 1
ece0: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76   of the sqlite_v
ecf0: 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64  fs object.  ** d
ed00: 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73  efinition.  Thos
ed10: 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72  e that follow ar
ed20: 65 20 61 64 64 65 64 20 69 6e 20 76 65 72 73 69  e added in versi
ed30: 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20 20  on 2 or later.  
ed40: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72  */.  int (*xCurr
ed50: 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73 71  entTimeInt64)(sq
ed60: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69  lite3_vfs*, sqli
ed70: 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f  te3_int64*);.  /
ed80: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
ed90: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
eda0: 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20 32  versions 1 and 2
edb0: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76   of the sqlite_v
edc0: 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20  fs object..  ** 
edd0: 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65 20  Those below are 
ede0: 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61 6e  for version 3 an
edf0: 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f 0a  d greater..  */.
ee00: 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73 74    int (*xSetSyst
ee10: 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f  emCall)(sqlite3_
ee20: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
ee30: 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33   *zName, sqlite3
ee40: 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 20  _syscall_ptr);. 
ee50: 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c   sqlite3_syscall
ee60: 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73 74 65  _ptr (*xGetSyste
ee70: 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76  mCall)(sqlite3_v
ee80: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
ee90: 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 74  *zName);.  const
eea0: 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53 79   char *(*xNextSy
eeb0: 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
eec0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
eed0: 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a  ar *zName);.  /*
eee0: 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64  .  ** The method
eef0: 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76  s above are in v
ef00: 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75 67  ersions 1 throug
ef10: 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69 74  h 3 of the sqlit
ef20: 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20  e_vfs object..  
ef30: 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61  ** New fields ma
ef40: 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e  y be appended in
ef50: 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
ef60: 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a  .  The iVersion.
ef70: 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20    ** value will 
ef80: 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76  increment whenev
ef90: 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e  er this happens.
efa0: 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a   .  */.};../*.**
efb0: 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73   CAPI3REF: Flags
efc0: 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73   for the xAccess
efd0: 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a   VFS method.**.*
efe0: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  * These integer 
eff0: 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65  constants can be
f000: 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68 69   used as the thi
f010: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  rd parameter to.
f020: 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  ** the xAccess m
f030: 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c  ethod of an [sql
f040: 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
f050: 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e  .  They determin
f060: 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f  e.** what kind o
f070: 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68  f permissions th
f080: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
f090: 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e   is looking for.
f0a0: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
f0b0: 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74  ACCESS_EXISTS, t
f0c0: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
f0d0: 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63  d.** simply chec
f0e0: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66  ks whether the f
f0f0: 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57  ile exists..** W
f100: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
f110: 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65  S_READWRITE, the
f120: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
f130: 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ** checks whethe
f140: 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72 65  r the named dire
f150: 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72 65  ctory is both re
f160: 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61  adable and writa
f170: 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72  ble.** (in other
f180: 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65 73   words, if files
f190: 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20 72   can be added, r
f1a0: 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e 61  emoved, and rena
f1b0: 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68  med within.** th
f1c0: 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a  e directory)..**
f1d0: 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45   The SQLITE_ACCE
f1e0: 53 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f 6e  SS_READWRITE con
f1f0: 73 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e 74  stant is current
f200: 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79 20  ly used only by 
f210: 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f  the.** [temp_sto
f220: 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61  re_directory pra
f230: 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68 69  gma], though thi
f240: 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20 69  s could change i
f250: 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65  n a future.** re
f260: 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e  lease of SQLite.
f270: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
f280: 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65  ACCESS_READ, the
f290: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
f2a0: 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ** checks whethe
f2b0: 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65  r the file is re
f2c0: 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51 4c  adable.  The SQL
f2d0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20  ITE_ACCESS_READ 
f2e0: 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63  constant is.** c
f2f0: 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c  urrently unused,
f300: 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68 74   though it might
f310: 20 62 65 20 75 73 65 64 20 69 6e 20 61 20 66 75   be used in a fu
f320: 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a  ture release of.
f330: 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64  ** SQLite..*/.#d
f340: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
f350: 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a  ESS_EXISTS    0.
f360: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
f370: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20  CCESS_READWRITE 
f380: 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20 50  1   /* Used by P
f390: 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65  RAGMA temp_store
f3a0: 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64  _directory */.#d
f3b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
f3c0: 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 20  ESS_READ      2 
f3d0: 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a    /* Unused */..
f3e0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
f3f0: 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 53  Flags for the xS
f400: 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f  hmLock VFS metho
f410: 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  d.**.** These in
f420: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
f430: 64 65 66 69 6e 65 20 74 68 65 20 76 61 72 69 6f  define the vario
f440: 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61  us locking opera
f450: 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64  tions.** allowed
f460: 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b   by the xShmLock
f470: 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69   method of [sqli
f480: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e  te3_io_methods].
f490: 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69    The.** followi
f4a0: 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20  ng are the only 
f4b0: 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f  legal combinatio
f4c0: 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20 74  ns of flags to t
f4d0: 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d  he.** xShmLock m
f4e0: 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  ethod:.**.** <ul
f4f0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  >.** <li>  SQLIT
f500: 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c  E_SHM_LOCK | SQL
f510: 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a  ITE_SHM_SHARED.*
f520: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
f530: 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45  HM_LOCK | SQLITE
f540: 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a  _SHM_EXCLUSIVE.*
f550: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
f560: 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49  HM_UNLOCK | SQLI
f570: 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a  TE_SHM_SHARED.**
f580: 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
f590: 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  M_UNLOCK | SQLIT
f5a0: 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a  E_SHM_EXCLUSIVE.
f5b0: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57  ** </ul>.**.** W
f5c0: 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74  hen unlocking, t
f5d0: 68 65 20 73 61 6d 65 20 53 48 41 52 45 44 20 6f  he same SHARED o
f5e0: 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67  r EXCLUSIVE flag
f5f0: 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69 65   must be supplie
f600: 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76 65  d as.** was give
f610: 6e 20 6f 6e 20 74 68 65 20 63 6f 72 72 65 73 70  n on the corresp
f620: 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a  onding lock.  .*
f630: 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63  *.** The xShmLoc
f640: 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72 61  k method can tra
f650: 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  nsition between 
f660: 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48 41  unlocked and SHA
f670: 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65  RED or.** betwee
f680: 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45  n unlocked and E
f690: 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63 61  XCLUSIVE.  It ca
f6a0: 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e 20  nnot transition 
f6b0: 62 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a 2a  between SHARED.*
f6c0: 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e  * and EXCLUSIVE.
f6d0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
f6e0: 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20  TE_SHM_UNLOCK   
f6f0: 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
f700: 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20  LITE_SHM_LOCK   
f710: 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
f720: 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45  SQLITE_SHM_SHARE
f730: 44 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e  D       4.#defin
f740: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43  e SQLITE_SHM_EXC
f750: 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a  LUSIVE    8../*.
f760: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61 78  ** CAPI3REF: Max
f770: 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e  imum xShmLock in
f780: 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53  dex.**.** The xS
f790: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e  hmLock method on
f7a0: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
f7b0: 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76 61  hods] may use va
f7c0: 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20  lues.** between 
f7d0: 30 20 61 6e 64 20 74 68 69 73 20 75 70 70 65 72  0 and this upper
f7e0: 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22 6f   bound as its "o
f7f0: 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74 2e  ffset" argument.
f800: 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63  .** The SQLite c
f810: 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 61  ore will never a
f820: 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69 72  ttempt to acquir
f830: 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a 2a  e or release a.*
f840: 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f  * lock outside o
f850: 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a  f this range.*/.
f860: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
f870: 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20  HM_NLOCK        
f880: 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  8.../*.** CAPI3R
f890: 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54  EF: Initialize T
f8a0: 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72  he SQLite Librar
f8b0: 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  y.**.** ^The sql
f8c0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
f8d0: 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61  ) routine initia
f8e0: 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c  lizes the.** SQL
f8f0: 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e 54  ite library.  ^T
f900: 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  he sqlite3_shutd
f910: 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a  own() routine.**
f920: 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79   deallocates any
f930: 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 20   resources that 
f940: 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62  were allocated b
f950: 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  y sqlite3_initia
f960: 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65  lize()..** These
f970: 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65   routines are de
f980: 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69 6e  signed to aid in
f990: 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c   process initial
f9a0: 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73  ization and.** s
f9b0: 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64  hutdown on embed
f9c0: 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57 6f  ded systems.  Wo
f9d0: 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 63  rkstation applic
f9e0: 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20  ations using.** 
f9f0: 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20  SQLite normally 
fa00: 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69  do not need to i
fa10: 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 20  nvoke either of 
fa20: 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
fa30: 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20  **.** A call to 
fa40: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
fa50: 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 65  ze() is an "effe
fa60: 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69  ctive" call if i
fa70: 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73  t is.** the firs
fa80: 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69  t time sqlite3_i
fa90: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
faa0: 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68  nvoked during th
fab0: 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a  e lifetime of.**
fac0: 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72   the process, or
fad0: 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69   if it is the fi
fae0: 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33  rst time sqlite3
faf0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
fb00: 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c   invoked.** foll
fb10: 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20  owing a call to 
fb20: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
fb30: 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65  ().  ^(Only an e
fb40: 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a  ffective call.**
fb50: 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   of sqlite3_init
fb60: 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e  ialize() does an
fb70: 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  y initialization
fb80: 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c  .  All other cal
fb90: 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65  ls.** are harmle
fba0: 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a  ss no-ops.)^.**.
fbb0: 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ** A call to sql
fbc0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
fbd0: 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65  is an "effective
fbe0: 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20  " call if it is 
fbf0: 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c  the first.** cal
fc00: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
fc10: 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68  tdown() since th
fc20: 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69  e last sqlite3_i
fc30: 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28  nitialize().  ^(
fc40: 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63  Only.** an effec
fc50: 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c  tive call to sql
fc60: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
fc70: 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69  does any deiniti
fc80: 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c  alization..** Al
fc90: 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61  l other valid ca
fca0: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  lls to sqlite3_s
fcb0: 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61  hutdown() are ha
fcc0: 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e  rmless no-ops.)^
fcd0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
fce0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
fcf0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 72  interface is thr
fd00: 65 61 64 73 61 66 65 2c 20 62 75 74 20 73 71 6c  eadsafe, but sql
fd10: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a  ite3_shutdown().
fd20: 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 20  ** is not.  The 
fd30: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
fd40: 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75 73  () interface mus
fd50: 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64  t only be called
fd60: 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c   from a.** singl
fd70: 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f  e thread.  All o
fd80: 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f  pen [database co
fd90: 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20  nnections] must 
fda0: 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c  be closed and al
fdb0: 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74  l.** other SQLit
fdc0: 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73 74  e resources must
fdd0: 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
fde0: 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e  prior to invokin
fdf0: 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 75  g.** sqlite3_shu
fe00: 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41  tdown()..**.** A
fe10: 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67  mong other thing
fe20: 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74  s, ^sqlite3_init
fe30: 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e  ialize() will in
fe40: 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  voke.** sqlite3_
fe50: 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69  os_init().  Simi
fe60: 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f  larly, ^sqlite3_
fe70: 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69  shutdown().** wi
fe80: 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ll invoke sqlite
fe90: 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a  3_os_end()..**.*
fea0: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
feb0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
fec0: 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ine returns [SQL
fed0: 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
fee0: 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73  ss..** ^If for s
fef0: 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69  ome reason, sqli
ff00: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
ff10: 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e   is unable to in
ff20: 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20  itialize.** the 
ff30: 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 70 73  library (perhaps
ff40: 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f   it is unable to
ff50: 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64   allocate a need
ff60: 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 68  ed resource such
ff70: 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20  .** as a mutex) 
ff80: 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65  it returns an [e
ff90: 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72  rror code] other
ffa0: 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b   than [SQLITE_OK
ffb0: 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ]..**.** ^The sq
ffc0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
ffd0: 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61  () routine is ca
ffe0: 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  lled internally 
fff0: 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a  by many other.**
10000 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
10010 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70  es so that an ap
10020 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c  plication usuall
10030 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  y does not need 
10040 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c  to.** invoke sql
10050 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
10060 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72  ) directly.  For
10070 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74   example, [sqlit
10080 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61  e3_open()].** ca
10090 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  lls sqlite3_init
100a0 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20  ialize() so the 
100b0 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77  SQLite library w
100c0 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63  ill be automatic
100d0 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69  ally.** initiali
100e0 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  zed when [sqlite
100f0 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c  3_open()] is cal
10100 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f  led if it has no
10110 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64  t be initialized
10120 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e 48  .** already.  ^H
10130 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74  owever, if SQLit
10140 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
10150 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  th the [SQLITE_O
10160 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a  MIT_AUTOINIT].**
10170 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
10180 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61  tion, then the a
10190 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74  utomatic calls t
101a0 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  o sqlite3_initia
101b0 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d  lize().** are om
101c0 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 70  itted and the ap
101d0 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63  plication must c
101e0 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  all sqlite3_init
101f0 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c  ialize() directl
10200 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73  y.** prior to us
10210 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51  ing any other SQ
10220 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
10230 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72   For maximum por
10240 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20  tability,.** it 
10250 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
10260 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  hat applications
10270 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73   always invoke s
10280 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
10290 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20  e().** directly 
102a0 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61  prior to using a
102b0 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ny other SQLite 
102c0 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 75  interface.  Futu
102d0 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f  re releases.** o
102e0 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71  f SQLite may req
102f0 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f  uire this.  In o
10300 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
10310 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 74  behavior exhibit
10320 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74  ed.** when SQLit
10330 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
10340 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  th [SQLITE_OMIT_
10350 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20  AUTOINIT] might 
10360 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65  become the.** de
10370 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69  fault behavior i
10380 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65  n some future re
10390 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e  lease of SQLite.
103a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
103b0 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75  e3_os_init() rou
103c0 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74  tine does operat
103d0 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69  ing-system speci
103e0 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a  fic.** initializ
103f0 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c  ation of the SQL
10400 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68  ite library.  Th
10410 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  e sqlite3_os_end
10420 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e  ().** routine un
10430 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20  does the effect 
10440 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  of sqlite3_os_in
10450 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74  it().  Typical t
10460 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65  asks.** performe
10470 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 69  d by these routi
10480 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f  nes include allo
10490 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f  cation or deallo
104a0 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61  cation.** of sta
104b0 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69  tic resources, i
104c0 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66  nitialization of
104d0 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65   global variable
104e0 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70  s,.** setting up
104f0 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69   a default [sqli
10500 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c  te3_vfs] module,
10510 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a   or setting up.*
10520 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  * a default conf
10530 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20  iguration using 
10540 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
10550 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70  )]..**.** The ap
10560 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
10570 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69   never invoke ei
10580 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  ther sqlite3_os_
10590 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  init().** or sql
105a0 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69  ite3_os_end() di
105b0 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70  rectly.  The app
105c0 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
105d0 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73  only invoke.** s
105e0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
105f0 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
10600 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65  shutdown().  The
10610 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
10620 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
10630 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61  is called automa
10640 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74  tically by sqlit
10650 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
10660 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  and.** sqlite3_o
10670 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65  s_end() is calle
10680 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75  d by sqlite3_shu
10690 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70  tdown().  Approp
106a0 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  riate.** impleme
106b0 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c  ntations for sql
106c0 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61  ite3_os_init() a
106d0 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nd sqlite3_os_en
106e0 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74  d().** are built
106f0 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65   into SQLite whe
10700 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64  n it is compiled
10710 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f   for Unix, Windo
10720 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20  ws, or OS/2..** 
10730 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69  When [custom bui
10740 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 20  lds | built for 
10750 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d  other platforms]
10760 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20 5b  .** (using the [
10770 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d  SQLITE_OS_OTHER=
10780 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a  1] compile-time.
10790 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61  ** option) the a
107a0 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
107b0 73 75 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c  supply a suitabl
107c0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
107d0 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
107e0 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71  os_init() and sq
107f0 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20  lite3_os_end(). 
10800 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   An application-
10810 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c  supplied.** impl
10820 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71  ementation of sq
10830 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
10840 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  or sqlite3_os_en
10850 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75  d().** must retu
10860 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  rn [SQLITE_OK] o
10870 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f  n success and so
10880 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20  me other [error 
10890 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61  code] upon.** fa
108a0 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ilure..*/.int sq
108b0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
108c0 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69  (void);.int sqli
108d0 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69  te3_shutdown(voi
108e0 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
108f0 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 69  os_init(void);.i
10900 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nt sqlite3_os_en
10910 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20  d(void);../*.** 
10920 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67  CAPI3REF: Config
10930 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65  uring The SQLite
10940 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54   Library.**.** T
10950 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  he sqlite3_confi
10960 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  g() interface is
10970 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c   used to make gl
10980 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69  obal configurati
10990 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  on.** changes to
109a0 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72   SQLite in order
109b0 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20   to tune SQLite 
109c0 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20  to the specific 
109d0 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20  needs of.** the 
109e0 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68  application.  Th
109f0 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67  e default config
10a00 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d  uration is recom
10a10 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a  mended for most.
10a20 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** applications 
10a30 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74  and so this rout
10a40 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e  ine is usually n
10a50 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49  ot necessary.  I
10a60 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64  t is.** provided
10a70 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65   to support rare
10a80 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69   applications wi
10a90 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73  th unusual needs
10aa0 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 54 68 65 20 73  ..**.** <b>The s
10ab0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
10ac0 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74  interface is not
10ad0 20 74 68 72 65 61 64 73 61 66 65 2e 20 54 68 65   threadsafe. The
10ae0 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
10af0 6d 75 73 74 20 65 6e 73 75 72 65 20 74 68 61 74  must ensure that
10b00 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65   no other SQLite
10b10 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
10b20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72  invoked by other
10b30 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c  .** threads whil
10b40 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
10b50 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 3c 2f  () is running.</
10b60 62 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  b>.**.** The sql
10b70 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e  ite3_config() in
10b80 74 65 72 66 61 63 65 0a 2a 2a 20 6d 61 79 20 6f  terface.** may o
10b90 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70  nly be invoked p
10ba0 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20  rior to library 
10bb0 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75  initialization u
10bc0 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
10bd0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f  _initialize()] o
10be0 72 20 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e  r after shutdown
10bf0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75   by [sqlite3_shu
10c00 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66  tdown()]..** ^If
10c10 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
10c20 29 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65  ) is called afte
10c30 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  r [sqlite3_initi
10c40 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66  alize()] and bef
10c50 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ore.** [sqlite3_
10c60 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e  shutdown()] then
10c70 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20   it will return 
10c80 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a  SQLITE_MISUSE..*
10c90 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c  * Note, however,
10ca0 20 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63   that ^sqlite3_c
10cb0 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 63  onfig() can be c
10cc0 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66  alled as part of
10cd0 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   the.** implemen
10ce0 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70  tation of an app
10cf0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
10d00 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69   [sqlite3_os_ini
10d10 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  t()]..**.** The 
10d20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
10d30 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  o sqlite3_config
10d40 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  () is an integer
10d50 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74 69  .** [configurati
10d60 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20  on option] that 
10d70 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68  determines.** wh
10d80 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53  at property of S
10d90 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20 63  QLite is to be c
10da0 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62 73  onfigured.  Subs
10db0 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73  equent arguments
10dc0 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69  .** vary dependi
10dd0 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69  ng on the [confi
10de0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d  guration option]
10df0 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74  .** in the first
10e00 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
10e10 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75   ^When a configu
10e20 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
10e30 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f   set, sqlite3_co
10e40 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b  nfig() returns [
10e50 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e  SQLITE_OK]..** ^
10e60 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73  If the option is
10e70 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69   unknown or SQLi
10e80 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  te is unable to 
10e90 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a  set the option.*
10ea0 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74  * then this rout
10eb0 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f  ine returns a no
10ec0 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f  n-zero [error co
10ed0 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  de]..*/.int sqli
10ee0 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20  te3_config(int, 
10ef0 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ...);../*.** CAP
10f00 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65  I3REF: Configure
10f10 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
10f20 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  tions.** METHOD:
10f30 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54   sqlite3.**.** T
10f40 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  he sqlite3_db_co
10f50 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
10f60 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65   is used to make
10f70 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a   configuration.*
10f80 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b  * changes to a [
10f90 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
10fa0 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72  ion].  The inter
10fb0 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20  face is similar 
10fc0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
10fd0 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74 20  onfig()] except 
10fe0 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65 73  that the changes
10ff0 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67   apply to a sing
11000 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  le.** [database 
11010 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65  connection] (spe
11020 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66 69  cified in the fi
11030 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a 2a  rst argument)..*
11040 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  *.** The second 
11050 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
11060 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c  te3_db_config(D,
11070 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a  V,...)  is the.*
11080 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  * [SQLITE_DBCONF
11090 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 63  IG_LOOKASIDE | c
110a0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72  onfiguration ver
110b0 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20  b] - an integer 
110c0 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69 6e  code .** that in
110d0 64 69 63 61 74 65 73 20 77 68 61 74 20 61 73 70  dicates what asp
110e0 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61  ect of the [data
110f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
11100 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 67   is being config
11110 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71 75  ured..** Subsequ
11120 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76 61  ent arguments va
11130 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ry depending on 
11140 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
11150 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43  n verb..**.** ^C
11160 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
11170 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75  db_config() retu
11180 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20  rn SQLITE_OK if 
11190 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74  and only if.** t
111a0 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69  he call is consi
111b0 64 65 72 65 64 20 73 75 63 63 65 73 73 66 75 6c  dered successful
111c0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
111d0 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74  _db_config(sqlit
111e0 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e  e3*, int op, ...
111f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
11200 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63  EF: Memory Alloc
11210 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a  ation Routines.*
11220 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
11230 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
11240 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
11250 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53 51  rface between SQ
11260 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d  Lite.** and low-
11270 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  level memory all
11280 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
11290 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a  ..**.** This obj
112a0 65 63 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f  ect is used in o
112b0 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e  nly one place in
112c0 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65   the SQLite inte
112d0 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e  rface..** A poin
112e0 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
112f0 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
11300 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e  t is the argumen
11310 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  t to.** [sqlite3
11320 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20  _config()] when 
11330 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
11340 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b  n option is.** [
11350 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
11360 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45  LLOC] or [SQLITE
11370 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
11380 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65 61  C].  .** By crea
11390 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65  ting an instance
113a0 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a   of this object.
113b0 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69  ** and passing i
113c0 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
113d0 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f  nfig]([SQLITE_CO
113e0 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a  NFIG_MALLOC]).**
113f0 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72   during configur
11400 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63  ation, an applic
11410 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 66  ation can specif
11420 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65  y an alternative
11430 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
11440 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20  ation subsystem 
11450 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75 73  for SQLite to us
11460 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  e for all of its
11470 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f  .** dynamic memo
11480 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20  ry needs..**.** 
11490 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74 65  Note that SQLite
114a0 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76 65   comes with seve
114b0 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65  ral [built-in me
114c0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d  mory allocators]
114d0 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65 72  .** that are per
114e0 66 65 63 74 6c 79 20 61 64 65 71 75 61 74 65 20  fectly adequate 
114f0 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c  for the overwhel
11500 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66  ming majority of
11510 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
11520 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f   and that this o
11530 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73  bject is only us
11540 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d  eful to a tiny m
11550 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69  inority of appli
11560 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20  cations.** with 
11570 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f  specialized memo
11580 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65  ry allocation re
11590 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69  quirements.  Thi
115a0 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61  s object is.** a
115b0 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20  lso used during 
115c0 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74  testing of SQLit
115d0 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70  e in order to sp
115e0 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61  ecify an alterna
115f0 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  tive.** memory a
11600 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69  llocator that si
11610 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f  mulates memory o
11620 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e  ut-of-memory con
11630 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72  ditions in.** or
11640 64 65 72 20 74 6f 20 76 65 72 69 66 79 20 74 68  der to verify th
11650 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65  at SQLite recove
11660 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72  rs gracefully fr
11670 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69  om such.** condi
11680 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tions..**.** The
11690 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c   xMalloc, xReall
116a0 6f 63 2c 20 61 6e 64 20 78 46 72 65 65 20 6d 65  oc, and xFree me
116b0 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20  thods must work 
116c0 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c  like the.** mall
116d0 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20  oc(), realloc() 
116e0 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63 74  and free() funct
116f0 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74  ions from the st
11700 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
11710 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61  ..** ^SQLite gua
11720 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65  rantees that the
11730 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
11740 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20   to.** xRealloc 
11750 69 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c 75  is always a valu
11760 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 61 20  e returned by a 
11770 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52  prior call to xR
11780 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53  oundup..**.** xS
11790 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72  ize should retur
117a0 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20  n the allocated 
117b0 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79  size of a memory
117c0 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70   allocation.** p
117d0 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e  reviously obtain
117e0 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20  ed from xMalloc 
117f0 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68  or xRealloc.  Th
11800 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65  e allocated size
11810 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 74  .** is always at
11820 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61 73   least as big as
11830 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 73   the requested s
11840 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20 6c  ize but may be l
11850 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  arger..**.** The
11860 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64   xRoundup method
11870 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 77 6f   returns what wo
11880 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f 63  uld be the alloc
11890 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20  ated size of.** 
118a0 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
118b0 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72 74  ion given a part
118c0 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 65 64  icular requested
118d0 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d   size.  Most mem
118e0 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72  ory.** allocator
118f0 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72  s round up memor
11900 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74  y allocations at
11910 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e 65   least to the ne
11920 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f  xt multiple.** o
11930 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63  f 8.  Some alloc
11940 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 74  ators round up t
11950 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 69  o a larger multi
11960 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 65  ple or to a powe
11970 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79  r of 2..** Every
11980 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
11990 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69 6e  on request comin
119a0 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73 71  g in through [sq
119b0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a  lite3_malloc()].
119c0 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  ** or [sqlite3_r
119d0 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74 20  ealloc()] first 
119e0 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20  calls xRoundup. 
119f0 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65 74   If xRoundup ret
11a00 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74  urns 0, .** that
11a10 20 63 61 75 73 65 73 20 74 68 65 20 63 6f 72 72   causes the corr
11a20 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79  esponding memory
11a30 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66   allocation to f
11a40 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ail..**.** The x
11a50 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69 74  Init method init
11a60 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f  ializes the memo
11a70 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 46  ry allocator.  F
11a80 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69  or example,.** i
11a90 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 65  t might allocate
11aa0 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75 74   any require mut
11ab0 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c 69  exes or initiali
11ac0 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  ze internal data
11ad0 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e 20  .** structures. 
11ae0 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20 6d   The xShutdown m
11af0 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64  ethod is invoked
11b00 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62 79   (indirectly) by
11b10 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  .** [sqlite3_shu
11b20 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f  tdown()] and sho
11b30 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 61  uld deallocate a
11b40 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61 63 71  ny resources acq
11b50 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69  uired.** by xIni
11b60 74 2e 20 20 54 68 65 20 70 41 70 70 44 61 74 61  t.  The pAppData
11b70 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65 64   pointer is used
11b80 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72   as the only par
11b90 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e  ameter to.** xIn
11ba0 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e  it and xShutdown
11bb0 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68  ..**.** SQLite h
11bc0 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45  olds the [SQLITE
11bd0 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41  _MUTEX_STATIC_MA
11be0 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68 65 6e  STER] mutex when
11bf0 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74   it invokes.** t
11c00 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c  he xInit method,
11c10 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20 6d 65   so the xInit me
11c20 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62 65  thod need not be
11c30 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68   threadsafe.  Th
11c40 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d  e.** xShutdown m
11c50 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61  ethod is only ca
11c60 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  lled from [sqlit
11c70 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 73  e3_shutdown()] s
11c80 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  o it does.** not
11c90 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68 72 65   need to be thre
11ca0 61 64 73 61 66 65 20 65 69 74 68 65 72 2e 20 20  adsafe either.  
11cb0 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65  For all other me
11cc0 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a  thods, SQLite.**
11cd0 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49   holds the [SQLI
11ce0 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
11cf0 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f  MEM] mutex as lo
11d00 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51  ng as the.** [SQ
11d10 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
11d20 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 72 61  TATUS] configura
11d30 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74  tion option is t
11d40 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 68 0a  urned on (which.
11d50 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65 66 61  ** it is by defa
11d60 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 65 20  ult) and so the 
11d70 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75 74 6f  methods are auto
11d80 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69 61 6c  matically serial
11d90 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72  ized..** However
11da0 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  , if [SQLITE_CON
11db0 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69  FIG_MEMSTATUS] i
11dc0 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 6e  s disabled, then
11dd0 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65   the other.** me
11de0 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20 74 68  thods must be th
11df0 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c 73 65  readsafe or else
11e00 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 6e 20   make their own 
11e10 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72  arrangements for
11e20 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 69 6f  .** serializatio
11e30 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  n..**.** SQLite 
11e40 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b  will never invok
11e50 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 20 74  e xInit() more t
11e60 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75 74  han once without
11e70 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a   an intervening.
11e80 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 75 74  ** call to xShut
11e90 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64  down()..*/.typed
11ea0 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
11eb0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71  3_mem_methods sq
11ec0 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
11ed0 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  s;.struct sqlite
11ee0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a  3_mem_methods {.
11ef0 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f    void *(*xMallo
11f00 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20  c)(int);        
11f10 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63   /* Memory alloc
11f20 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a  ation function *
11f30 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65 65  /.  void (*xFree
11f40 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20  )(void*);       
11f50 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69     /* Free a pri
11f60 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f  or allocation */
11f70 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c  .  void *(*xReal
11f80 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b  loc)(void*,int);
11f90 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61    /* Resize an a
11fa0 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69  llocation */.  i
11fb0 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 64  nt (*xSize)(void
11fc0 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a  *);           /*
11fd0 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65   Return the size
11fe0 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f   of an allocatio
11ff0 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f  n */.  int (*xRo
12000 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20  undup)(int);    
12010 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75        /* Round u
12020 70 20 72 65 71 75 65 73 74 20 73 69 7a 65 20 74  p request size t
12030 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  o allocation siz
12040 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e  e */.  int (*xIn
12050 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  it)(void*);     
12060 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c        /* Initial
12070 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ize the memory a
12080 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f  llocator */.  vo
12090 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28  id (*xShutdown)(
120a0 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20  void*);      /* 
120b0 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65  Deinitialize the
120c0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
120d0 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70  r */.  void *pAp
120e0 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20  pData;          
120f0 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e        /* Argumen
12100 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64  t to xInit() and
12110 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a   xShutdown() */.
12120 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
12130 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f  EF: Configuratio
12140 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59  n Options.** KEY
12150 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72  WORDS: {configur
12160 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a  ation option}.**
12170 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
12180 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69  nts are the avai
12190 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f  lable integer co
121a0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
121b0 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20  ons that.** can 
121c0 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
121d0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
121e0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
121f0 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
12200 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63  ace..**.** New c
12210 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
12220 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65  ions may be adde
12230 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
12240 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
12250 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66  ** Existing conf
12260 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
12270 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f  s might be disco
12280 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63  ntinued.  Applic
12290 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64  ations.** should
122a0 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72   check the retur
122b0 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c  n code from [sql
122c0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74  ite3_config()] t
122d0 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74  o make sure that
122e0 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72  .** the call wor
122f0 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ked.  The [sqlit
12300 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  e3_config()] int
12310 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75  erface will retu
12320 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f  rn a.** non-zero
12330 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66   [error code] if
12340 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20   a discontinued 
12350 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63  or unsupported c
12360 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
12370 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65  ion.** is invoke
12380 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  d..**.** <dl>.**
12390 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
123a0 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20  _SINGLETHREAD]] 
123b0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
123c0 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f  G_SINGLETHREAD</
123d0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65  dt>.** <dd>There
123e0 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74   are no argument
123f0 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
12400 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  .  ^This option 
12410 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72  sets the.** [thr
12420 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20  eading mode] to 
12430 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20 20  Single-thread.  
12440 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
12450 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61  it disables.** a
12460 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20  ll mutexing and 
12470 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f  puts SQLite into
12480 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74   a mode where it
12490 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65   can only be use
124a0 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65  d.** by a single
124b0 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20 53   thread.   ^If S
124c0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
124d0 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
124e0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
124f0 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
12500 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
12510 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
12520 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f  .** it is not po
12530 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67 65  ssible to change
12540 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20   the [threading 
12550 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20 64  mode] from its d
12560 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20  efault.** value 
12570 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64  of Single-thread
12580 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65 33   and so [sqlite3
12590 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20  _config()] will 
125a0 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49  return .** [SQLI
125b0 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c  TE_ERROR] if cal
125c0 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c  led with the SQL
125d0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
125e0 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69  ETHREAD.** confi
125f0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
12600 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
12610 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
12620 49 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51  ITHREAD]] <dt>SQ
12630 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
12640 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20  ITHREAD</dt>.** 
12650 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f  <dd>There are no
12660 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
12670 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69  is option.  ^Thi
12680 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68  s option sets th
12690 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20  e.** [threading 
126a0 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74  mode] to Multi-t
126b0 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72  hread.  In other
126c0 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62   words, it disab
126d0 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20  les.** mutexing 
126e0 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  on [database con
126f0 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72  nection] and [pr
12700 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
12710 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68  ] objects..** Th
12720 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73  e application is
12730 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
12740 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63   serializing acc
12750 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62  ess to.** [datab
12760 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
12770 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
12780 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74  tatements].  But
12790 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a   other mutexes.*
127a0 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f  * are enabled so
127b0 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
127c0 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 73 65  l be safe to use
127d0 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65   in a multi-thre
127e0 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d  aded.** environm
127f0 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e  ent as long as n
12800 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 61 74  o two threads at
12810 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65  tempt to use the
12820 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61   same.** [databa
12830 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
12840 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e  t the same time.
12850 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20    ^If SQLite is 
12860 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
12870 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
12880 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
12890 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
128a0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
128b0 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73  on then.** it is
128c0 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f   not possible to
128d0 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d 74   set the Multi-t
128e0 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67  hread [threading
128f0 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73   mode] and.** [s
12900 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
12910 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
12920 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
12930 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  alled with the.*
12940 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  * SQLITE_CONFIG_
12950 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e 66  MULTITHREAD conf
12960 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
12970 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
12980 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
12990 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51  IALIZED]] <dt>SQ
129a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
129b0 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  ALIZED</dt>.** <
129c0 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20  dd>There are no 
129d0 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
129e0 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73  s option.  ^This
129f0 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65   option sets the
12a00 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  .** [threading m
12a10 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a  ode] to Serializ
12a20 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  ed. In other wor
12a30 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e 20  ds, this option 
12a40 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d  enables.** all m
12a50 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e 67  utexes including
12a60 20 74 68 65 20 72 65 63 75 72 73 69 76 65 0a 2a   the recursive.*
12a70 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 61  * mutexes on [da
12a80 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
12a90 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  n] and [prepared
12aa0 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65   statement] obje
12ab0 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20  cts..** In this 
12ac0 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73 20 74  mode (which is t
12ad0 68 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e 20  he default when 
12ae0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
12af0 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49  ed with.** [SQLI
12b00 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 5d  TE_THREADSAFE=1]
12b10 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  ) the SQLite lib
12b20 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66  rary will itself
12b30 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73   serialize acces
12b40 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73  s.** to [databas
12b50 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61  e connections] a
12b60 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  nd [prepared sta
12b70 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74  tements] so that
12b80 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74   the.** applicat
12b90 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75  ion is free to u
12ba0 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  se the same [dat
12bb0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
12bc0 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65  ] or the.** same
12bd0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
12be0 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65  ment] in differe
12bf0 6e 74 20 74 68 72 65 61 64 73 20 61 74 20 74 68  nt threads at th
12c00 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20  e same time..** 
12c10 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
12c20 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
12c30 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
12c40 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
12c50 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
12c60 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
12c70 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e   then.** it is n
12c80 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73  ot possible to s
12c90 65 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a 65  et the Serialize
12ca0 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
12cb0 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  e] and.** [sqlit
12cc0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c  e3_config()] wil
12cd0 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
12ce0 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65  _ERROR] if calle
12cf0 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51  d with the.** SQ
12d00 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
12d10 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72 61  ALIZED configura
12d20 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64  tion option.</dd
12d30 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
12d40 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d  _CONFIG_MALLOC]]
12d50 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
12d60 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a  IG_MALLOC</dt>.*
12d70 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c  * <dd> ^(The SQL
12d80 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
12d90 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  C option takes a
12da0 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
12db0 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 61 20   which is .** a 
12dc0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
12dd0 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
12de0 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
12df0 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a  ds] structure..*
12e00 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73  * The argument s
12e10 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65  pecifies.** alte
12e20 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65  rnative low-leve
12e30 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
12e40 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ion routines to 
12e50 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65  be used in place
12e60 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72   of.** the memor
12e70 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
12e80 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f  tines built into
12e90 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69   SQLite.)^ ^SQLi
12ea0 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20  te makes.** its 
12eb0 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79  own private copy
12ec0 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20   of the content 
12ed0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
12ee0 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  mem_methods] str
12ef0 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65  ucture.** before
12f00 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
12f10 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65 74  nfig()] call ret
12f20 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  urns.</dd>.**.**
12f30 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
12f40 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74  _GETMALLOC]] <dt
12f50 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
12f60 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a  ETMALLOC</dt>.**
12f70 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49   <dd> ^(The SQLI
12f80 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
12f90 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  LOC option takes
12fa0 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
12fb0 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61  nt which.** is a
12fc0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
12fd0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
12fe0 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
12ff0 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a  ods] structure..
13000 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
13010 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  mem_methods].** 
13020 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c  structure is fil
13030 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72  led with the cur
13040 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d  rently defined m
13050 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
13060 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20   routines.)^.** 
13070 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20  This option can 
13080 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c  be used to overl
13090 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20  oad the default 
130a0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
130b0 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69  n.** routines wi
130c0 74 68 20 61 20 77 72 61 70 70 65 72 20 74 68 61  th a wrapper tha
130d0 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65  t simulations me
130e0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
130f0 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72  failure or.** tr
13100 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67  acks memory usag
13110 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20  e, for example. 
13120 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
13130 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
13140 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49  TATUS]] <dt>SQLI
13150 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
13160 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TUS</dt>.** <dd>
13170 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e   ^The SQLITE_CON
13180 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 6f 70  FIG_MEMSTATUS op
13190 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c  tion takes singl
131a0 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79  e argument of ty
131b0 70 65 20 69 6e 74 2c 0a 2a 2a 20 69 6e 74 65 72  pe int,.** inter
131c0 70 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c  preted as a bool
131d0 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c  ean, which enabl
131e0 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74  es or disables t
131f0 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66  he collection of
13200 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
13210 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73  ation statistics
13220 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20  . ^(When memory 
13230 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
13240 73 74 69 63 73 20 61 72 65 0a 2a 2a 20 64 69 73  stics are.** dis
13250 61 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c 6c 6f  abled, the follo
13260 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65  wing SQLite inte
13270 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f  rfaces become no
13280 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a  n-operational:.*
13290 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  *   <ul>.**   <l
132a0 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  i> [sqlite3_memo
132b0 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20  ry_used()].**   
132c0 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65  <li> [sqlite3_me
132d0 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
132e0 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
132f0 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
13300 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c  imit64()].**   <
13310 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61  li> [sqlite3_sta
13320 74 75 73 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 2f  tus64()].**   </
13330 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79  ul>)^.** ^Memory
13340 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74   allocation stat
13350 69 73 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c  istics are enabl
13360 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e  ed by default un
13370 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a  less SQLite is.*
13380 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  * compiled with 
13390 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f  [SQLITE_DEFAULT_
133a0 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20  MEMSTATUS]=0 in 
133b0 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72  which case memor
133c0 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  y.** allocation 
133d0 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64  statistics are d
133e0 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
133f0 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a  lt..** </dd>.**.
13400 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
13410 49 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64 74  IG_SCRATCH]] <dt
13420 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
13430 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  CRATCH</dt>.** <
13440 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  dd> ^The SQLITE_
13450 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 6f  CONFIG_SCRATCH o
13460 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20  ption specifies 
13470 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20  a static memory 
13480 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 53  buffer.** that S
13490 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f  QLite can use fo
134a0 72 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79  r scratch memory
134b0 2e 20 20 5e 28 54 68 65 72 65 20 61 72 65 20 74  .  ^(There are t
134c0 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 0a 2a  hree arguments.*
134d0 2a 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46  * to SQLITE_CONF
134e0 49 47 5f 53 43 52 41 54 43 48 3a 20 20 41 20 70  IG_SCRATCH:  A p
134f0 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79 74 65  ointer an 8-byte
13500 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f  .** aligned memo
13510 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d 20 77  ry buffer from w
13520 68 69 63 68 20 74 68 65 20 73 63 72 61 74 63 68  hich the scratch
13530 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c   allocations wil
13540 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74  l be.** drawn, t
13550 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  he size of each 
13560 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69  scratch allocati
13570 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20  on (sz),.** and 
13580 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  the maximum numb
13590 65 72 20 6f 66 20 73 63 72 61 74 63 68 20 61 6c  er of scratch al
135a0 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e 29 5e  locations (N).)^
135b0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
135c0 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61  gument must be a
135d0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38   pointer to an 8
135e0 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75  -byte aligned bu
135f0 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65  ffer.** of at le
13600 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f  ast sz*N bytes o
13610 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51  f memory..** ^SQ
13620 4c 69 74 65 20 77 69 6c 6c 20 6e 6f 74 20 75 73  Lite will not us
13630 65 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  e more than one 
13640 73 63 72 61 74 63 68 20 62 75 66 66 65 72 73 20  scratch buffers 
13650 70 65 72 20 74 68 72 65 61 64 2e 0a 2a 2a 20 5e  per thread..** ^
13660 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65  SQLite will neve
13670 72 20 72 65 71 75 65 73 74 20 61 20 73 63 72 61  r request a scra
13680 74 63 68 20 62 75 66 66 65 72 20 74 68 61 74 20  tch buffer that 
13690 69 73 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a  is more than 6.*
136a0 2a 20 74 69 6d 65 73 20 74 68 65 20 64 61 74 61  * times the data
136b0 62 61 73 65 20 70 61 67 65 20 73 69 7a 65 2e 0a  base page size..
136c0 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 6e 65  ** ^If SQLite ne
136d0 65 64 73 20 6e 65 65 64 73 20 61 64 64 69 74 69  eds needs additi
136e0 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20  onal.** scratch 
136f0 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77 68  memory beyond wh
13700 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62  at is provided b
13710 79 20 74 68 69 73 20 63 6f 6e 66 69 67 75 72 61  y this configura
13720 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65  tion option, the
13730 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  n .** [sqlite3_m
13740 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65  alloc()] will be
13750 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20   used to obtain 
13760 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65  the memory neede
13770 64 2e 3c 70 3e 0a 2a 2a 20 5e 57 68 65 6e 20 74  d.<p>.** ^When t
13780 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 70  he application p
13790 72 6f 76 69 64 65 73 20 61 6e 79 20 61 6d 6f 75  rovides any amou
137a0 6e 74 20 6f 66 20 73 63 72 61 74 63 68 20 6d 65  nt of scratch me
137b0 6d 6f 72 79 20 75 73 69 6e 67 0a 2a 2a 20 53 51  mory using.** SQ
137c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
137d0 54 43 48 2c 20 53 51 4c 69 74 65 20 61 76 6f 69  TCH, SQLite avoi
137e0 64 73 20 75 6e 6e 65 63 65 73 73 61 72 79 20 6c  ds unnecessary l
137f0 61 72 67 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  arge.** [sqlite3
13800 5f 6d 61 6c 6c 6f 63 7c 68 65 61 70 20 61 6c 6c  _malloc|heap all
13810 6f 63 61 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68  ocations]..** Th
13820 69 73 20 63 61 6e 20 68 65 6c 70 20 5b 52 6f 62  is can help [Rob
13830 73 6f 6e 20 70 72 6f 6f 66 7c 70 72 65 76 65 6e  son proof|preven
13840 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  t memory allocat
13850 69 6f 6e 20 66 61 69 6c 75 72 65 73 5d 20 64 75  ion failures] du
13860 65 20 74 6f 20 68 65 61 70 0a 2a 2a 20 66 72 61  e to heap.** fra
13870 67 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 20 6c 6f  gmentation in lo
13880 77 2d 6d 65 6d 6f 72 79 20 65 6d 62 65 64 64 65  w-memory embedde
13890 64 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 20 3c 2f  d systems..** </
138a0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
138b0 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
138c0 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  CHE]] <dt>SQLITE
138d0 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
138e0 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
138f0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
13900 47 5f 50 41 47 45 43 41 43 48 45 20 6f 70 74 69  G_PAGECACHE opti
13910 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 6d  on specifies a m
13920 65 6d 6f 72 79 20 70 6f 6f 6c 0a 2a 2a 20 74 68  emory pool.** th
13930 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73  at SQLite can us
13940 65 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61  e for the databa
13950 73 65 20 70 61 67 65 20 63 61 63 68 65 20 77 69  se page cache wi
13960 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 20 70  th the default p
13970 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70  age.** cache imp
13980 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a  lementation.  .*
13990 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61  * This configura
139a0 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 61  tion option is a
139b0 20 6e 6f 2d 6f 70 20 69 66 20 61 6e 20 61 70 70   no-op if an app
139c0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20  lication-define 
139d0 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d  page.** cache im
139e0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20  plementation is 
139f0 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68 65  loaded using the
13a00 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
13a10 50 43 41 43 48 45 32 5d 2e 0a 2a 2a 20 5e 54 68  PCACHE2]..** ^Th
13a20 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
13a30 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54  guments to SQLIT
13a40 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
13a50 48 45 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  HE: A pointer to
13a60 0a 2a 2a 20 38 2d 62 79 74 65 20 61 6c 69 67 6e  .** 8-byte align
13a70 65 64 20 6d 65 6d 6f 72 79 20 28 70 4d 65 6d 29  ed memory (pMem)
13a80 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61  , the size of ea
13a90 63 68 20 70 61 67 65 20 63 61 63 68 65 20 6c 69  ch page cache li
13aa0 6e 65 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20  ne (sz),.** and 
13ab0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 61  the number of ca
13ac0 63 68 65 20 6c 69 6e 65 73 20 28 4e 29 2e 0a 2a  che lines (N)..*
13ad0 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e  * The sz argumen
13ae0 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20  t should be the 
13af0 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67  size of the larg
13b00 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67  est database pag
13b10 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66  e.** (a power of
13b20 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32   two between 512
13b30 20 61 6e 64 20 36 35 35 33 36 29 20 70 6c 75 73   and 65536) plus
13b40 20 73 6f 6d 65 20 65 78 74 72 61 20 62 79 74 65   some extra byte
13b50 73 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61  s for each.** pa
13b60 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65  ge header.  ^The
13b70 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61   number of extra
13b80 20 62 79 74 65 73 20 6e 65 65 64 65 64 20 62 79   bytes needed by
13b90 20 74 68 65 20 70 61 67 65 20 68 65 61 64 65 72   the page header
13ba0 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65 72  .** can be deter
13bb0 6d 69 6e 65 64 20 75 73 69 6e 67 20 5b 53 51 4c  mined using [SQL
13bc0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
13bd0 45 5f 48 44 52 53 5a 5d 2e 0a 2a 2a 20 5e 49 74  E_HDRSZ]..** ^It
13be0 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70   is harmless, ap
13bf0 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73  art from the was
13c00 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 66  ted memory,.** f
13c10 6f 72 20 74 68 65 20 73 7a 20 70 61 72 61 6d 65  or the sz parame
13c20 74 65 72 20 74 6f 20 62 65 20 6c 61 72 67 65 72  ter to be larger
13c30 20 74 68 61 6e 20 6e 65 63 65 73 73 61 72 79 2e   than necessary.
13c40 20 20 54 68 65 20 70 4d 65 6d 0a 2a 2a 20 61 72    The pMem.** ar
13c50 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 65  gument must be e
13c60 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69  ither a NULL poi
13c70 6e 74 65 72 20 6f 72 20 61 20 70 6f 69 6e 74 65  nter or a pointe
13c80 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a  r to an 8-byte.*
13c90 2a 20 61 6c 69 67 6e 65 64 20 62 6c 6f 63 6b 20  * aligned block 
13ca0 6f 66 20 6d 65 6d 6f 72 79 20 6f 66 20 61 74 20  of memory of at 
13cb0 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73  least sz*N bytes
13cc0 2c 20 6f 74 68 65 72 77 69 73 65 0a 2a 2a 20 73  , otherwise.** s
13cd0 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69  ubsequent behavi
13ce0 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
13cf0 0a 2a 2a 20 5e 57 68 65 6e 20 70 4d 65 6d 20 69  .** ^When pMem i
13d00 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69  s not NULL, SQLi
13d10 74 65 20 77 69 6c 6c 20 73 74 72 69 76 65 20 74  te will strive t
13d20 6f 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  o use the memory
13d30 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 74 6f 20   provided.** to 
13d40 73 61 74 69 73 66 79 20 70 61 67 65 20 63 61 63  satisfy page cac
13d50 68 65 20 6e 65 65 64 73 2c 20 66 61 6c 6c 69 6e  he needs, fallin
13d60 67 20 62 61 63 6b 20 74 6f 20 5b 73 71 6c 69 74  g back to [sqlit
13d70 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 66 0a  e3_malloc()] if.
13d80 2a 2a 20 61 20 70 61 67 65 20 63 61 63 68 65 20  ** a page cache 
13d90 6c 69 6e 65 20 69 73 20 6c 61 72 67 65 72 20 74  line is larger t
13da0 68 61 6e 20 73 7a 20 62 79 74 65 73 20 6f 72 20  han sz bytes or 
13db0 69 66 20 61 6c 6c 20 6f 66 20 74 68 65 20 70 4d  if all of the pM
13dc0 65 6d 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20  em buffer.** is 
13dd0 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 5e 49  exhausted..** ^I
13de0 66 20 70 4d 65 6d 20 69 73 20 4e 55 4c 4c 20 61  f pMem is NULL a
13df0 6e 64 20 4e 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f  nd N is non-zero
13e00 2c 20 74 68 65 6e 20 65 61 63 68 20 64 61 74 61  , then each data
13e10 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
13e20 2a 2a 20 64 6f 65 73 20 61 6e 20 69 6e 69 74 69  ** does an initi
13e30 61 6c 20 62 75 6c 6b 20 61 6c 6c 6f 63 61 74 69  al bulk allocati
13e40 6f 6e 20 66 6f 72 20 70 61 67 65 20 63 61 63 68  on for page cach
13e50 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 66 72 6f 6d  e memory.** from
13e60 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
13e70 28 29 5d 20 73 75 66 66 69 63 69 65 6e 74 20 66  ()] sufficient f
13e80 6f 72 20 4e 20 63 61 63 68 65 20 6c 69 6e 65 73  or N cache lines
13e90 20 69 66 20 4e 20 69 73 20 70 6f 73 69 74 69 76   if N is positiv
13ea0 65 20 6f 72 0a 2a 2a 20 6f 66 20 2d 31 30 32 34  e or.** of -1024
13eb0 2a 4e 20 62 79 74 65 73 20 69 66 20 4e 20 69 73  *N bytes if N is
13ec0 20 6e 65 67 61 74 69 76 65 2c 20 2e 20 5e 49 66   negative, . ^If
13ed0 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70   additional.** p
13ee0 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79  age cache memory
13ef0 20 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e   is needed beyon
13f00 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64  d what is provid
13f10 65 64 20 62 79 20 74 68 65 20 69 6e 69 74 69 61  ed by the initia
13f20 6c 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c  l.** allocation,
13f30 20 74 68 65 6e 20 53 51 4c 69 74 65 20 67 6f 65   then SQLite goe
13f40 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61  s to [sqlite3_ma
13f50 6c 6c 6f 63 28 29 5d 20 73 65 70 61 72 61 74 65  lloc()] separate
13f60 6c 79 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 61  ly for each.** a
13f70 64 64 69 74 69 6f 6e 61 6c 20 63 61 63 68 65 20  dditional cache 
13f80 6c 69 6e 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  line. </dd>.**.*
13f90 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
13fa0 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c  G_HEAP]] <dt>SQL
13fb0 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c  ITE_CONFIG_HEAP<
13fc0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
13fd0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
13fe0 48 45 41 50 20 6f 70 74 69 6f 6e 20 73 70 65 63  HEAP option spec
13ff0 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d  ifies a static m
14000 65 6d 6f 72 79 20 62 75 66 66 65 72 20 0a 2a 2a  emory buffer .**
14010 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
14020 6c 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66  l use for all of
14030 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d   its dynamic mem
14040 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
14050 65 65 64 73 0a 2a 2a 20 62 65 79 6f 6e 64 20 74  eeds.** beyond t
14060 68 6f 73 65 20 70 72 6f 76 69 64 65 64 20 66 6f  hose provided fo
14070 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  r by [SQLITE_CON
14080 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64  FIG_SCRATCH] and
14090 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
140a0 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a  IG_PAGECACHE]..*
140b0 2a 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  * ^The SQLITE_CO
140c0 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e  NFIG_HEAP option
140d0 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62   is only availab
140e0 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  le if SQLite is 
140f0 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68  compiled.** with
14100 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
14110 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20  ENABLE_MEMSYS3] 
14120 6f 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  or [SQLITE_ENABL
14130 45 5f 4d 45 4d 53 59 53 35 5d 20 61 6e 64 20 72  E_MEMSYS5] and r
14140 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54  eturns.** [SQLIT
14150 45 5f 45 52 52 4f 52 5d 20 69 66 20 69 6e 76 6f  E_ERROR] if invo
14160 6b 65 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a  ked otherwise..*
14170 2a 20 5e 54 68 65 72 65 20 61 72 65 20 74 68 72  * ^There are thr
14180 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  ee arguments to 
14190 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
141a0 41 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79 74 65  AP:.** An 8-byte
141b0 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72   aligned pointer
141c0 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a   to the memory,.
141d0 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
141e0 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65   bytes in the me
141f0 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64  mory buffer, and
14200 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   the minimum all
14210 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a  ocation size..**
14220 20 5e 49 66 20 74 68 65 20 66 69 72 73 74 20 70   ^If the first p
14230 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f  ointer (the memo
14240 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e  ry pointer) is N
14250 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ULL, then SQLite
14260 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75   reverts.** to u
14270 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74  sing its default
14280 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
14290 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61  r (the system ma
142a0 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74  lloc() implement
142b0 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69  ation),.** undoi
142c0 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76  ng any prior inv
142d0 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49  ocation of [SQLI
142e0 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
142f0 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d  ].  ^If the.** m
14300 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73  emory pointer is
14310 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 74   not NULL then t
14320 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d  he alternative m
14330 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
14340 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f  or is engaged to
14350 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53   handle all of S
14360 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c  QLites memory al
14370 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a  location needs..
14380 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f 69  ** The first poi
14390 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79  nter (the memory
143a0 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62   pointer) must b
143b0 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
143c0 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61  8-byte.** bounda
143d0 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74  ry or subsequent
143e0 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c   behavior of SQL
143f0 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65  ite will be unde
14400 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69  fined..** The mi
14410 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e  nimum allocation
14420 20 73 69 7a 65 20 69 73 20 63 61 70 70 65 64 20   size is capped 
14430 61 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e  at 2**12. Reason
14440 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66  able values.** f
14450 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61  or the minimum a
14460 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61  llocation size a
14470 72 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20  re 2**5 through 
14480 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  2**8.</dd>.**.**
14490 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
144a0 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c  _MUTEX]] <dt>SQL
144b0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
144c0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
144d0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
144e0 47 5f 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74  G_MUTEX option t
144f0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
14500 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
14510 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20  a.** pointer to 
14520 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
14530 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
14540 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
14550 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67  ture..** The arg
14560 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 20  ument specifies 
14570 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d  alternative low-
14580 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74  level mutex rout
14590 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 0a  ines to be used.
145a0 2a 2a 20 69 6e 20 70 6c 61 63 65 20 74 68 65 20  ** in place the 
145b0 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62  mutex routines b
145c0 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65  uilt into SQLite
145d0 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b  .)^  ^SQLite mak
145e0 65 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  es a copy of.** 
145f0 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
14600 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
14610 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
14620 74 75 72 65 20 62 65 66 6f 72 65 20 74 68 65 20  ture before the 
14630 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
14640 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65  te3_config()] re
14650 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74  turns. ^If SQLit
14660 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
14670 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
14680 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
14690 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
146a0 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
146b0 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
146c0 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78  the entire mutex
146d0 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73  ing subsystem is
146e0 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
146f0 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63  e build and henc
14700 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73  e calls to.** [s
14710 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
14720 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
14730 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f  _CONFIG_MUTEX co
14740 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
14750 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72  on will.** retur
14760 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
14770 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
14780 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
14790 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49  MUTEX]] <dt>SQLI
147a0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
147b0 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  EX</dt>.** <dd> 
147c0 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  ^(The SQLITE_CON
147d0 46 49 47 5f 47 45 54 4d 55 54 45 58 20 6f 70 74  FIG_GETMUTEX opt
147e0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
147f0 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
14800 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65  h.** is a pointe
14810 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
14820 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
14830 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
14840 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a  structure.  The.
14850 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ** [sqlite3_mute
14860 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74  x_methods].** st
14870 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65  ructure is fille
14880 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  d with the curre
14890 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74  ntly defined mut
148a0 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a  ex routines.)^.*
148b0 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61  * This option ca
148c0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65  n be used to ove
148d0 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c  rload the defaul
148e0 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69  t mutex allocati
148f0 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77  on.** routines w
14900 69 74 68 20 61 20 77 72 61 70 70 65 72 20 75 73  ith a wrapper us
14910 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65  ed to track mute
14920 78 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 66  x usage for perf
14930 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69  ormance.** profi
14940 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c  ling or testing,
14950 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20   for example.   
14960 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
14970 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
14980 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
14990 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
149a0 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
149b0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
149c0 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74   then.** the ent
149d0 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62  ire mutexing sub
149e0 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65  system is omitte
149f0 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64  d from the build
14a00 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73   and hence calls
14a10 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
14a20 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74  config()] with t
14a30 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
14a40 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67  _GETMUTEX config
14a50 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77  uration option w
14a60 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  ill.** return [S
14a70 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64  QLITE_ERROR].</d
14a80 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
14a90 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
14aa0 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  DE]] <dt>SQLITE_
14ab0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
14ac0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
14ad0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
14ae0 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f 70 74 69  G_LOOKASIDE opti
14af0 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67  on takes two arg
14b00 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65  uments that dete
14b10 72 6d 69 6e 65 0a 2a 2a 20 74 68 65 20 64 65 66  rmine.** the def
14b20 61 75 6c 74 20 73 69 7a 65 20 6f 66 20 6c 6f 6f  ault size of loo
14b30 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 6f 6e  kaside memory on
14b40 20 65 61 63 68 20 5b 64 61 74 61 62 61 73 65 20   each [database 
14b50 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20  connection]..** 
14b60 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
14b70 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a  nt is the.** siz
14b80 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73  e of each lookas
14b90 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20  ide buffer slot 
14ba0 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69  and the second i
14bb0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  s the number of.
14bc0 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74  ** slots allocat
14bd0 65 64 20 74 6f 20 65 61 63 68 20 64 61 74 61 62  ed to each datab
14be0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29  ase connection.)
14bf0 5e 20 20 5e 28 53 51 4c 49 54 45 5f 43 4f 4e 46  ^  ^(SQLITE_CONF
14c00 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a 2a 20  IG_LOOKASIDE.** 
14c10 73 65 74 73 20 74 68 65 20 3c 69 3e 64 65 66 61  sets the <i>defa
14c20 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64  ult</i> lookasid
14c30 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c  e size. The [SQL
14c40 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
14c50 4b 41 53 49 44 45 5d 0a 2a 2a 20 6f 70 74 69 6f  KASIDE].** optio
14c60 6e 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62  n to [sqlite3_db
14c70 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62  _config()] can b
14c80 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65  e used to change
14c90 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a   the lookaside.*
14ca0 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
14cb0 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f  on individual co
14cc0 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64  nnections.)^ </d
14cd0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
14ce0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32  E_CONFIG_PCACHE2
14cf0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
14d00 4e 46 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 74  NFIG_PCACHE2</dt
14d10 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20  >.** <dd> ^(The 
14d20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
14d30 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b  ACHE2 option tak
14d40 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
14d50 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a  ment which is .*
14d60 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * a pointer to a
14d70 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68  n [sqlite3_pcach
14d80 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65  e_methods2] obje
14d90 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74  ct.  This object
14da0 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68   specifies.** th
14db0 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 61  e interface to a
14dc0 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63   custom page cac
14dd0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
14de0 6e 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  n.)^.** ^SQLite 
14df0 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
14e00 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 63 61  the [sqlite3_pca
14e10 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62  che_methods2] ob
14e20 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ject.</dd>.**.**
14e30 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
14e40 5f 47 45 54 50 43 41 43 48 45 32 5d 5d 20 3c 64  _GETPCACHE2]] <d
14e50 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
14e60 47 45 54 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a  GETPCACHE2</dt>.
14e70 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51  ** <dd> ^(The SQ
14e80 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
14e90 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61  CACHE2 option ta
14ea0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
14eb0 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69  ument which.** i
14ec0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
14ed0 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68  n [sqlite3_pcach
14ee0 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65  e_methods2] obje
14ef0 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69  ct.  SQLite copi
14f00 65 73 20 6f 66 0a 2a 2a 20 74 68 65 20 63 75 72  es of.** the cur
14f10 72 65 6e 74 20 70 61 67 65 20 63 61 63 68 65 20  rent page cache 
14f20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
14f30 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e  nto that object.
14f40 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  )^ </dd>.**.** [
14f50 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  [SQLITE_CONFIG_L
14f60 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  OG]] <dt>SQLITE_
14f70 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a  CONFIG_LOG</dt>.
14f80 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49  ** <dd> The SQLI
14f90 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70  TE_CONFIG_LOG op
14fa0 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
14fb0 63 6f 6e 66 69 67 75 72 65 20 74 68 65 20 53 51  configure the SQ
14fc0 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b  Lite.** global [
14fd0 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28  error log]..** (
14fe0 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
14ff0 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61  IG_LOG option ta
15000 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  kes two argument
15010 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  s: a pointer to 
15020 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69  a.** function wi
15030 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74  th a call signat
15040 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76  ure of void(*)(v
15050 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63  oid*,int,const c
15060 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61  har*), .** and a
15070 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64   pointer to void
15080 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69  . ^If the functi
15090 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f  on pointer is no
150a0 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a  t NULL, it is.**
150b0 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c   invoked by [sql
150c0 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70  ite3_log()] to p
150d0 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67  rocess each logg
150e0 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20  ing event.  ^If 
150f0 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  the.** function 
15100 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c  pointer is NULL,
15110 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f   the [sqlite3_lo
15120 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62  g()] interface b
15130 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a  ecomes a no-op..
15140 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69  ** ^The void poi
15150 6e 74 65 72 20 74 68 61 74 20 69 73 20 74 68 65  nter that is the
15160 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
15170 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49   to SQLITE_CONFI
15180 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73  G_LOG is.** pass
15190 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68  ed through as th
151a0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
151b0 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  r to the applica
151c0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67  tion-defined log
151d0 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ger.** function 
151e0 77 68 65 6e 65 76 65 72 20 74 68 61 74 20 66 75  whenever that fu
151f0 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65  nction is invoke
15200 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  d.  ^The second 
15210 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
15220 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74  the logger funct
15230 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ion is a copy of
15240 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
15250 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72  eter to the corr
15260 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71  esponding.** [sq
15270 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c  lite3_log()] cal
15280 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65  l and is intende
15290 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c  d to be a [resul
152a0 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a  t code] or an.**
152b0 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
152c0 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74  t code].  ^The t
152d0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 70  hird parameter p
152e0 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67  assed to the log
152f0 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65  ger is.** log me
15300 73 73 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d  ssage after form
15310 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69  atting via [sqli
15320 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e  te3_snprintf()].
15330 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c  .** The SQLite l
15340 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65  ogging interface
15350 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e   is not reentran
15360 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75  t; the logger fu
15370 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69  nction.** suppli
15380 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ed by the applic
15390 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69  ation must not i
153a0 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65  nvoke any SQLite
153b0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49   interface..** I
153c0 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64  n a multi-thread
153d0 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20  ed application, 
153e0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
153f0 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a  defined logger.*
15400 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  * function must 
15410 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c  be threadsafe. <
15420 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
15430 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d  ITE_CONFIG_URI]]
15440 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
15450 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28  IG_URI.** <dd>^(
15460 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
15470 47 5f 55 52 49 20 6f 70 74 69 6f 6e 20 74 61 6b  G_URI option tak
15480 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
15490 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74  ment of type int
154a0 2e 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f  ..** If non-zero
154b0 2c 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c  , then URI handl
154c0 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20  ing is globally 
154d0 65 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 65 20  enabled. If the 
154e0 70 61 72 61 6d 65 74 65 72 20 69 73 20 7a 65 72  parameter is zer
154f0 6f 2c 0a 2a 2a 20 74 68 65 6e 20 55 52 49 20 68  o,.** then URI h
15500 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61  andling is globa
15510 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e 29 5e 20  lly disabled.)^ 
15520 5e 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e 67  ^If URI handling
15530 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20   is globally.** 
15540 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c  enabled, all fil
15550 65 6e 61 6d 65 73 20 70 61 73 73 65 64 20 74 6f  enames passed to
15560 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
15570 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
15580 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  _v2()],.** [sqli
15590 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72  te3_open16()] or
155a0 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20 61 73  .** specified as
155b0 20 70 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48   part of [ATTACH
155c0 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69  ] commands are i
155d0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52  nterpreted as UR
155e0 49 73 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a  Is, regardless.*
155f0 2a 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  * of whether or 
15600 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  not the [SQLITE_
15610 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69  OPEN_URI] flag i
15620 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 64  s set when the d
15630 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
15640 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e  ction is opened.
15650 20 5e 49 66 20 69 74 20 69 73 20 67 6c 6f 62 61   ^If it is globa
15660 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 66 69  lly disabled, fi
15670 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f  lenames are.** o
15680 6e 6c 79 20 69 6e 74 65 72 70 72 65 74 65 64 20  nly interpreted 
15690 61 73 20 55 52 49 73 20 69 66 20 74 68 65 20 53  as URIs if the S
156a0 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66  QLITE_OPEN_URI f
156b0 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20  lag is set when 
156c0 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
156d0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70  connection is op
156e0 65 6e 65 64 2e 20 5e 28 42 79 20 64 65 66 61 75  ened. ^(By defau
156f0 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67  lt, URI handling
15700 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20   is globally.** 
15710 64 69 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65  disabled. The de
15720 66 61 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20  fault value may 
15730 62 65 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f  be changed by co
15740 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65  mpiling with the
15750 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f  .** [SQLITE_USE_
15760 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69  URI] symbol defi
15770 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  ned.)^.**.** [[S
15780 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56  QLITE_CONFIG_COV
15790 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e  ERING_INDEX_SCAN
157a0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
157b0 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e  NFIG_COVERING_IN
157c0 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e  DEX_SCAN.** <dd>
157d0 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
157e0 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45  IG_COVERING_INDE
157f0 58 5f 53 43 41 4e 20 6f 70 74 69 6f 6e 20 74 61  X_SCAN option ta
15800 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 69 6e 74  kes a single int
15810 65 67 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  eger.** argument
15820 20 77 68 69 63 68 20 69 73 20 69 6e 74 65 72 70   which is interp
15830 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65  reted as a boole
15840 61 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65  an in order to e
15850 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65  nable or disable
15860 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 63  .** the use of c
15870 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20  overing indices 
15880 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73  for full table s
15890 63 61 6e 73 20 69 6e 20 74 68 65 20 71 75 65 72  cans in the quer
158a0 79 20 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a 2a 20  y optimizer..** 
158b0 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74  ^The default set
158c0 74 69 6e 67 20 69 73 20 64 65 74 65 72 6d 69 6e  ting is determin
158d0 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53 51  ed.** by the [SQ
158e0 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52  LITE_ALLOW_COVER
158f0 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20  ING_INDEX_SCAN] 
15900 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
15910 69 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a  ion, or is "on".
15920 2a 2a 20 69 66 20 74 68 61 74 20 63 6f 6d 70 69  ** if that compi
15930 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69  le-time option i
15940 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68  s omitted..** Th
15950 65 20 61 62 69 6c 69 74 79 20 74 6f 20 64 69 73  e ability to dis
15960 61 62 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20  able the use of 
15970 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73  covering indices
15980 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20   for full table 
15990 73 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61  scans.** is beca
159a0 75 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65  use some incorre
159b0 63 74 6c 79 20 63 6f 64 65 64 20 6c 65 67 61 63  ctly coded legac
159c0 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d  y applications m
159d0 69 67 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e  ight malfunction
159e0 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 6f 70 74  .** when the opt
159f0 69 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e 61  imization is ena
15a00 62 6c 65 64 2e 20 20 50 72 6f 76 69 64 69 6e 67  bled.  Providing
15a10 20 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 0a   the ability to.
15a20 2a 2a 20 64 69 73 61 62 6c 65 20 74 68 65 20 6f  ** disable the o
15a30 70 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f  ptimization allo
15a40 77 73 20 74 68 65 20 6f 6c 64 65 72 2c 20 62 75  ws the older, bu
15a50 67 67 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  ggy application 
15a60 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20  code to work.** 
15a70 77 69 74 68 6f 75 74 20 63 68 61 6e 67 65 20 65  without change e
15a80 76 65 6e 20 77 69 74 68 20 6e 65 77 65 72 20 76  ven with newer v
15a90 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
15aa0 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  e..**.** [[SQLIT
15ab0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d  E_CONFIG_PCACHE]
15ac0 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ] [[SQLITE_CONFI
15ad0 47 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a  G_GETPCACHE]].**
15ae0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
15af0 49 47 5f 50 43 41 43 48 45 20 61 6e 64 20 53 51  IG_PCACHE and SQ
15b00 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
15b10 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68  CACHE.** <dd> Th
15b20 65 73 65 20 6f 70 74 69 6f 6e 73 20 61 72 65 20  ese options are 
15b30 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f  obsolete and sho
15b40 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20  uld not be used 
15b50 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20  by new code..** 
15b60 54 68 65 79 20 61 72 65 20 72 65 74 61 69 6e 65  They are retaine
15b70 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20  d for backwards 
15b80 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 62 75  compatibility bu
15b90 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73  t are now no-ops
15ba0 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
15bb0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
15bc0 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74  _SQLLOG]].** <dt
15bd0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
15be0 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 69  QLLOG.** <dd>Thi
15bf0 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79  s option is only
15c00 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 73 71   available if sq
15c10 6c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  lite is compiled
15c20 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51   with the.** [SQ
15c30 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c  LITE_ENABLE_SQLL
15c40 4f 47 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f  OG] pre-processo
15c50 72 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 2e  r macro defined.
15c60 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
15c70 65 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65  ent should.** be
15c80 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
15c90 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65  function of type
15ca0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73   void(*)(void*,s
15cb0 71 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68  qlite3*,const ch
15cc0 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68  ar*, int)..** Th
15cd0 65 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20  e second should 
15ce0 62 65 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64  be of type (void
15cf0 2a 29 2e 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  *). The callback
15d00 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 74   is invoked by t
15d10 68 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e  he library.** in
15d20 20 74 68 72 65 65 20 73 65 70 61 72 61 74 65 20   three separate 
15d30 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 69  circumstances, i
15d40 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65  dentified by the
15d50 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73   value passed as
15d60 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70   the.** fourth p
15d70 61 72 61 6d 65 74 65 72 2e 20 49 66 20 74 68 65  arameter. If the
15d80 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
15d90 72 20 69 73 20 30 2c 20 74 68 65 6e 20 74 68 65  r is 0, then the
15da0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
15db0 74 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61  tion.** passed a
15dc0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
15dd0 75 6d 65 6e 74 20 68 61 73 20 6a 75 73 74 20 62  ument has just b
15de0 65 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65 20  een opened. The 
15df0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a  third argument.*
15e00 2a 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 62 75  * points to a bu
15e10 66 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ffer containing 
15e20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
15e30 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 69  main database fi
15e40 6c 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f  le. If the.** fo
15e50 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
15e60 73 20 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51  s 1, then the SQ
15e70 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  L statement that
15e80 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
15e90 65 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74  eter.** points t
15ea0 6f 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20  o has just been 
15eb0 65 78 65 63 75 74 65 64 2e 20 4f 72 2c 20 69 66  executed. Or, if
15ec0 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
15ed0 6d 65 74 65 72 20 69 73 20 32 2c 20 74 68 65 6e  meter is 2, then
15ee0 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74 69  .** the connecti
15ef0 6f 6e 20 62 65 69 6e 67 20 70 61 73 73 65 64 20  on being passed 
15f00 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
15f10 72 61 6d 65 74 65 72 20 69 73 20 62 65 69 6e 67  rameter is being
15f20 20 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20   closed. The.** 
15f30 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
15f40 69 73 20 70 61 73 73 65 64 20 4e 55 4c 4c 20 49  is passed NULL I
15f50 6e 20 74 68 69 73 20 63 61 73 65 2e 20 20 41 6e  n this case.  An
15f60 20 65 78 61 6d 70 6c 65 20 6f 66 20 75 73 69 6e   example of usin
15f70 67 20 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 67  g this.** config
15f80 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 63  uration option c
15f90 61 6e 20 62 65 20 73 65 65 6e 20 69 6e 20 74 68  an be seen in th
15fa0 65 20 22 74 65 73 74 5f 73 71 6c 6c 6f 67 2e 63  e "test_sqllog.c
15fb0 22 20 73 6f 75 72 63 65 20 66 69 6c 65 20 69 6e  " source file in
15fc0 0a 2a 2a 20 74 68 65 20 63 61 6e 6f 6e 69 63 61  .** the canonica
15fd0 6c 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20  l SQLite source 
15fe0 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tree.</dd>.**.**
15ff0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
16000 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20  _MMAP_SIZE]].** 
16010 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
16020 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c  G_MMAP_SIZE.** <
16030 64 64 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  dd>^SQLITE_CONFI
16040 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 74 61 6b 65  G_MMAP_SIZE take
16050 73 20 74 77 6f 20 36 34 2d 62 69 74 20 69 6e 74  s two 64-bit int
16060 65 67 65 72 20 28 73 71 6c 69 74 65 33 5f 69 6e  eger (sqlite3_in
16070 74 36 34 29 20 76 61 6c 75 65 73 0a 2a 2a 20 74  t64) values.** t
16080 68 61 74 20 61 72 65 20 74 68 65 20 64 65 66 61  hat are the defa
16090 75 6c 74 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69  ult mmap size li
160a0 6d 69 74 20 28 74 68 65 20 64 65 66 61 75 6c 74  mit (the default
160b0 20 73 65 74 74 69 6e 67 20 66 6f 72 0a 2a 2a 20   setting for.** 
160c0 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a  [PRAGMA mmap_siz
160d0 65 5d 29 20 61 6e 64 20 74 68 65 20 6d 61 78 69  e]) and the maxi
160e0 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70  mum allowed mmap
160f0 20 73 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20   size limit..** 
16100 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74  ^The default set
16110 74 69 6e 67 20 63 61 6e 20 62 65 20 6f 76 65 72  ting can be over
16120 72 69 64 64 65 6e 20 62 79 20 65 61 63 68 20 64  ridden by each d
16130 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
16140 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 65 69 74 68  on using.** eith
16150 65 72 20 74 68 65 20 5b 50 52 41 47 4d 41 20 6d  er the [PRAGMA m
16160 6d 61 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e  map_size] comman
16170 64 2c 20 6f 72 20 62 79 20 75 73 69 6e 67 20 74  d, or by using t
16180 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43  he.** [SQLITE_FC
16190 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66  NTL_MMAP_SIZE] f
161a0 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e 28  ile control.  ^(
161b0 54 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f  The maximum allo
161c0 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a  wed mmap size.**
161d0 20 77 69 6c 6c 20 62 65 20 73 69 6c 65 6e 74 6c   will be silentl
161e0 79 20 74 72 75 6e 63 61 74 65 64 20 69 66 20 6e  y truncated if n
161f0 65 63 65 73 73 61 72 79 20 73 6f 20 74 68 61 74  ecessary so that
16200 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 65 78 63   it does not exc
16210 65 65 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69  eed the.** compi
16220 6c 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20  le-time maximum 
16230 6d 6d 61 70 20 73 69 7a 65 20 73 65 74 20 62 79  mmap size set by
16240 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
16250 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63  MAX_MMAP_SIZE] c
16260 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
16270 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74  on.)^.** ^If eit
16280 68 65 72 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  her argument to 
16290 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e  this option is n
162a0 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68  egative, then th
162b0 61 74 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a  at argument is.*
162c0 2a 20 63 68 61 6e 67 65 64 20 74 6f 20 69 74 73  * changed to its
162d0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65   compile-time de
162e0 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  fault..**.** [[S
162f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e  QLITE_CONFIG_WIN
16300 33 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a  32_HEAPSIZE]].**
16310 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
16320 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a  IG_WIN32_HEAPSIZ
16330 45 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51  E.** <dd>^The SQ
16340 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33  LITE_CONFIG_WIN3
16350 32 5f 48 45 41 50 53 49 5a 45 20 6f 70 74 69 6f  2_HEAPSIZE optio
16360 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61  n is only availa
16370 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 73  ble if SQLite is
16380 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72  .** compiled for
16390 20 57 69 6e 64 6f 77 73 20 77 69 74 68 20 74 68   Windows with th
163a0 65 20 5b 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f  e [SQLITE_WIN32_
163b0 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d 70 72 6f 63  MALLOC] pre-proc
163c0 65 73 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a 20 64  essor macro.** d
163d0 65 66 69 6e 65 64 2e 20 5e 53 51 4c 49 54 45 5f  efined. ^SQLITE_
163e0 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41  CONFIG_WIN32_HEA
163f0 50 53 49 5a 45 20 74 61 6b 65 73 20 61 20 33 32  PSIZE takes a 32
16400 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e  -bit unsigned in
16410 74 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a 20 74  teger value.** t
16420 68 61 74 20 73 70 65 63 69 66 69 65 73 20 74 68  hat specifies th
16430 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f  e maximum size o
16440 66 20 74 68 65 20 63 72 65 61 74 65 64 20 68 65  f the created he
16450 61 70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  ap..**.** [[SQLI
16460 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
16470 5f 48 44 52 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e  _HDRSZ]].** <dt>
16480 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
16490 41 43 48 45 5f 48 44 52 53 5a 0a 2a 2a 20 3c 64  ACHE_HDRSZ.** <d
164a0 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  d>^The SQLITE_CO
164b0 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53  NFIG_PCACHE_HDRS
164c0 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  Z option takes a
164d0 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65   single paramete
164e0 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20  r which.** is a 
164f0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
16500 74 65 67 65 72 20 61 6e 64 20 77 72 69 74 65 73  teger and writes
16510 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67   into that integ
16520 65 72 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  er the number of
16530 20 65 78 74 72 61 0a 2a 2a 20 62 79 74 65 73 20   extra.** bytes 
16540 70 65 72 20 70 61 67 65 20 72 65 71 75 69 72 65  per page require
16550 64 20 66 6f 72 20 65 61 63 68 20 70 61 67 65 20  d for each page 
16560 69 6e 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  in [SQLITE_CONFI
16570 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a  G_PAGECACHE]..**
16580 20 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 65   The amount of e
16590 78 74 72 61 20 73 70 61 63 65 20 72 65 71 75 69  xtra space requi
165a0 72 65 64 20 63 61 6e 20 63 68 61 6e 67 65 20 64  red can change d
165b0 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
165c0 63 6f 6d 70 69 6c 65 72 2c 0a 2a 2a 20 74 61 72  compiler,.** tar
165d0 67 65 74 20 70 6c 61 74 66 6f 72 6d 2c 20 61 6e  get platform, an
165e0 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  d SQLite version
165f0 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
16600 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 5d 5d 0a  _CONFIG_PMASZ]].
16610 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
16620 4e 46 49 47 5f 50 4d 41 53 5a 0a 2a 2a 20 3c 64  NFIG_PMASZ.** <d
16630 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  d>^The SQLITE_CO
16640 4e 46 49 47 5f 50 4d 41 53 5a 20 6f 70 74 69 6f  NFIG_PMASZ optio
16650 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
16660 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68   parameter which
16670 0a 2a 2a 20 69 73 20 61 6e 20 75 6e 73 69 67 6e  .** is an unsign
16680 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 73  ed integer and s
16690 65 74 73 20 74 68 65 20 22 4d 69 6e 69 6d 75 6d  ets the "Minimum
166a0 20 50 4d 41 20 53 69 7a 65 22 20 66 6f 72 20 74   PMA Size" for t
166b0 68 65 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64  he multithreaded
166c0 0a 2a 2a 20 73 6f 72 74 65 72 20 74 6f 20 74 68  .** sorter to th
166d0 61 74 20 69 6e 74 65 67 65 72 2e 20 20 54 68 65  at integer.  The
166e0 20 64 65 66 61 75 6c 74 20 6d 69 6e 69 6d 75 6d   default minimum
166f0 20 50 4d 41 20 53 69 7a 65 20 69 73 20 73 65 74   PMA Size is set
16700 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49   by the.** [SQLI
16710 54 45 5f 53 4f 52 54 45 52 5f 50 4d 41 53 5a 5d  TE_SORTER_PMASZ]
16720 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
16730 74 69 6f 6e 2e 20 20 4e 65 77 20 74 68 72 65 61  tion.  New threa
16740 64 73 20 61 72 65 20 6c 61 75 6e 63 68 65 64 0a  ds are launched.
16750 2a 2a 20 74 6f 20 68 65 6c 70 20 77 69 74 68 20  ** to help with 
16760 73 6f 72 74 20 6f 70 65 72 61 74 69 6f 6e 73 20  sort operations 
16770 77 68 65 6e 20 6d 75 6c 74 69 74 68 72 65 61 64  when multithread
16780 65 64 20 73 6f 72 74 69 6e 67 0a 2a 2a 20 69 73  ed sorting.** is
16790 20 65 6e 61 62 6c 65 64 20 28 75 73 69 6e 67 20   enabled (using 
167a0 74 68 65 20 5b 50 52 41 47 4d 41 20 74 68 72 65  the [PRAGMA thre
167b0 61 64 73 5d 20 63 6f 6d 6d 61 6e 64 29 20 61 6e  ads] command) an
167c0 64 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20  d the amount of 
167d0 63 6f 6e 74 65 6e 74 0a 2a 2a 20 74 6f 20 62 65  content.** to be
167e0 20 73 6f 72 74 65 64 20 65 78 63 65 65 64 73 20   sorted exceeds 
167f0 74 68 65 20 70 61 67 65 20 73 69 7a 65 20 74 69  the page size ti
16800 6d 65 73 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20  mes the minimum 
16810 6f 66 20 74 68 65 0a 2a 2a 20 5b 50 52 41 47 4d  of the.** [PRAGM
16820 41 20 63 61 63 68 65 5f 73 69 7a 65 5d 20 73 65  A cache_size] se
16830 74 74 69 6e 67 20 61 6e 64 20 74 68 69 73 20 76  tting and this v
16840 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  alue..**.** [[SQ
16850 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54  LITE_CONFIG_STMT
16860 4a 52 4e 4c 5f 53 50 49 4c 4c 5d 5d 0a 2a 2a 20  JRNL_SPILL]].** 
16870 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
16880 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c  G_STMTJRNL_SPILL
16890 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c  .** <dd>^The SQL
168a0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a  ITE_CONFIG_STMTJ
168b0 52 4e 4c 5f 53 50 49 4c 4c 20 6f 70 74 69 6f 6e  RNL_SPILL option
168c0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
168d0 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a  parameter which.
168e0 2a 2a 20 62 65 63 6f 6d 65 73 20 74 68 65 20 5b  ** becomes the [
168f0 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61  statement journa
16900 6c 5d 20 73 70 69 6c 6c 2d 74 6f 2d 64 69 73 6b  l] spill-to-disk
16910 20 74 68 72 65 73 68 6f 6c 64 2e 20 20 0a 2a 2a   threshold.  .**
16920 20 5b 53 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72   [Statement jour
16930 6e 61 6c 73 5d 20 61 72 65 20 68 65 6c 64 20 69  nals] are held i
16940 6e 20 6d 65 6d 6f 72 79 20 75 6e 74 69 6c 20 74  n memory until t
16950 68 65 69 72 20 73 69 7a 65 20 28 69 6e 20 62 79  heir size (in by
16960 74 65 73 29 0a 2a 2a 20 65 78 63 65 65 64 73 20  tes).** exceeds 
16970 74 68 69 73 20 74 68 72 65 73 68 6f 6c 64 2c 20  this threshold, 
16980 61 74 20 77 68 69 63 68 20 70 6f 69 6e 74 20 74  at which point t
16990 68 65 79 20 61 72 65 20 77 72 69 74 74 65 6e 20  hey are written 
169a0 74 6f 20 64 69 73 6b 2e 0a 2a 2a 20 4f 72 20 69  to disk..** Or i
169b0 66 20 74 68 65 20 74 68 72 65 73 68 6f 6c 64 20  f the threshold 
169c0 69 73 20 2d 31 2c 20 73 74 61 74 65 6d 65 6e 74  is -1, statement
169d0 20 6a 6f 75 72 6e 61 6c 73 20 61 72 65 20 61 6c   journals are al
169e0 77 61 79 73 20 68 65 6c 64 0a 2a 2a 20 65 78 63  ways held.** exc
169f0 6c 75 73 69 76 65 6c 79 20 69 6e 20 6d 65 6d 6f  lusively in memo
16a00 72 79 2e 0a 2a 2a 20 53 69 6e 63 65 20 6d 61 6e  ry..** Since man
16a10 79 20 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72  y statement jour
16a20 6e 61 6c 73 20 6e 65 76 65 72 20 62 65 63 6f 6d  nals never becom
16a30 65 20 6c 61 72 67 65 2c 20 73 65 74 74 69 6e 67  e large, setting
16a40 20 74 68 65 20 73 70 69 6c 6c 0a 2a 2a 20 74 68   the spill.** th
16a50 72 65 73 68 6f 6c 64 20 74 6f 20 61 20 76 61 6c  reshold to a val
16a60 75 65 20 73 75 63 68 20 61 73 20 36 34 4b 69 42  ue such as 64KiB
16a70 20 63 61 6e 20 67 72 65 61 74 6c 79 20 72 65 64   can greatly red
16a80 75 63 65 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f  uce the amount o
16a90 66 0a 2a 2a 20 49 2f 4f 20 72 65 71 75 69 72 65  f.** I/O require
16aa0 64 20 74 6f 20 73 75 70 70 6f 72 74 20 73 74 61  d to support sta
16ab0 74 65 6d 65 6e 74 20 72 6f 6c 6c 62 61 63 6b 2e  tement rollback.
16ac0 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20  .** The default 
16ad0 76 61 6c 75 65 20 66 6f 72 20 74 68 69 73 20 73  value for this s
16ae0 65 74 74 69 6e 67 20 69 73 20 63 6f 6e 74 72 6f  etting is contro
16af0 6c 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b  lled by the.** [
16b00 53 51 4c 49 54 45 5f 53 54 4d 54 4a 52 4e 4c 5f  SQLITE_STMTJRNL_
16b10 53 50 49 4c 4c 5d 20 63 6f 6d 70 69 6c 65 2d 74  SPILL] compile-t
16b20 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 3c  ime option..** <
16b30 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
16b40 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
16b50 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f  NGLETHREAD  1  /
16b60 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
16b70 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
16b80 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 20  ULTITHREAD   2  
16b90 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
16ba0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16bb0 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20  SERIALIZED    3 
16bc0 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
16bd0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
16be0 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34  _MALLOC        4
16bf0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d    /* sqlite3_mem
16c00 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
16c10 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16c20 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20  IG_GETMALLOC    
16c30 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d   5  /* sqlite3_m
16c40 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  em_methods* */.#
16c50 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
16c60 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 20  NFIG_SCRATCH    
16c70 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20     6  /* void*, 
16c80 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f  int sz, int N */
16c90 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16ca0 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
16cb0 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a       7  /* void*
16cc0 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20  , int sz, int N 
16cd0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16ce0 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20  E_CONFIG_HEAP   
16cf0 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69         8  /* voi
16d00 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69  d*, int nByte, i
16d10 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e  nt min */.#defin
16d20 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16d30 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 39 20  MEMSTATUS     9 
16d40 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23   /* boolean */.#
16d50 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
16d60 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20  NFIG_MUTEX      
16d70 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33    10  /* sqlite3
16d80 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20  _mutex_methods* 
16d90 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16da0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
16db0 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c  X     11  /* sql
16dc0 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
16dd0 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f  ds* */./* previo
16de0 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46  usly SQLITE_CONF
16df0 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32  IG_CHUNKALLOC 12
16e00 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e   which is now un
16e10 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e  used. */ .#defin
16e20 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16e30 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20  LOOKASIDE    13 
16e40 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23   /* int int */.#
16e50 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
16e60 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20 20 20  NFIG_PCACHE     
16e70 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a    14  /* no-op *
16e80 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16e90 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
16ea0 45 20 20 20 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f  E    15  /* no-o
16eb0 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  p */.#define SQL
16ec0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20  ITE_CONFIG_LOG  
16ed0 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a 20 78          16  /* x
16ee0 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23  Func, void* */.#
16ef0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
16f00 4e 46 49 47 5f 55 52 49 20 20 20 20 20 20 20 20  NFIG_URI        
16f10 20 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a    17  /* int */.
16f20 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16f30 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 20 20  ONFIG_PCACHE2   
16f40 20 20 20 31 38 20 20 2f 2a 20 73 71 6c 69 74 65     18  /* sqlite
16f50 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
16f60 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  2* */.#define SQ
16f70 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
16f80 43 41 43 48 45 32 20 20 20 31 39 20 20 2f 2a 20  CACHE2   19  /* 
16f90 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
16fa0 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66  ethods2* */.#def
16fb0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
16fc0 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58  G_COVERING_INDEX
16fd0 5f 53 43 41 4e 20 32 30 20 20 2f 2a 20 69 6e 74  _SCAN 20  /* int
16fe0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16ff0 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47  TE_CONFIG_SQLLOG
17000 20 20 20 20 20 20 20 32 31 20 20 2f 2a 20 78 53         21  /* xS
17010 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20 2a 2f 0a  qllog, void* */.
17020 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
17030 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20  ONFIG_MMAP_SIZE 
17040 20 20 20 32 32 20 20 2f 2a 20 73 71 6c 69 74 65     22  /* sqlite
17050 33 5f 69 6e 74 36 34 2c 20 73 71 6c 69 74 65 33  3_int64, sqlite3
17060 5f 69 6e 74 36 34 20 2a 2f 0a 23 64 65 66 69 6e  _int64 */.#defin
17070 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
17080 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 20  WIN32_HEAPSIZE  
17090 20 20 20 20 32 33 20 20 2f 2a 20 69 6e 74 20 6e      23  /* int n
170a0 42 79 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  Byte */.#define 
170b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
170c0 41 43 48 45 5f 48 44 52 53 5a 20 20 20 20 20 20  ACHE_HDRSZ      
170d0 20 20 32 34 20 20 2f 2a 20 69 6e 74 20 2a 70 73    24  /* int *ps
170e0 7a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  z */.#define SQL
170f0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a  ITE_CONFIG_PMASZ
17100 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
17110 35 20 20 2f 2a 20 75 6e 73 69 67 6e 65 64 20 69  5  /* unsigned i
17120 6e 74 20 73 7a 50 6d 61 20 2a 2f 0a 23 64 65 66  nt szPma */.#def
17130 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
17140 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c  G_STMTJRNL_SPILL
17150 20 20 20 20 20 20 32 36 20 20 2f 2a 20 69 6e 74        26  /* int
17160 20 6e 42 79 74 65 20 2a 2f 0a 0a 2f 2a 0a 2a 2a   nByte */../*.**
17170 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62   CAPI3REF: Datab
17180 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43  ase Connection C
17190 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74  onfiguration Opt
171a0 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
171b0 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74   constants are t
171c0 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74  he available int
171d0 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69  eger configurati
171e0 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a  on options that.
171f0 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64  ** can be passed
17200 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   as the second a
17210 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b  rgument to the [
17220 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
17230 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  g()] interface..
17240 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67  **.** New config
17250 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
17260 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
17270 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
17280 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78  of SQLite..** Ex
17290 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61  isting configura
172a0 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67  tion options mig
172b0 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75  ht be discontinu
172c0 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  ed.  Application
172d0 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63  s.** should chec
172e0 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64  k the return cod
172f0 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  e from [sqlite3_
17300 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20  db_config()] to 
17310 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a  make sure that.*
17320 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65  * the call worke
17330 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  d.  ^The [sqlite
17340 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69  3_db_config()] i
17350 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65  nterface will re
17360 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65  turn a.** non-ze
17370 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ro [error code] 
17380 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65  if a discontinue
17390 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64  d or unsupported
173a0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
173b0 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f  ption.** is invo
173c0 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  ked..**.** <dl>.
173d0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
173e0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
173f0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
17400 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
17410 20 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61   three additiona
17420 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  l arguments that
17430 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a   determine the .
17440 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  ** [lookaside me
17450 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20  mory allocator] 
17460 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f  configuration fo
17470 72 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  r the [database 
17480 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20  connection]..** 
17490 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
174a0 65 6e 74 20 28 74 68 65 20 74 68 69 72 64 20 70  ent (the third p
174b0 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
174c0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
174d0 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65  ] is a.** pointe
174e0 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75  r to a memory bu
174f0 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72 20  ffer to use for 
17500 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
17510 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  ..** ^The first 
17520 61 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20 74  argument after t
17530 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  he SQLITE_DBCONF
17540 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72  IG_LOOKASIDE ver
17550 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c  b.** may be NULL
17560 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 53   in which case S
17570 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63  QLite will alloc
17580 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61  ate the.** looka
17590 73 69 64 65 20 62 75 66 66 65 72 20 69 74 73 65  side buffer itse
175a0 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  lf using [sqlite
175b0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68  3_malloc()]. ^Th
175c0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
175d0 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65  t is the.** size
175e0 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69   of each lookasi
175f0 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e 20  de buffer slot. 
17600 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75   ^The third argu
17610 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62  ment is the numb
17620 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20  er of.** slots. 
17630 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   The size of the
17640 20 62 75 66 66 65 72 20 69 6e 20 74 68 65 20 66   buffer in the f
17650 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75  irst argument mu
17660 73 74 20 62 65 20 67 72 65 61 74 65 72 20 74 68  st be greater th
17670 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74  an.** or equal t
17680 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66  o the product of
17690 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20   the second and 
176a0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e  third arguments.
176b0 20 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a 20    The buffer.** 
176c0 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20  must be aligned 
176d0 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75  to an 8-byte bou
176e0 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65 20  ndary.  ^If the 
176f0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
17700 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43  to.** SQLITE_DBC
17710 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
17720 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c  is not a multipl
17730 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69 6e  e of 8, it is in
17740 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e  ternally.** roun
17750 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65 20  ded down to the 
17760 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75 6c  next smaller mul
17770 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28 54  tiple of 8.  ^(T
17780 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  he lookaside mem
17790 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  ory.** configura
177a0 74 69 6f 6e 20 66 6f 72 20 61 20 64 61 74 61 62  tion for a datab
177b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63  ase connection c
177c0 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e 67  an only be chang
177d0 65 64 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a 20  ed when that.** 
177e0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e 6f  connection is no
177f0 74 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69 6e  t currently usin
17800 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  g lookaside memo
17810 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72 20  ry, or in other 
17820 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74 68  words.** when th
17830 65 20 22 63 75 72 72 65 6e 74 20 76 61 6c 75 65  e "current value
17840 22 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  " returned by.**
17850 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 61   [sqlite3_db_sta
17860 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 43  tus](D,[SQLITE_C
17870 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d  ONFIG_LOOKASIDE]
17880 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a 2a  ,...) is zero..*
17890 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f  * Any attempt to
178a0 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b   change the look
178b0 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f 6e  aside memory con
178c0 66 69 67 75 72 61 74 69 6f 6e 20 77 68 65 6e 20  figuration when 
178d0 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65 6d  lookaside.** mem
178e0 6f 72 79 20 69 73 20 69 6e 20 75 73 65 20 6c 65  ory is in use le
178f0 61 76 65 73 20 74 68 65 20 63 6f 6e 66 69 67 75  aves the configu
17900 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65 64  ration unchanged
17910 20 61 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a 2a   and returns .**
17920 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 29   [SQLITE_BUSY].)
17930 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  ^</dd>.**.** <dt
17940 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
17950 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64 74  _ENABLE_FKEY</dt
17960 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
17970 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  option is used t
17980 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61  o enable or disa
17990 62 6c 65 20 74 68 65 20 65 6e 66 6f 72 63 65 6d  ble the enforcem
179a0 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69  ent of.** [forei
179b0 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e  gn key constrain
179c0 74 73 5d 2e 20 20 54 68 65 72 65 20 73 68 6f 75  ts].  There shou
179d0 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69  ld be two additi
179e0 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a  onal arguments..
179f0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
17a00 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65  ument is an inte
17a10 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74  ger which is 0 t
17a20 6f 20 64 69 73 61 62 6c 65 20 46 4b 20 65 6e 66  o disable FK enf
17a30 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73  orcement,.** pos
17a40 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20  itive to enable 
17a50 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f  FK enforcement o
17a60 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65  r negative to le
17a70 61 76 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  ave FK enforceme
17a80 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e  nt.** unchanged.
17a90 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72    The second par
17aa0 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
17ab0 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
17ac0 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20  r into which.** 
17ad0 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20  is written 0 or 
17ae0 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  1 to indicate wh
17af0 65 74 68 65 72 20 46 4b 20 65 6e 66 6f 72 63 65  ether FK enforce
17b00 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f 72 20 6f  ment is off or o
17b10 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74  n.** following t
17b20 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73  his call.  The s
17b30 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
17b40 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f  may be a NULL po
17b50 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69  inter, in.** whi
17b60 63 68 20 63 61 73 65 20 74 68 65 20 46 4b 20 65  ch case the FK e
17b70 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65 74 74 69  nforcement setti
17b80 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74  ng is not report
17b90 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a  ed back. </dd>.*
17ba0 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
17bb0 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
17bc0 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20  TRIGGER</dt>.** 
17bd0 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
17be0 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61  n is used to ena
17bf0 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 5b  ble or disable [
17c00 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c  CREATE TRIGGER |
17c10 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 54   triggers]..** T
17c20 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74  here should be t
17c30 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72  wo additional ar
17c40 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20  guments..** The 
17c50 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
17c60 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
17c70 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  ch is 0 to disab
17c80 6c 65 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a 20  le triggers,.** 
17c90 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62  positive to enab
17ca0 6c 65 20 74 72 69 67 67 65 72 73 20 6f 72 20 6e  le triggers or n
17cb0 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65  egative to leave
17cc0 20 74 68 65 20 73 65 74 74 69 6e 67 20 75 6e 63   the setting unc
17cd0 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73  hanged..** The s
17ce0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
17cf0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
17d00 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20  an integer into 
17d10 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74  which.** is writ
17d20 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e  ten 0 or 1 to in
17d30 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 74  dicate whether t
17d40 72 69 67 67 65 72 73 20 61 72 65 20 64 69 73 61  riggers are disa
17d50 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a  bled or enabled.
17d60 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69  ** following thi
17d70 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63  s call.  The sec
17d80 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61  ond parameter ma
17d90 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  y be a NULL poin
17da0 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68  ter, in.** which
17db0 20 63 61 73 65 20 74 68 65 20 74 72 69 67 67 65   case the trigge
17dc0 72 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74  r setting is not
17dd0 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20   reported back. 
17de0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
17df0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
17e00 45 4e 41 42 4c 45 5f 46 54 53 33 5f 54 4f 4b 45  ENABLE_FTS3_TOKE
17e10 4e 49 5a 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  NIZER</dt>.** <d
17e20 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
17e30 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c  is used to enabl
17e40 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65  e or disable the
17e50 20 74 77 6f 2d 61 72 67 75 6d 65 6e 74 0a 2a 2a   two-argument.**
17e60 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20   version of the 
17e70 5b 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28  [fts3_tokenizer(
17e80 29 5d 20 66 75 6e 63 74 69 6f 6e 20 77 68 69 63  )] function whic
17e90 68 20 69 73 20 70 61 72 74 20 6f 66 20 74 68 65  h is part of the
17ea0 0a 2a 2a 20 5b 46 54 53 33 5d 20 66 75 6c 6c 2d  .** [FTS3] full-
17eb0 74 65 78 74 20 73 65 61 72 63 68 20 65 6e 67 69  text search engi
17ec0 6e 65 20 65 78 74 65 6e 73 69 6f 6e 2e 0a 2a 2a  ne extension..**
17ed0 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65   There should be
17ee0 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
17ef0 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68  arguments..** Th
17f00 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
17f10 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77   is an integer w
17f20 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73  hich is 0 to dis
17f30 61 62 6c 65 20 66 74 73 33 5f 74 6f 6b 65 6e 69  able fts3_tokeni
17f40 7a 65 72 28 29 20 6f 72 0a 2a 2a 20 70 6f 73 69  zer() or.** posi
17f50 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 66  tive to enable f
17f60 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28 29 20  ts3_tokenizer() 
17f70 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c  or negative to l
17f80 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e 67  eave the setting
17f90 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a  .** unchanged..*
17fa0 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * The second par
17fb0 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
17fc0 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
17fd0 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20  r into which.** 
17fe0 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20  is written 0 or 
17ff0 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  1 to indicate wh
18000 65 74 68 65 72 20 66 74 73 33 5f 74 6f 6b 65 6e  ether fts3_token
18010 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65 64  izer is disabled
18020 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66   or enabled.** f
18030 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61  ollowing this ca
18040 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ll.  The second 
18050 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
18060 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
18070 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73   in.** which cas
18080 65 20 74 68 65 20 6e 65 77 20 73 65 74 74 69 6e  e the new settin
18090 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65  g is not reporte
180a0 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a  d back. </dd>.**
180b0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
180c0 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 4c  BCONFIG_ENABLE_L
180d0 4f 41 44 5f 45 58 54 45 4e 53 49 4f 4e 3c 2f 64  OAD_EXTENSION</d
180e0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
180f0 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
18100 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73  to enable or dis
18110 61 62 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65  able the [sqlite
18120 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e  3_load_extension
18130 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
18140 20 69 6e 64 65 70 65 6e 64 65 6e 74 6c 79 20 6f   independently o
18150 66 20 74 68 65 20 5b 6c 6f 61 64 5f 65 78 74 65  f the [load_exte
18160 6e 73 69 6f 6e 28 29 5d 20 53 51 4c 20 66 75 6e  nsion()] SQL fun
18170 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20 5b 73  ction..** The [s
18180 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f  qlite3_enable_lo
18190 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20  ad_extension()] 
181a0 41 50 49 20 65 6e 61 62 6c 65 73 20 6f 72 20 64  API enables or d
181b0 69 73 61 62 6c 65 73 20 62 6f 74 68 20 74 68 65  isables both the
181c0 0a 2a 2a 20 43 2d 41 50 49 20 5b 73 71 6c 69 74  .** C-API [sqlit
181d0 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  e3_load_extensio
181e0 6e 28 29 5d 20 61 6e 64 20 74 68 65 20 53 51 4c  n()] and the SQL
181f0 20 66 75 6e 63 74 69 6f 6e 20 5b 6c 6f 61 64 5f   function [load_
18200 65 78 74 65 6e 73 69 6f 6e 28 29 5d 2e 0a 2a 2a  extension()]..**
18210 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65   There should be
18220 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
18230 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 57 68  arguments..** Wh
18240 65 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  en the first arg
18250 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 69 6e  ument to this in
18260 74 65 72 66 61 63 65 20 69 73 20 31 2c 20 74 68  terface is 1, th
18270 65 6e 20 6f 6e 6c 79 20 74 68 65 20 43 2d 41 50  en only the C-AP
18280 49 20 69 73 0a 2a 2a 20 65 6e 61 62 6c 65 64 20  I is.** enabled 
18290 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63  and the SQL func
182a0 74 69 6f 6e 20 72 65 6d 61 69 6e 73 20 64 69 73  tion remains dis
182b0 61 62 6c 65 64 2e 20 20 49 66 20 74 68 65 20 66  abled.  If the f
182c0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
182d0 0a 2a 2a 20 74 68 69 73 20 69 6e 74 65 72 66 61  .** this interfa
182e0 63 65 20 69 73 20 30 2c 20 74 68 65 6e 20 62 6f  ce is 0, then bo
182f0 74 68 20 74 68 65 20 43 2d 41 50 49 20 61 6e 64  th the C-API and
18300 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
18310 6e 20 61 72 65 20 64 69 73 61 62 6c 65 64 2e 0a  n are disabled..
18320 2a 2a 20 49 66 20 74 68 65 20 66 69 72 73 74 20  ** If the first 
18330 61 72 67 75 6d 65 6e 74 20 69 73 20 2d 31 2c 20  argument is -1, 
18340 74 68 65 6e 20 6e 6f 20 63 68 61 6e 67 65 73 20  then no changes 
18350 61 72 65 20 6d 61 64 65 20 74 6f 20 73 74 61 74  are made to stat
18360 65 20 6f 66 20 65 69 74 68 65 72 20 74 68 65 0a  e of either the.
18370 2a 2a 20 43 2d 41 50 49 20 6f 72 20 74 68 65 20  ** C-API or the 
18380 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  SQL function..**
18390 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
183a0 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74  meter is a point
183b0 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
183c0 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69   into which.** i
183d0 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31  s written 0 or 1
183e0 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65   to indicate whe
183f0 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 6c 6f  ther [sqlite3_lo
18400 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20  ad_extension()] 
18410 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 73 20  interface.** is 
18420 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62  disabled or enab
18430 6c 65 64 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  led following th
18440 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65  is call.  The se
18450 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d  cond parameter m
18460 61 79 0a 2a 2a 20 62 65 20 61 20 4e 55 4c 4c 20  ay.** be a NULL 
18470 70 6f 69 6e 74 65 72 2c 20 69 6e 20 77 68 69 63  pointer, in whic
18480 68 20 63 61 73 65 20 74 68 65 20 6e 65 77 20 73  h case the new s
18490 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65  etting is not re
184a0 70 6f 72 74 65 64 20 62 61 63 6b 2e 0a 2a 2a 20  ported back..** 
184b0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
184c0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
184d0 4d 41 49 4e 44 42 4e 41 4d 45 3c 2f 64 74 3e 0a  MAINDBNAME</dt>.
184e0 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
184f0 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
18500 63 68 61 6e 67 65 20 74 68 65 20 6e 61 6d 65 20  change the name 
18510 6f 66 20 74 68 65 20 22 6d 61 69 6e 22 20 64 61  of the "main" da
18520 74 61 62 61 73 65 0a 2a 2a 20 73 63 68 65 6d 61  tabase.** schema
18530 2e 20 20 5e 54 68 65 20 73 6f 6c 65 20 61 72 67  .  ^The sole arg
18540 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
18550 65 72 20 74 6f 20 61 20 63 6f 6e 73 74 61 6e 74  er to a constant
18560 20 55 54 46 38 20 73 74 72 69 6e 67 0a 2a 2a 20   UTF8 string.** 
18570 77 68 69 63 68 20 77 69 6c 6c 20 62 65 63 6f 6d  which will becom
18580 65 20 74 68 65 20 6e 65 77 20 73 63 68 65 6d 61  e the new schema
18590 20 6e 61 6d 65 20 69 6e 20 70 6c 61 63 65 20 6f   name in place o
185a0 66 20 22 6d 61 69 6e 22 2e 20 20 5e 53 51 4c 69  f "main".  ^SQLi
185b0 74 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6d  te.** does not m
185c0 61 6b 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68  ake a copy of th
185d0 65 20 6e 65 77 20 6d 61 69 6e 20 73 63 68 65 6d  e new main schem
185e0 61 20 6e 61 6d 65 20 73 74 72 69 6e 67 2c 20 73  a name string, s
185f0 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
18600 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e 73 75 72 65  n.** must ensure
18610 20 74 68 61 74 20 74 68 65 20 61 72 67 75 6d 65   that the argume
18620 6e 74 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74  nt passed into t
18630 68 69 73 20 44 42 43 4f 4e 46 49 47 20 6f 70 74  his DBCONFIG opt
18640 69 6f 6e 20 69 73 20 75 6e 63 68 61 6e 67 65 64  ion is unchanged
18650 0a 2a 2a 20 75 6e 74 69 6c 20 61 66 74 65 72 20  .** until after 
18660 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
18670 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 0a  nection closes..
18680 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </dd>.**.** <
18690 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
186a0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
186b0 4d 41 49 4e 44 42 4e 41 4d 45 20 20 20 20 20 20  MAINDBNAME      
186c0 20 20 20 20 20 20 31 30 30 30 20 2f 2a 20 63 6f        1000 /* co
186d0 6e 73 74 20 63 68 61 72 2a 20 2a 2f 0a 23 64 65  nst char* */.#de
186e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
186f0 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20  NFIG_LOOKASIDE  
18700 20 20 20 20 20 20 20 20 20 20 20 31 30 30 31 20             1001 
18710 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74  /* void* int int
18720 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18730 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
18740 4c 45 5f 46 4b 45 59 20 20 20 20 20 20 20 20 20  LE_FKEY         
18750 20 20 31 30 30 32 20 2f 2a 20 69 6e 74 20 69 6e    1002 /* int in
18760 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t* */.#define SQ
18770 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
18780 41 42 4c 45 5f 54 52 49 47 47 45 52 20 20 20 20  ABLE_TRIGGER    
18790 20 20 20 20 31 30 30 33 20 2f 2a 20 69 6e 74 20      1003 /* int 
187a0 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  int* */.#define 
187b0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
187c0 45 4e 41 42 4c 45 5f 46 54 53 33 5f 54 4f 4b 45  ENABLE_FTS3_TOKE
187d0 4e 49 5a 45 52 20 31 30 30 34 20 2f 2a 20 69 6e  NIZER 1004 /* in
187e0 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e  t int* */.#defin
187f0 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
18800 47 5f 45 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45 58  G_ENABLE_LOAD_EX
18810 54 45 4e 53 49 4f 4e 20 31 30 30 35 20 2f 2a 20  TENSION 1005 /* 
18820 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a  int int* */.../*
18830 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e  .** CAPI3REF: En
18840 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20  able Or Disable 
18850 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20  Extended Result 
18860 43 6f 64 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  Codes.** METHOD:
18870 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
18880 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65  The sqlite3_exte
18890 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
188a0 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62  s() routine enab
188b0 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
188c0 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64  the.** [extended
188d0 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66   result codes] f
188e0 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65  eature of SQLite
188f0 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20  . ^The extended 
18900 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20  result.** codes 
18910 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20  are disabled by 
18920 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74  default for hist
18930 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69  orical compatibi
18940 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  lity..*/.int sql
18950 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
18960 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74  sult_codes(sqlit
18970 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b  e3*, int onoff);
18980 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
18990 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f  : Last Insert Ro
189a0 77 69 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  wid.** METHOD: s
189b0 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 45 61  qlite3.**.** ^Ea
189c0 63 68 20 65 6e 74 72 79 20 69 6e 20 6d 6f 73 74  ch entry in most
189d0 20 53 51 4c 69 74 65 20 74 61 62 6c 65 73 20 28   SQLite tables (
189e0 65 78 63 65 70 74 20 66 6f 72 20 5b 57 49 54 48  except for [WITH
189f0 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65  OUT ROWID] table
18a00 73 29 0a 2a 2a 20 68 61 73 20 61 20 75 6e 69 71  s).** has a uniq
18a10 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  ue 64-bit signed
18a20 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20  .** integer key 
18a30 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49  called the [ROWI
18a40 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54  D | "rowid"]. ^T
18a50 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61  he rowid is alwa
18a60 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20  ys available.** 
18a70 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64  as an undeclared
18a80 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f   column named RO
18a90 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f  WID, OID, or _RO
18aa0 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20  WID_ as long as 
18ab0 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61  those.** names a
18ac0 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64  re not also used
18ad0 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64   by explicitly d
18ae0 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e  eclared columns.
18af0 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c   ^If.** the tabl
18b00 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f  e has a column o
18b10 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20  f type [INTEGER 
18b20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65  PRIMARY KEY] the
18b30 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a  n that column.**
18b40 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61   is another alia
18b50 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e  s for the rowid.
18b60 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
18b70 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
18b80 72 6f 77 69 64 28 44 29 20 69 6e 74 65 72 66 61  rowid(D) interfa
18b90 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b  ce returns the [
18ba0 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 0a 2a  rowid] of the .*
18bb0 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 75  * most recent su
18bc0 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54  ccessful [INSERT
18bd0 5d 20 69 6e 74 6f 20 61 20 72 6f 77 69 64 20 74  ] into a rowid t
18be0 61 62 6c 65 20 6f 72 20 5b 76 69 72 74 75 61 6c  able or [virtual
18bf0 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e 20 64 61   table].** on da
18c00 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
18c10 6e 20 44 2e 0a 2a 2a 20 5e 49 6e 73 65 72 74 73  n D..** ^Inserts
18c20 20 69 6e 74 6f 20 5b 57 49 54 48 4f 55 54 20 52   into [WITHOUT R
18c30 4f 57 49 44 5d 20 74 61 62 6c 65 73 20 61 72 65  OWID] tables are
18c40 20 6e 6f 74 20 72 65 63 6f 72 64 65 64 2e 0a 2a   not recorded..*
18c50 2a 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73  * ^If no success
18c60 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 20 69 6e  ful [INSERT]s in
18c70 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 73 0a  to rowid tables.
18c80 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f 63 63  ** have ever occ
18c90 75 72 72 65 64 20 6f 6e 20 74 68 65 20 64 61 74  urred on the dat
18ca0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
18cb0 20 44 2c 20 0a 2a 2a 20 74 68 65 6e 20 73 71 6c   D, .** then sql
18cc0 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
18cd0 5f 72 6f 77 69 64 28 44 29 20 72 65 74 75 72 6e  _rowid(D) return
18ce0 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 28  s zero..**.** ^(
18cf0 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f  If an [INSERT] o
18d00 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74  ccurs within a t
18d10 72 69 67 67 65 72 20 6f 72 20 77 69 74 68 69 6e  rigger or within
18d20 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c   a [virtual tabl
18d30 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 68  e].** method, th
18d40 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  en this routine 
18d50 77 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20  will return the 
18d60 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69  [rowid] of the i
18d70 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 61  nserted.** row a
18d80 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72  s long as the tr
18d90 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c  igger or virtual
18da0 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 69 73   table method is
18db0 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74   running..** But
18dc0 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65   once the trigge
18dd0 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62  r or virtual tab
18de0 6c 65 20 6d 65 74 68 6f 64 20 65 6e 64 73 2c 20  le method ends, 
18df0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
18e00 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72  ed .** by this r
18e10 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73 20 74  outine reverts t
18e20 6f 20 77 68 61 74 20 69 74 20 77 61 73 20 62 65  o what it was be
18e30 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72  fore the trigger
18e40 20 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74   or virtual.** t
18e50 61 62 6c 65 20 6d 65 74 68 6f 64 20 62 65 67 61  able method bega
18e60 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b  n.)^.**.** ^An [
18e70 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61 69  INSERT] that fai
18e80 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73  ls due to a cons
18e90 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
18ea0 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63   is not a.** suc
18eb0 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d  cessful [INSERT]
18ec0 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68   and does not ch
18ed0 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 72  ange the value r
18ee0 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a  eturned by this.
18ef0 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68  ** routine.  ^Th
18f00 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49  us INSERT OR FAI
18f10 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e  L, INSERT OR IGN
18f20 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52  ORE, INSERT OR R
18f30 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20  OLLBACK,.** and 
18f40 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20  INSERT OR ABORT 
18f50 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20  make no changes 
18f60 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  to the return va
18f70 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72  lue of this.** r
18f80 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69  outine when thei
18f90 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c  r insertion fail
18fa0 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52  s.  ^(When INSER
18fb0 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20  T OR REPLACE.** 
18fc0 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e  encounters a con
18fd0 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
18fe0 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66  n, it does not f
18ff0 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53  ail.  The.** INS
19000 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f  ERT continues to
19010 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65   completion afte
19020 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20  r deleting rows 
19030 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74  that caused.** t
19040 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72  he constraint pr
19050 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20  oblem so INSERT 
19060 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20  OR REPLACE will 
19070 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a  always change.**
19080 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
19090 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66  e of this interf
190a0 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f  ace.)^.**.** ^Fo
190b0 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f  r the purposes o
190c0 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20  f this routine, 
190d0 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63  an [INSERT] is c
190e0 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20  onsidered to.** 
190f0 62 65 20 73 75 63 63 65 73 73 66 75 6c 20 65 76  be successful ev
19100 65 6e 20 69 66 20 69 74 20 69 73 20 73 75 62 73  en if it is subs
19110 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20  equently rolled 
19120 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  back..**.** This
19130 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63   function is acc
19140 65 73 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73  essible to SQL s
19150 74 61 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68  tatements via th
19160 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72  e.** [last_inser
19170 74 5f 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75  t_rowid() SQL fu
19180 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49  nction]..**.** I
19190 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
191a0 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e  ead performs a n
191b0 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74  ew [INSERT] on t
191c0 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62  he same.** datab
191d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77  ase connection w
191e0 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65  hile the [sqlite
191f0 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
19200 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69  wid()].** functi
19210 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e  on is running an
19220 64 20 74 68 75 73 20 63 68 61 6e 67 65 73 20 74  d thus changes t
19230 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b  he last insert [
19240 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20  rowid],.** then 
19250 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
19260 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c  ed by [sqlite3_l
19270 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
19280 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64  ()] is.** unpred
19290 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68  ictable and migh
192a0 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68  t not equal eith
192b0 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68  er the old or th
192c0 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e  e new.** last in
192d0 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f  sert [rowid]..*/
192e0 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
192f0 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
19300 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33  rt_rowid(sqlite3
19310 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
19320 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e  REF: Count The N
19330 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f  umber Of Rows Mo
19340 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48 4f 44  dified.** METHOD
19350 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
19360 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72  ^This function r
19370 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
19380 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69  r of rows modifi
19390 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 0a  ed, inserted or.
193a0 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20 74 68  ** deleted by th
193b0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20  e most recently 
193c0 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54  completed INSERT
193d0 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45  , UPDATE or DELE
193e0 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  TE.** statement 
193f0 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  on the database 
19400 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 70 65 63 69  connection speci
19410 66 69 65 64 20 62 79 20 74 68 65 20 6f 6e 6c 79  fied by the only
19420 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e   parameter..** ^
19430 45 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f 74  Executing any ot
19440 68 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c 20  her type of SQL 
19450 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e  statement does n
19460 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20 76 61  ot modify the va
19470 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lue.** returned 
19480 62 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  by this function
19490 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 63 68  ..**.** ^Only ch
194a0 61 6e 67 65 73 20 6d 61 64 65 20 64 69 72 65 63  anges made direc
194b0 74 6c 79 20 62 79 20 74 68 65 20 49 4e 53 45 52  tly by the INSER
194c0 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c  T, UPDATE or DEL
194d0 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 61 72  ETE statement ar
194e0 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20  e.** considered 
194f0 2d 20 61 75 78 69 6c 69 61 72 79 20 63 68 61 6e  - auxiliary chan
19500 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b 43  ges caused by [C
19510 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20  REATE TRIGGER | 
19520 74 72 69 67 67 65 72 73 5d 2c 20 0a 2a 2a 20 5b  triggers], .** [
19530 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69  foreign key acti
19540 6f 6e 73 5d 20 6f 72 20 5b 52 45 50 4c 41 43 45  ons] or [REPLACE
19550 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73  ] constraint res
19560 6f 6c 75 74 69 6f 6e 20 61 72 65 20 6e 6f 74 20  olution are not 
19570 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20  counted..** .** 
19580 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65  Changes to a vie
19590 77 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72  w that are inter
195a0 63 65 70 74 65 64 20 62 79 20 0a 2a 2a 20 5b 49  cepted by .** [I
195b0 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65  NSTEAD OF trigge
195c0 72 20 7c 20 49 4e 53 54 45 41 44 20 4f 46 20 74  r | INSTEAD OF t
195d0 72 69 67 67 65 72 73 5d 20 61 72 65 20 6e 6f 74  riggers] are not
195e0 20 63 6f 75 6e 74 65 64 2e 20 5e 54 68 65 20 76   counted. ^The v
195f0 61 6c 75 65 20 0a 2a 2a 20 72 65 74 75 72 6e 65  alue .** returne
19600 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61  d by sqlite3_cha
19610 6e 67 65 73 28 29 20 69 6d 6d 65 64 69 61 74 65  nges() immediate
19620 6c 79 20 61 66 74 65 72 20 61 6e 20 49 4e 53 45  ly after an INSE
19630 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 0a 2a  RT, UPDATE or .*
19640 2a 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65  * DELETE stateme
19650 6e 74 20 72 75 6e 20 6f 6e 20 61 20 76 69 65 77  nt run on a view
19660 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2e   is always zero.
19670 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61   Only changes ma
19680 64 65 20 74 6f 20 72 65 61 6c 20 0a 2a 2a 20 74  de to real .** t
19690 61 62 6c 65 73 20 61 72 65 20 63 6f 75 6e 74 65  ables are counte
196a0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 67 73 20  d..**.** Things 
196b0 61 72 65 20 6d 6f 72 65 20 63 6f 6d 70 6c 69 63  are more complic
196c0 61 74 65 64 20 69 66 20 74 68 65 20 73 71 6c 69  ated if the sqli
196d0 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66 75  te3_changes() fu
196e0 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 65 78 65  nction is.** exe
196f0 63 75 74 65 64 20 77 68 69 6c 65 20 61 20 74 72  cuted while a tr
19700 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 69 73  igger program is
19710 20 72 75 6e 6e 69 6e 67 2e 20 54 68 69 73 20 6d   running. This m
19720 61 79 20 68 61 70 70 65 6e 20 69 66 20 74 68 65  ay happen if the
19730 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 65 73  .** program uses
19740 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20   the [changes() 
19750 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2c 20 6f  SQL function], o
19760 72 20 69 66 20 73 6f 6d 65 20 6f 74 68 65 72 20  r if some other 
19770 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63  callback.** func
19780 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 73 71 6c  tion invokes sql
19790 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 64  ite3_changes() d
197a0 69 72 65 63 74 6c 79 2e 20 45 73 73 65 6e 74 69  irectly. Essenti
197b0 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c  ally:.** .** <ul
197c0 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 42 65  >.**   <li> ^(Be
197d0 66 6f 72 65 20 65 6e 74 65 72 69 6e 67 20 61 20  fore entering a 
197e0 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20  trigger program 
197f0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
19800 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20  ed by.**        
19810 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
19820 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 73 61  ) function is sa
19830 76 65 64 2e 20 41 66 74 65 72 20 74 68 65 20 74  ved. After the t
19840 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 0a  rigger program .
19850 2a 2a 20 20 20 20 20 20 20 20 68 61 73 20 66 69  **        has fi
19860 6e 69 73 68 65 64 2c 20 74 68 65 20 6f 72 69 67  nished, the orig
19870 69 6e 61 6c 20 76 61 6c 75 65 20 69 73 20 72 65  inal value is re
19880 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20 0a 2a 2a  stored.)^.** .**
19890 20 20 20 3c 6c 69 3e 20 5e 28 57 69 74 68 69 6e     <li> ^(Within
198a0 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72   a trigger progr
198b0 61 6d 20 65 61 63 68 20 49 4e 53 45 52 54 2c 20  am each INSERT, 
198c0 55 50 44 41 54 45 20 61 6e 64 20 44 45 4c 45 54  UPDATE and DELET
198d0 45 20 0a 2a 2a 20 20 20 20 20 20 20 20 73 74 61  E .**        sta
198e0 74 65 6d 65 6e 74 20 73 65 74 73 20 74 68 65 20  tement sets the 
198f0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
19900 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  y sqlite3_change
19910 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 75  s() .**        u
19920 70 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61  pon completion a
19930 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20 63 6f 75  s normal. Of cou
19940 72 73 65 2c 20 74 68 69 73 20 76 61 6c 75 65 20  rse, this value 
19950 77 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c 75 64 65  will not include
19960 20 0a 2a 2a 20 20 20 20 20 20 20 20 61 6e 79 20   .**        any 
19970 63 68 61 6e 67 65 73 20 70 65 72 66 6f 72 6d 65  changes performe
19980 64 20 62 79 20 73 75 62 2d 74 72 69 67 67 65 72  d by sub-trigger
19990 73 2c 20 61 73 20 74 68 65 20 73 71 6c 69 74 65  s, as the sqlite
199a0 33 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20  3_changes() .** 
199b0 20 20 20 20 20 20 20 76 61 6c 75 65 20 77 69 6c         value wil
199c0 6c 20 62 65 20 73 61 76 65 64 20 61 6e 64 20 72  l be saved and r
199d0 65 73 74 6f 72 65 64 20 61 66 74 65 72 20 65 61  estored after ea
199e0 63 68 20 73 75 62 2d 74 72 69 67 67 65 72 20 68  ch sub-trigger h
199f0 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f 75  as run.)^.** </u
19a00 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68 69 73 20  l>.** .** ^This 
19a10 6d 65 61 6e 73 20 74 68 61 74 20 69 66 20 74 68  means that if th
19a20 65 20 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20  e changes() SQL 
19a30 66 75 6e 63 74 69 6f 6e 20 28 6f 72 20 73 69 6d  function (or sim
19a40 69 6c 61 72 29 20 69 73 20 75 73 65 64 0a 2a 2a  ilar) is used.**
19a50 20 62 79 20 74 68 65 20 66 69 72 73 74 20 49 4e   by the first IN
19a60 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20  SERT, UPDATE or 
19a70 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74  DELETE statement
19a80 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65   within a trigge
19a90 72 2c 20 69 74 20 0a 2a 2a 20 72 65 74 75 72 6e  r, it .** return
19aa0 73 20 74 68 65 20 76 61 6c 75 65 20 61 73 20 73  s the value as s
19ab0 65 74 20 77 68 65 6e 20 74 68 65 20 63 61 6c 6c  et when the call
19ac0 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 62 65  ing statement be
19ad0 67 61 6e 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a  gan executing..*
19ae0 2a 20 5e 49 66 20 69 74 20 69 73 20 75 73 65 64  * ^If it is used
19af0 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 6f   by the second o
19b00 72 20 73 75 62 73 65 71 75 65 6e 74 20 73 75 63  r subsequent suc
19b10 68 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  h statement with
19b20 69 6e 20 61 20 74 72 69 67 67 65 72 20 0a 2a 2a  in a trigger .**
19b30 20 70 72 6f 67 72 61 6d 2c 20 74 68 65 20 76 61   program, the va
19b40 6c 75 65 20 72 65 74 75 72 6e 65 64 20 72 65 66  lue returned ref
19b50 6c 65 63 74 73 20 74 68 65 20 6e 75 6d 62 65 72  lects the number
19b60 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 65   of rows modifie
19b70 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 70 72 65  d by the .** pre
19b80 76 69 6f 75 73 20 49 4e 53 45 52 54 2c 20 55 50  vious INSERT, UP
19b90 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73  DATE or DELETE s
19ba0 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
19bb0 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72  the same trigger
19bc0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
19bd0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f   the [sqlite3_to
19be0 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  tal_changes()] i
19bf0 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a  nterface, the.**
19c00 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20   [count_changes 
19c10 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65  pragma], and the
19c20 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20   [changes() SQL 
19c30 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  function]..**.**
19c40 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
19c50 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e  hread makes chan
19c60 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ges on the same 
19c70 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
19c80 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71  ion.** while [sq
19c90 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d  lite3_changes()]
19ca0 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
19cb0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
19cc0 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64  ned.** is unpred
19cd0 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20  ictable and not 
19ce0 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69  meaningful..*/.i
19cf0 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  nt sqlite3_chang
19d00 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  es(sqlite3*);../
19d10 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
19d20 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52  otal Number Of R
19d30 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20  ows Modified.** 
19d40 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
19d50 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
19d60 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
19d70 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66   total number of
19d80 20 72 6f 77 73 20 69 6e 73 65 72 74 65 64 2c 20   rows inserted, 
19d90 6d 6f 64 69 66 69 65 64 20 6f 72 0a 2a 2a 20 64  modified or.** d
19da0 65 6c 65 74 65 64 20 62 79 20 61 6c 6c 20 5b 49  eleted by all [I
19db0 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d  NSERT], [UPDATE]
19dc0 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61   or [DELETE] sta
19dd0 74 65 6d 65 6e 74 73 20 63 6f 6d 70 6c 65 74 65  tements complete
19de0 64 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 64  d.** since the d
19df0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
19e00 6f 6e 20 77 61 73 20 6f 70 65 6e 65 64 2c 20 69  on was opened, i
19e10 6e 63 6c 75 64 69 6e 67 20 74 68 6f 73 65 20 65  ncluding those e
19e20 78 65 63 75 74 65 64 20 61 73 0a 2a 2a 20 70 61  xecuted as.** pa
19e30 72 74 20 6f 66 20 74 72 69 67 67 65 72 20 70 72  rt of trigger pr
19e40 6f 67 72 61 6d 73 2e 20 5e 45 78 65 63 75 74 69  ograms. ^Executi
19e50 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70  ng any other typ
19e60 65 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65  e of SQL stateme
19e70 6e 74 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 61  nt.** does not a
19e80 66 66 65 63 74 20 74 68 65 20 76 61 6c 75 65 20  ffect the value 
19e90 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
19ea0 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
19eb0 73 28 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 61  s()..** .** ^Cha
19ec0 6e 67 65 73 20 6d 61 64 65 20 61 73 20 70 61 72  nges made as par
19ed0 74 20 6f 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65  t of [foreign ke
19ee0 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 69  y actions] are i
19ef0 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 0a 2a  ncluded in the.*
19f00 2a 20 63 6f 75 6e 74 2c 20 62 75 74 20 74 68 6f  * count, but tho
19f10 73 65 20 6d 61 64 65 20 61 73 20 70 61 72 74 20  se made as part 
19f20 6f 66 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74  of REPLACE const
19f30 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e  raint resolution
19f40 20 61 72 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 68   are.** not. ^Ch
19f50 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20  anges to a view 
19f60 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 63 65  that are interce
19f70 70 74 65 64 20 62 79 20 49 4e 53 54 45 41 44 20  pted by INSTEAD 
19f80 4f 46 20 74 72 69 67 67 65 72 73 20 0a 2a 2a 20  OF triggers .** 
19f90 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e  are not counted.
19fa0 0a 2a 2a 20 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  .** .** See also
19fb0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68   the [sqlite3_ch
19fc0 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61  anges()] interfa
19fd0 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e  ce, the.** [coun
19fe0 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61  t_changes pragma
19ff0 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61  ], and the [tota
1a000 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20  l_changes() SQL 
1a010 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  function]..**.**
1a020 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
1a030 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e  hread makes chan
1a040 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ges on the same 
1a050 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1a060 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71  ion.** while [sq
1a070 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
1a080 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e  ges()] is runnin
1a090 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  g then the value
1a0a0 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20  .** returned is 
1a0b0 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
1a0c0 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c  d not meaningful
1a0d0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1a0e0 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73  _total_changes(s
1a0f0 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
1a100 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72   CAPI3REF: Inter
1a110 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e  rupt A Long-Runn
1a120 69 6e 67 20 51 75 65 72 79 0a 2a 2a 20 4d 45 54  ing Query.** MET
1a130 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
1a140 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
1a150 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e  n causes any pen
1a160 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70  ding database op
1a170 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74  eration to abort
1a180 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61   and.** return a
1a190 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f  t its earliest o
1a1a0 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73  pportunity. This
1a1b0 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69   routine is typi
1a1c0 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20  cally.** called 
1a1d0 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61  in response to a
1a1e0 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63   user action suc
1a1f0 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43  h as pressing "C
1a200 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72  ancel".** or Ctr
1a210 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73  l-C where the us
1a220 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20  er wants a long 
1a230 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20  query operation 
1a240 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64  to halt.** immed
1a250 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49  iately..**.** ^I
1a260 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c  t is safe to cal
1a270 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66  l this routine f
1a280 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66  rom a thread dif
1a290 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a  ferent from the.
1a2a0 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69  ** thread that i
1a2b0 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e  s currently runn
1a2c0 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65  ing the database
1a2d0 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74   operation.  But
1a2e0 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61   it.** is not sa
1a2f0 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20  fe to call this 
1a300 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b  routine with a [
1a310 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1a320 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20  ion] that.** is 
1a330 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20  closed or might 
1a340 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c  close before sql
1a350 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
1a360 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
1a370 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61  ^If an SQL opera
1a380 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61  tion is very nea
1a390 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 20  rly finished at 
1a3a0 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a  the time when.**
1a3b0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
1a3c0 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20  pt() is called, 
1a3d0 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f  then it might no
1a3e0 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74  t have an opport
1a3f0 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69  unity.** to be i
1a400 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d  nterrupted and m
1a410 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f  ight continue to
1a420 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a   completion..**.
1a430 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61  ** ^An SQL opera
1a440 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74  tion that is int
1a450 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65  errupted will re
1a460 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54  turn [SQLITE_INT
1a470 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20  ERRUPT]..** ^If 
1a480 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20  the interrupted 
1a490 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  SQL operation is
1a4a0 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41   an INSERT, UPDA
1a4b0 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  TE, or DELETE.**
1a4c0 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20   that is inside 
1a4d0 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  an explicit tran
1a4e0 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68  saction, then th
1a4f0 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63  e entire transac
1a500 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  tion.** will be 
1a510 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f  rolled back auto
1a520 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a  matically..**.**
1a530 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
1a540 74 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20  terrupt(D) call 
1a550 69 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74  is in effect unt
1a560 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79  il all currently
1a570 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20   running.** SQL 
1a580 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64  statements on [d
1a590 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1a5a0 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20  on] D complete. 
1a5b0 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74   ^Any new SQL st
1a5c0 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
1a5d0 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
1a5e0 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  er the sqlite3_i
1a5f0 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20  nterrupt() call 
1a600 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a  and before the .
1a610 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65  ** running state
1a620 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65  ments reaches ze
1a630 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70 74  ro are interrupt
1a640 65 64 20 61 73 20 69 66 20 74 68 65 79 20 68 61  ed as if they ha
1a650 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e  d been.** runnin
1a660 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73  g prior to the s
1a670 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1a680 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53  () call.  ^New S
1a690 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
1a6a0 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65   that are starte
1a6b0 64 20 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e  d after the runn
1a6c0 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  ing statement co
1a6d0 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f  unt reaches zero
1a6e0 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65   are.** not effe
1a6f0 63 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69  cted by the sqli
1a700 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e  te3_interrupt().
1a710 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73  .** ^A call to s
1a720 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1a730 28 44 29 20 74 68 61 74 20 6f 63 63 75 72 73 20  (D) that occurs 
1a740 77 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e  when there are n
1a750 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c  o running.** SQL
1a760 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61   statements is a
1a770 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e   no-op and has n
1a780 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20  o effect on SQL 
1a790 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68  statements.** th
1a7a0 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61  at are started a
1a7b0 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33  fter the sqlite3
1a7c0 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c  _interrupt() cal
1a7d0 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  l returns..**.**
1a7e0 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65   If the database
1a7f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73   connection clos
1a800 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  es while [sqlite
1a810 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a  3_interrupt()].*
1a820 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  * is running the
1a830 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c  n bad things wil
1a840 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e  l likely happen.
1a850 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
1a860 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74  _interrupt(sqlit
1a870 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
1a880 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
1a890 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65   If An SQL State
1a8a0 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65  ment Is Complete
1a8b0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
1a8c0 74 69 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c  tines are useful
1a8d0 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d   during command-
1a8e0 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65  line input to de
1a8f0 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a  termine if the.*
1a900 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65  * currently ente
1a910 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20 74  red text seems t
1a920 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74  o form a complet
1a930 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
1a940 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f  or.** if additio
1a950 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65  nal input is nee
1a960 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69  ded before sendi
1a970 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f  ng the text into
1a980 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70  .** SQLite for p
1a990 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 20  arsing.  ^These 
1a9a0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
1a9b0 31 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 73  1 if the input s
1a9c0 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73  tring.** appears
1a9d0 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74   to be a complet
1a9e0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  e SQL statement.
1a9f0 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 69    ^A statement i
1aa00 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a  s judged to be.*
1aa10 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74  * complete if it
1aa20 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d   ends with a sem
1aa30 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64  icolon token and
1aa40 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78   is not a prefix
1aa50 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f   of a.** well-fo
1aa60 72 6d 65 64 20 43 52 45 41 54 45 20 54 52 49 47  rmed CREATE TRIG
1aa70 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  GER statement.  
1aa80 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74  ^Semicolons that
1aa90 20 61 72 65 20 65 6d 62 65 64 64 65 64 20 77 69   are embedded wi
1aaa0 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c  thin.** string l
1aab0 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65  iterals or quote
1aac0 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d  d identifier nam
1aad0 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61  es or comments a
1aae0 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65  re not.** indepe
1aaf0 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68  ndent tokens (th
1ab00 65 79 20 61 72 65 20 70 61 72 74 20 6f 66 20 74  ey are part of t
1ab10 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63  he token in whic
1ab20 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d  h they are.** em
1ab30 62 65 64 64 65 64 29 20 61 6e 64 20 74 68 75 73  bedded) and thus
1ab40 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73   do not count as
1ab50 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72   a statement ter
1ab60 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 65  minator.  ^White
1ab70 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d  space.** and com
1ab80 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f  ments that follo
1ab90 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69  w the final semi
1aba0 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65  colon are ignore
1abb0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  d..**.** ^These 
1abc0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
1abd0 30 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65  0 if the stateme
1abe0 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65  nt is incomplete
1abf0 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f  .  ^If a.** memo
1ac00 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
1ac10 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45  ils, then SQLITE
1ac20 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e  _NOMEM is return
1ac30 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ed..**.** ^These
1ac40 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74   routines do not
1ac50 20 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 73   parse the SQL s
1ac60 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a  tatements thus.*
1ac70 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63  * will not detec
1ac80 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20  t syntactically 
1ac90 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a  incorrect SQL..*
1aca0 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 65  *.** ^(If SQLite
1acb0 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e   has not been in
1acc0 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20  itialized using 
1acd0 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  [sqlite3_initial
1ace0 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a  ize()] prior .**
1acf0 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c   to invoking sql
1ad00 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
1ad10 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69  ) then sqlite3_i
1ad20 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
1ad30 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61  nvoked.** automa
1ad40 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74  tically by sqlit
1ad50 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e  e3_complete16().
1ad60 20 20 49 66 20 74 68 61 74 20 69 6e 69 74 69 61    If that initia
1ad70 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a  lization fails,.
1ad80 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75  ** then the retu
1ad90 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  rn value from sq
1ada0 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
1adb0 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a  () will be non-z
1adc0 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73  ero.** regardles
1add0 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
1ade0 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53 51  not the input SQ
1adf0 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e  L is complete.)^
1ae00 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74  .**.** The input
1ae10 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d   to [sqlite3_com
1ae20 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65  plete()] must be
1ae30 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
1ae40 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69  ed.** UTF-8 stri
1ae50 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  ng..**.** The in
1ae60 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
1ae70 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75  complete16()] mu
1ae80 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72  st be a zero-ter
1ae90 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31  minated.** UTF-1
1aea0 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69  6 string in nati
1aeb0 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
1aec0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  /.int sqlite3_co
1aed0 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61  mplete(const cha
1aee0 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c  r *sql);.int sql
1aef0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
1af00 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29  const void *sql)
1af10 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1af20 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 43 61  F: Register A Ca
1af30 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65  llback To Handle
1af40 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72   SQLITE_BUSY Err
1af50 6f 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ors.** KEYWORDS:
1af60 20 7b 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63   {busy-handler c
1af70 61 6c 6c 62 61 63 6b 7d 20 7b 62 75 73 79 20 68  allback} {busy h
1af80 61 6e 64 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f  andler}.** METHO
1af90 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
1afa0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 75   ^The sqlite3_bu
1afb0 73 79 5f 68 61 6e 64 6c 65 72 28 44 2c 58 2c 50  sy_handler(D,X,P
1afc0 29 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61  ) routine sets a
1afd0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1afe0 6f 6e 20 58 0a 2a 2a 20 74 68 61 74 20 6d 69 67  on X.** that mig
1aff0 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69  ht be invoked wi
1b000 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77 68  th argument P wh
1b010 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74  enever.** an att
1b020 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20  empt is made to 
1b030 61 63 63 65 73 73 20 61 20 64 61 74 61 62 61 73  access a databas
1b040 65 20 74 61 62 6c 65 20 61 73 73 6f 63 69 61 74  e table associat
1b050 65 64 20 77 69 74 68 0a 2a 2a 20 5b 64 61 74 61  ed with.** [data
1b060 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1b070 20 44 20 77 68 65 6e 20 61 6e 6f 74 68 65 72 20   D when another 
1b080 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f  thread.** or pro
1b090 63 65 73 73 20 68 61 73 20 74 68 65 20 74 61 62  cess has the tab
1b0a0 6c 65 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20 54 68  le locked..** Th
1b0b0 65 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  e sqlite3_busy_h
1b0c0 61 6e 64 6c 65 72 28 29 20 69 6e 74 65 72 66 61  andler() interfa
1b0d0 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 69 6d  ce is used to im
1b0e0 70 6c 65 6d 65 6e 74 0a 2a 2a 20 5b 73 71 6c 69  plement.** [sqli
1b0f0 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
1b100 28 29 5d 20 61 6e 64 20 5b 50 52 41 47 4d 41 20  ()] and [PRAGMA 
1b110 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 2e 0a 2a  busy_timeout]..*
1b120 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73  *.** ^If the bus
1b130 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55  y callback is NU
1b140 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45  LL, then [SQLITE
1b150 5f 42 55 53 59 5d 0a 2a 2a 20 69 73 20 72 65 74  _BUSY].** is ret
1b160 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  urned immediatel
1b170 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72  y upon encounter
1b180 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e  ing the lock.  ^
1b190 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c  If the busy call
1b1a0 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e  back.** is not N
1b1b0 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61  ULL, then the ca
1b1c0 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62 65 20  llback might be 
1b1d0 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f  invoked with two
1b1e0 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a   arguments..**.*
1b1f0 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
1b200 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62 75 73  ument to the bus
1b210 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63  y handler is a c
1b220 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a  opy of the void*
1b230 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a   pointer which.*
1b240 2a 20 69 73 20 74 68 65 20 74 68 69 72 64 20 61  * is the third a
1b250 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
1b260 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
1b270 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  ).  ^The second 
1b280 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74  argument to.** t
1b290 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
1b2a0 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20  callback is the 
1b2b0 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20  number of times 
1b2c0 74 68 61 74 20 74 68 65 20 62 75 73 79 20 68 61  that the busy ha
1b2d0 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65  ndler has.** bee
1b2e0 6e 20 69 6e 76 6f 6b 65 64 20 70 72 65 76 69 6f  n invoked previo
1b2f0 75 73 6c 79 20 66 6f 72 20 74 68 65 20 73 61 6d  usly for the sam
1b300 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e  e locking event.
1b310 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 73    ^If the.** bus
1b320 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  y callback retur
1b330 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64  ns 0, then no ad
1b340 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74  ditional attempt
1b350 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a  s are made to.**
1b360 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61   access the data
1b370 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45  base and [SQLITE
1b380 5f 42 55 53 59 5d 20 69 73 20 72 65 74 75 72 6e  _BUSY] is return
1b390 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 70  ed.** to the app
1b3a0 6c 69 63 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66  lication..** ^If
1b3b0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
1b3c0 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
1b3d0 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74  then another att
1b3e0 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20  empt.** is made 
1b3f0 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 61  to access the da
1b400 74 61 62 61 73 65 20 61 6e 64 20 74 68 65 20 63  tabase and the c
1b410 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a  ycle repeats..**
1b420 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65  .** The presence
1b430 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c   of a busy handl
1b440 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72  er does not guar
1b450 61 6e 74 65 65 20 74 68 61 74 20 69 74 20 77 69  antee that it wi
1b460 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a  ll be invoked.**
1b470 20 77 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c   when there is l
1b480 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20  ock contention. 
1b490 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74 65 72  ^If SQLite deter
1b4a0 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b  mines that invok
1b4b0 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20  ing the busy.** 
1b4c0 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65  handler could re
1b4d0 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f  sult in a deadlo
1b4e0 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61  ck, it will go a
1b4f0 68 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20  head and return 
1b500 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a  [SQLITE_BUSY].**
1b510 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
1b520 69 6f 6e 20 69 6e 73 74 65 61 64 20 6f 66 20 69  ion instead of i
1b530 6e 76 6f 6b 69 6e 67 20 74 68 65 20 0a 2a 2a 20  nvoking the .** 
1b540 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  busy handler..**
1b550 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e   Consider a scen
1b560 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70  ario where one p
1b570 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e  rocess is holdin
1b580 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68  g a read lock th
1b590 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69  at.** it is tryi
1b5a0 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f  ng to promote to
1b5b0 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b   a reserved lock
1b5c0 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64   and.** a second
1b5d0 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64   process is hold
1b5e0 69 6e 67 20 61 20 72 65 73 65 72 76 65 64 20 6c  ing a reserved l
1b5f0 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73 20 74  ock that it is t
1b600 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d  rying.** to prom
1b610 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73  ote to an exclus
1b620 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66  ive lock.  The f
1b630 69 72 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e  irst process can
1b640 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62  not proceed.** b
1b650 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f  ecause it is blo
1b660 63 6b 65 64 20 62 79 20 74 68 65 20 73 65 63 6f  cked by the seco
1b670 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  nd and the secon
1b680 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74  d process cannot
1b690 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61  .** proceed beca
1b6a0 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65  use it is blocke
1b6b0 64 20 62 79 20 74 68 65 20 66 69 72 73 74 2e 20  d by the first. 
1b6c0 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73   If both process
1b6d0 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65  es.** invoke the
1b6e0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20   busy handlers, 
1b6f0 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b  neither will mak
1b700 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20  e any progress. 
1b710 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53   Therefore,.** S
1b720 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53  QLite returns [S
1b730 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20  QLITE_BUSY] for 
1b740 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  the first proces
1b750 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74  s, hoping that t
1b760 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75  his.** will indu
1b770 63 65 20 74 68 65 20 66 69 72 73 74 20 70 72 6f  ce the first pro
1b780 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20  cess to release 
1b790 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e  its read lock an
1b7a0 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73  d allow.** the s
1b7b0 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f  econd process to
1b7c0 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20   proceed..**.** 
1b7d0 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 75 73  ^The default bus
1b7e0 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55  y callback is NU
1b7f0 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72  LL..**.** ^(Ther
1b800 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20  e can only be a 
1b810 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64  single busy hand
1b820 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20  ler defined for 
1b830 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73  each.** [databas
1b840 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20  e connection].  
1b850 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75  Setting a new bu
1b860 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72  sy handler clear
1b870 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75  s any.** previou
1b880 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e  sly set handler.
1b890 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 63  )^  ^Note that c
1b8a0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
1b8b0 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a  busy_timeout()].
1b8c0 2a 2a 20 6f 72 20 65 76 61 6c 75 61 74 69 6e 67  ** or evaluating
1b8d0 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69   [PRAGMA busy_ti
1b8e0 6d 65 6f 75 74 3d 4e 5d 20 77 69 6c 6c 20 63 68  meout=N] will ch
1b8f0 61 6e 67 65 20 74 68 65 0a 2a 2a 20 62 75 73 79  ange the.** busy
1b900 20 68 61 6e 64 6c 65 72 20 61 6e 64 20 74 68 75   handler and thu
1b910 73 20 63 6c 65 61 72 20 61 6e 79 20 70 72 65 76  s clear any prev
1b920 69 6f 75 73 6c 79 20 73 65 74 20 62 75 73 79 20  iously set busy 
1b930 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  handler..**.** T
1b940 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  he busy callback
1b950 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65   should not take
1b960 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69   any actions whi
1b970 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a  ch modify the.**
1b980 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1b990 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
1b9a0 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  d the busy handl
1b9b0 65 72 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  er.  In other wo
1b9c0 72 64 73 2c 0a 2a 2a 20 74 68 65 20 62 75 73 79  rds,.** the busy
1b9d0 20 68 61 6e 64 6c 65 72 20 69 73 20 6e 6f 74 20   handler is not 
1b9e0 72 65 65 6e 74 72 61 6e 74 2e 20 20 41 6e 79 20  reentrant.  Any 
1b9f0 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20  such actions.** 
1ba00 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69  result in undefi
1ba10 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  ned behavior..**
1ba20 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64   .** A busy hand
1ba30 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f  ler must not clo
1ba40 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
1ba50 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72  connection.** or
1ba60 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1ba70 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b  ment] that invok
1ba80 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ed the busy hand
1ba90 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ler..*/.int sqli
1baa0 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
1bab0 28 73 71 6c 69 74 65 33 2a 2c 69 6e 74 28 2a 29  (sqlite3*,int(*)
1bac0 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 76 6f 69 64  (void*,int),void
1bad0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1bae0 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 79 20  REF: Set A Busy 
1baf0 54 69 6d 65 6f 75 74 0a 2a 2a 20 4d 45 54 48 4f  Timeout.** METHO
1bb00 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
1bb10 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73   ^This routine s
1bb20 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62  ets a [sqlite3_b
1bb30 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75  usy_handler | bu
1bb40 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74  sy handler] that
1bb50 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61   sleeps.** for a
1bb60 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e   specified amoun
1bb70 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61  t of time when a
1bb80 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64   table is locked
1bb90 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a  .  ^The handler.
1bba0 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75  ** will sleep mu
1bbb0 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74  ltiple times unt
1bbc0 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22  il at least "ms"
1bbd0 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
1bbe0 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76   sleeping.** hav
1bbf0 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 20  e accumulated.  
1bc00 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73 74 20  ^After at least 
1bc10 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  "ms" millisecond
1bc20 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a  s of sleeping,.*
1bc30 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65  * the handler re
1bc40 74 75 72 6e 73 20 30 20 77 68 69 63 68 20 63 61  turns 0 which ca
1bc50 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74  uses [sqlite3_st
1bc60 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a  ep()] to return.
1bc70 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ** [SQLITE_BUSY]
1bc80 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  ..**.** ^Calling
1bc90 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
1bca0 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c  th an argument l
1bcb0 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61  ess than or equa
1bcc0 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72  l to zero.** tur
1bcd0 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20  ns off all busy 
1bce0 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  handlers..**.** 
1bcf0 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79  ^(There can only
1bd00 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73   be a single bus
1bd10 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20  y handler for a 
1bd20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64  particular.** [d
1bd30 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1bd40 6f 6e 5d 20 61 74 20 61 6e 79 20 67 69 76 65 6e  on] at any given
1bd50 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f   moment.  If ano
1bd60 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65  ther busy handle
1bd70 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 64  r.** was defined
1bd80 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65    (using [sqlite
1bd90 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29  3_busy_handler()
1bda0 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c  ]) prior to call
1bdb0 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74  ing.** this rout
1bdc0 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20  ine, that other 
1bdd0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20  busy handler is 
1bde0 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a  cleared.)^.**.**
1bdf0 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 50 52 41   See also:  [PRA
1be00 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74  GMA busy_timeout
1be10 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
1be20 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71  _busy_timeout(sq
1be30 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b  lite3*, int ms);
1be40 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1be50 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f  : Convenience Ro
1be60 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69  utines For Runni
1be70 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 20 4d 45  ng Queries.** ME
1be80 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
1be90 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 6c 65  .** This is a le
1bea0 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 20 74  gacy interface t
1beb0 68 61 74 20 69 73 20 70 72 65 73 65 72 76 65 64  hat is preserved
1bec0 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
1bed0 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a  ompatibility..**
1bee0 20 55 73 65 20 6f 66 20 74 68 69 73 20 69 6e 74   Use of this int
1bef0 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65  erface is not re
1bf00 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a  commended..**.**
1bf10 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c   Definition: A <
1bf20 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f  b>result table</
1bf30 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74  b> is memory dat
1bf40 61 20 73 74 72 75 63 74 75 72 65 20 63 72 65 61  a structure crea
1bf50 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73  ted by the.** [s
1bf60 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1bf70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ()] interface.  
1bf80 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72  A result table r
1bf90 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f  ecords the.** co
1bfa0 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72 65 73  mplete query res
1bfb0 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72  ults from one or
1bfc0 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a   more queries..*
1bfd0 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63  *.** The table c
1bfe0 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20  onceptually has 
1bff0 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  a number of rows
1c000 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42   and columns.  B
1c010 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62  ut.** these numb
1c020 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74  ers are not part
1c030 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74   of the result t
1c040 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68  able itself.  Th
1c050 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61  ese.** numbers a
1c060 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61  re obtained sepa
1c070 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62  rately.  Let N b
1c080 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  e the number of 
1c090 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65  rows.** and M be
1c0a0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
1c0b0 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20  olumns..**.** A 
1c0c0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20  result table is 
1c0d0 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
1c0e0 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72  ters to zero-ter
1c0f0 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74  minated UTF-8 st
1c100 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20  rings..** There 
1c110 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d  are (N+1)*M elem
1c120 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72 61  ents in the arra
1c130 79 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d 20  y.  The first M 
1c140 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a  pointers point.*
1c150 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  * to zero-termin
1c160 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61  ated strings tha
1c170 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e  t  contain the n
1c180 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75  ames of the colu
1c190 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61  mns..** The rema
1c1a0 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c  ining entries al
1c1b0 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79  l point to query
1c1c0 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20   results.  NULL 
1c1d0 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a  values result.**
1c1e0 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72   in NULL pointer
1c1f0 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61  s.  All other va
1c200 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68 65 69  lues are in thei
1c210 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72  r UTF-8 zero-ter
1c220 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e  minated.** strin
1c230 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  g representation
1c240 20 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20   as returned by 
1c250 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
1c260 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41  text()]..**.** A
1c270 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69   result table mi
1c280 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f  ght consist of o
1c290 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72  ne or more memor
1c2a0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a  y allocations..*
1c2b0 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65  * It is not safe
1c2c0 20 74 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c   to pass a resul
1c2d0 74 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79  t table directly
1c2e0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   to [sqlite3_fre
1c2f0 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c  e()]..** A resul
1c300 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62  t table should b
1c310 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73  e deallocated us
1c320 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  ing [sqlite3_fre
1c330 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a  e_table()]..**.*
1c340 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 6d 70 6c  * ^(As an exampl
1c350 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  e of the result 
1c360 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75  table format, su
1c370 70 70 6f 73 65 20 61 20 71 75 65 72 79 20 72 65  ppose a query re
1c380 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f  sult.** is as fo
1c390 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
1c3a0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1c3b0 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20  *        Name   
1c3c0 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20       | Age.**   
1c3d0 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d       -----------
1c3e0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20  ------------.** 
1c3f0 20 20 20 20 20 20 20 41 6c 69 63 65 20 20 20 20         Alice    
1c400 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20     | 43.**      
1c410 20 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20    Bob         | 
1c420 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e  28.**        Cin
1c430 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a  dy       | 21.**
1c440 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1c450 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65  ote>.**.** There
1c460 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20   are two column 
1c470 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65  (M==2) and three
1c480 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54   rows (N==3).  T
1c490 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c  hus the.** resul
1c4a0 74 20 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e  t table has 8 en
1c4b0 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20  tries.  Suppose 
1c4c0 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
1c4d0 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e   is stored.** in
1c4e0 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20   an array names 
1c4f0 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20  azResult.  Then 
1c500 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74  azResult holds t
1c510 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a  his content:.**.
1c520 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1c530 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61  pre>.**        a
1c540 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d  zResult&#91;0] =
1c550 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20   "Name";.**     
1c560 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1c570 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20  1] = "Age";.**  
1c580 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1c590 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b  91;2] = "Alice";
1c5a0 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1c5b0 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33  ult&#91;3] = "43
1c5c0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1c5d0 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22  esult&#91;4] = "
1c5e0 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  Bob";.**        
1c5f0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20  azResult&#91;5] 
1c600 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20  = "28";.**      
1c610 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36    azResult&#91;6
1c620 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20  ] = "Cindy";.** 
1c630 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1c640 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a  #91;7] = "21";.*
1c650 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1c660 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  uote>)^.**.** ^T
1c670 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
1c680 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  able() function 
1c690 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72  evaluates one or
1c6a0 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c   more.** semicol
1c6b0 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c  on-separated SQL
1c6c0 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74   statements in t
1c6d0 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  he zero-terminat
1c6e0 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69  ed UTF-8.** stri
1c6f0 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70 61  ng of its 2nd pa
1c700 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75  rameter and retu
1c710 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61 62  rns a result tab
1c720 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69  le to the.** poi
1c730 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69 74  nter given in it
1c740 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 2e  s 3rd parameter.
1c750 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65  .**.** After the
1c760 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68 61 73   application has
1c770 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 74   finished with t
1c780 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 73  he result from s
1c790 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1c7a0 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70  (),.** it must p
1c7b0 61 73 73 20 74 68 65 20 72 65 73 75 6c 74 20 74  ass the result t
1c7c0 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f 20  able pointer to 
1c7d0 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
1c7e0 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f  le() in order to
1c7f0 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20  .** release the 
1c800 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20  memory that was 
1c810 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75  malloced.  Becau
1c820 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 74 68  se of the way th
1c830 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61  e.** [sqlite3_ma
1c840 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20  lloc()] happens 
1c850 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67  within sqlite3_g
1c860 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20  et_table(), the 
1c870 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74  calling.** funct
1c880 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79  ion must not try
1c890 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65   to call [sqlite
1c8a0 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63 74  3_free()] direct
1c8b0 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71  ly.  Only.** [sq
1c8c0 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
1c8d0 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72  ()] is able to r
1c8e0 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72  elease the memor
1c8f0 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73  y properly and s
1c900 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  afely..**.** The
1c910 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1c920 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  le() interface i
1c930 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73  s implemented as
1c940 20 61 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e   a wrapper aroun
1c950 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  d.** [sqlite3_ex
1c960 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69  ec()].  The sqli
1c970 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
1c980 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74  routine does not
1c990 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20   have access.** 
1c9a0 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20  to any internal 
1c9b0 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20  data structures 
1c9c0 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75  of SQLite.  It u
1c9d0 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62  ses only the pub
1c9e0 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  lic.** interface
1c9f0 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20   defined here.  
1ca00 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65  As a consequence
1ca10 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63  , errors that oc
1ca20 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72  cur in the.** wr
1ca30 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73  apper layer outs
1ca40 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72  ide of the inter
1ca50 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  nal [sqlite3_exe
1ca60 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f  c()] call are no
1ca70 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69  t.** reflected i
1ca80 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  n subsequent cal
1ca90 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  ls to [sqlite3_e
1caa0 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20  rrcode()] or.** 
1cab0 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
1cac0 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
1cad0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20  e3_get_table(.  
1cae0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
1caf0 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e        /* An open
1cb00 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63   database */.  c
1cb10 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
1cb20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62       /* SQL to b
1cb30 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20  e evaluated */. 
1cb40 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75   char ***pazResu
1cb50 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74  lt,    /* Result
1cb60 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a  s of the query *
1cb70 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20  /.  int *pnRow, 
1cb80 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d            /* Num
1cb90 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f  ber of result ro
1cba0 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  ws written here 
1cbb0 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75  */.  int *pnColu
1cbc0 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75  mn,        /* Nu
1cbd0 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63  mber of result c
1cbe0 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68  olumns written h
1cbf0 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ere */.  char **
1cc00 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f  pzErrmsg       /
1cc10 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
1cc20 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76  ten here */.);.v
1cc30 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65  oid sqlite3_free
1cc40 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65  _table(char **re
1cc50 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  sult);../*.** CA
1cc60 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65  PI3REF: Formatte
1cc70 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e  d String Printin
1cc80 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  g Functions.**.*
1cc90 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
1cca0 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73   are work-alikes
1ccb0 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66 28   of the "printf(
1ccc0 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e  )" family of fun
1ccd0 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74  ctions.** from t
1cce0 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
1ccf0 62 72 61 72 79 2e 0a 2a 2a 20 54 68 65 73 65 20  brary..** These 
1cd00 72 6f 75 74 69 6e 65 73 20 75 6e 64 65 72 73 74  routines underst
1cd10 61 6e 64 20 6d 6f 73 74 20 6f 66 20 74 68 65 20  and most of the 
1cd20 63 6f 6d 6d 6f 6e 20 4b 26 52 20 66 6f 72 6d 61  common K&R forma
1cd30 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 2c 0a 2a  tting options,.*
1cd40 2a 20 70 6c 75 73 20 73 6f 6d 65 20 61 64 64 69  * plus some addi
1cd50 74 69 6f 6e 61 6c 20 6e 6f 6e 2d 73 74 61 6e 64  tional non-stand
1cd60 61 72 64 20 66 6f 72 6d 61 74 73 2c 20 64 65 74  ard formats, det
1cd70 61 69 6c 65 64 20 62 65 6c 6f 77 2e 0a 2a 2a 20  ailed below..** 
1cd80 4e 6f 74 65 20 74 68 61 74 20 73 6f 6d 65 20 6f  Note that some o
1cd90 66 20 74 68 65 20 6d 6f 72 65 20 6f 62 73 63 75  f the more obscu
1cda0 72 65 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  re formatting op
1cdb0 74 69 6f 6e 73 20 66 72 6f 6d 20 72 65 63 65 6e  tions from recen
1cdc0 74 0a 2a 2a 20 43 2d 6c 69 62 72 61 72 79 20 73  t.** C-library s
1cdd0 74 61 6e 64 61 72 64 73 20 61 72 65 20 6f 6d 69  tandards are omi
1cde0 74 74 65 64 20 66 72 6f 6d 20 74 68 69 73 20 69  tted from this i
1cdf0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a  mplementation..*
1ce00 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1ce10 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20  3_mprintf() and 
1ce20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66  sqlite3_vmprintf
1ce30 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74  () routines writ
1ce40 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c  e their.** resul
1ce50 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  ts into memory o
1ce60 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
1ce70 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
1ce80 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20  .** The strings 
1ce90 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73  returned by thes
1cea0 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73  e two routines s
1ceb0 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65  hould be.** rele
1cec0 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  ased by [sqlite3
1ced0 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68  _free()].  ^Both
1cee0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
1cef0 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74   a.** NULL point
1cf00 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d  er if [sqlite3_m
1cf10 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62  alloc()] is unab
1cf20 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65  le to allocate e
1cf30 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20  nough.** memory 
1cf40 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75  to hold the resu
1cf50 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a  lting string..**
1cf60 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65  .** ^(The sqlite
1cf70 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75  3_snprintf() rou
1cf80 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20  tine is similar 
1cf90 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20  to "snprintf()" 
1cfa0 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e  from.** the stan
1cfb0 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20  dard C library. 
1cfc0 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77   The result is w
1cfd0 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a  ritten into the.
1cfe0 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69  ** buffer suppli
1cff0 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
1d000 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65   parameter whose
1d010 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62   size is given b
1d020 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70  y.** the first p
1d030 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74  arameter. Note t
1d040 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66  hat the order of
1d050 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77   the.** first tw
1d060 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20  o parameters is 
1d070 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e  reversed from sn
1d080 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69  printf().)^  Thi
1d090 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f  s is an.** histo
1d0a0 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74  rical accident t
1d0b0 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69  hat cannot be fi
1d0c0 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61  xed without brea
1d0d0 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64  king.** backward
1d0e0 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  s compatibility.
1d0f0 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68    ^(Note also th
1d100 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  at sqlite3_snpri
1d110 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73  ntf().** returns
1d120 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74   a pointer to it
1d130 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64  s buffer instead
1d140 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   of the number o
1d150 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20  f.** characters 
1d160 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e  actually written
1d170 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72   into the buffer
1d180 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68  .)^  We admit th
1d190 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  at.** the number
1d1a0 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 77   of characters w
1d1b0 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20  ritten would be 
1d1c0 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65  a more useful re
1d1d0 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75  turn.** value bu
1d1e0 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e  t we cannot chan
1d1f0 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ge the implement
1d200 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  ation of sqlite3
1d210 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e  _snprintf().** n
1d220 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b  ow without break
1d230 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  ing compatibilit
1d240 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e  y..**.** ^As lon
1d250 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20  g as the buffer 
1d260 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20  size is greater 
1d270 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74  than zero, sqlit
1d280 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
1d290 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
1d2a0 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61   the buffer is a
1d2b0 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69  lways zero-termi
1d2c0 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72  nated.  ^The fir
1d2d0 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  st.** parameter 
1d2e0 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c  "n" is the total
1d2f0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66   size of the buf
1d300 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73  fer, including s
1d310 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  pace for.** the 
1d320 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
1d330 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74    So the longest
1d340 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e   string that can
1d350 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a   be completely.*
1d360 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62  * written will b
1d370 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73  e n-1 characters
1d380 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1d390 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29  ite3_vsnprintf()
1d3a0 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61   routine is a va
1d3b0 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66  rargs version of
1d3c0 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1d3d0 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  f()..**.** These
1d3e0 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d   routines all im
1d3f0 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64  plement some add
1d400 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69  itional formatti
1d410 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68  ng.** options th
1d420 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f  at are useful fo
1d430 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53  r constructing S
1d440 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  QL statements..*
1d450 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75  * All of the usu
1d460 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d  al printf() form
1d470 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61  atting options a
1d480 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69  pply.  In additi
1d490 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20  on, there.** is 
1d4a0 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20  are "%q", "%Q", 
1d4b0 22 25 77 22 20 61 6e 64 20 22 25 7a 22 20 6f 70  "%w" and "%z" op
1d4c0 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  tions..**.** ^(T
1d4d0 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72  he %q option wor
1d4e0 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68  ks like %s in th
1d4f0 61 74 20 69 74 20 73 75 62 73 74 69 74 75 74 65  at it substitute
1d500 73 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74  s a nul-terminat
1d510 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f  ed.** string fro
1d520 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c  m the argument l
1d530 69 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73  ist.  But %q als
1d540 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20  o doubles every 
1d550 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a  '\'' character..
1d560 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e 65  ** %q is designe
1d570 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65  d for use inside
1d580 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
1d590 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e  l.)^  By doublin
1d5a0 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63  g each '\''.** c
1d5b0 68 61 72 61 63 74 65 72 20 69 74 20 65 73 63 61  haracter it esca
1d5c0 70 65 73 20 74 68 61 74 20 63 68 61 72 61 63 74  pes that charact
1d5d0 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74  er and allows it
1d5e0 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20   to be inserted 
1d5f0 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69  into.** the stri
1d600 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78  ng..**.** For ex
1d610 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68  ample, assume th
1d620 65 20 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c  e string variabl
1d630 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73  e zText contains
1d640 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73   text as follows
1d650 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1d660 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
1d670 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27  ar *zText = "It'
1d680 73 20 61 20 68 61 70 70 79 20 64 61 79 21 22 3b  s a happy day!";
1d690 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1d6a0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e  kquote>.**.** On
1d6b0 65 20 63 61 6e 20 75 73 65 20 74 68 69 73 20 74  e can use this t
1d6c0 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74  ext in an SQL st
1d6d0 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f  atement as follo
1d6e0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
1d6f0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1d700 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c  char *zSQL = sql
1d710 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e  ite3_mprintf("IN
1d720 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20  SERT INTO table 
1d730 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a  VALUES('%q')", z
1d740 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  Text);.**  sqlit
1d750 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c  e3_exec(db, zSQL
1d760 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20  , 0, 0, 0);.**  
1d770 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51  sqlite3_free(zSQ
1d780 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  L);.** </pre></b
1d790 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1d7a0 20 42 65 63 61 75 73 65 20 74 68 65 20 25 71 20   Because the %q 
1d7b0 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73  format string is
1d7c0 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20   used, the '\'' 
1d7d0 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65  character in zTe
1d7e0 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64  xt.** is escaped
1d7f0 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e   and the SQL gen
1d800 65 72 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c  erated is as fol
1d810 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
1d820 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1d830 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61    INSERT INTO ta
1d840 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27  ble1 VALUES('It'
1d850 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27  's a happy day!'
1d860 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ).** </pre></blo
1d870 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
1d880 68 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20  his is correct. 
1d890 20 48 61 64 20 77 65 20 75 73 65 64 20 25 73 20   Had we used %s 
1d8a0 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74  instead of %q, t
1d8b0 68 65 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c  he generated SQL
1d8c0 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c  .** would have l
1d8d0 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a  ooked like this:
1d8e0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1d8f0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53  te><pre>.**  INS
1d900 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20  ERT INTO table1 
1d910 56 41 4c 55 45 53 28 27 49 74 27 73 20 61 20 68  VALUES('It's a h
1d920 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20  appy day!');.** 
1d930 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1d940 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73  te>.**.** This s
1d950 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73  econd example is
1d960 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65   an SQL syntax e
1d970 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65  rror.  As a gene
1d980 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f  ral rule you sho
1d990 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73  uld.** always us
1d9a0 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20  e %q instead of 
1d9b0 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e  %s when insertin
1d9c0 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74  g text into a st
1d9d0 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a  ring literal..**
1d9e0 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74  .** ^(The %Q opt
1d9f0 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25  ion works like %
1da00 71 20 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f  q except it also
1da10 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f   adds single quo
1da20 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68  tes around.** th
1da30 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65  e outside of the
1da40 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20   total string.  
1da50 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66  Additionally, if
1da60 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
1da70 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e  n the.** argumen
1da80 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c  t list is a NULL
1da90 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62   pointer, %Q sub
1daa0 73 74 69 74 75 74 65 73 20 74 68 65 20 74 65 78  stitutes the tex
1dab0 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75  t "NULL" (withou
1dac0 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74  t.** single quot
1dad0 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20  es).)^  So, for 
1dae0 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75  example, one cou
1daf0 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ld say:.**.** <b
1db00 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1db10 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d  **  char *zSQL =
1db20 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
1db30 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61  ("INSERT INTO ta
1db40 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c  ble VALUES(%Q)",
1db50 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c   zText);.**  sql
1db60 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53  ite3_exec(db, zS
1db70 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a  QL, 0, 0, 0);.**
1db80 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a    sqlite3_free(z
1db90 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  SQL);.** </pre><
1dba0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1dbb0 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76  ** The code abov
1dbc0 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20  e will render a 
1dbd0 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 74  correct SQL stat
1dbe0 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51  ement in the zSQ
1dbf0 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76  L.** variable ev
1dc00 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 20  en if the zText 
1dc10 76 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55  variable is a NU
1dc20 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
1dc30 2a 20 5e 28 54 68 65 20 22 25 77 22 20 66 6f 72  * ^(The "%w" for
1dc40 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 69  matting option i
1dc50 73 20 6c 69 6b 65 20 22 25 71 22 20 65 78 63 65  s like "%q" exce
1dc60 70 74 20 74 68 61 74 20 69 74 20 65 78 70 65 63  pt that it expec
1dc70 74 73 20 74 6f 0a 2a 2a 20 62 65 20 63 6f 6e 74  ts to.** be cont
1dc80 61 69 6e 65 64 20 77 69 74 68 69 6e 20 64 6f 75  ained within dou
1dc90 62 6c 65 2d 71 75 6f 74 65 73 20 69 6e 73 74 65  ble-quotes inste
1dca0 61 64 20 6f 66 20 73 69 6e 67 6c 65 20 71 75 6f  ad of single quo
1dcb0 74 65 73 2c 20 61 6e 64 20 69 74 0a 2a 2a 20 65  tes, and it.** e
1dcc0 73 63 61 70 65 73 20 74 68 65 20 64 6f 75 62 6c  scapes the doubl
1dcd0 65 2d 71 75 6f 74 65 20 63 68 61 72 61 63 74 65  e-quote characte
1dce0 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65  r instead of the
1dcf0 20 73 69 6e 67 6c 65 2d 71 75 6f 74 65 0a 2a 2a   single-quote.**
1dd00 20 63 68 61 72 61 63 74 65 72 2e 29 5e 20 20 54   character.)^  T
1dd10 68 65 20 22 25 77 22 20 66 6f 72 6d 61 74 74 69  he "%w" formatti
1dd20 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20 69 6e 74  ng option is int
1dd30 65 6e 64 65 64 20 66 6f 72 20 73 61 66 65 6c 79  ended for safely
1dd40 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 61   inserting.** ta
1dd50 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 6e  ble and column n
1dd60 61 6d 65 73 20 69 6e 74 6f 20 61 20 63 6f 6e 73  ames into a cons
1dd70 74 72 75 63 74 65 64 20 53 51 4c 20 73 74 61 74  tructed SQL stat
1dd80 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  ement..**.** ^(T
1dd90 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69  he "%z" formatti
1dda0 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  ng option works 
1ddb0 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20 77 69  like "%s" but wi
1ddc0 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69  th the.** additi
1ddd0 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68  on that after th
1dde0 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65  e string has bee
1ddf0 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65  n read and copie
1de00 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65  d into.** the re
1de10 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66  sult, [sqlite3_f
1de20 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  ree()] is called
1de30 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74   on the input st
1de40 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20  ring.)^.*/.char 
1de50 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  *sqlite3_mprintf
1de60 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e  (const char*,...
1de70 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
1de80 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20  _vmprintf(const 
1de90 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b  char*, va_list);
1dea0 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73  .char *sqlite3_s
1deb0 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72  nprintf(int,char
1dec0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e  *,const char*, .
1ded0 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74  ..);.char *sqlit
1dee0 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74  e3_vsnprintf(int
1def0 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61  ,char*,const cha
1df00 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f  r*, va_list);../
1df10 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
1df20 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e  emory Allocation
1df30 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a   Subsystem.**.**
1df40 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
1df50 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72 65   uses these thre
1df60 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61  e routines for a
1df70 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a  ll of its own.**
1df80 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79   internal memory
1df90 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
1dfa0 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65  s. "Core" in the
1dfb0 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e   previous senten
1dfc0 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69  ce.** does not i
1dfd0 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67  nclude operating
1dfe0 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63  -system specific
1dff0 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
1e000 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e  ion.  The.** Win
1e010 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e 61  dows VFS uses na
1e020 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e  tive malloc() an
1e030 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d  d free() for som
1e040 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a  e operations..**
1e050 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1e060 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e  _malloc() routin
1e070 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
1e080 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a  ter to a block.*
1e090 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c  * of memory at l
1e0a0 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20  east N bytes in 
1e0b0 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20  length, where N 
1e0c0 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  is the parameter
1e0d0 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  ..** ^If sqlite3
1e0e0 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61  _malloc() is una
1e0f0 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75  ble to obtain su
1e100 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a  fficient free.**
1e110 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75   memory, it retu
1e120 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
1e130 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72  er.  ^If the par
1e140 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73  ameter N to.** s
1e150 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1e160 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74  is zero or negat
1e170 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ive then sqlite3
1e180 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e  _malloc() return
1e190 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s.** a NULL poin
1e1a0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
1e1b0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34  sqlite3_malloc64
1e1c0 28 4e 29 20 72 6f 75 74 69 6e 65 20 77 6f 72 6b  (N) routine work
1e1d0 73 20 6a 75 73 74 20 6c 69 6b 65 0a 2a 2a 20 73  s just like.** s
1e1e0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29  qlite3_malloc(N)
1e1f0 20 65 78 63 65 70 74 20 74 68 61 74 20 4e 20 69   except that N i
1e200 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 36 34  s an unsigned 64
1e210 2d 62 69 74 20 69 6e 74 65 67 65 72 20 69 6e 73  -bit integer ins
1e220 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 73 69 67  tead.** of a sig
1e230 6e 65 64 20 33 32 2d 62 69 74 20 69 6e 74 65 67  ned 32-bit integ
1e240 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69  er..**.** ^Calli
1e250 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  ng sqlite3_free(
1e260 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72  ) with a pointer
1e270 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75   previously retu
1e280 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74  rned.** by sqlit
1e290 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73  e3_malloc() or s
1e2a0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1e2b0 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d   releases that m
1e2c0 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74  emory so.** that
1e2d0 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 75   it might be reu
1e2e0 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  sed.  ^The sqlit
1e2f0 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e  e3_free() routin
1e300 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20  e is.** a no-op 
1e310 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74  if is called wit
1e320 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
1e330 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c  .  Passing a NUL
1e340 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  L pointer.** to 
1e350 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69  sqlite3_free() i
1e360 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74  s harmless.  Aft
1e370 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20  er being freed, 
1e380 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64  memory.** should
1e390 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 64   neither be read
1e3a0 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45   nor written.  E
1e3b0 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76  ven reading prev
1e3c0 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20  iously freed.** 
1e3d0 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73  memory might res
1e3e0 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74  ult in a segment
1e3f0 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f  ation fault or o
1e400 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f  ther severe erro
1e410 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72  r..** Memory cor
1e420 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65  ruption, a segme
1e430 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f  ntation fault, o
1e440 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65  r other severe e
1e450 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65  rror.** might re
1e460 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f  sult if sqlite3_
1e470 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64  free() is called
1e480 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c   with a non-NULL
1e490 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a   pointer that.**
1e4a0 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65   was not obtaine
1e4b0 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  d from sqlite3_m
1e4c0 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74  alloc() or sqlit
1e4d0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a  e3_realloc()..**
1e4e0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1e4f0 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 6e  _realloc(X,N) in
1e500 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
1e510 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20   to resize a.** 
1e520 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c  prior memory all
1e530 6f 63 61 74 69 6f 6e 20 58 20 74 6f 20 62 65 20  ocation X to be 
1e540 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
1e550 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 58 20 70  ..** ^If the X p
1e560 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
1e570 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
1e580 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  .** is a NULL po
1e590 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20 62  inter then its b
1e5a0 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74  ehavior is ident
1e5b0 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a  ical to calling.
1e5c0 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
1e5d0 63 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  c(N)..** ^If the
1e5e0 20 4e 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   N parameter to 
1e5f0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1e600 58 2c 4e 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a  X,N) is zero or.
1e610 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  ** negative then
1e620 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
1e630 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d   exactly the sam
1e640 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  e as calling.** 
1e650 73 71 6c 69 74 65 33 5f 66 72 65 65 28 58 29 2e  sqlite3_free(X).
1e660 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61  .** ^sqlite3_rea
1e670 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e  lloc(X,N) return
1e680 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
1e690 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1e6a0 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73  on.** of at leas
1e6b0 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  t N bytes in siz
1e6c0 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 69 6e 73  e or NULL if ins
1e6d0 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79  ufficient memory
1e6e0 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a   is available..*
1e6f0 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20 73  * ^If M is the s
1e700 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72  ize of the prior
1e710 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65   allocation, the
1e720 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73  n min(N,M) bytes
1e730 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72  .** of the prior
1e740 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20   allocation are 
1e750 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20  copied into the 
1e760 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66  beginning of buf
1e770 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  fer returned.** 
1e780 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  by sqlite3_reall
1e790 6f 63 28 58 2c 4e 29 20 61 6e 64 20 74 68 65 20  oc(X,N) and the 
1e7a0 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
1e7b0 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49   is freed..** ^I
1e7c0 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  f sqlite3_reallo
1e7d0 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 20 4e  c(X,N) returns N
1e7e0 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20 70 6f 73  ULL and N is pos
1e7f0 69 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 0a  itive, then the.
1e800 2a 2a 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  ** prior allocat
1e810 69 6f 6e 20 69 73 20 6e 6f 74 20 66 72 65 65 64  ion is not freed
1e820 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1e830 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 58  ite3_realloc64(X
1e840 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 73 20 77  ,N) interfaces w
1e850 6f 72 6b 73 20 74 68 65 20 73 61 6d 65 20 61 73  orks the same as
1e860 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  .** sqlite3_real
1e870 6c 6f 63 28 58 2c 4e 29 20 65 78 63 65 70 74 20  loc(X,N) except 
1e880 74 68 61 74 20 4e 20 69 73 20 61 20 36 34 2d 62  that N is a 64-b
1e890 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65  it unsigned inte
1e8a0 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f  ger instead.** o
1e8b0 66 20 61 20 33 32 2d 62 69 74 20 73 69 67 6e 65  f a 32-bit signe
1e8c0 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a  d integer..**.**
1e8d0 20 5e 49 66 20 58 20 69 73 20 61 20 6d 65 6d 6f   ^If X is a memo
1e8e0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 70 72  ry allocation pr
1e8f0 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65  eviously obtaine
1e900 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  d from sqlite3_m
1e910 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69  alloc(),.** sqli
1e920 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20  te3_malloc64(), 
1e930 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1e940 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ), or sqlite3_re
1e950 61 6c 6c 6f 63 36 34 28 29 2c 20 74 68 65 6e 0a  alloc64(), then.
1e960 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65  ** sqlite3_msize
1e970 28 58 29 20 72 65 74 75 72 6e 73 20 74 68 65 20  (X) returns the 
1e980 73 69 7a 65 20 6f 66 20 74 68 61 74 20 6d 65 6d  size of that mem
1e990 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69  ory allocation i
1e9a0 6e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 54 68 65  n bytes..** ^The
1e9b0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
1e9c0 62 79 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65  by sqlite3_msize
1e9d0 28 58 29 20 6d 69 67 68 74 20 62 65 20 6c 61 72  (X) might be lar
1e9e0 67 65 72 20 74 68 61 6e 20 74 68 65 20 6e 75 6d  ger than the num
1e9f0 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74 65 73 20  ber.** of bytes 
1ea00 72 65 71 75 65 73 74 65 64 20 77 68 65 6e 20 58  requested when X
1ea10 20 77 61 73 20 61 6c 6c 6f 63 61 74 65 64 2e 20   was allocated. 
1ea20 20 5e 49 66 20 58 20 69 73 20 61 20 4e 55 4c 4c   ^If X is a NULL
1ea30 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a 2a 2a   pointer then.**
1ea40 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58   sqlite3_msize(X
1ea50 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 20  ) returns zero. 
1ea60 20 49 66 20 58 20 70 6f 69 6e 74 73 20 74 6f 20   If X points to 
1ea70 73 6f 6d 65 74 68 69 6e 67 20 74 68 61 74 20 69  something that i
1ea80 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 62 65 67  s not.** the beg
1ea90 69 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d 6f 72 79  inning of memory
1eaa0 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 6f 72 20   allocation, or 
1eab0 69 66 20 69 74 20 70 6f 69 6e 74 73 20 74 6f 20  if it points to 
1eac0 61 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a 20 76 61  a formerly.** va
1ead0 6c 69 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  lid memory alloc
1eae0 61 74 69 6f 6e 20 74 68 61 74 20 68 61 73 20 6e  ation that has n
1eaf0 6f 77 20 62 65 65 6e 20 66 72 65 65 64 2c 20 74  ow been freed, t
1eb00 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
1eb10 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6d  .** of sqlite3_m
1eb20 73 69 7a 65 28 58 29 20 69 73 20 75 6e 64 65 66  size(X) is undef
1eb30 69 6e 65 64 20 61 6e 64 20 70 6f 73 73 69 62 6c  ined and possibl
1eb40 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a  y harmful..**.**
1eb50 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74   ^The memory ret
1eb60 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
1eb70 5f 6d 61 6c 6c 6f 63 28 29 2c 20 73 71 6c 69 74  _malloc(), sqlit
1eb80 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 0a 2a 2a  e3_realloc(),.**
1eb90 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36   sqlite3_malloc6
1eba0 34 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33  4(), and sqlite3
1ebb0 5f 72 65 61 6c 6c 6f 63 36 34 28 29 0a 2a 2a 20  _realloc64().** 
1ebc0 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65  is always aligne
1ebd0 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e  d to at least an
1ebe0 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79   8 byte boundary
1ebf0 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62  , or to a.** 4 b
1ec00 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69 66 20  yte boundary if 
1ec10 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59  the [SQLITE_4_BY
1ec20 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f  TE_ALIGNED_MALLO
1ec30 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a  C] compile-time.
1ec40 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  ** option is use
1ec50 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69  d..**.** In SQLi
1ec60 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30  te version 3.5.0
1ec70 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77   and 3.5.1, it w
1ec80 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64  as possible to d
1ec90 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c  efine.** the SQL
1eca0 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f  ITE_OMIT_MEMORY_
1ecb0 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68  ALLOCATION which
1ecc0 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65   would cause the
1ecd0 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70   built-in.** imp
1ece0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
1ecf0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f  hese routines to
1ed00 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68   be omitted.  Th
1ed10 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a  at capability.**
1ed20 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72   is no longer pr
1ed30 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75  ovided.  Only bu
1ed40 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c  ilt-in memory al
1ed50 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20  locators can be 
1ed60 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f  used..**.** Prio
1ed70 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73  r to SQLite vers
1ed80 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68 65 20  ion 3.7.10, the 
1ed90 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72  Windows OS inter
1eda0 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 65  face layer calle
1edb0 64 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20  d.** the system 
1edc0 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
1edd0 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 68 65  e() directly whe
1ede0 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20  n converting.** 
1edf0 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65  filenames betwee
1ee00 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f  n the UTF-8 enco
1ee10 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c  ding used by SQL
1ee20 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65  ite.** and whate
1ee30 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63  ver filename enc
1ee40 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 62 79  oding is used by
1ee50 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
1ee60 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61  Windows.** insta
1ee70 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79  llation.  Memory
1ee80 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
1ee90 72 73 20 77 65 72 65 20 64 65 74 65 63 74 65 64  rs were detected
1eea0 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 77 65  , but.** they we
1eeb0 72 65 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  re reported back
1eec0 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54   as [SQLITE_CANT
1eed0 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  OPEN] or.** [SQL
1eee0 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65  ITE_IOERR] rathe
1eef0 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e  r than [SQLITE_N
1ef00 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  OMEM]..**.** The
1ef10 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e   pointer argumen
1ef20 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  ts to [sqlite3_f
1ef30 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ree()] and [sqli
1ef40 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a  te3_realloc()].*
1ef50 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72  * must be either
1ef60 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f   NULL or else po
1ef70 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20  inters obtained 
1ef80 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20  from a prior.** 
1ef90 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73  invocation of [s
1efa0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1efb0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
1efc0 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76  lloc()] that hav
1efd0 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65  e.** not yet bee
1efe0 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a  n released..**.*
1eff0 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
1f000 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20  n must not read 
1f010 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70 61 72  or write any par
1f020 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20  t of.** a block 
1f030 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20  of memory after 
1f040 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65  it has been rele
1f050 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  ased using.** [s
1f060 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f  qlite3_free()] o
1f070 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
1f080 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  oc()]..*/.void *
1f090 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69  sqlite3_malloc(i
1f0a0 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74  nt);.void *sqlit
1f0b0 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 73 71 6c 69  e3_malloc64(sqli
1f0c0 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 76 6f 69  te3_uint64);.voi
1f0d0 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d *sqlite3_reall
1f0e0 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a  oc(void*, int);.
1f0f0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65  void *sqlite3_re
1f100 61 6c 6c 6f 63 36 34 28 76 6f 69 64 2a 2c 20 73  alloc64(void*, s
1f110 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a  qlite3_uint64);.
1f120 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65  void sqlite3_fre
1f130 65 28 76 6f 69 64 2a 29 3b 0a 73 71 6c 69 74 65  e(void*);.sqlite
1f140 33 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33  3_uint64 sqlite3
1f150 5f 6d 73 69 7a 65 28 76 6f 69 64 2a 29 3b 0a 0a  _msize(void*);..
1f160 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1f170 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72  Memory Allocator
1f180 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a   Statistics.**.*
1f190 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65  * SQLite provide
1f1a0 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65  s these two inte
1f1b0 72 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72  rfaces for repor
1f1c0 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74  ting on the stat
1f1d0 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  us.** of the [sq
1f1e0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c  lite3_malloc()],
1f1f0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1f200 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
1f210 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f  realloc()].** ro
1f220 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f  utines, which fo
1f230 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20  rm the built-in 
1f240 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1f250 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a  n subsystem..**.
1f260 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
1f270 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
1f280 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
1f290 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
1f2a0 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79  tes.** of memory
1f2b0 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74   currently outst
1f2c0 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64  anding (malloced
1f2d0 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e   but not freed).
1f2e0 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
1f2f0 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
1f300 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65  er()] routine re
1f310 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75  turns the maximu
1f320 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73  m.** value of [s
1f330 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
1f340 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20  ed()] since the 
1f350 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a  high-water mark.
1f360 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73 65  ** was last rese
1f370 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20  t.  ^The values 
1f380 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
1f390 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
1f3a0 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  ()] and.** [sqli
1f3b0 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
1f3c0 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20  ater()] include 
1f3d0 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20  any overhead.** 
1f3e0 61 64 64 65 64 20 62 79 20 53 51 4c 69 74 65 20  added by SQLite 
1f3f0 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74  in its implement
1f400 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65  ation of [sqlite
1f410 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20  3_malloc()],.** 
1f420 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64  but not overhead
1f430 20 61 64 64 65 64 20 62 79 20 74 68 65 20 61 6e   added by the an
1f440 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73  y underlying sys
1f450 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72  tem library.** r
1f460 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71  outines that [sq
1f470 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
1f480 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20  may call..**.** 
1f490 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68  ^The memory high
1f4a0 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72  -water mark is r
1f4b0 65 73 65 74 20 74 6f 20 74 68 65 20 63 75 72 72  eset to the curr
1f4c0 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20  ent value of.** 
1f4d0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1f4e0 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f  used()] if and o
1f4f0 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72 61 6d  nly if the param
1f500 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  eter to.** [sqli
1f510 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
1f520 61 74 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e  ater()] is true.
1f530 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74    ^The value ret
1f540 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c  urned.** by [sql
1f550 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
1f560 77 61 74 65 72 28 31 29 5d 20 69 73 20 74 68 65  water(1)] is the
1f570 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b   high-water mark
1f580 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65  .** prior to the
1f590 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74   reset..*/.sqlit
1f5a0 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
1f5b0 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69  _memory_used(voi
1f5c0 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  d);.sqlite3_int6
1f5d0 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  4 sqlite3_memory
1f5e0 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 20 72  _highwater(int r
1f5f0 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a  esetFlag);../*.*
1f600 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 65 75  * CAPI3REF: Pseu
1f610 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72  do-Random Number
1f620 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a   Generator.**.**
1f630 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73   SQLite contains
1f640 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20   a high-quality 
1f650 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75  pseudo-random nu
1f660 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28  mber generator (
1f670 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a  PRNG) used to.**
1f680 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b   select random [
1f690 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20  ROWID | ROWIDs] 
1f6a0 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e  when inserting n
1f6b0 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20  ew records into 
1f6c0 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20  a table that.** 
1f6d0 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 65  already uses the
1f6e0 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c   largest possibl
1f6f0 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20  e [ROWID].  The 
1f700 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65  PRNG is also use
1f710 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69  d for.** the bui
1f720 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61  ld-in random() a
1f730 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20  nd randomblob() 
1f740 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20  SQL functions.  
1f750 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61  This interface a
1f760 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61  llows.** applica
1f770 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20  tions to access 
1f780 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f  the same PRNG fo
1f790 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73  r other purposes
1f7a0 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20  ..**.** ^A call 
1f7b0 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  to this routine 
1f7c0 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f  stores N bytes o
1f7d0 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74  f randomness int
1f7e0 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 20 5e  o buffer P..** ^
1f7f0 54 68 65 20 50 20 70 61 72 61 6d 65 74 65 72 20  The P parameter 
1f800 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f  can be a NULL po
1f810 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  inter..**.** ^If
1f820 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68 61   this routine ha
1f830 73 20 6e 6f 74 20 62 65 65 6e 20 70 72 65 76 69  s not been previ
1f840 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20 6f 72 20  ously called or 
1f850 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 0a  if the previous.
1f860 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e 20 6c 65  ** call had N le
1f870 73 73 20 74 68 61 6e 20 6f 6e 65 20 6f 72 20 61  ss than one or a
1f880 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f   NULL pointer fo
1f890 72 20 50 2c 20 74 68 65 6e 20 74 68 65 20 50 52  r P, then the PR
1f8a0 4e 47 20 69 73 0a 2a 2a 20 73 65 65 64 65 64 20  NG is.** seeded 
1f8b0 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73  using randomness
1f8c0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 74   obtained from t
1f8d0 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d  he xRandomness m
1f8e0 65 74 68 6f 64 20 6f 66 0a 2a 2a 20 74 68 65 20  ethod of.** the 
1f8f0 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
1f900 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  _vfs] object..**
1f910 20 5e 49 66 20 74 68 65 20 70 72 65 76 69 6f 75   ^If the previou
1f920 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72  s call to this r
1f930 6f 75 74 69 6e 65 20 68 61 64 20 61 6e 20 4e 20  outine had an N 
1f940 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20 61 6e 64  of 1 or more and
1f950 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c 20 50   a.** non-NULL P
1f960 20 74 68 65 6e 20 74 68 65 20 70 73 65 75 64 6f   then the pseudo
1f970 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67  -randomness is g
1f980 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65  enerated.** inte
1f990 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f  rnally and witho
1f9a0 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74  ut recourse to t
1f9b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  he [sqlite3_vfs]
1f9c0 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20   xRandomness.** 
1f9d0 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20  method..*/.void 
1f9e0 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65  sqlite3_randomne
1f9f0 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a  ss(int N, void *
1fa00 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  P);../*.** CAPI3
1fa10 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d  REF: Compile-Tim
1fa20 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20  e Authorization 
1fa30 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54  Callbacks.** MET
1fa40 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
1fa50 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
1fa60 20 72 65 67 69 73 74 65 72 73 20 61 6e 20 61 75   registers an au
1fa70 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1fa80 6b 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75  k with a particu
1fa90 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  lar.** [database
1faa0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75   connection], su
1fab0 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69  pplied in the fi
1fac0 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  rst argument..**
1fad0 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72   ^The authorizer
1fae0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
1faf0 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74  oked as SQL stat
1fb00 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67  ements are being
1fb10 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20   compiled.** by 
1fb20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1fb30 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
1fb40 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  nts [sqlite3_pre
1fb50 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b  pare_v2()],.** [
1fb60 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1fb70 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  6()] and [sqlite
1fb80 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
1fb90 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 75 73 0a  ].  ^At various.
1fba0 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67  ** points during
1fbb0 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e   the compilation
1fbc0 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67   process, as log
1fbd0 69 63 20 69 73 20 62 65 69 6e 67 20 63 72 65 61  ic is being crea
1fbe0 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72  ted.** to perfor
1fbf0 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e  m various action
1fc00 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  s, the authorize
1fc10 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
1fc20 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20  voked to.** see 
1fc30 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73  if those actions
1fc40 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e   are allowed.  ^
1fc50 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
1fc60 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a  allback should.*
1fc70 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
1fc80 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68  _OK] to allow th
1fc90 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54  e action, [SQLIT
1fca0 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73  E_IGNORE] to dis
1fcb0 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65  allow the.** spe
1fcc0 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74  cific action but
1fcd0 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73   allow the SQL s
1fce0 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74  tatement to cont
1fcf0 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f  inue to be.** co
1fd00 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49  mpiled, or [SQLI
1fd10 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73  TE_DENY] to caus
1fd20 65 20 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c  e the entire SQL
1fd30 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65   statement to be
1fd40 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74  .** rejected wit
1fd50 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66  h an error.  ^If
1fd60 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1fd70 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1fd80 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74  .** any value ot
1fd90 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
1fda0 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54  _IGNORE], [SQLIT
1fdb0 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  E_OK], or [SQLIT
1fdc0 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20  E_DENY].** then 
1fdd0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  the [sqlite3_pre
1fde0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71  pare_v2()] or eq
1fdf0 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68  uivalent call th
1fe00 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20  at triggered.** 
1fe10 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77  the authorizer w
1fe20 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e  ill fail with an
1fe30 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a   error message..
1fe40 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63  **.** When the c
1fe50 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
1fe60 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61  [SQLITE_OK], tha
1fe70 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72  t means the oper
1fe80 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74  ation.** request
1fe90 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e  ed is ok.  ^When
1fea0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
1feb0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45  turns [SQLITE_DE
1fec0 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  NY], the.** [sql
1fed0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1fee0 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74  )] or equivalent
1fef0 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67   call that trigg
1ff00 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68  ered the.** auth
1ff10 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c  orizer will fail
1ff20 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d   with an error m
1ff30 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e  essage explainin
1ff40 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73  g that.** access
1ff50 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a   is denied. .**.
1ff60 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61  ** ^The first pa
1ff70 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
1ff80 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1ff90 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  ck is a copy of 
1ffa0 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72  the third.** par
1ffb0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
1ffc0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1ffd0 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63 65  izer() interface
1ffe0 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  . ^The second pa
1fff0 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68  rameter.** to th
20000 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  e callback is an
20010 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45   integer [SQLITE
20020 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63  _COPY | action c
20030 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 66  ode] that specif
20040 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69  ies.** the parti
20050 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20  cular action to 
20060 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e  be authorized. ^
20070 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67  The third throug
20080 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65  h sixth paramete
20090 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c  rs.** to the cal
200a0 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74  lback are zero-t
200b0 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67  erminated string
200c0 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61  s that contain a
200d0 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74  dditional.** det
200e0 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61  ails about the a
200f0 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68  ction to be auth
20100 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  orized..**.** ^I
20110 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64  f the action cod
20120 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41  e is [SQLITE_REA
20130 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61  D].** and the ca
20140 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
20150 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74  SQLITE_IGNORE] t
20160 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70  hen the.** [prep
20170 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
20180 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e  statement is con
20190 73 74 72 75 63 74 65 64 20 74 6f 20 73 75 62 73  structed to subs
201a0 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c  titute.** a NULL
201b0 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20   value in place 
201c0 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c  of the table col
201d0 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68  umn that would h
201e0 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64  ave.** been read
201f0 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20   if [SQLITE_OK] 
20200 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65  had been returne
20210 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  d.  The [SQLITE_
20220 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72  IGNORE].** retur
20230 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
20240 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74   deny an untrust
20250 65 64 20 75 73 65 72 20 61 63 63 65 73 73 20 74  ed user access t
20260 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20  o individual.** 
20270 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62  columns of a tab
20280 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61  le..** ^If the a
20290 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53  ction code is [S
202a0 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e  QLITE_DELETE] an
202b0 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  d the callback r
202c0 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54  eturns.** [SQLIT
202d0 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74  E_IGNORE] then t
202e0 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72  he [DELETE] oper
202f0 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62  ation proceeds b
20300 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63  ut the.** [trunc
20310 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  ate optimization
20320 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e  ] is disabled an
20330 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64  d all rows are d
20340 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75 61  eleted individua
20350 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75  lly..**.** An au
20360 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64  thorizer is used
20370 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70   when [sqlite3_p
20380 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 69  repare | prepari
20390 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ng].** SQL state
203a0 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e  ments from an un
203b0 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20  trusted source, 
203c0 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  to ensure that t
203d0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
203e0 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20  s.** do not try 
203f0 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 20 74  to access data t
20400 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f  hey are not allo
20410 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74  wed to see, or t
20420 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a  hat they do not.
20430 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75 74  ** try to execut
20440 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74  e malicious stat
20450 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61  ements that dama
20460 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e  ge the database.
20470 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65    For.** example
20480 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
20490 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65   may allow a use
204a0 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74  r to enter arbit
204b0 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72  rary.** SQL quer
204c0 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69  ies for evaluati
204d0 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 73 65  on by a database
204e0 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 6c 69  .  But the appli
204f0 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e  cation does.** n
20500 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 65 72  ot want the user
20510 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d   to be able to m
20520 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 63 68  ake arbitrary ch
20530 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20  anges to the.** 
20540 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75  database.  An au
20550 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74  thorizer could t
20560 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c  hen be put in pl
20570 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a  ace while the.**
20580 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51   user-entered SQ
20590 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69  L is being [sqli
205a0 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72  te3_prepare | pr
205b0 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20  epared] that.** 
205c0 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74  disallows everyt
205d0 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c  hing except [SEL
205e0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e  ECT] statements.
205f0 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
20600 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f  ons that need to
20610 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f   process SQL fro
20620 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72  m untrusted sour
20630 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73  ces.** might als
20640 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72  o consider lower
20650 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d  ing resource lim
20660 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  its using [sqlit
20670 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61  e3_limit()].** a
20680 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61  nd limiting data
20690 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20  base size using 
206a0 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f  the [max_page_co
206b0 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a  unt] [PRAGMA].**
206c0 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20   in addition to 
206d0 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69  using an authori
206e0 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c  zer..**.** ^(Onl
206f0 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f  y a single autho
20700 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20  rizer can be in 
20710 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62  place on a datab
20720 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
20730 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61  * at a time.  Ea
20740 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ch call to sqlit
20750 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
20760 72 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a  r overrides the.
20770 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  ** previous call
20780 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68  .)^  ^Disable th
20790 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20  e authorizer by 
207a0 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c  installing a NUL
207b0 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54  L callback..** T
207c0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73  he authorizer is
207d0 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
207e0 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ault..**.** The 
207f0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
20800 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20  ack must not do 
20810 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69  anything that wi
20820 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65  ll modify.** the
20830 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
20840 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
20850 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  d the authorizer
20860 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f   callback..** No
20870 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  te that [sqlite3
20880 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
20890 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  nd [sqlite3_step
208a0 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20  ()] both modify 
208b0 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73  their.** databas
208c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
208d0 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
208e0 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
208f0 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
20900 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65  ** ^When [sqlite
20910 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
20920 69 73 20 75 73 65 64 20 74 6f 20 70 72 65 70 61  is used to prepa
20930 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20  re a statement, 
20940 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  the.** statement
20950 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70 72 65   might be re-pre
20960 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71  pared during [sq
20970 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75  lite3_step()] du
20980 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d  e to a .** schem
20990 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65  a change.  Hence
209a0 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  , the applicatio
209b0 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20  n should ensure 
209c0 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72  that the.** corr
209d0 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63  ect authorizer c
209e0 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20  allback remains 
209f0 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20  in place during 
20a00 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
20a10 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74  p()]..**.** ^Not
20a20 65 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f  e that the autho
20a30 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
20a40 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64  s invoked only d
20a50 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  uring.** [sqlite
20a60 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
20a70 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41  its variants.  A
20a80 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20  uthorization is 
20a90 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64  not.** performed
20aa0 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e   during statemen
20ab0 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20  t evaluation in 
20ac0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
20ad0 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73  , unless.** as s
20ae0 74 61 74 65 64 20 69 6e 20 74 68 65 20 70 72 65  tated in the pre
20af0 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c  vious paragraph,
20b00 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
20b10 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74  invokes.** sqlit
20b20 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20  e3_prepare_v2() 
20b30 74 6f 20 72 65 70 72 65 70 61 72 65 20 61 20 73  to reprepare a s
20b40 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61  tatement after a
20b50 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a   schema change..
20b60 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
20b70 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20  et_authorizer(. 
20b80 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74   sqlite3*,.  int
20b90 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c   (*xAuth)(void*,
20ba0 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  int,const char*,
20bb0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
20bc0 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
20bd0 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55  ar*),.  void *pU
20be0 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a  serData.);../*.*
20bf0 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68  * CAPI3REF: Auth
20c00 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f  orizer Return Co
20c10 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73  des.**.** The [s
20c20 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
20c30 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
20c40 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  er callback func
20c50 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65  tion] must.** re
20c60 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c  turn either [SQL
20c70 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f  ITE_OK] or one o
20c80 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73  f these two cons
20c90 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a  tants in order.*
20ca0 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69  * to signal SQLi
20cb0 74 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  te whether or no
20cc0 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20  t the action is 
20cd0 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20  permitted.  See 
20ce0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
20cf0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
20d00 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75   authorizer docu
20d10 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61  mentation] for a
20d20 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66  dditional.** inf
20d30 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
20d40 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 49 54 45  Note that SQLITE
20d50 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20  _IGNORE is also 
20d60 75 73 65 64 20 61 73 20 61 20 5b 63 6f 6e 66 6c  used as a [confl
20d70 69 63 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6d  ict resolution m
20d80 6f 64 65 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64  ode].** returned
20d90 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74   from the [sqlit
20da0 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c  e3_vtab_on_confl
20db0 69 63 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ict()] interface
20dc0 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
20dd0 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f  ITE_DENY   1   /
20de0 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20  * Abort the SQL 
20df0 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61  statement with a
20e00 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  n error */.#defi
20e10 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  ne SQLITE_IGNORE
20e20 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c   2   /* Don't al
20e30 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 20  low access, but 
20e40 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61  don't generate a
20e50 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a  n error */../*.*
20e60 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68  * CAPI3REF: Auth
20e70 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f  orizer Action Co
20e80 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73  des.**.** The [s
20e90 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
20ea0 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61  rizer()] interfa
20eb0 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63  ce registers a c
20ec0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
20ed0 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f  .** that is invo
20ee0 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65  ked to authorize
20ef0 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61   certain SQL sta
20f00 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20  tement actions. 
20f10 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   The.** second p
20f20 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
20f30 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69  callback is an i
20f40 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74  nteger code that
20f50 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68   specifies.** wh
20f60 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69  at action is bei
20f70 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20  ng authorized.  
20f80 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69 6e  These are the in
20f90 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64  teger action cod
20fa0 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61  es that.** the a
20fb0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
20fc0 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 64  ck may be passed
20fd0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63  ..**.** These ac
20fe0 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73  tion code values
20ff0 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69   signify what ki
21000 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20  nd of operation 
21010 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68  is to be.** auth
21020 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64  orized.  The 3rd
21030 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74   and 4th paramet
21040 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ers to the autho
21050 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c  rization.** call
21060 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69  back function wi
21070 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73  ll be parameters
21080 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69   or NULL dependi
21090 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74  ng on which of t
210a0 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73  hese.** codes is
210b0 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63   used as the sec
210c0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  ond parameter.  
210d0 5e 28 54 68 65 20 35 74 68 20 70 61 72 61 6d 65  ^(The 5th parame
210e0 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75  ter to the.** au
210f0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
21100 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  k is the name of
21110 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22   the database ("
21120 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a  main", "temp",.*
21130 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69  * etc.) if appli
21140 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36  cable.)^  ^The 6
21150 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
21160 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
21170 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68  allback.** is th
21180 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e  e name of the in
21190 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72  ner-most trigger
211a0 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 73   or view that is
211b0 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
211c0 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20 61  .** the access a
211d0 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69  ttempt or NULL i
211e0 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61 74  f this access at
211f0 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c  tempt is directl
21200 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65  y from.** top-le
21210 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f  vel SQL code..*/
21220 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ./**************
21230 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
21240 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72  ************* 3r
21250 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34  d ************ 4
21260 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a  th ***********/.
21270 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
21280 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20  REATE_INDEX     
21290 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65       1   /* Inde
212a0 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
212b0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
212c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
212d0 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20  EATE_TABLE      
212e0 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65      2   /* Table
212f0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
21300 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
21310 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
21320 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20  ATE_TEMP_INDEX  
21330 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20     3   /* Index 
21340 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
21350 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
21360 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
21370 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20  TE_TEMP_TABLE   
21380 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    4   /* Table N
21390 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
213a0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
213b0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
213c0 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20  E_TEMP_TRIGGER  
213d0 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20   5   /* Trigger 
213e0 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
213f0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
21400 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
21410 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20  _TEMP_VIEW      
21420 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  6   /* View Name
21430 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
21440 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
21450 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
21460 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 37  TRIGGER        7
21470 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
21480 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
21490 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
214a0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56   SQLITE_CREATE_V
214b0 49 45 57 20 20 20 20 20 20 20 20 20 20 20 38 20  IEW           8 
214c0 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
214d0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
214e0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
214f0 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20  SQLITE_DELETE   
21500 20 20 20 20 20 20 20 20 20 20 20 20 20 39 20 20               9  
21510 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
21520 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
21530 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
21540 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58  QLITE_DROP_INDEX
21550 20 20 20 20 20 20 20 20 20 20 20 31 30 20 20 20             10   
21560 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
21570 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
21580 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
21590 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20  LITE_DROP_TABLE 
215a0 20 20 20 20 20 20 20 20 20 20 31 31 20 20 20 2f            11   /
215b0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
215c0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
215d0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
215e0 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e  ITE_DROP_TEMP_IN
215f0 44 45 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a  DEX      12   /*
21600 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
21610 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
21620 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
21630 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42  TE_DROP_TEMP_TAB
21640 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20  LE      13   /* 
21650 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
21660 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
21670 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
21680 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47  E_DROP_TEMP_TRIG
21690 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54  GER    14   /* T
216a0 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
216b0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
216c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
216d0 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20  _DROP_TEMP_VIEW 
216e0 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69        15   /* Vi
216f0 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
21700 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
21710 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
21720 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20  DROP_TRIGGER    
21730 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69       16   /* Tri
21740 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
21750 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
21760 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
21770 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 20  ROP_VIEW        
21780 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77      17   /* View
21790 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
217a0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
217b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
217c0 53 45 52 54 20 20 20 20 20 20 20 20 20 20 20 20  SERT            
217d0 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65     18   /* Table
217e0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
217f0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
21800 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41  efine SQLITE_PRA
21810 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20  GMA             
21820 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61    19   /* Pragma
21830 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 72   Name     1st ar
21840 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65  g or NULL */.#de
21850 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
21860 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
21870 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   20   /* Table N
21880 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20  ame      Column 
21890 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
218a0 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43  ine SQLITE_SELEC
218b0 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
218c0 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  21   /* NULL    
218d0 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
218e0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
218f0 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41  ne SQLITE_TRANSA
21900 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32  CTION          2
21910 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e  2   /* Operation
21920 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
21930 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
21940 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20  e SQLITE_UPDATE 
21950 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 33                23
21960 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
21970 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d        Column Nam
21980 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
21990 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20   SQLITE_ATTACH  
219a0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34 20               24 
219b0 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20    /* Filename   
219c0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
219d0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
219e0 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20  SQLITE_DETACH   
219f0 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20              25  
21a00 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d   /* Database Nam
21a10 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20  e   NULL        
21a20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
21a30 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c  QLITE_ALTER_TABL
21a40 45 20 20 20 20 20 20 20 20 20 20 32 36 20 20 20  E          26   
21a50 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65  /* Database Name
21a60 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
21a70 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
21a80 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20  LITE_REINDEX    
21a90 20 20 20 20 20 20 20 20 20 20 32 37 20 20 20 2f            27   /
21aa0 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
21ab0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
21ac0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
21ad0 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20  ITE_ANALYZE     
21ae0 20 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a           28   /*
21af0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
21b00 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
21b10 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
21b20 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45  TE_CREATE_VTABLE
21b30 20 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20          29   /* 
21b40 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
21b50 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20  Module Name     
21b60 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
21b70 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20  E_DROP_VTABLE   
21b80 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54         30   /* T
21b90 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d  able Name      M
21ba0 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a  odule Name     *
21bb0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
21bc0 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20  _FUNCTION       
21bd0 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55        31   /* NU
21be0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 46 75  LL            Fu
21bf0 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f  nction Name   */
21c00 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
21c10 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20  SAVEPOINT       
21c20 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65       32   /* Ope
21c30 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76  ration       Sav
21c40 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a  epoint Name  */.
21c50 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
21c60 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 20 20  OPY             
21c70 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c       0   /* No l
21c80 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 23 64  onger used */.#d
21c90 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 43  efine SQLITE_REC
21ca0 55 52 53 49 56 45 20 20 20 20 20 20 20 20 20 20  URSIVE          
21cb0 20 20 33 33 20 20 20 2f 2a 20 4e 55 4c 4c 20 20    33   /* NULL  
21cc0 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20            NULL  
21cd0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a            */../*
21ce0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72  .** CAPI3REF: Tr
21cf0 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c  acing And Profil
21d00 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ing Functions.**
21d10 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
21d20 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
21d30 74 69 6e 65 73 20 61 72 65 20 64 65 70 72 65 63  tines are deprec
21d40 61 74 65 64 2e 20 55 73 65 20 74 68 65 20 5b 73  ated. Use the [s
21d50 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28  qlite3_trace_v2(
21d60 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  )] interface.** 
21d70 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 72  instead of the r
21d80 6f 75 74 69 6e 65 73 20 64 65 73 63 72 69 62 65  outines describe
21d90 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  d here..**.** Th
21da0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67  ese routines reg
21db0 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66  ister callback f
21dc0 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61  unctions that ca
21dd0 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a  n be used for.**
21de0 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f   tracing and pro
21df0 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75  filing the execu
21e00 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74  tion of SQL stat
21e10 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ements..**.** ^T
21e20 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
21e30 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20  tion registered 
21e40 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  by sqlite3_trace
21e50 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74  () is invoked at
21e60 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65  .** various time
21e70 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74  s when an SQL st
21e80 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67  atement is being
21e90 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33   run by [sqlite3
21ea0 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68  _step()]..** ^Th
21eb0 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  e sqlite3_trace(
21ec0 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  ) callback is in
21ed0 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54 46  voked with a UTF
21ee0 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  -8 rendering of 
21ef0 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  the.** SQL state
21f00 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74 68 65  ment text as the
21f10 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74   statement first
21f20 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e   begins executin
21f30 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e  g..** ^(Addition
21f40 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  al sqlite3_trace
21f50 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67  () callbacks mig
21f60 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65  ht occur.** as e
21f70 61 63 68 20 74 72 69 67 67 65 72 65 64 20 73 75  ach triggered su
21f80 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65  bprogram is ente
21f90 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61  red.  The callba
21fa0 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72 73  cks for triggers
21fb0 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54  .** contain a UT
21fc0 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20  F-8 SQL comment 
21fd0 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 73 20  that identifies 
21fe0 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a  the trigger.)^.*
21ff0 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  *.** The [SQLITE
22000 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49  _TRACE_SIZE_LIMI
22010 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  T] compile-time 
22020 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  option can be us
22030 65 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74  ed to limit.** t
22040 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b 62 6f  he length of [bo
22050 75 6e 64 20 70 61 72 61 6d 65 74 65 72 5d 20 65  und parameter] e
22060 78 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68 65 20  xpansion in the 
22070 6f 75 74 70 75 74 20 6f 66 20 73 71 6c 69 74 65  output of sqlite
22080 33 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a  3_trace()..**.**
22090 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66   ^The callback f
220a0 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72  unction register
220b0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72  ed by sqlite3_pr
220c0 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b  ofile() is invok
220d0 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51  ed.** as each SQ
220e0 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69  L statement fini
220f0 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66  shes.  ^The prof
22100 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e  ile callback con
22110 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69  tains.** the ori
22120 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20  ginal statement 
22130 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69  text and an esti
22140 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f  mate of wall-clo
22150 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f  ck time.** of ho
22160 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74  w long that stat
22170 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75  ement took to ru
22180 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65  n.  ^The profile
22190 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d   callback.** tim
221a0 65 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f 66  e is in units of
221b0 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f   nanoseconds, ho
221c0 77 65 76 65 72 20 74 68 65 20 63 75 72 72 65 6e  wever the curren
221d0 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  t implementation
221e0 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 61  .** is only capa
221f0 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ble of milliseco
22200 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f  nd resolution so
22210 20 74 68 65 20 73 69 78 20 6c 65 61 73 74 20 73   the six least s
22220 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69  ignificant.** di
22230 67 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d 65  gits in the time
22240 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73   are meaningless
22250 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
22260 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  ns of SQLite.** 
22270 6d 69 67 68 74 20 70 72 6f 76 69 64 65 20 67 72  might provide gr
22280 65 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e  eater resolution
22290 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 72   on the profiler
222a0 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a   callback.  The.
222b0 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  ** sqlite3_profi
222c0 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  le() function is
222d0 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65   considered expe
222e0 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a  rimental and is.
222f0 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  ** subject to ch
22300 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20 76  ange in future v
22310 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
22320 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 44 45 50  e..*/.SQLITE_DEP
22330 52 45 43 41 54 45 44 20 76 6f 69 64 20 2a 73 71  RECATED void *sq
22340 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69  lite3_trace(sqli
22350 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78  te3*,.   void(*x
22360 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e  Trace)(void*,con
22370 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a  st char*), void*
22380 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  );.SQLITE_DEPREC
22390 41 54 45 44 20 76 6f 69 64 20 2a 73 71 6c 69 74  ATED void *sqlit
223a0 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74  e3_profile(sqlit
223b0 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50  e3*,.   void(*xP
223c0 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f  rofile)(void*,co
223d0 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65  nst char*,sqlite
223e0 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a  3_uint64), void*
223f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
22400 45 46 3a 20 53 51 4c 20 54 72 61 63 65 20 45 76  EF: SQL Trace Ev
22410 65 6e 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59  ent Codes.** KEY
22420 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 52  WORDS: SQLITE_TR
22430 41 43 45 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ACE.**.** These 
22440 63 6f 6e 73 74 61 6e 74 73 20 69 64 65 6e 74 69  constants identi
22450 66 79 20 63 6c 61 73 73 65 73 20 6f 66 20 65 76  fy classes of ev
22460 65 6e 74 73 20 74 68 61 74 20 63 61 6e 20 62 65  ents that can be
22470 20 6d 6f 6e 69 74 6f 72 65 64 0a 2a 2a 20 75 73   monitored.** us
22480 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ing the [sqlite3
22490 5f 74 72 61 63 65 5f 76 32 28 29 5d 20 74 72 61  _trace_v2()] tra
224a0 63 69 6e 67 20 6c 6f 67 69 63 2e 20 20 54 68 65  cing logic.  The
224b0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a   third argument.
224c0 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74  ** to [sqlite3_t
224d0 72 61 63 65 5f 76 32 28 29 5d 20 69 73 20 61 6e  race_v2()] is an
224e0 20 4f 52 2d 65 64 20 63 6f 6d 62 69 6e 61 74 69   OR-ed combinati
224f0 6f 6e 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72  on of one or mor
22500 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c  e of.** the foll
22510 6f 77 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 2e  owing constants.
22520 20 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67    ^The first arg
22530 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 74 72 61  ument to the tra
22540 63 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69  ce callback.** i
22550 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  s one of the fol
22560 6c 6f 77 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73  lowing constants
22570 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 74 72 61 63  ..**.** New trac
22580 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61  ing constants ma
22590 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
225a0 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a  ture releases..*
225b0 2a 0a 2a 2a 20 5e 41 20 74 72 61 63 65 20 63 61  *.** ^A trace ca
225c0 6c 6c 62 61 63 6b 20 68 61 73 20 66 6f 75 72 20  llback has four 
225d0 61 72 67 75 6d 65 6e 74 73 3a 20 78 43 61 6c 6c  arguments: xCall
225e0 62 61 63 6b 28 54 2c 43 2c 50 2c 58 29 2e 0a 2a  back(T,C,P,X)..*
225f0 2a 20 5e 54 68 65 20 54 20 61 72 67 75 6d 65 6e  * ^The T argumen
22600 74 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20  t is one of the 
22610 69 6e 74 65 67 65 72 20 74 79 70 65 20 63 6f 64  integer type cod
22620 65 73 20 61 62 6f 76 65 2e 0a 2a 2a 20 5e 54 68  es above..** ^Th
22630 65 20 43 20 61 72 67 75 6d 65 6e 74 20 69 73 20  e C argument is 
22640 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f  a copy of the co
22650 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 20 70 61  ntext pointer pa
22660 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a  ssed in as the.*
22670 2a 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  * fourth argumen
22680 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72  t to [sqlite3_tr
22690 61 63 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 54 68  ace_v2()]..** Th
226a0 65 20 50 20 61 6e 64 20 58 20 61 72 67 75 6d 65  e P and X argume
226b0 6e 74 73 20 61 72 65 20 70 6f 69 6e 74 65 72 73  nts are pointers
226c0 20 77 68 6f 73 65 20 6d 65 61 6e 69 6e 67 73 20   whose meanings 
226d0 64 65 70 65 6e 64 20 6f 6e 20 54 2e 0a 2a 2a 0a  depend on T..**.
226e0 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c  ** <dl>.** [[SQL
226f0 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 5d 5d  ITE_TRACE_STMT]]
22700 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43   <dt>SQLITE_TRAC
22710 45 5f 53 54 4d 54 3c 2f 64 74 3e 0a 2a 2a 20 3c  E_STMT</dt>.** <
22720 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52  dd>^An SQLITE_TR
22730 41 43 45 5f 53 54 4d 54 20 63 61 6c 6c 62 61 63  ACE_STMT callbac
22740 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65  k is invoked whe
22750 6e 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61  n a prepared sta
22760 74 65 6d 65 6e 74 0a 2a 2a 20 66 69 72 73 74 20  tement.** first 
22770 62 65 67 69 6e 73 20 72 75 6e 6e 69 6e 67 20 61  begins running a
22780 6e 64 20 70 6f 73 73 69 62 6c 79 20 61 74 20 6f  nd possibly at o
22790 74 68 65 72 20 74 69 6d 65 73 20 64 75 72 69 6e  ther times durin
227a0 67 20 74 68 65 0a 2a 2a 20 65 78 65 63 75 74 69  g the.** executi
227b0 6f 6e 20 6f 66 20 74 68 65 20 70 72 65 70 61 72  on of the prepar
227c0 65 64 20 73 74 61 74 65 6d 65 6e 74 2c 20 73 75  ed statement, su
227d0 63 68 20 61 73 20 61 74 20 74 68 65 20 73 74 61  ch as at the sta
227e0 72 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20 74 72  rt of each.** tr
227f0 69 67 67 65 72 20 73 75 62 70 72 6f 67 72 61 6d  igger subprogram
22800 2e 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e  . ^The P argumen
22810 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
22820 6f 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  o the.** [prepar
22830 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e  ed statement]. ^
22840 54 68 65 20 58 20 61 72 67 75 6d 65 6e 74 20 69  The X argument i
22850 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
22860 20 73 74 72 69 6e 67 20 77 68 69 63 68 0a 2a 2a   string which.**
22870 20 69 73 20 74 68 65 20 75 6e 65 78 70 61 6e 64   is the unexpand
22880 65 64 20 53 51 4c 20 74 65 78 74 20 6f 66 20 74  ed SQL text of t
22890 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
228a0 65 6d 65 6e 74 20 6f 72 20 61 6e 20 53 51 4c 20  ement or an SQL 
228b0 63 6f 6d 6d 65 6e 74 20 0a 2a 2a 20 74 68 61 74  comment .** that
228c0 20 69 6e 64 69 63 61 74 65 73 20 74 68 65 20 69   indicates the i
228d0 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 61 20 74  nvocation of a t
228e0 72 69 67 67 65 72 2e 20 20 5e 54 68 65 20 63 61  rigger.  ^The ca
228f0 6c 6c 62 61 63 6b 20 63 61 6e 20 63 6f 6d 70 75  llback can compu
22900 74 65 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 74  te.** the same t
22910 65 78 74 20 74 68 61 74 20 77 6f 75 6c 64 20 68  ext that would h
22920 61 76 65 20 62 65 65 6e 20 72 65 74 75 72 6e 65  ave been returne
22930 64 20 62 79 20 74 68 65 20 6c 65 67 61 63 79 20  d by the legacy 
22940 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29  [sqlite3_trace()
22950 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 62  ].** interface b
22960 79 20 75 73 69 6e 67 20 74 68 65 20 58 20 61 72  y using the X ar
22970 67 75 6d 65 6e 74 20 77 68 65 6e 20 58 20 62 65  gument when X be
22980 67 69 6e 73 20 77 69 74 68 20 22 2d 2d 22 20 61  gins with "--" a
22990 6e 64 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 5b  nd invoking.** [
229a0 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64  sqlite3_expanded
229b0 5f 73 71 6c 28 50 29 5d 20 6f 74 68 65 72 77 69  _sql(P)] otherwi
229c0 73 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  se..**.** [[SQLI
229d0 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45  TE_TRACE_PROFILE
229e0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52  ]] <dt>SQLITE_TR
229f0 41 43 45 5f 50 52 4f 46 49 4c 45 3c 2f 64 74 3e  ACE_PROFILE</dt>
22a00 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49  .** <dd>^An SQLI
22a10 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45  TE_TRACE_PROFILE
22a20 20 63 61 6c 6c 62 61 63 6b 20 70 72 6f 76 69 64   callback provid
22a30 65 73 20 61 70 70 72 6f 78 69 6d 61 74 65 6c 79  es approximately
22a40 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 69 6e 66   the same.** inf
22a50 6f 72 6d 61 74 69 6f 6e 20 61 73 20 69 73 20 70  ormation as is p
22a60 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 5b  rovided by the [
22a70 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
22a80 29 5d 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20  )] callback..** 
22a90 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20  ^The P argument 
22aa0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
22ab0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
22ac0 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 74 68 65  atement] and the
22ad0 0a 2a 2a 20 58 20 61 72 67 75 6d 65 6e 74 20 70  .** X argument p
22ae0 6f 69 6e 74 73 20 74 6f 20 61 20 36 34 2d 62 69  oints to a 64-bi
22af0 74 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  t integer which 
22b00 69 73 20 74 68 65 20 65 73 74 69 6d 61 74 65 64  is the estimated
22b10 20 6f 66 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65   of.** the numbe
22b20 72 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 20  r of nanosecond 
22b30 74 68 61 74 20 74 68 65 20 70 72 65 70 61 72 65  that the prepare
22b40 64 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b  d statement took
22b50 20 74 6f 20 72 75 6e 2e 0a 2a 2a 20 5e 54 68 65   to run..** ^The
22b60 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52   SQLITE_TRACE_PR
22b70 4f 46 49 4c 45 20 63 61 6c 6c 62 61 63 6b 20 69  OFILE callback i
22b80 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74  s invoked when t
22b90 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e  he statement fin
22ba0 69 73 68 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  ishes..**.** [[S
22bb0 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 5d  QLITE_TRACE_ROW]
22bc0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41  ] <dt>SQLITE_TRA
22bd0 43 45 5f 52 4f 57 3c 2f 64 74 3e 0a 2a 2a 20 3c  CE_ROW</dt>.** <
22be0 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52  dd>^An SQLITE_TR
22bf0 41 43 45 5f 52 4f 57 20 63 61 6c 6c 62 61 63 6b  ACE_ROW callback
22c00 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   is invoked when
22c10 65 76 65 72 20 61 20 70 72 65 70 61 72 65 64 0a  ever a prepared.
22c20 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 67 65 6e  ** statement gen
22c30 65 72 61 74 65 73 20 61 20 73 69 6e 67 6c 65 20  erates a single 
22c40 72 6f 77 20 6f 66 20 72 65 73 75 6c 74 2e 20 20  row of result.  
22c50 0a 2a 2a 20 5e 54 68 65 20 50 20 61 72 67 75 6d  .** ^The P argum
22c60 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
22c70 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65   to the [prepare
22c80 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64  d statement] and
22c90 20 74 68 65 0a 2a 2a 20 58 20 61 72 67 75 6d 65   the.** X argume
22ca0 6e 74 20 69 73 20 75 6e 75 73 65 64 2e 0a 2a 2a  nt is unused..**
22cb0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41  .** [[SQLITE_TRA
22cc0 43 45 5f 43 4c 4f 53 45 5d 5d 20 3c 64 74 3e 53  CE_CLOSE]] <dt>S
22cd0 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53  QLITE_TRACE_CLOS
22ce0 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41  E</dt>.** <dd>^A
22cf0 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43  n SQLITE_TRACE_C
22d00 4c 4f 53 45 20 63 61 6c 6c 62 61 63 6b 20 69 73  LOSE callback is
22d10 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61 20   invoked when a 
22d20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
22d30 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 0a 2a  ection closes..*
22d40 2a 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e  * ^The P argumen
22d50 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
22d60 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  o the [database 
22d70 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 6a 65  connection] obje
22d80 63 74 0a 2a 2a 20 61 6e 64 20 74 68 65 20 58 20  ct.** and the X 
22d90 61 72 67 75 6d 65 6e 74 20 69 73 20 75 6e 75 73  argument is unus
22da0 65 64 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  ed..** </dl>.*/.
22db0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
22dc0 52 41 43 45 5f 53 54 4d 54 20 20 20 20 20 20 20  RACE_STMT       
22dd0 30 78 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  0x01.#define SQL
22de0 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c  ITE_TRACE_PROFIL
22df0 45 20 20 20 20 30 78 30 32 0a 23 64 65 66 69 6e  E    0x02.#defin
22e00 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52  e SQLITE_TRACE_R
22e10 4f 57 20 20 20 20 20 20 20 20 30 78 30 34 0a 23  OW        0x04.#
22e20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52  define SQLITE_TR
22e30 41 43 45 5f 43 4c 4f 53 45 20 20 20 20 20 20 30  ACE_CLOSE      0
22e40 78 30 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  x08../*.** CAPI3
22e50 52 45 46 3a 20 53 51 4c 20 54 72 61 63 65 20 48  REF: SQL Trace H
22e60 6f 6f 6b 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ook.** METHOD: s
22e70 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
22e80 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f  e sqlite3_trace_
22e90 76 32 28 44 2c 4d 2c 58 2c 50 29 20 69 6e 74 65  v2(D,M,X,P) inte
22ea0 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20  rface registers 
22eb0 61 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b  a trace callback
22ec0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 61  .** function X a
22ed0 67 61 69 6e 73 74 20 5b 64 61 74 61 62 61 73 65  gainst [database
22ee0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20   connection] D, 
22ef0 75 73 69 6e 67 20 70 72 6f 70 65 72 74 79 20 6d  using property m
22f00 61 73 6b 20 4d 0a 2a 2a 20 61 6e 64 20 63 6f 6e  ask M.** and con
22f10 74 65 78 74 20 70 6f 69 6e 74 65 72 20 50 2e 20  text pointer P. 
22f20 20 5e 49 66 20 74 68 65 20 58 20 63 61 6c 6c 62   ^If the X callb
22f30 61 63 6b 20 69 73 0a 2a 2a 20 4e 55 4c 4c 20 6f  ack is.** NULL o
22f40 72 20 69 66 20 74 68 65 20 4d 20 6d 61 73 6b 20  r if the M mask 
22f50 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74 72  is zero, then tr
22f60 61 63 69 6e 67 20 69 73 20 64 69 73 61 62 6c 65  acing is disable
22f70 64 2e 20 20 54 68 65 0a 2a 2a 20 4d 20 61 72 67  d.  The.** M arg
22f80 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20  ument should be 
22f90 74 68 65 20 62 69 74 77 69 73 65 20 4f 52 2d 65  the bitwise OR-e
22fa0 64 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66  d combination of
22fb0 0a 2a 2a 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65  .** zero or more
22fc0 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5d 20   [SQLITE_TRACE] 
22fd0 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a  constants..**.**
22fe0 20 5e 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 65   ^Each call to e
22ff0 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 74 72  ither sqlite3_tr
23000 61 63 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ace() or sqlite3
23010 5f 74 72 61 63 65 5f 76 32 28 29 20 6f 76 65 72  _trace_v2() over
23020 72 69 64 65 73 20 0a 2a 2a 20 28 63 61 6e 63 65  rides .** (cance
23030 6c 73 29 20 61 6e 79 20 70 72 69 6f 72 20 63 61  ls) any prior ca
23040 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 74  lls to sqlite3_t
23050 72 61 63 65 28 29 20 6f 72 20 73 71 6c 69 74 65  race() or sqlite
23060 33 5f 74 72 61 63 65 5f 76 32 28 29 2e 0a 2a 2a  3_trace_v2()..**
23070 0a 2a 2a 20 5e 54 68 65 20 58 20 63 61 6c 6c 62  .** ^The X callb
23080 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  ack is invoked w
23090 68 65 6e 65 76 65 72 20 61 6e 79 20 6f 66 20 74  henever any of t
230a0 68 65 20 65 76 65 6e 74 73 20 69 64 65 6e 74 69  he events identi
230b0 66 69 65 64 20 62 79 20 0a 2a 2a 20 6d 61 73 6b  fied by .** mask
230c0 20 4d 20 6f 63 63 75 72 2e 20 20 5e 54 68 65 20   M occur.  ^The 
230d0 69 6e 74 65 67 65 72 20 72 65 74 75 72 6e 20 76  integer return v
230e0 61 6c 75 65 20 66 72 6f 6d 20 74 68 65 20 63 61  alue from the ca
230f0 6c 6c 62 61 63 6b 20 69 73 20 63 75 72 72 65 6e  llback is curren
23100 74 6c 79 0a 2a 2a 20 69 67 6e 6f 72 65 64 2c 20  tly.** ignored, 
23110 74 68 6f 75 67 68 20 74 68 69 73 20 6d 61 79 20  though this may 
23120 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65  change in future
23130 20 72 65 6c 65 61 73 65 73 2e 20 20 43 61 6c 6c   releases.  Call
23140 62 61 63 6b 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  back.** implemen
23150 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 72  tations should r
23160 65 74 75 72 6e 20 7a 65 72 6f 20 74 6f 20 65 6e  eturn zero to en
23170 73 75 72 65 20 66 75 74 75 72 65 20 63 6f 6d 70  sure future comp
23180 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a  atibility..**.**
23190 20 5e 41 20 74 72 61 63 65 20 63 61 6c 6c 62 61   ^A trace callba
231a0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69  ck is invoked wi
231b0 74 68 20 66 6f 75 72 20 61 72 67 75 6d 65 6e 74  th four argument
231c0 73 3a 20 63 61 6c 6c 62 61 63 6b 28 54 2c 43 2c  s: callback(T,C,
231d0 50 2c 58 29 2e 0a 2a 2a 20 5e 54 68 65 20 54 20  P,X)..** ^The T 
231e0 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20  argument is one 
231f0 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  of the [SQLITE_T
23200 52 41 43 45 5d 0a 2a 2a 20 63 6f 6e 73 74 61 6e  RACE].** constan
23210 74 73 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77  ts to indicate w
23220 68 79 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  hy the callback 
23230 77 61 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20  was invoked..** 
23240 5e 54 68 65 20 43 20 61 72 67 75 6d 65 6e 74 20  ^The C argument 
23250 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
23260 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72   context pointer
23270 2e 0a 2a 2a 20 54 68 65 20 50 20 61 6e 64 20 58  ..** The P and X
23280 20 61 72 67 75 6d 65 6e 74 73 20 61 72 65 20 70   arguments are p
23290 6f 69 6e 74 65 72 73 20 77 68 6f 73 65 20 6d 65  ointers whose me
232a0 61 6e 69 6e 67 73 20 64 65 70 65 6e 64 20 6f 6e  anings depend on
232b0 20 54 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71   T..**.** The sq
232c0 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29  lite3_trace_v2()
232d0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e   interface is in
232e0 74 65 6e 64 65 64 20 74 6f 20 72 65 70 6c 61 63  tended to replac
232f0 65 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20  e the legacy.** 
23300 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69  interfaces [sqli
23310 74 65 33 5f 74 72 61 63 65 28 29 5d 20 61 6e 64  te3_trace()] and
23320 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c   [sqlite3_profil
23330 65 28 29 5d 2c 20 62 6f 74 68 20 6f 66 20 77 68  e()], both of wh
23340 69 63 68 0a 2a 2a 20 61 72 65 20 64 65 70 72 65  ich.** are depre
23350 63 61 74 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71  cated..*/.int sq
23360 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 0a  lite3_trace_v2(.
23370 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 75 6e    sqlite3*,.  un
23380 73 69 67 6e 65 64 20 75 4d 61 73 6b 2c 0a 20 20  signed uMask,.  
23390 69 6e 74 28 2a 78 43 61 6c 6c 62 61 63 6b 29 28  int(*xCallback)(
233a0 75 6e 73 69 67 6e 65 64 2c 76 6f 69 64 2a 2c 76  unsigned,void*,v
233b0 6f 69 64 2a 2c 76 6f 69 64 2a 29 2c 0a 20 20 76  oid*,void*),.  v
233c0 6f 69 64 20 2a 70 43 74 78 0a 29 3b 0a 0a 2f 2a  oid *pCtx.);../*
233d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75  .** CAPI3REF: Qu
233e0 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c  ery Progress Cal
233f0 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44  lbacks.** METHOD
23400 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
23410 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f  ^The sqlite3_pro
23420 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c  gress_handler(D,
23430 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65  N,X,P) interface
23440 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c   causes the call
23450 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  back.** function
23460 20 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64   X to be invoked
23470 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75   periodically du
23480 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e  ring long runnin
23490 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73  g calls to.** [s
234a0 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20  qlite3_exec()], 
234b0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
234c0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65   and [sqlite3_ge
234d0 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a  t_table()] for.*
234e0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
234f0 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61  ction D.  An exa
23500 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69  mple use for thi
23510 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69  s.** interface i
23520 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20  s to keep a GUI 
23530 75 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 61  updated during a
23540 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a   large query..**
23550 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74  .** ^The paramet
23560 65 72 20 50 20 69 73 20 70 61 73 73 65 64 20 74  er P is passed t
23570 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e  hrough as the on
23580 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ly parameter to 
23590 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  the .** callback
235a0 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54   function X.  ^T
235b0 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69  he parameter N i
235c0 73 20 74 68 65 20 61 70 70 72 6f 78 69 6d 61 74  s the approximat
235d0 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20  e number of .** 
235e0 5b 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65  [virtual machine
235f0 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74   instructions] t
23600 68 61 74 20 61 72 65 20 65 76 61 6c 75 61 74 65  hat are evaluate
23610 64 20 62 65 74 77 65 65 6e 20 73 75 63 63 65 73  d between succes
23620 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69  sive.** invocati
23630 6f 6e 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62  ons of the callb
23640 61 63 6b 20 58 2e 20 20 5e 49 66 20 4e 20 69 73  ack X.  ^If N is
23650 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 74   less than one t
23660 68 65 6e 20 74 68 65 20 70 72 6f 67 72 65 73 73  hen the progress
23670 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 69 73 20 64  .** handler is d
23680 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  isabled..**.** ^
23690 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72  Only a single pr
236a0 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d  ogress handler m
236b0 61 79 20 62 65 20 64 65 66 69 6e 65 64 20 61 74  ay be defined at
236c0 20 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a   one time per.**
236d0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
236e0 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20  ction]; setting 
236f0 61 20 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68  a new progress h
23700 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74  andler cancels t
23710 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20  he.** old one.  
23720 5e 53 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74  ^Setting paramet
23730 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73  er X to NULL dis
23740 61 62 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65  ables the progre
23750 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e  ss handler..** ^
23760 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  The progress han
23770 64 6c 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73  dler is also dis
23780 61 62 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67  abled by setting
23790 20 4e 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65   N to a value le
237a0 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a  ss.** than 1..**
237b0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67  .** ^If the prog
237c0 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65  ress callback re
237d0 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
237e0 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  the operation is
237f0 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e  .** interrupted.
23800 20 20 54 68 69 73 20 66 65 61 74 75 72 65 20 63    This feature c
23810 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d  an be used to im
23820 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61  plement a.** "Ca
23830 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20  ncel" button on 
23840 61 20 47 55 49 20 70 72 6f 67 72 65 73 73 20 64  a GUI progress d
23850 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a  ialog box..**.**
23860 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61   The progress ha
23870 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d  ndler callback m
23880 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68  ust not do anyth
23890 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f  ing that will mo
238a0 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61  dify.** the data
238b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
238c0 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
238d0 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
238e0 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  r..** Note that 
238f0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
23900 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
23910 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68  te3_step()] both
23920 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a   modify their.**
23930 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
23940 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65  tions for the me
23950 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79  aning of "modify
23960 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72  " in this paragr
23970 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20  aph..**.*/.void 
23980 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
23990 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33  _handler(sqlite3
239a0 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76  *, int, int(*)(v
239b0 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  oid*), void*);..
239c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
239d0 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61  Opening A New Da
239e0 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
239f0 6e 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52  n.** CONSTRUCTOR
23a00 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
23a10 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
23a20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64  open an SQLite d
23a30 61 74 61 62 61 73 65 20 66 69 6c 65 20 61 73 20  atabase file as 
23a40 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
23a50 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72   .** filename ar
23a60 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c  gument. ^The fil
23a70 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69  ename argument i
23a80 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
23a90 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71   UTF-8 for.** sq
23aa0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64  lite3_open() and
23ab0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
23ac0 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36  () and as UTF-16
23ad0 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
23ae0 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72  yte.** order for
23af0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
23b00 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65  ). ^(A [database
23b10 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
23b20 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a  dle is usually.*
23b30 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70  * returned in *p
23b40 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20  pDb, even if an 
23b50 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54  error occurs.  T
23b60 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f  he only exceptio
23b70 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20  n is that.** if 
23b80 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65  SQLite is unable
23b90 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d   to allocate mem
23ba0 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
23bb0 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
23bc0 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c  ,.** a NULL will
23bd0 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   be written into
23be0 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f   *ppDb instead o
23bf0 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  f a pointer to t
23c00 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20  he [sqlite3].** 
23c10 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74  object.)^ ^(If t
23c20 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
23c30 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72  pened (and/or cr
23c40 65 61 74 65 64 29 20 73 75 63 63 65 73 73 66 75  eated) successfu
23c50 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51  lly, then.** [SQ
23c60 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75  LITE_OK] is retu
23c70 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65  rned.  Otherwise
23c80 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
23c90 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20   is returned.)^ 
23ca0 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ^The.** [sqlite3
23cb0 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73  _errmsg()] or [s
23cc0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
23cd0 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20  )] routines can 
23ce0 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  be used to obtai
23cf0 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20  n.** an English 
23d00 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 70  language descrip
23d10 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f  tion of the erro
23d20 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61  r following a fa
23d30 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20  ilure of any.** 
23d40 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f  of the sqlite3_o
23d50 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a  pen() routines..
23d60 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  **.** ^The defau
23d70 6c 74 20 65 6e 63 6f 64 69 6e 67 20 77 69 6c 6c  lt encoding will
23d80 20 62 65 20 55 54 46 2d 38 20 66 6f 72 20 64 61   be UTF-8 for da
23d90 74 61 62 61 73 65 73 20 63 72 65 61 74 65 64 20  tabases created 
23da0 75 73 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  using.** sqlite3
23db0 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74  _open() or sqlit
23dc0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 5e  e3_open_v2().  ^
23dd0 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f  The default enco
23de0 64 69 6e 67 20 66 6f 72 20 64 61 74 61 62 61 73  ding for databas
23df0 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 75 73  es.** created us
23e00 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ing sqlite3_open
23e10 31 36 28 29 20 77 69 6c 6c 20 62 65 20 55 54 46  16() will be UTF
23e20 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76  -16 in the nativ
23e30 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a  e byte order..**
23e40 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e  .** Whether or n
23e50 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  ot an error occu
23e60 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70  rs when it is op
23e70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a  ened, resources.
23e80 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ** associated wi
23e90 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  th the [database
23ea0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
23eb0 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65  dle should be re
23ec0 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73  leased by.** pas
23ed0 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69  sing it to [sqli
23ee0 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65  te3_close()] whe
23ef0 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65  n it is no longe
23f00 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  r required..**.*
23f10 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70  * The sqlite3_op
23f20 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  en_v2() interfac
23f30 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c  e works like sql
23f40 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65  ite3_open().** e
23f50 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 63  xcept that it ac
23f60 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 69  cepts two additi
23f70 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20  onal parameters 
23f80 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63  for additional c
23f90 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74  ontrol.** over t
23fa0 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20  he new database 
23fb0 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54  connection.  ^(T
23fc0 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  he flags paramet
23fd0 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  er to.** sqlite3
23fe0 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74  _open_v2() can t
23ff0 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68  ake one of.** th
24000 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65  e following thre
24010 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e  e values, option
24020 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69  ally combined wi
24030 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49  th the .** [SQLI
24040 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d  TE_OPEN_NOMUTEX]
24050 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  , [SQLITE_OPEN_F
24060 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49  ULLMUTEX], [SQLI
24070 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
24080 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  CHE],.** [SQLITE
24090 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
240a0 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c  HE], and/or [SQL
240b0 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c  ITE_OPEN_URI] fl
240c0 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  ags:)^.**.** <dl
240d0 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49  >.** ^(<dt>[SQLI
240e0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
240f0 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
24100 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
24110 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c  ened in read-onl
24120 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20  y mode.  If the 
24130 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f  database does no
24140 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69  t.** already exi
24150 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20  st, an error is 
24160 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e  returned.</dd>)^
24170 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  .**.** ^(<dt>[SQ
24180 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
24190 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ITE]</dt>.** <dd
241a0 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
241b0 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
241c0 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20  ing and writing 
241d0 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20  if possible, or 
241e0 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20  reading.** only 
241f0 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77  if the file is w
24200 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62  rite protected b
24210 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  y the operating 
24220 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68  system.  In eith
24230 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64  er.** case the d
24240 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72  atabase must alr
24250 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65  eady exist, othe
24260 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69  rwise an error i
24270 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e  s returned.</dd>
24280 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b  )^.**.** ^(<dt>[
24290 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
242a0 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45  WRITE] | [SQLITE
242b0 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64  _OPEN_CREATE]</d
242c0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
242d0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
242e0 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64   for reading and
242f0 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73   writing, and is
24300 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69   created if.** i
24310 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61  t does not alrea
24320 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 69  dy exist. This i
24330 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 74  s the behavior t
24340 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73  hat is always us
24350 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  ed for.** sqlite
24360 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
24370 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f  ite3_open16().</
24380 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  dd>)^.** </dl>.*
24390 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20  *.** If the 3rd 
243a0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
243b0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
243c0 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65  s not one of the
243d0 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73  .** combinations
243e0 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74   shown above opt
243f0 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64  ionally combined
24400 20 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b   with other.** [
24410 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
24420 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50  ONLY | SQLITE_OP
24430 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68  EN_* bits].** th
24440 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
24450 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
24460 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c  .** ^If the [SQL
24470 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
24480 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74  ] flag is set, t
24490 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
244a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f   connection.** o
244b0 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74  pens in the mult
244c0 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64  i-thread [thread
244d0 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e  ing mode] as lon
244e0 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d  g as the single-
244f0 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68  thread.** mode h
24500 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20  as not been set 
24510 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
24520 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20  or start-time.  
24530 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ^If the.** [SQLI
24540 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
24550 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 74  X] flag is set t
24560 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
24570 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e   connection open
24580 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69  s.** in the seri
24590 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
245a0 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73  g mode] unless s
245b0 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73  ingle-thread was
245c0 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73  .** previously s
245d0 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69  elected at compi
245e0 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74  le-time or start
245f0 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b  -time..** ^The [
24600 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
24610 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61  EDCACHE] flag ca
24620 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73  uses the databas
24630 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  e connection to 
24640 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74  be.** eligible t
24650 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20 63 61  o use [shared ca
24660 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72  che mode], regar
24670 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
24680 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a   or not shared.*
24690 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c  * cache is enabl
246a0 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
246b0 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f  3_enable_shared_
246c0 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a  cache()].  ^The.
246d0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
246e0 50 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c  PRIVATECACHE] fl
246f0 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61  ag causes the da
24700 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
24710 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74  n to not.** part
24720 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72  icipate in [shar
24730 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65  ed cache mode] e
24740 76 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61  ven if it is ena
24750 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  bled..**.** ^The
24760 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
24770 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
24780 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61  n_v2() is the na
24790 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  me of the.** [sq
247a0 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
247b0 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74  t that defines t
247c0 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
247d0 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68  tem interface th
247e0 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61  at.** the new da
247f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
24800 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e  n should use.  ^
24810 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
24820 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20  rameter is.** a 
24830 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
24840 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  n the default [s
24850 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
24860 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  ct is used..**.*
24870 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61  * ^If the filena
24880 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22  me is ":memory:"
24890 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65  , then a private
248a0 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d  , temporary in-m
248b0 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a  emory database.*
248c0 2a 20 69 73 20 63 72 65 61 74 65 64 20 66 6f 72  * is created for
248d0 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e   the connection.
248e0 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72    ^This in-memor
248f0 79 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  y database will 
24900 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74  vanish when.** t
24910 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
24920 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64  ection is closed
24930 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
24940 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67  ns of SQLite mig
24950 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f  ht.** make use o
24960 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65  f additional spe
24970 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74  cial filenames t
24980 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 20 74  hat begin with t
24990 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 65 72  he ":" character
249a0 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d  ..** It is recom
249b0 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e  mended that when
249c0 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
249d0 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f  name actually do
249e0 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a  es begin with.**
249f0 20 61 20 22 3a 22 20 63 68 61 72 61 63 74 65 72   a ":" character
24a00 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66   you should pref
24a10 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  ix the filename 
24a20 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20  with a pathname 
24a30 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20  such as.** "./" 
24a40 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69  to avoid ambigui
24a50 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ty..**.** ^If th
24a60 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e  e filename is an
24a70 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74   empty string, t
24a80 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74  hen a private, t
24a90 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64  emporary.** on-d
24aa0 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c  isk database wil
24ab0 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e  l be created.  ^
24ac0 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74  This private dat
24ad0 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a  abase will be.**
24ae0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64   automatically d
24af0 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61  eleted as soon a
24b00 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
24b10 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
24b20 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49  sed..**.** [[URI
24b30 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71   filenames in sq
24b40 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c  lite3_open()]] <
24b50 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73  h3>URI Filenames
24b60 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  </h3>.**.** ^If 
24b70 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69  [URI filename] i
24b80 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73  nterpretation is
24b90 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68   enabled, and th
24ba0 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
24bb0 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69  ent.** begins wi
24bc0 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e  th "file:", then
24bd0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
24be0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
24bf0 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66  a URI. ^URI.** f
24c00 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65  ilename interpre
24c10 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  tation is enable
24c20 64 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45  d if the [SQLITE
24c30 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20  _OPEN_URI] flag 
24c40 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 65  is.** set in the
24c50 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
24c60 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
24c70 5f 76 32 28 29 2c 20 6f 72 20 69 66 20 69 74 20  _v2(), or if it 
24c80 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62  has.** been enab
24c90 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69  led globally usi
24ca0 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43  ng the [SQLITE_C
24cb0 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f  ONFIG_URI] optio
24cc0 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73  n with the.** [s
24cd0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
24ce0 20 6d 65 74 68 6f 64 20 6f 72 20 62 79 20 74 68   method or by th
24cf0 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52  e [SQLITE_USE_UR
24d00 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  I] compile-time 
24d10 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66  option..** As of
24d20 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
24d30 33 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e  3.7.7, URI filen
24d40 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69  ame interpretati
24d50 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 66 66  on is turned off
24d60 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2c 20  .** by default, 
24d70 62 75 74 20 66 75 74 75 72 65 20 72 65 6c 65 61  but future relea
24d80 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ses of SQLite mi
24d90 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49 20 66  ght enable URI f
24da0 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72  ilename.** inter
24db0 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64 65 66  pretation by def
24dc0 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 49  ault.  See "[URI
24dd0 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72   filenames]" for
24de0 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
24df0 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
24e00 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20  * URI filenames 
24e10 61 72 65 20 70 61 72 73 65 64 20 61 63 63 6f 72  are parsed accor
24e20 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39 38 36  ding to RFC 3986
24e30 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20 63 6f  . ^If the URI co
24e40 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74  ntains an.** aut
24e50 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69 74 20  hority, then it 
24e60 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61  must be either a
24e70 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f  n empty string o
24e80 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a  r the string .**
24e90 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49   "localhost". ^I
24ea0 66 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20  f the authority 
24eb0 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20  is not an empty 
24ec0 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c  string or "local
24ed0 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72  host", an .** er
24ee0 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20  ror is returned 
24ef0 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e  to the caller. ^
24f00 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d  The fragment com
24f10 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 2c  ponent of a URI,
24f20 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c   if .** present,
24f30 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a   is ignored..**.
24f40 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20  ** ^SQLite uses 
24f50 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65  the path compone
24f60 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20 61 73  nt of the URI as
24f70 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
24f80 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68   disk file.** wh
24f90 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  ich contains the
24fa0 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66 20 74   database. ^If t
24fb0 68 65 20 70 61 74 68 20 62 65 67 69 6e 73 20 77  he path begins w
24fc0 69 74 68 20 61 20 27 2f 27 20 63 68 61 72 61 63  ith a '/' charac
24fd0 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74  ter, .** then it
24fe0 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
24ff0 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70  as an absolute p
25000 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70 61 74  ath. ^If the pat
25010 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e  h does not begin
25020 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 20   .** with a '/' 
25030 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20 74 68  (meaning that th
25040 65 20 61 75 74 68 6f 72 69 74 79 20 73 65 63 74  e authority sect
25050 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 66  ion is omitted f
25060 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a 20  rom the URI).** 
25070 74 68 65 6e 20 74 68 65 20 70 61 74 68 20 69 73  then the path is
25080 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
25090 61 20 72 65 6c 61 74 69 76 65 20 70 61 74 68 2e  a relative path.
250a0 20 0a 2a 2a 20 5e 28 4f 6e 20 77 69 6e 64 6f 77   .** ^(On window
250b0 73 2c 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d  s, the first com
250c0 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73  ponent of an abs
250d0 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69  olute path .** i
250e0 73 20 61 20 64 72 69 76 65 20 73 70 65 63 69 66  s a drive specif
250f0 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43  ication (e.g. "C
25100 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 63  :").)^.**.** [[c
25110 6f 72 65 20 55 52 49 20 71 75 65 72 79 20 70 61  ore URI query pa
25120 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68  rameters]].** Th
25130 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e  e query componen
25140 74 20 6f 66 20 61 20 55 52 49 20 6d 61 79 20 63  t of a URI may c
25150 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 74 65 72  ontain parameter
25160 73 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72  s that are inter
25170 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 72  preted.** either
25180 20 62 79 20 53 51 4c 69 74 65 20 69 74 73 65 6c   by SQLite itsel
25190 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 46 53 20  f, or by a [VFS 
251a0 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 69 6d 70  | custom VFS imp
251b0 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a  lementation]..**
251c0 20 53 51 4c 69 74 65 20 61 6e 64 20 69 74 73 20   SQLite and its 
251d0 62 75 69 6c 74 2d 69 6e 20 5b 56 46 53 65 73 5d  built-in [VFSes]
251e0 20 69 6e 74 65 72 70 72 65 74 20 74 68 65 0a 2a   interpret the.*
251f0 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 71 75 65 72  * following quer
25200 79 20 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a  y parameters:.**
25210 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  .** <ul>.**   <l
25220 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e  i> <b>vfs</b>: ^
25230 54 68 65 20 22 76 66 73 22 20 70 61 72 61 6d 65  The "vfs" parame
25240 74 65 72 20 6d 61 79 20 62 65 20 75 73 65 64 20  ter may be used 
25250 74 6f 20 73 70 65 63 69 66 79 20 74 68 65 20 6e  to specify the n
25260 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20  ame of.**     a 
25270 56 46 53 20 6f 62 6a 65 63 74 20 74 68 61 74 20  VFS object that 
25280 70 72 6f 76 69 64 65 73 20 74 68 65 20 6f 70 65  provides the ope
25290 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e  rating system in
252a0 74 65 72 66 61 63 65 20 74 68 61 74 20 73 68 6f  terface that sho
252b0 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20 75 73  uld.**     be us
252c0 65 64 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  ed to access the
252d0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 6f   database file o
252e0 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74 68 69 73  n disk. ^If this
252f0 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74   option is set t
25300 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70 74  o.**     an empt
25310 79 20 73 74 72 69 6e 67 20 74 68 65 20 64 65 66  y string the def
25320 61 75 6c 74 20 56 46 53 20 6f 62 6a 65 63 74 20  ault VFS object 
25330 69 73 20 75 73 65 64 2e 20 5e 53 70 65 63 69 66  is used. ^Specif
25340 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a  ying an unknown.
25350 2a 2a 20 20 20 20 20 56 46 53 20 69 73 20 61 6e  **     VFS is an
25360 20 65 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69   error. ^If sqli
25370 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
25380 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 76 66   used and the vf
25390 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20  s option is.**  
253a0 20 20 20 70 72 65 73 65 6e 74 2c 20 74 68 65 6e     present, then
253b0 20 74 68 65 20 56 46 53 20 73 70 65 63 69 66 69   the VFS specifi
253c0 65 64 20 62 79 20 74 68 65 20 6f 70 74 69 6f 6e  ed by the option
253d0 20 74 61 6b 65 73 20 70 72 65 63 65 64 65 6e 63   takes precedenc
253e0 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74 68  e over.**     th
253f0 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61  e value passed a
25400 73 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  s the fourth par
25410 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
25420 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  3_open_v2()..**.
25430 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64  **   <li> <b>mod
25440 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64  e</b>: ^(The mod
25450 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  e parameter may 
25460 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72  be set to either
25470 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a 20   "ro", "rw",.** 
25480 20 20 20 20 22 72 77 63 22 2c 20 6f 72 20 22 6d      "rwc", or "m
25490 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d 70 74 69  emory". Attempti
254a0 6e 67 20 74 6f 20 73 65 74 20 69 74 20 74 6f 20  ng to set it to 
254b0 61 6e 79 20 6f 74 68 65 72 20 76 61 6c 75 65 20  any other value 
254c0 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20 65 72 72  is.**     an err
254d0 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49  or)^. .**     ^I
254e0 66 20 22 72 6f 22 20 69 73 20 73 70 65 63 69 66  f "ro" is specif
254f0 69 65 64 2c 20 74 68 65 6e 20 74 68 65 20 64 61  ied, then the da
25500 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
25510 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a   for read-only .
25520 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 6a  **     access, j
25530 75 73 74 20 61 73 20 69 66 20 74 68 65 20 5b 53  ust as if the [S
25540 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
25550 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64 20 62 65  NLY] flag had be
25560 65 6e 20 73 65 74 20 69 6e 20 74 68 65 20 0a 2a  en set in the .*
25570 2a 20 20 20 20 20 74 68 69 72 64 20 61 72 67 75  *     third argu
25580 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
25590 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 49 66 20 74  open_v2(). ^If t
255a0 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69  he mode option i
255b0 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20  s set to .**    
255c0 20 22 72 77 22 2c 20 74 68 65 6e 20 74 68 65 20   "rw", then the 
255d0 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
255e0 65 64 20 66 6f 72 20 72 65 61 64 2d 77 72 69 74  ed for read-writ
255f0 65 20 28 62 75 74 20 6e 6f 74 20 63 72 65 61 74  e (but not creat
25600 65 29 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73  e) .**     acces
25610 73 2c 20 61 73 20 69 66 20 53 51 4c 49 54 45 5f  s, as if SQLITE_
25620 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 28  OPEN_READWRITE (
25630 62 75 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f  but not SQLITE_O
25640 50 45 4e 5f 43 52 45 41 54 45 29 20 68 61 64 20  PEN_CREATE) had 
25650 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20 73 65 74  .**     been set
25660 2e 20 5e 56 61 6c 75 65 20 22 72 77 63 22 20 69  . ^Value "rwc" i
25670 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20  s equivalent to 
25680 73 65 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a  setting both .**
25690 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e       SQLITE_OPEN
256a0 5f 52 45 41 44 57 52 49 54 45 20 61 6e 64 20 53  _READWRITE and S
256b0 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
256c0 45 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 64 65  E.  ^If the mode
256d0 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20   option is.**   
256e0 20 20 73 65 74 20 74 6f 20 22 6d 65 6d 6f 72 79    set to "memory
256f0 22 20 74 68 65 6e 20 61 20 70 75 72 65 20 5b 69  " then a pure [i
25700 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
25710 65 5d 20 74 68 61 74 20 6e 65 76 65 72 20 72 65  e] that never re
25720 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72 20 77 72  ads.**     or wr
25730 69 74 65 73 20 66 72 6f 6d 20 64 69 73 6b 20 69  ites from disk i
25740 73 20 75 73 65 64 2e 20 5e 49 74 20 69 73 20 61  s used. ^It is a
25750 6e 20 65 72 72 6f 72 20 74 6f 20 73 70 65 63 69  n error to speci
25760 66 79 20 61 20 76 61 6c 75 65 20 66 6f 72 0a 2a  fy a value for.*
25770 2a 20 20 20 20 20 74 68 65 20 6d 6f 64 65 20 70  *     the mode p
25780 61 72 61 6d 65 74 65 72 20 74 68 61 74 20 69 73  arameter that is
25790 20 6c 65 73 73 20 72 65 73 74 72 69 63 74 69 76   less restrictiv
257a0 65 20 74 68 61 6e 20 74 68 61 74 20 73 70 65 63  e than that spec
257b0 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20  ified by.**     
257c0 74 68 65 20 66 6c 61 67 73 20 70 61 73 73 65 64  the flags passed
257d0 20 69 6e 20 74 68 65 20 74 68 69 72 64 20 70 61   in the third pa
257e0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
257f0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a  e3_open_v2()..**
25800 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61  .**   <li> <b>ca
25810 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61  che</b>: ^The ca
25820 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61  che parameter ma
25830 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68  y be set to eith
25840 65 72 20 22 73 68 61 72 65 64 22 20 6f 72 0a 2a  er "shared" or.*
25850 2a 20 20 20 20 20 22 70 72 69 76 61 74 65 22 2e  *     "private".
25860 20 5e 53 65 74 74 69 6e 67 20 69 74 20 74 6f 20   ^Setting it to 
25870 22 73 68 61 72 65 64 22 20 69 73 20 65 71 75 69  "shared" is equi
25880 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e  valent to settin
25890 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c  g the.**     SQL
258a0 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
258b0 41 43 48 45 20 62 69 74 20 69 6e 20 74 68 65 20  ACHE bit in the 
258c0 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 70  flags argument p
258d0 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20  assed to.**     
258e0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
258f0 29 2e 20 5e 53 65 74 74 69 6e 67 20 74 68 65 20  ). ^Setting the 
25900 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20  cache parameter 
25910 74 6f 20 22 70 72 69 76 61 74 65 22 20 69 73 20  to "private" is 
25920 0a 2a 2a 20 20 20 20 20 65 71 75 69 76 61 6c 65  .**     equivale
25930 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68  nt to setting th
25940 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52  e SQLITE_OPEN_PR
25950 49 56 41 54 45 43 41 43 48 45 20 62 69 74 2e 0a  IVATECACHE bit..
25960 2a 2a 20 20 20 20 20 5e 49 66 20 73 71 6c 69 74  **     ^If sqlit
25970 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
25980 75 73 65 64 20 61 6e 64 20 74 68 65 20 22 63 61  used and the "ca
25990 63 68 65 22 20 70 61 72 61 6d 65 74 65 72 20 69  che" parameter i
259a0 73 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20  s present in.** 
259b0 20 20 20 20 61 20 55 52 49 20 66 69 6c 65 6e 61      a URI filena
259c0 6d 65 2c 20 69 74 73 20 76 61 6c 75 65 20 6f 76  me, its value ov
259d0 65 72 72 69 64 65 73 20 61 6e 79 20 62 65 68 61  errides any beha
259e0 76 69 6f 72 20 72 65 71 75 65 73 74 65 64 20 62  vior requested b
259f0 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20  y setting.**    
25a00 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49   SQLITE_OPEN_PRI
25a10 56 41 54 45 43 41 43 48 45 20 6f 72 20 53 51 4c  VATECACHE or SQL
25a20 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
25a30 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a  ACHE flag..**.**
25a40 20 20 3c 6c 69 3e 20 3c 62 3e 70 73 6f 77 3c 2f    <li> <b>psow</
25a50 62 3e 3a 20 5e 54 68 65 20 70 73 6f 77 20 70 61  b>: ^The psow pa
25a60 72 61 6d 65 74 65 72 20 69 6e 64 69 63 61 74 65  rameter indicate
25a70 73 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  s whether or not
25a80 20 74 68 65 0a 2a 2a 20 20 20 20 20 5b 70 6f 77   the.**     [pow
25a90 65 72 73 61 66 65 20 6f 76 65 72 77 72 69 74 65  ersafe overwrite
25aa0 5d 20 70 72 6f 70 65 72 74 79 20 64 6f 65 73 20  ] property does 
25ab0 6f 72 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 6c  or does not appl
25ac0 79 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20  y to the.**     
25ad0 73 74 6f 72 61 67 65 20 6d 65 64 69 61 20 6f 6e  storage media on
25ae0 20 77 68 69 63 68 20 74 68 65 20 64 61 74 61 62   which the datab
25af0 61 73 65 20 66 69 6c 65 20 72 65 73 69 64 65 73  ase file resides
25b00 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62  ..**.**  <li> <b
25b10 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e 54 68  >nolock</b>: ^Th
25b20 65 20 6e 6f 6c 6f 63 6b 20 70 61 72 61 6d 65 74  e nolock paramet
25b30 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20  er is a boolean 
25b40 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 0a  query parameter.
25b50 2a 2a 20 20 20 20 20 77 68 69 63 68 20 69 66 20  **     which if 
25b60 73 65 74 20 64 69 73 61 62 6c 65 73 20 66 69 6c  set disables fil
25b70 65 20 6c 6f 63 6b 69 6e 67 20 69 6e 20 72 6f 6c  e locking in rol
25b80 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 20 6d 6f  lback journal mo
25b90 64 65 73 2e 20 20 54 68 69 73 0a 2a 2a 20 20 20  des.  This.**   
25ba0 20 20 69 73 20 75 73 65 66 75 6c 20 66 6f 72 20    is useful for 
25bb0 61 63 63 65 73 73 69 6e 67 20 61 20 64 61 74 61  accessing a data
25bc0 62 61 73 65 20 6f 6e 20 61 20 66 69 6c 65 73 79  base on a filesy
25bd0 73 74 65 6d 20 74 68 61 74 20 64 6f 65 73 20 6e  stem that does n
25be0 6f 74 0a 2a 2a 20 20 20 20 20 73 75 70 70 6f 72  ot.**     suppor
25bf0 74 20 6c 6f 63 6b 69 6e 67 2e 20 20 43 61 75 74  t locking.  Caut
25c00 69 6f 6e 3a 20 20 44 61 74 61 62 61 73 65 20 63  ion:  Database c
25c10 6f 72 72 75 70 74 69 6f 6e 20 6d 69 67 68 74 20  orruption might 
25c20 72 65 73 75 6c 74 20 69 66 20 74 77 6f 0a 2a 2a  result if two.**
25c30 20 20 20 20 20 6f 72 20 6d 6f 72 65 20 70 72 6f       or more pro
25c40 63 65 73 73 65 73 20 77 72 69 74 65 20 74 6f 20  cesses write to 
25c50 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
25c60 65 20 61 6e 64 20 61 6e 79 20 6f 6e 65 20 6f 66  e and any one of
25c70 20 74 68 6f 73 65 0a 2a 2a 20 20 20 20 20 70 72   those.**     pr
25c80 6f 63 65 73 73 65 73 20 75 73 65 73 20 6e 6f 6c  ocesses uses nol
25c90 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c  ock=1..**.**  <l
25ca0 69 3e 20 3c 62 3e 69 6d 6d 75 74 61 62 6c 65 3c  i> <b>immutable<
25cb0 2f 62 3e 3a 20 5e 54 68 65 20 69 6d 6d 75 74 61  /b>: ^The immuta
25cc0 62 6c 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  ble parameter is
25cd0 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79   a boolean query
25ce0 0a 2a 2a 20 20 20 20 20 70 61 72 61 6d 65 74 65  .**     paramete
25cf0 72 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73  r that indicates
25d00 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61   that the databa
25d10 73 65 20 66 69 6c 65 20 69 73 20 73 74 6f 72 65  se file is store
25d20 64 20 6f 6e 0a 2a 2a 20 20 20 20 20 72 65 61 64  d on.**     read
25d30 2d 6f 6e 6c 79 20 6d 65 64 69 61 2e 20 20 5e 57  -only media.  ^W
25d40 68 65 6e 20 69 6d 6d 75 74 61 62 6c 65 20 69 73  hen immutable is
25d50 20 73 65 74 2c 20 53 51 4c 69 74 65 20 61 73 73   set, SQLite ass
25d60 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a  umes that the.**
25d70 20 20 20 20 20 64 61 74 61 62 61 73 65 20 66 69       database fi
25d80 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61  le cannot be cha
25d90 6e 67 65 64 2c 20 65 76 65 6e 20 62 79 20 61 20  nged, even by a 
25da0 70 72 6f 63 65 73 73 20 77 69 74 68 20 68 69 67  process with hig
25db0 68 65 72 0a 2a 2a 20 20 20 20 20 70 72 69 76 69  her.**     privi
25dc0 6c 65 67 65 2c 20 61 6e 64 20 73 6f 20 74 68 65  lege, and so the
25dd0 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
25de0 6e 65 64 20 72 65 61 64 2d 6f 6e 6c 79 20 61 6e  ned read-only an
25df0 64 20 61 6c 6c 20 6c 6f 63 6b 69 6e 67 0a 2a 2a  d all locking.**
25e00 20 20 20 20 20 61 6e 64 20 63 68 61 6e 67 65 20       and change 
25e10 64 65 74 65 63 74 69 6f 6e 20 69 73 20 64 69 73  detection is dis
25e20 61 62 6c 65 64 2e 20 20 43 61 75 74 69 6f 6e 3a  abled.  Caution:
25e30 20 53 65 74 74 69 6e 67 20 74 68 65 20 69 6d 6d   Setting the imm
25e40 75 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20 70 72  utable.**     pr
25e50 6f 70 65 72 74 79 20 6f 6e 20 61 20 64 61 74 61  operty on a data
25e60 62 61 73 65 20 66 69 6c 65 20 74 68 61 74 20 64  base file that d
25e70 6f 65 73 20 69 6e 20 66 61 63 74 20 63 68 61 6e  oes in fact chan
25e80 67 65 20 63 61 6e 20 72 65 73 75 6c 74 0a 2a 2a  ge can result.**
25e90 20 20 20 20 20 69 6e 20 69 6e 63 6f 72 72 65 63       in incorrec
25ea0 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20  t query results 
25eb0 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 43  and/or [SQLITE_C
25ec0 4f 52 52 55 50 54 5d 20 65 72 72 6f 72 73 2e 0a  ORRUPT] errors..
25ed0 2a 2a 20 20 20 20 20 53 65 65 20 61 6c 73 6f 3a  **     See also:
25ee0 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49   [SQLITE_IOCAP_I
25ef0 4d 4d 55 54 41 42 4c 45 5d 2e 0a 2a 2a 20 20 20  MMUTABLE]..**   
25f00 20 20 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a      .** </ul>.**
25f10 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 20  .** ^Specifying 
25f20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d  an unknown param
25f30 65 74 65 72 20 69 6e 20 74 68 65 20 71 75 65 72  eter in the quer
25f40 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61  y component of a
25f50 20 55 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a   URI is not an.*
25f60 2a 20 65 72 72 6f 72 2e 20 20 46 75 74 75 72 65  * error.  Future
25f70 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
25f80 69 74 65 20 6d 69 67 68 74 20 75 6e 64 65 72 73  ite might unders
25f90 74 61 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c 20  tand additional 
25fa0 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74  query.** paramet
25fb0 65 72 73 2e 20 20 53 65 65 20 22 5b 71 75 65 72  ers.  See "[quer
25fc0 79 20 70 61 72 61 6d 65 74 65 72 73 20 77 69 74  y parameters wit
25fd0 68 20 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e  h special meanin
25fe0 67 20 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f  g to SQLite]" fo
25ff0 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20  r.** additional 
26000 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
26010 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d  ** [[URI filenam
26020 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33  e examples]] <h3
26030 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78  >URI filename ex
26040 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a  amples</h3>.**.*
26050 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d  * <table border=
26060 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72  "1" align=center
26070 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a   cellpadding=5>.
26080 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20  ** <tr><th> URI 
26090 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52  filenames <th> R
260a0 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74  esults.** <tr><t
260b0 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 20  d> file:data.db 
260c0 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
260d0 20 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20    Open the file 
260e0 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65  "data.db" in the
260f0 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f   current directo
26100 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ry..** <tr><td> 
26110 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f  file:/home/fred/
26120 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20  data.db<br>.**  
26130 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f          file:///
26140 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
26150 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20  b <br> .**      
26160 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c      file://local
26170 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  host/home/fred/d
26180 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e  ata.db <br> <td>
26190 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70   .**          Op
261a0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
261b0 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64  file "/home/fred
261c0 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74  /data.db"..** <t
261d0 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61  r><td> file://da
261e0 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64  rkstar/home/fred
261f0 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a  /data.db <td> .*
26200 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72  *          An er
26210 72 6f 72 2e 20 22 64 61 72 6b 73 74 61 72 22 20  ror. "darkstar" 
26220 69 73 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69  is not a recogni
26230 7a 65 64 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a  zed authority..*
26240 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d  * <tr><td style=
26250 22 77 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77  "white-space:now
26260 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20  rap"> .**       
26270 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f     file:///C:/Do
26280 63 75 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 30  cuments%20and%20
26290 53 65 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 65  Settings/fred/De
262a0 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a  sktop/data.db.**
262b0 20 20 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77       <td> Window
262c0 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65  s only: Open the
262d0 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20   file "data.db" 
262e0 6f 6e 20 66 72 65 64 27 73 20 64 65 73 6b 74 6f  on fred's deskto
262f0 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20  p on drive.**   
26300 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20         C:. Note 
26310 74 68 61 74 20 74 68 65 20 25 32 30 20 65 73 63  that the %20 esc
26320 61 70 69 6e 67 20 69 6e 20 74 68 69 73 20 65 78  aping in this ex
26330 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 72  ample is not str
26340 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20  ictly .**       
26350 20 20 20 6e 65 63 65 73 73 61 72 79 20 2d 20 73     necessary - s
26360 70 61 63 65 20 63 68 61 72 61 63 74 65 72 73 20  pace characters 
26370 63 61 6e 20 62 65 20 75 73 65 64 20 6c 69 74 65  can be used lite
26380 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20  rally.**        
26390 20 20 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d    in URI filenam
263a0 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  es..** <tr><td> 
263b0 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64  file:data.db?mod
263c0 65 3d 72 6f 26 63 61 63 68 65 3d 70 72 69 76 61  e=ro&cache=priva
263d0 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  te <td> .**     
263e0 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22       Open file "
263f0 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20  data.db" in the 
26400 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72  current director
26410 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20  y for read-only 
26420 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20  access..**      
26430 20 20 20 20 52 65 67 61 72 64 6c 65 73 73 20 6f      Regardless o
26440 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
26450 20 73 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f   shared-cache mo
26460 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79  de is enabled by
26470 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 66  .**          def
26480 61 75 6c 74 2c 20 75 73 65 20 61 20 70 72 69 76  ault, use a priv
26490 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74  ate cache..** <t
264a0 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d  r><td> file:/hom
264b0 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3f 76  e/fred/data.db?v
264c0 66 73 3d 75 6e 69 78 2d 64 6f 74 66 69 6c 65 20  fs=unix-dotfile 
264d0 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20  <td>.**         
264e0 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d   Open file "/hom
264f0 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e  e/fred/data.db".
26500 20 55 73 65 20 74 68 65 20 73 70 65 63 69 61 6c   Use the special
26510 20 56 46 53 20 22 75 6e 69 78 2d 64 6f 74 66 69   VFS "unix-dotfi
26520 6c 65 22 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  le".**          
26530 74 68 61 74 20 75 73 65 73 20 64 6f 74 2d 66 69  that uses dot-fi
26540 6c 65 73 20 69 6e 20 70 6c 61 63 65 20 6f 66 20  les in place of 
26550 70 6f 73 69 78 20 61 64 76 69 73 6f 72 79 20 6c  posix advisory l
26560 6f 63 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 72 3e 3c  ocking..** <tr><
26570 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62  td> file:data.db
26580 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c  ?mode=readonly <
26590 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
265a0 20 41 6e 20 65 72 72 6f 72 2e 20 22 72 65 61 64   An error. "read
265b0 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61 20 76  only" is not a v
265c0 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20  alid option for 
265d0 74 68 65 20 22 6d 6f 64 65 22 20 70 61 72 61 6d  the "mode" param
265e0 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65  eter..** </table
265f0 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78  >.**.** ^URI 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 28 25 48 48 29 20  sequences (%HH) 
26620 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 77 69  are supported wi
26630 74 68 69 6e 20 74 68 65 20 70 61 74 68 20 61 6e  thin the path an
26640 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f  d.** query compo
26650 6e 65 6e 74 73 20 6f 66 20 61 20 55 52 49 2e 20  nents of a URI. 
26660 41 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73  A hexadecimal es
26670 63 61 70 65 20 73 65 71 75 65 6e 63 65 20 63 6f  cape sequence co
26680 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70  nsists of a.** p
26690 65 72 63 65 6e 74 20 73 69 67 6e 20 2d 20 22 25  ercent sign - "%
266a0 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  " - followed by 
266b0 65 78 61 63 74 6c 79 20 74 77 6f 20 68 65 78 61  exactly two hexa
266c0 64 65 63 69 6d 61 6c 20 64 69 67 69 74 73 20 0a  decimal digits .
266d0 2a 2a 20 73 70 65 63 69 66 79 69 6e 67 20 61 6e  ** specifying an
266e0 20 6f 63 74 65 74 20 76 61 6c 75 65 2e 20 5e 42   octet value. ^B
266f0 65 66 6f 72 65 20 74 68 65 20 70 61 74 68 20 6f  efore the path o
26700 72 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e  r query componen
26710 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66  ts of a.** URI f
26720 69 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e 74 65  ilename are inte
26730 72 70 72 65 74 65 64 2c 20 74 68 65 79 20 61 72  rpreted, they ar
26740 65 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20  e encoded using 
26750 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a  UTF-8 and all .*
26760 2a 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73  * hexadecimal es
26770 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 72  cape sequences r
26780 65 70 6c 61 63 65 64 20 62 79 20 61 20 73 69 6e  eplaced by a sin
26790 67 6c 65 20 62 79 74 65 20 63 6f 6e 74 61 69 6e  gle byte contain
267a0 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65  ing the.** corre
267b0 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20  sponding octet. 
267c0 49 66 20 74 68 69 73 20 70 72 6f 63 65 73 73 20  If this process 
267d0 67 65 6e 65 72 61 74 65 73 20 61 6e 20 69 6e 76  generates an inv
267e0 61 6c 69 64 20 55 54 46 2d 38 20 65 6e 63 6f 64  alid UTF-8 encod
267f0 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75  ing,.** the resu
26800 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
26810 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65  d..**.** <b>Note
26820 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72   to Windows user
26830 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f  s:</b>  The enco
26840 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68  ding used for th
26850 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
26860 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65  ent.** of sqlite
26870 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
26880 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d  ite3_open_v2() m
26890 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f  ust be UTF-8, no
268a0 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f  t whatever.** co
268b0 64 65 70 61 67 65 20 69 73 20 63 75 72 72 65 6e  depage is curren
268c0 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69  tly defined.  Fi
268d0 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69  lenames containi
268e0 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c  ng international
268f0 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d  .** characters m
26900 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
26910 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20   to UTF-8 prior 
26920 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20  to passing them 
26930 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  into.** sqlite3_
26940 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  open() or sqlite
26950 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  3_open_v2()..**.
26960 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69  ** <b>Note to Wi
26970 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73  ndows Runtime us
26980 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65  ers:</b>  The te
26990 6d 70 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72  mporary director
269a0 79 20 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a  y must be set.**
269b0 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e   prior to callin
269c0 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  g sqlite3_open()
269d0 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   or sqlite3_open
269e0 5f 76 32 28 29 2e 20 20 4f 74 68 65 72 77 69 73  _v2().  Otherwis
269f0 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65  e, various.** fe
26a00 61 74 75 72 65 73 20 74 68 61 74 20 72 65 71 75  atures that requ
26a10 69 72 65 20 74 68 65 20 75 73 65 20 6f 66 20 74  ire the use of t
26a20 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d  emporary files m
26a30 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53  ay fail..**.** S
26a40 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
26a50 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79  3_temp_directory
26a60 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
26a70 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63  _open(.  const c
26a80 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  har *filename,  
26a90 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
26aa0 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f  ename (UTF-8) */
26ab0 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
26ac0 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b          /* OU
26ad0 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
26ae0 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  dle */.);.int sq
26af0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20  lite3_open16(.  
26b00 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65  const void *file
26b10 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
26b20 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
26b30 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74  F-16) */.  sqlit
26b40 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20  e3 **ppDb       
26b50 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74     /* OUT: SQLit
26b60 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29  e db handle */.)
26b70 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  ;.int sqlite3_op
26b80 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63  en_v2(.  const c
26b90 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  har *filename,  
26ba0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
26bb0 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f  ename (UTF-8) */
26bc0 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
26bd0 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b,         /* OU
26be0 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
26bf0 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61  dle */.  int fla
26c00 67 73 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  gs,             
26c10 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63   /* Flags */.  c
26c20 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20  onst char *zVfs 
26c30 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
26c40 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20  f VFS module to 
26c50 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  use */.);../*.**
26c60 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69   CAPI3REF: Obtai
26c70 6e 20 56 61 6c 75 65 73 20 46 6f 72 20 55 52 49  n Values For URI
26c80 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a   Parameters.**.*
26c90 2a 20 54 68 65 73 65 20 61 72 65 20 75 74 69 6c  * These are util
26ca0 69 74 79 20 72 6f 75 74 69 6e 65 73 2c 20 75 73  ity routines, us
26cb0 65 66 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c  eful to VFS impl
26cc0 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61  ementations, tha
26cd0 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65  t check.** to se
26ce0 65 20 69 66 20 61 20 64 61 74 61 62 61 73 65 20  e if a database 
26cf0 66 69 6c 65 20 77 61 73 20 61 20 55 52 49 20 74  file was a URI t
26d00 68 61 74 20 63 6f 6e 74 61 69 6e 65 64 20 61 20  hat contained a 
26d10 73 70 65 63 69 66 69 63 20 71 75 65 72 79 20 0a  specific query .
26d20 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 61 6e  ** parameter, an
26d30 64 20 69 66 20 73 6f 20 6f 62 74 61 69 6e 73 20  d if so obtains 
26d40 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61  the value of tha
26d50 74 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  t query paramete
26d60 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73  r..**.** If F is
26d70 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
26d80 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70  lename pointer p
26d90 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78  assed into the x
26da0 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66  Open() method of
26db0 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c 65   .** a VFS imple
26dc0 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20 74  mentation when t
26dd0 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  he flags paramet
26de0 65 72 20 74 6f 20 78 4f 70 65 6e 28 29 20 68 61  er to xOpen() ha
26df0 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72  s one or .** mor
26e00 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45  e of the [SQLITE
26e10 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53  _OPEN_URI] or [S
26e20 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
26e30 44 42 5d 20 62 69 74 73 20 73 65 74 20 61 6e 64  DB] bits set and
26e40 0a 2a 2a 20 50 20 69 73 20 74 68 65 20 6e 61 6d  .** P is the nam
26e50 65 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 70  e of the query p
26e60 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a  arameter, then.*
26e70 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61  * sqlite3_uri_pa
26e80 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74  rameter(F,P) ret
26e90 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f  urns the value o
26ea0 66 20 74 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d  f the P.** param
26eb0 65 74 65 72 20 69 66 20 69 74 20 65 78 69 73 74  eter if it exist
26ec0 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s or a NULL poin
26ed0 74 65 72 20 69 66 20 50 20 64 6f 65 73 20 6e 6f  ter if P does no
26ee0 74 20 61 70 70 65 61 72 20 61 73 20 61 20 0a 2a  t appear as a .*
26ef0 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  * query paramete
26f00 72 20 6f 6e 20 46 2e 20 20 49 66 20 50 20 69 73  r on F.  If P is
26f10 20 61 20 71 75 65 72 79 20 70 61 72 61 6d 65 74   a query paramet
26f20 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e  er of F.** has n
26f30 6f 20 65 78 70 6c 69 63 69 74 20 76 61 6c 75 65  o explicit value
26f40 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75  , then sqlite3_u
26f50 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50  ri_parameter(F,P
26f60 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70  ) returns.** a p
26f70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d 70  ointer to an emp
26f80 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ty string..**.**
26f90 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69   The sqlite3_uri
26fa0 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20  _boolean(F,P,B) 
26fb0 72 6f 75 74 69 6e 65 20 61 73 73 75 6d 65 73 20  routine assumes 
26fc0 74 68 61 74 20 50 20 69 73 20 61 20 62 6f 6f 6c  that P is a bool
26fd0 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ean.** parameter
26fe0 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 72 75   and returns tru
26ff0 65 20 28 31 29 20 6f 72 20 66 61 6c 73 65 20 28  e (1) or false (
27000 30 29 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20  0) according to 
27010 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  the value.** of 
27020 50 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  P.  The sqlite3_
27030 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
27040 42 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  B) routine retur
27050 6e 73 20 74 72 75 65 20 28 31 29 20 69 66 20 74  ns true (1) if t
27060 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71  he.** value of q
27070 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 50  uery parameter P
27080 20 69 73 20 6f 6e 65 20 6f 66 20 22 79 65 73 22   is one of "yes"
27090 2c 20 22 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e  , "true", or "on
270a0 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65  " in any.** case
270b0 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65   or if the value
270c0 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e   begins with a n
270d0 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20  on-zero number. 
270e0 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33   The .** sqlite3
270f0 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50  _uri_boolean(F,P
27100 2c 42 29 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ,B) routines ret
27110 75 72 6e 73 20 66 61 6c 73 65 20 28 30 29 20 69  urns false (0) i
27120 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a  f the value of.*
27130 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  * query paramete
27140 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e  r P is one of "n
27150 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72 20  o", "false", or 
27160 22 6f 66 66 22 20 69 6e 20 61 6e 79 20 63 61 73  "off" in any cas
27170 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20 76  e or.** if the v
27180 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68  alue begins with
27190 20 61 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e   a numeric zero.
271a0 20 20 49 66 20 50 20 69 73 20 6e 6f 74 20 61 20    If P is not a 
271b0 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74  query.** paramet
271c0 65 72 20 6f 6e 20 46 20 6f 72 20 69 66 20 74 68  er on F or if th
271d0 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20  e value of P is 
271e0 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 61  does not match a
271f0 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f  ny of the.** abo
27200 76 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ve, then sqlite3
27210 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50  _uri_boolean(F,P
27220 2c 42 29 20 72 65 74 75 72 6e 73 20 28 42 21 3d  ,B) returns (B!=
27230 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  0)..**.** The sq
27240 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28  lite3_uri_int64(
27250 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e 65 20 63  F,P,D) routine c
27260 6f 6e 76 65 72 74 73 20 74 68 65 20 76 61 6c 75  onverts the valu
27270 65 20 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a  e of P into a.**
27280 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
27290 6e 74 65 67 65 72 20 61 6e 64 20 72 65 74 75 72  nteger and retur
272a0 6e 73 20 74 68 61 74 20 69 6e 74 65 67 65 72 2c  ns that integer,
272b0 20 6f 72 20 44 20 69 66 20 50 20 64 6f 65 73 20   or D if P does 
272c0 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49  not.** exist.  I
272d0 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50  f the value of P
272e0 20 69 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74   is something ot
272f0 68 65 72 20 74 68 61 6e 20 61 6e 20 69 6e 74 65  her than an inte
27300 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72  ger, then.** zer
27310 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  o is returned..*
27320 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73 20 61 20  * .** If F is a 
27330 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68  NULL pointer, th
27340 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70  en sqlite3_uri_p
27350 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65  arameter(F,P) re
27360 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a  turns NULL and.*
27370 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  * sqlite3_uri_bo
27380 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74  olean(F,P,B) ret
27390 75 72 6e 73 20 42 2e 20 20 49 66 20 46 20 69 73  urns B.  If F is
273a0 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e   not a NULL poin
273b0 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f  ter and.** is no
273c0 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  t a database fil
273d0 65 20 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74  e pathname point
273e0 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 70  er that SQLite p
273f0 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78  assed into the x
27400 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68  Open.** VFS meth
27410 6f 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  od, then the beh
27420 61 76 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f  avior of this ro
27430 75 74 69 6e 65 20 69 73 20 75 6e 64 65 66 69 6e  utine is undefin
27440 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a  ed and probably.
27450 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a  ** undesirable..
27460 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
27470 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d  qlite3_uri_param
27480 65 74 65 72 28 63 6f 6e 73 74 20 63 68 61 72 20  eter(const char 
27490 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73  *zFilename, cons
274a0 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b  t char *zParam);
274b0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 75 72 69  .int sqlite3_uri
274c0 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 20 63  _boolean(const c
274d0 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73  har *zFile, cons
274e0 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 2c 20  t char *zParam, 
274f0 69 6e 74 20 62 44 65 66 61 75 6c 74 29 3b 0a 73  int bDefault);.s
27500 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
27510 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 63  ite3_uri_int64(c
27520 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73  onst char*, cons
27530 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33  t char*, sqlite3
27540 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a  _int64);.../*.**
27550 20 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72   CAPI3REF: Error
27560 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61   Codes And Messa
27570 67 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ges.** METHOD: s
27580 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 49 66  qlite3.**.** ^If
27590 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
275a0 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63   sqlite3_* API c
275b0 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 20 77  all associated w
275c0 69 74 68 20 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ith .** [databas
275d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20  e connection] D 
275e0 66 61 69 6c 65 64 2c 20 74 68 65 6e 20 74 68 65  failed, then the
275f0 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65   sqlite3_errcode
27600 28 44 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  (D) interface.**
27610 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
27620 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64  eric [result cod
27630 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20  e] or [extended 
27640 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72  result code] for
27650 20 74 68 61 74 0a 2a 2a 20 41 50 49 20 63 61 6c   that.** API cal
27660 6c 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6d 6f 73  l..** If the mos
27670 74 20 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c  t recent API cal
27680 6c 20 77 61 73 20 73 75 63 63 65 73 73 66 75 6c  l was successful
27690 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65  ,.** then the re
276a0 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20  turn value from 
276b0 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
276c0 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  ) is undefined..
276d0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
276e0 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
276f0 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
27700 69 73 20 74 68 65 20 73 61 6d 65 20 65 78 63 65  is the same exce
27710 70 74 20 74 68 61 74 20 69 74 20 61 6c 77 61 79  pt that it alway
27720 73 20 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a  s returns the .*
27730 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
27740 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68  lt code] even wh
27750 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  en extended resu
27760 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20  lt codes are.** 
27770 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  disabled..**.** 
27780 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72  ^The sqlite3_err
27790 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65  msg() and sqlite
277a0 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65 74  3_errmsg16() ret
277b0 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67  urn English-lang
277c0 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61  uage.** text tha
277d0 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20  t describes the 
277e0 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72  error, as either
277f0 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36   UTF-8 or UTF-16
27800 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
27810 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f  * ^(Memory to ho
27820 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  ld the error mes
27830 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d  sage string is m
27840 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c  anaged internall
27850 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  y..** The applic
27860 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e  ation does not n
27870 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f  eed to worry abo
27880 75 74 20 66 72 65 65 69 6e 67 20 74 68 65 20 72  ut freeing the r
27890 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65  esult..** Howeve
278a0 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74 72  r, the error str
278b0 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65  ing might be ove
278c0 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c  rwritten or deal
278d0 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75  located by.** su
278e0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
278f0 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  o other SQLite i
27900 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f  nterface functio
27910 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ns.)^.**.** ^The
27920 20 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28   sqlite3_errstr(
27930 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
27940 72 6e 73 20 74 68 65 20 45 6e 67 6c 69 73 68 2d  rns the English-
27950 6c 61 6e 67 75 61 67 65 20 74 65 78 74 0a 2a 2a  language text.**
27960 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20   that describes 
27970 74 68 65 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  the [result code
27980 5d 2c 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20  ], as UTF-8..** 
27990 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  ^(Memory to hold
279a0 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
279b0 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e  ge string is man
279c0 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a  aged internally.
279d0 2a 2a 20 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20  ** and must not 
279e0 62 65 20 66 72 65 65 64 20 62 79 20 74 68 65 20  be freed by the 
279f0 61 70 70 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a  application)^..*
27a00 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65  *.** When the se
27a10 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64  rialized [thread
27a20 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20  ing mode] is in 
27a30 75 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65  use, it might be
27a40 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61   the.** case tha
27a50 74 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72  t a second error
27a60 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70   occurs on a sep
27a70 61 72 61 74 65 20 74 68 72 65 61 64 20 69 6e 20  arate thread in 
27a80 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74  between.** the t
27a90 69 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73 74  ime of the first
27aa0 20 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63   error and the c
27ab0 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74  all to these int
27ac0 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e  erfaces..** When
27ad0 20 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74   that happens, t
27ae0 68 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20  he second error 
27af0 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64  will be reported
27b00 20 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20   since these.** 
27b10 69 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61 79  interfaces alway
27b20 73 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73  s report the mos
27b30 74 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e  t recent result.
27b40 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68    To avoid.** th
27b50 69 73 2c 20 65 61 63 68 20 74 68 72 65 61 64 20  is, each thread 
27b60 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75  can obtain exclu
27b70 73 69 76 65 20 75 73 65 20 6f 66 20 74 68 65 20  sive use of the 
27b80 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
27b90 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e  tion] D.** by in
27ba0 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  voking [sqlite3_
27bb0 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71  mutex_enter]([sq
27bc0 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28  lite3_db_mutex](
27bd0 44 29 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e  D)) before begin
27be0 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44  ning.** to use D
27bf0 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73   and invoking [s
27c00 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61  qlite3_mutex_lea
27c10 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f  ve]([sqlite3_db_
27c20 6d 75 74 65 78 5d 28 44 29 29 20 61 66 74 65 72  mutex](D)) after
27c30 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f  .** all calls to
27c40 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20   the interfaces 
27c50 6c 69 73 74 65 64 20 68 65 72 65 20 61 72 65 20  listed here are 
27c60 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a  completed..**.**
27c70 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65   If an interface
27c80 20 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49   fails with SQLI
27c90 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20  TE_MISUSE, that 
27ca0 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66  means the interf
27cb0 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b  ace.** was invok
27cc0 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62  ed incorrectly b
27cd0 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  y the applicatio
27ce0 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73 65  n.  In that case
27cf0 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63  , the.** error c
27d00 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20  ode and message 
27d10 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62  may or may not b
27d20 65 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71  e set..*/.int sq
27d30 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71  lite3_errcode(sq
27d40 6c 69 74 65 33 20 2a 64 62 29 3b 0a 69 6e 74 20  lite3 *db);.int 
27d50 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
27d60 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33  _errcode(sqlite3
27d70 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61   *db);.const cha
27d80 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  r *sqlite3_errms
27d90 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e  g(sqlite3*);.con
27da0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
27db0 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65  _errmsg16(sqlite
27dc0 33 2a 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  3*);.const char 
27dd0 2a 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28  *sqlite3_errstr(
27de0 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
27df0 49 33 52 45 46 3a 20 50 72 65 70 61 72 65 64 20  I3REF: Prepared 
27e00 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
27e10 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70  .** KEYWORDS: {p
27e20 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
27e30 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74 61  t} {prepared sta
27e40 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41  tements}.**.** A
27e50 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
27e60 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73  is object repres
27e70 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51  ents a single SQ
27e80 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  L statement that
27e90 0a 2a 2a 20 68 61 73 20 62 65 65 6e 20 63 6f 6d  .** has been com
27ea0 70 69 6c 65 64 20 69 6e 74 6f 20 62 69 6e 61 72  piled into binar
27eb0 79 20 66 6f 72 6d 20 61 6e 64 20 69 73 20 72 65  y form and is re
27ec0 61 64 79 20 74 6f 20 62 65 20 65 76 61 6c 75 61  ady to be evalua
27ed0 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 6b  ted..**.** Think
27ee0 20 6f 66 20 65 61 63 68 20 53 51 4c 20 73 74 61   of each SQL sta
27ef0 74 65 6d 65 6e 74 20 61 73 20 61 20 73 65 70 61  tement as a sepa
27f00 72 61 74 65 20 63 6f 6d 70 75 74 65 72 20 70 72  rate computer pr
27f10 6f 67 72 61 6d 2e 20 20 54 68 65 0a 2a 2a 20 6f  ogram.  The.** o
27f20 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74  riginal SQL text
27f30 20 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65 2e   is source code.
27f40 20 20 41 20 70 72 65 70 61 72 65 64 20 73 74 61    A prepared sta
27f50 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 0a 2a  tement object .*
27f60 2a 20 69 73 20 74 68 65 20 63 6f 6d 70 69 6c 65  * is the compile
27f70 64 20 6f 62 6a 65 63 74 20 63 6f 64 65 2e 20 20  d object code.  
27f80 41 6c 6c 20 53 51 4c 20 6d 75 73 74 20 62 65 20  All SQL must be 
27f90 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61  converted into a
27fa0 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61  .** prepared sta
27fb0 74 65 6d 65 6e 74 20 62 65 66 6f 72 65 20 69 74  tement before it
27fc0 20 63 61 6e 20 62 65 20 72 75 6e 2e 0a 2a 2a 0a   can be run..**.
27fd0 2a 2a 20 54 68 65 20 6c 69 66 65 2d 63 79 63 6c  ** The life-cycl
27fe0 65 20 6f 66 20 61 20 70 72 65 70 61 72 65 64 20  e of a prepared 
27ff0 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74  statement object
28000 20 75 73 75 61 6c 6c 79 20 67 6f 65 73 20 6c 69   usually goes li
28010 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ke this:.**.** <
28020 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61  ol>.** <li> Crea
28030 74 65 20 74 68 65 20 70 72 65 70 61 72 65 64 20  te the prepared 
28040 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74  statement object
28050 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
28060 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2e 0a 2a  prepare_v2()]..*
28070 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75  * <li> Bind valu
28080 65 73 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72  es to [parameter
28090 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  s] using the sql
280a0 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a  ite3_bind_*().**
280b0 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73        interfaces
280c0 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68  ..** <li> Run th
280d0 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67  e SQL by calling
280e0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
280f0 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69  ] one or more ti
28100 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73  mes..** <li> Res
28110 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20  et the prepared 
28120 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20  statement using 
28130 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
28140 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a  ] then go back.*
28150 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70 20 32  *      to step 2
28160 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20  .  Do this zero 
28170 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a  or more times..*
28180 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74  * <li> Destroy t
28190 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20  he object using 
281a0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
281b0 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a  e()]..** </ol>.*
281c0 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
281d0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71   sqlite3_stmt sq
281e0 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a  lite3_stmt;../*.
281f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
28200 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 20  -time Limits.** 
28210 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
28220 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74  **.** ^(This int
28230 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68  erface allows th
28240 65 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75  e size of variou
28250 73 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20  s constructs to 
28260 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e  be limited.** on
28270 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79   a connection by
28280 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69   connection basi
28290 73 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61  s.  The first pa
282a0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
282b0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
282c0 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69  ection] whose li
282d0 6d 69 74 20 69 73 20 74 6f 20 62 65 20 73 65 74  mit is to be set
282e0 20 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54 68   or queried.  Th
282f0 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61  e.** second para
28300 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20  meter is one of 
28310 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67  the [limit categ
28320 6f 72 69 65 73 5d 20 74 68 61 74 20 64 65 66 69  ories] that defi
28330 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66  ne a.** class of
28340 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62   constructs to b
28350 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20  e size limited. 
28360 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   The third param
28370 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e  eter is the.** n
28380 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61  ew limit for tha
28390 74 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a  t construct.)^.*
283a0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77  *.** ^If the new
283b0 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61   limit is a nega
283c0 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65  tive number, the
283d0 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e   limit is unchan
283e0 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61  ged..** ^(For ea
283f0 63 68 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  ch limit categor
28400 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c  y SQLITE_LIMIT_<
28410 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65  i>NAME</i> there
28420 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74   is a .** [limit
28430 73 20 7c 20 68 61 72 64 20 75 70 70 65 72 20 62  s | hard upper b
28440 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20  ound].** set at 
28450 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79 20  compile-time by 
28460 61 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  a C preprocessor
28470 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a   macro called.**
28480 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54   [limits | SQLIT
28490 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69  E_MAX_<i>NAME</i
284a0 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49  >]..** (The "_LI
284b0 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d  MIT_" in the nam
284c0 65 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20  e is changed to 
284d0 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e  "_MAX_".))^.** ^
284e0 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72  Attempts to incr
284f0 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f  ease a limit abo
28500 76 65 20 69 74 73 20 68 61 72 64 20 75 70 70 65  ve its hard uppe
28510 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73  r bound are.** s
28520 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65  ilently truncate
28530 64 20 74 6f 20 74 68 65 20 68 61 72 64 20 75 70  d to the hard up
28540 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a  per bound..**.**
28550 20 5e 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20   ^Regardless of 
28560 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
28570 68 65 20 6c 69 6d 69 74 20 77 61 73 20 63 68 61  he limit was cha
28580 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73  nged, the .** [s
28590 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20  qlite3_limit()] 
285a0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
285b0 73 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75  s the prior valu
285c0 65 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a  e of the limit..
285d0 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69  ** ^Hence, to fi
285e0 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74 20 76  nd the current v
285f0 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69 74 20  alue of a limit 
28600 77 69 74 68 6f 75 74 20 63 68 61 6e 67 69 6e 67  without changing
28610 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69   it,.** simply i
28620 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 72  nvoke this inter
28630 66 61 63 65 20 77 69 74 68 20 74 68 65 20 74 68  face with the th
28640 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 73 65  ird parameter se
28650 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52  t to -1..**.** R
28660 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61  un-time limits a
28670 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
28680 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69  use in applicati
28690 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a  ons that manage.
286a0 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77  ** both their ow
286b0 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62  n internal datab
286c0 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74  ase and also dat
286d0 61 62 61 73 65 73 20 74 68 61 74 20 61 72 65 20  abases that are 
286e0 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79  controlled.** by
286f0 20 75 6e 74 72 75 73 74 65 64 20 65 78 74 65 72   untrusted exter
28700 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e  nal sources.  An
28710 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61   example applica
28720 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a  tion might be a.
28730 2a 2a 20 77 65 62 20 62 72 6f 77 73 65 72 20 74  ** web browser t
28740 68 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20  hat has its own 
28750 64 61 74 61 62 61 73 65 73 20 66 6f 72 20 73 74  databases for st
28760 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e  oring history an
28770 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61  d.** separate da
28780 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c  tabases controll
28790 65 64 20 62 79 20 4a 61 76 61 53 63 72 69 70 74  ed by JavaScript
287a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f   applications do
287b0 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20  wnloaded.** off 
287c0 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54  the Internet.  T
287d0 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  he internal data
287e0 62 61 73 65 73 20 63 61 6e 20 62 65 20 67 69 76  bases can be giv
287f0 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c  en the.** large,
28800 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e   default limits.
28810 20 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61    Databases mana
28820 67 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20  ged by external 
28830 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62  sources can.** b
28840 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61  e given much sma
28850 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69  ller limits desi
28860 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20  gned to prevent 
28870 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76  a denial of serv
28880 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20  ice.** attack.  
28890 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74  Developers might
288a0 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73   also want to us
288b0 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  e the [sqlite3_s
288c0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d  et_authorizer()]
288d0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f  .** interface to
288e0 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c   further control
288f0 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20   untrusted SQL. 
28900 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   The size of the
28910 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65   database.** cre
28920 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75  ated by an untru
28930 73 74 65 64 20 73 63 72 69 70 74 20 63 61 6e 20  sted script can 
28940 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69  be contained usi
28950 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70  ng the.** [max_p
28960 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47  age_count] [PRAG
28970 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72  MA]..**.** New r
28980 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61  un-time limit ca
28990 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20  tegories may be 
289a0 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
289b0 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74  releases..*/.int
289c0 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73   sqlite3_limit(s
289d0 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c  qlite3*, int id,
289e0 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f   int newVal);../
289f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
28a00 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61  un-Time Limit Ca
28a10 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57  tegories.** KEYW
28a20 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74  ORDS: {limit cat
28a30 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63  egory} {*limit c
28a40 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a  ategories}.**.**
28a50 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
28a60 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20   define various 
28a70 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69  performance limi
28a80 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62  ts.** that can b
28a90 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e  e lowered at run
28aa0 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c  -time using [sql
28ab0 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a  ite3_limit()]..*
28ac0 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f  * The synopsis o
28ad0 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f  f the meanings o
28ae0 66 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69  f the various li
28af0 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65  mits is shown be
28b00 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e  low..** Addition
28b10 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  al information i
28b20 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b  s available at [
28b30 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20  limits | Limits 
28b40 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a  in SQLite]..**.*
28b50 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49  * <dl>.** [[SQLI
28b60 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d  TE_LIMIT_LENGTH]
28b70 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
28b80 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e  IMIT_LENGTH</dt>
28b90 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
28ba0 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20  mum size of any 
28bb0 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f  string or BLOB o
28bc0 72 20 74 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20  r table row, in 
28bd0 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a  bytes.<dd>)^.**.
28be0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
28bf0 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e  T_SQL_LENGTH]] ^
28c00 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
28c10 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74  T_SQL_LENGTH</dt
28c20 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
28c30 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61  imum length of a
28c40 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  n SQL statement,
28c50 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29   in bytes.</dd>)
28c60 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
28c70 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20  _LIMIT_COLUMN]] 
28c80 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
28c90 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a  IT_COLUMN</dt>.*
28ca0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
28cb0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  m number of colu
28cc0 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64  mns in a table d
28cd0 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20  efinition or in 
28ce0 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65  the.** result se
28cf0 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20  t of a [SELECT] 
28d00 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e  or the maximum n
28d10 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
28d20 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20   in an index.** 
28d30 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42  or in an ORDER B
28d40 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c  Y or GROUP BY cl
28d50 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  ause.</dd>)^.**.
28d60 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
28d70 54 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e  T_EXPR_DEPTH]] ^
28d80 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
28d90 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74  T_EXPR_DEPTH</dt
28da0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
28db0 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68  imum depth of th
28dc0 65 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20  e parse tree on 
28dd0 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c  any expression.<
28de0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
28df0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50  QLITE_LIMIT_COMP
28e00 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28  OUND_SELECT]] ^(
28e10 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
28e20 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54  _COMPOUND_SELECT
28e30 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
28e40 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
28e50 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f  of terms in a co
28e60 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74  mpound SELECT st
28e70 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a  atement.</dd>)^.
28e80 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
28e90 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e  IMIT_VDBE_OP]] ^
28ea0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
28eb0 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a  T_VDBE_OP</dt>.*
28ec0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
28ed0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74  m number of inst
28ee0 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69  ructions in a vi
28ef0 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72  rtual machine pr
28f00 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f  ogram.** used to
28f10 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51   implement an SQ
28f20 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68  L statement.  Th
28f30 69 73 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20  is limit is not 
28f40 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66  currently.** enf
28f50 6f 72 63 65 64 2c 20 74 68 6f 75 67 68 20 74 68  orced, though th
28f60 61 74 20 6d 69 67 68 74 20 62 65 20 61 64 64 65  at might be adde
28f70 64 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65  d in some future
28f80 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53   release of.** S
28f90 51 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  QLite.</dd>)^.**
28fa0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
28fb0 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d  IT_FUNCTION_ARG]
28fc0 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
28fd0 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
28fe0 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  G</dt>.** <dd>Th
28ff0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
29000 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e   of arguments on
29010 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64   a function.</dd
29020 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
29030 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45  TE_LIMIT_ATTACHE
29040 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  D]] ^(<dt>SQLITE
29050 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c  _LIMIT_ATTACHED<
29060 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
29070 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
29080 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74 74 61  f [ATTACH | atta
29090 63 68 65 64 20 64 61 74 61 62 61 73 65 73 5d 2e  ched databases].
290a0 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  )^</dd>.**.** [[
290b0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b  SQLITE_LIMIT_LIK
290c0 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48  E_PATTERN_LENGTH
290d0 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49  ]].** ^(<dt>SQLI
290e0 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41  TE_LIMIT_LIKE_PA
290f0 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74  TTERN_LENGTH</dt
29100 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
29110 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74  imum length of t
29120 68 65 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d  he pattern argum
29130 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45  ent to the [LIKE
29140 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f  ] or.** [GLOB] o
29150 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e  perators.</dd>)^
29160 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
29170 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
29180 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74  UMBER]].** ^(<dt
29190 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41  >SQLITE_LIMIT_VA
291a0 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64  RIABLE_NUMBER</d
291b0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
291c0 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62  ximum index numb
291d0 65 72 20 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d  er of any [param
291e0 65 74 65 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20  eter] in an SQL 
291f0 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a  statement.)^.**.
29200 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
29210 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 5d  T_TRIGGER_DEPTH]
29220 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
29230 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50  IMIT_TRIGGER_DEP
29240 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
29250 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68  he maximum depth
29260 20 6f 66 20 72 65 63 75 72 73 69 6f 6e 20 66 6f   of recursion fo
29270 72 20 74 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e  r triggers.</dd>
29280 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
29290 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54  E_LIMIT_WORKER_T
292a0 48 52 45 41 44 53 5d 5d 20 5e 28 3c 64 74 3e 53  HREADS]] ^(<dt>S
292b0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b  QLITE_LIMIT_WORK
292c0 45 52 5f 54 48 52 45 41 44 53 3c 2f 64 74 3e 0a  ER_THREADS</dt>.
292d0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
292e0 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 75 78  um number of aux
292f0 69 6c 69 61 72 79 20 77 6f 72 6b 65 72 20 74 68  iliary worker th
29300 72 65 61 64 73 20 74 68 61 74 20 61 20 73 69 6e  reads that a sin
29310 67 6c 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  gle.** [prepared
29320 20 73 74 61 74 65 6d 65 6e 74 5d 20 6d 61 79 20   statement] may 
29330 73 74 61 72 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  start.</dd>)^.**
29340 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
29350 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  e SQLITE_LIMIT_L
29360 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20  ENGTH           
29370 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69           0.#defi
29380 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
29390 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20  SQL_LENGTH      
293a0 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66            1.#def
293b0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
293c0 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20  _COLUMN         
293d0 20 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65             2.#de
293e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
293f0 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20 20  T_EXPR_DEPTH    
29400 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64              3.#d
29410 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
29420 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
29430 43 54 20 20 20 20 20 20 20 20 20 20 20 34 0a 23  CT           4.#
29440 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
29450 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20  MIT_VDBE_OP     
29460 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a                5.
29470 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
29480 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
29490 47 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36  G              6
294a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
294b0 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20  LIMIT_ATTACHED  
294c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
294d0 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  7.#define SQLITE
294e0 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
294f0 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20  ERN_LENGTH      
29500 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   8.#define SQLIT
29510 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
29520 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20 20  _NUMBER         
29530 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    9.#define SQLI
29540 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52  TE_LIMIT_TRIGGER
29550 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20  _DEPTH          
29560 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c    10.#define SQL
29570 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52  ITE_LIMIT_WORKER
29580 5f 54 48 52 45 41 44 53 20 20 20 20 20 20 20 20  _THREADS        
29590 20 20 20 31 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50     11../*.** CAP
295a0 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67  I3REF: Compiling
295b0 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
295c0 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  t.** KEYWORDS: {
295d0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  SQL statement co
295e0 6d 70 69 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f  mpiler}.** METHO
295f0 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 20 43 4f  D: sqlite3.** CO
29600 4e 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74  NSTRUCTOR: sqlit
29610 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 6f  e3_stmt.**.** To
29620 20 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20   execute an SQL 
29630 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66  query, it must f
29640 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64  irst be compiled
29650 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64   into a byte-cod
29660 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69  e.** program usi
29670 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  ng one of these 
29680 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
29690 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
296a0 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b  nt, "db", is a [
296b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
296c0 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72  ion] obtained fr
296d0 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75  om a.** prior su
296e0 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
296f0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
29700 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
29710 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  _v2()] or.** [sq
29720 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e  lite3_open16()].
29730 20 20 54 68 65 20 64 61 74 61 62 61 73 65 20 63    The database c
29740 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e  onnection must n
29750 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f  ot have been clo
29760 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  sed..**.** The s
29770 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20  econd argument, 
29780 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73  "zSql", is the s
29790 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63  tatement to be c
297a0 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64  ompiled, encoded
297b0 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 54  .** as either UT
297c0 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20  F-8 or UTF-16.  
297d0 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  The sqlite3_prep
297e0 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  are() and sqlite
297f0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a  3_prepare_v2().*
29800 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 65  * interfaces use
29810 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69   UTF-8, and sqli
29820 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 20  te3_prepare16() 
29830 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
29840 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73  are16_v2().** us
29850 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20  e UTF-16..**.** 
29860 5e 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72  ^If the nByte ar
29870 67 75 6d 65 6e 74 20 69 73 20 6e 65 67 61 74 69  gument is negati
29880 76 65 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73  ve, then zSql is
29890 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a   read up to the.
298a0 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65  ** first zero te
298b0 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42  rminator. ^If nB
298c0 79 74 65 20 69 73 20 70 6f 73 69 74 69 76 65 2c  yte is positive,
298d0 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 0a   then it is the.
298e0 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  ** number of byt
298f0 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71  es read from zSq
29900 6c 2e 20 20 5e 49 66 20 6e 42 79 74 65 20 69 73  l.  ^If nByte is
29910 20 7a 65 72 6f 2c 20 74 68 65 6e 20 6e 6f 20 70   zero, then no p
29920 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65  repared.** state
29930 6d 65 6e 74 20 69 73 20 67 65 6e 65 72 61 74 65  ment is generate
29940 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 61 6c  d..** If the cal
29950 6c 65 72 20 6b 6e 6f 77 73 20 74 68 61 74 20 74  ler knows that t
29960 68 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 69  he supplied stri
29970 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e  ng is nul-termin
29980 61 74 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 74 68  ated, then.** th
29990 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 20 70  ere is a small p
299a0 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e  erformance advan
299b0 74 61 67 65 20 74 6f 20 70 61 73 73 69 6e 67 20  tage to passing 
299c0 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74  an nByte paramet
299d0 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 74 68  er that.** is th
299e0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
299f0 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73  s in the input s
29a00 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69  tring <i>includi
29a10 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75  ng</i>.** the nu
29a20 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a  l-terminator..**
29a30 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69  .** ^If pzTail i
29a40 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20  s not NULL then 
29a50 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20  *pzTail is made 
29a60 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20  to point to the 
29a70 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61  first byte.** pa
29a80 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68  st the end of th
29a90 65 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74  e first SQL stat
29aa0 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20  ement in zSql.  
29ab0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  These routines o
29ac0 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74  nly.** compile t
29ad0 68 65 20 66 69 72 73 74 20 73 74 61 74 65 6d 65  he first stateme
29ae0 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a  nt in zSql, so *
29af0 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70  pzTail is left p
29b00 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68  ointing to.** wh
29b10 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d  at remains uncom
29b20 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70  piled..**.** ^*p
29b30 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f  pStmt is left po
29b40 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70  inting to a comp
29b50 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 73  iled [prepared s
29b60 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63  tatement] that c
29b70 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65  an be.** execute
29b80 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
29b90 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74  _step()].  ^If t
29ba0 68 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72  here is an error
29bb0 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74  , *ppStmt is set
29bc0 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49  .** to NULL.  ^I
29bd0 66 20 74 68 65 20 69 6e 70 75 74 20 74 65 78 74  f the input text
29be0 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c   contains no SQL
29bf0 20 28 69 66 20 74 68 65 20 69 6e 70 75 74 20 69   (if the input i
29c00 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74  s an empty.** st
29c10 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e  ring or a commen
29c20 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20  t) then *ppStmt 
29c30 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a  is set to NULL..
29c40 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70  ** The calling p
29c50 72 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 70  rocedure is resp
29c60 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65  onsible for dele
29c70 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65  ting the compile
29c80 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  d.** SQL stateme
29c90 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  nt using [sqlite
29ca0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66  3_finalize()] af
29cb0 74 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73  ter it has finis
29cc0 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20  hed with it..** 
29cd0 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62  ppStmt may not b
29ce0 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f  e NULL..**.** ^O
29cf0 6e 20 73 75 63 63 65 73 73 2c 20 74 68 65 20 73  n success, the s
29d00 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
29d10 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69   family of routi
29d20 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  nes return [SQLI
29d30 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72  TE_OK];.** other
29d40 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63  wise an [error c
29d50 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
29d60 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
29d70 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
29d80 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
29d90 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65  pare16_v2() inte
29da0 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65  rfaces are.** re
29db0 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c  commended for al
29dc0 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20  l new programs. 
29dd0 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e  The two older in
29de0 74 65 72 66 61 63 65 73 20 61 72 65 20 72 65 74  terfaces are ret
29df0 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63  ained.** for bac
29e00 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
29e10 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69 72 20  lity, but their 
29e20 75 73 65 20 69 73 20 64 69 73 63 6f 75 72 61 67  use is discourag
29e30 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22  ed..** ^In the "
29e40 76 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20  v2" interfaces, 
29e50 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
29e60 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69  tement.** that i
29e70 73 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20  s returned (the 
29e80 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f  [sqlite3_stmt] o
29e90 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20  bject) contains 
29ea0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
29eb0 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65   original SQL te
29ec0 78 74 2e 20 54 68 69 73 20 63 61 75 73 65 73 20  xt. This causes 
29ed0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
29ee0 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74  p()] interface t
29ef0 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66  o.** behave diff
29f00 65 72 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65  erently in three
29f10 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c   ways:.**.** <ol
29f20 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66  >.** <li>.** ^If
29f30 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63   the database sc
29f40 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e  hema changes, in
29f50 73 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69  stead of returni
29f60 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  ng [SQLITE_SCHEM
29f70 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61  A] as it.** alwa
29f80 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b  ys used to do, [
29f90 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
29fa0 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c  will automatical
29fb0 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65  ly recompile the
29fc0 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   SQL.** statemen
29fd0 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e  t and try to run
29fe0 20 69 74 20 61 67 61 69 6e 2e 20 41 73 20 6d 61   it again. As ma
29ff0 6e 79 20 61 73 20 5b 53 51 4c 49 54 45 5f 4d 41  ny as [SQLITE_MA
2a000 58 5f 53 43 48 45 4d 41 5f 52 45 54 52 59 5d 0a  X_SCHEMA_RETRY].
2a010 2a 2a 20 72 65 74 72 69 65 73 20 77 69 6c 6c 20  ** retries will 
2a020 6f 63 63 75 72 20 62 65 66 6f 72 65 20 73 71 6c  occur before sql
2a030 69 74 65 33 5f 73 74 65 70 28 29 20 67 69 76 65  ite3_step() give
2a040 73 20 75 70 20 61 6e 64 20 72 65 74 75 72 6e 73  s up and returns
2a050 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f   an error..** </
2a060 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a  li>.**.** <li>.*
2a070 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72  * ^When an error
2a080 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65   occurs, [sqlite
2a090 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72  3_step()] will r
2a0a0 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65  eturn one of the
2a0b0 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72   detailed.** [er
2a0c0 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65  ror codes] or [e
2a0d0 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
2a0e0 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61  des].  ^The lega
2a0f0 63 79 20 62 65 68 61 76 69 6f 72 20 77 61 73 20  cy behavior was 
2a100 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  that.** [sqlite3
2a110 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f  _step()] would o
2a120 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e  nly return a gen
2a130 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52  eric [SQLITE_ERR
2a140 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a  OR] result code.
2a150 2a 2a 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69  ** and the appli
2a160 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76  cation would hav
2a170 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f  e to make a seco
2a180 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nd call to [sqli
2a190 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20  te3_reset()].** 
2a1a0 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64  in order to find
2a1b0 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
2a1c0 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f  cause of the pro
2a1d0 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22  blem. With the "
2a1e0 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69  v2" prepare.** i
2a1f0 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 75  nterfaces, the u
2a200 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e  nderlying reason
2a210 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69   for the error i
2a220 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64  s returned immed
2a230 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e  iately..** </li>
2a240 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e  .**.** <li>.** ^
2a250 49 66 20 74 68 65 20 73 70 65 63 69 66 69 63 20  If the specific 
2a260 76 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b  value bound to [
2a270 70 61 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74  parameter | host
2a280 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74   parameter] in t
2a290 68 65 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61  he .** WHERE cla
2a2a0 75 73 65 20 6d 69 67 68 74 20 69 6e 66 6c 75 65  use might influe
2a2b0 6e 63 65 20 74 68 65 20 63 68 6f 69 63 65 20 6f  nce the choice o
2a2c0 66 20 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72  f query plan for
2a2d0 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a   a statement,.**
2a2e0 20 74 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d   then the statem
2a2f0 65 6e 74 20 77 69 6c 6c 20 62 65 20 61 75 74 6f  ent will be auto
2a300 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70  matically recomp
2a310 69 6c 65 64 2c 20 61 73 20 69 66 20 74 68 65 72  iled, as if ther
2a320 65 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61  e had been .** a
2a330 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2c 20   schema change, 
2a340 6f 6e 20 74 68 65 20 66 69 72 73 74 20 20 5b 73  on the first  [s
2a350 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63  qlite3_step()] c
2a360 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e  all following an
2a370 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74  y change.** to t
2a380 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
2a390 5f 74 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73  _text | bindings
2a3a0 5d 20 6f 66 20 74 68 61 74 20 5b 70 61 72 61 6d  ] of that [param
2a3b0 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20  eter]. .** ^The 
2a3c0 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 6f  specific value o
2a3d0 66 20 57 48 45 52 45 2d 63 6c 61 75 73 65 20 5b  f WHERE-clause [
2a3e0 70 61 72 61 6d 65 74 65 72 5d 20 6d 69 67 68 74  parameter] might
2a3f0 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 0a   influence the .
2a400 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65  ** choice of que
2a410 72 79 20 70 6c 61 6e 20 69 66 20 74 68 65 20 70  ry plan if the p
2a420 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
2a430 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f  left-hand side o
2a440 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72  f a [LIKE].** or
2a450 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72   [GLOB] operator
2a460 20 6f 72 20 69 66 20 74 68 65 20 70 61 72 61 6d   or if the param
2a470 65 74 65 72 20 69 73 20 63 6f 6d 70 61 72 65 64  eter is compared
2a480 20 74 6f 20 61 6e 20 69 6e 64 65 78 65 64 20 63   to an indexed c
2a490 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65  olumn.** and the
2a4a0 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
2a4b0 53 54 41 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74  STAT3] compile-t
2a4c0 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e  ime option is en
2a4d0 61 62 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a  abled..** </li>.
2a4e0 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20  ** </ol>.*/.int 
2a4f0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
2a500 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
2a510 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
2a520 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
2a530 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
2a540 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
2a550 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
2a560 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  -8 encoded */.  
2a570 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
2a580 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
2a590 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
2a5a0 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
2a5b0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
2a5c0 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
2a5d0 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
2a5e0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
2a5f0 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  r **pzTail     /
2a600 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
2a610 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
2a620 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
2a630 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
2a640 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  re_v2(.  sqlite3
2a650 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
2a660 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
2a670 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
2a680 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  har *zSql,      
2a690 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
2a6a0 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  t, UTF-8 encoded
2a6b0 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
2a6c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2a6d0 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
2a6e0 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
2a6f0 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
2a700 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
2a710 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
2a720 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2a730 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c  st char **pzTail
2a740 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
2a750 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
2a760 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
2a770 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
2a780 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71  _prepare16(.  sq
2a790 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
2a7a0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
2a7b0 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
2a7c0 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
2a7d0 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
2a7e0 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
2a7f0 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
2a800 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
2a810 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
2a820 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
2a830 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
2a840 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
2a850 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
2a860 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
2a870 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
2a880 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
2a890 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
2a8a0 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
2a8b0 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
2a8c0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2a8d0 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
2a8e0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
2a8f0 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
2a900 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
2a910 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  d *zSql,       /
2a920 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
2a930 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
2a940 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
2a950 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
2a960 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
2a970 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
2a980 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
2a990 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
2a9a0 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
2a9b0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
2a9c0 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20  t void **pzTail 
2a9d0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
2a9e0 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
2a9f0 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
2aa00 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
2aa10 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20  REF: Retrieving 
2aa20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a  Statement SQL.**
2aa30 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2aa40 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _stmt.**.** ^The
2aa50 20 73 71 6c 69 74 65 33 5f 73 71 6c 28 50 29 20   sqlite3_sql(P) 
2aa60 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2aa70 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
2aa80 20 63 6f 70 79 20 6f 66 20 74 68 65 20 55 54 46   copy of the UTF
2aa90 2d 38 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75  -8.** SQL text u
2aaa0 73 65 64 20 74 6f 20 63 72 65 61 74 65 20 5b 70  sed to create [p
2aab0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2aac0 74 5d 20 50 20 69 66 20 50 20 77 61 73 0a 2a 2a  t] P if P was.**
2aad0 20 63 72 65 61 74 65 64 20 62 79 20 65 69 74 68   created by eith
2aae0 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  er [sqlite3_prep
2aaf0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71  are_v2()] or [sq
2ab00 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2ab10 76 32 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73  v2()]..** ^The s
2ab20 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f  qlite3_expanded_
2ab30 73 71 6c 28 50 29 20 69 6e 74 65 72 66 61 63 65  sql(P) interface
2ab40 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
2ab50 65 72 20 74 6f 20 61 20 55 54 46 2d 38 0a 2a 2a  er to a UTF-8.**
2ab60 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69   string containi
2ab70 6e 67 20 74 68 65 20 53 51 4c 20 74 65 78 74 20  ng the SQL text 
2ab80 6f 66 20 70 72 65 70 61 72 65 64 20 73 74 61 74  of prepared stat
2ab90 65 6d 65 6e 74 20 50 20 77 69 74 68 0a 2a 2a 20  ement P with.** 
2aba0 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72  [bound parameter
2abb0 73 5d 20 65 78 70 61 6e 64 65 64 2e 0a 2a 2a 0a  s] expanded..**.
2abc0 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65  ** ^(For example
2abd0 2c 20 69 66 20 61 20 70 72 65 70 61 72 65 64 20  , if a prepared 
2abe0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 72 65  statement is cre
2abf0 61 74 65 64 20 75 73 69 6e 67 20 74 68 65 20 53  ated using the S
2ac00 51 4c 0a 2a 2a 20 74 65 78 74 20 22 53 45 4c 45  QL.** text "SELE
2ac10 43 54 20 24 61 62 63 2c 3a 78 79 7a 22 20 61 6e  CT $abc,:xyz" an
2ac20 64 20 69 66 20 70 61 72 61 6d 65 74 65 72 20 24  d if parameter $
2ac30 61 62 63 20 69 73 20 62 6f 75 6e 64 20 74 6f 20  abc is bound to 
2ac40 69 6e 74 65 67 65 72 20 32 33 34 35 0a 2a 2a 20  integer 2345.** 
2ac50 61 6e 64 20 70 61 72 61 6d 65 74 65 72 20 3a 78  and parameter :x
2ac60 79 7a 20 69 73 20 75 6e 62 6f 75 6e 64 2c 20 74  yz is unbound, t
2ac70 68 65 6e 20 73 71 6c 69 74 65 33 5f 73 71 6c 28  hen sqlite3_sql(
2ac80 29 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a  ) will return.**
2ac90 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74   the original st
2aca0 72 69 6e 67 2c 20 22 53 45 4c 45 43 54 20 24 61  ring, "SELECT $a
2acb0 62 63 2c 3a 78 79 7a 22 20 62 75 74 20 73 71 6c  bc,:xyz" but sql
2acc0 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71  ite3_expanded_sq
2acd0 6c 28 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75  l().** will retu
2ace0 72 6e 20 22 53 45 4c 45 43 54 20 32 33 34 35 2c  rn "SELECT 2345,
2acf0 4e 55 4c 4c 22 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  NULL".)^.**.** ^
2ad00 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 70 61  The sqlite3_expa
2ad10 6e 64 65 64 5f 73 71 6c 28 29 20 69 6e 74 65 72  nded_sql() inter
2ad20 66 61 63 65 20 72 65 74 75 72 6e 73 20 4e 55 4c  face returns NUL
2ad30 4c 20 69 66 20 69 6e 73 75 66 66 69 63 69 65 6e  L if insufficien
2ad40 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 69 73 20 61  t memory.** is a
2ad50 76 61 69 6c 61 62 6c 65 20 74 6f 20 68 6f 6c 64  vailable to hold
2ad60 20 74 68 65 20 72 65 73 75 6c 74 2c 20 6f 72 20   the result, or 
2ad70 69 66 20 74 68 65 20 72 65 73 75 6c 74 20 77 6f  if the result wo
2ad80 75 6c 64 20 65 78 63 65 65 64 20 74 68 65 0a 2a  uld exceed the.*
2ad90 2a 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 73 74  * the maximum st
2ada0 72 69 6e 67 20 6c 65 6e 67 74 68 20 64 65 74 65  ring length dete
2adb0 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20 5b 53  rmined by the [S
2adc0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
2add0 54 48 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  TH]..**.** ^The 
2ade0 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 49  [SQLITE_TRACE_SI
2adf0 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c  ZE_LIMIT] compil
2ae00 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 6c 69  e-time option li
2ae10 6d 69 74 73 20 74 68 65 20 73 69 7a 65 20 6f 66  mits the size of
2ae20 0a 2a 2a 20 62 6f 75 6e 64 20 70 61 72 61 6d 65  .** bound parame
2ae30 74 65 72 20 65 78 70 61 6e 73 69 6f 6e 73 2e 20  ter expansions. 
2ae40 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d   ^The [SQLITE_OM
2ae50 49 54 5f 54 52 41 43 45 5d 20 63 6f 6d 70 69 6c  IT_TRACE] compil
2ae60 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e  e-time.** option
2ae70 20 63 61 75 73 65 73 20 73 71 6c 69 74 65 33 5f   causes sqlite3_
2ae80 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 29 20 74  expanded_sql() t
2ae90 6f 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20  o always return 
2aea0 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  NULL..**.** ^The
2aeb0 20 73 74 72 69 6e 67 20 72 65 74 75 72 6e 65 64   string returned
2aec0 20 62 79 20 73 71 6c 69 74 65 33 5f 73 71 6c 28   by sqlite3_sql(
2aed0 50 29 20 69 73 20 6d 61 6e 61 67 65 64 20 62 79  P) is managed by
2aee0 20 53 51 4c 69 74 65 20 61 6e 64 20 69 73 0a 2a   SQLite and is.*
2aef0 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  * automatically 
2af00 66 72 65 65 64 20 77 68 65 6e 20 74 68 65 20 70  freed when the p
2af10 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2af20 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 2e 0a  t is finalized..
2af30 2a 2a 20 5e 54 68 65 20 73 74 72 69 6e 67 20 72  ** ^The string r
2af40 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
2af50 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28  e3_expanded_sql(
2af60 50 29 2c 20 6f 6e 20 74 68 65 20 6f 74 68 65 72  P), on the other
2af70 20 68 61 6e 64 2c 0a 2a 2a 20 69 73 20 6f 62 74   hand,.** is obt
2af80 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
2af90 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e  te3_malloc()] an
2afa0 64 20 6d 75 73 74 20 62 65 20 66 72 65 65 20 62  d must be free b
2afb0 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  y the applicatio
2afc0 6e 0a 2a 2a 20 62 79 20 70 61 73 73 69 6e 67 20  n.** by passing 
2afd0 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  it to [sqlite3_f
2afe0 72 65 65 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74  ree()]..*/.const
2aff0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73   char *sqlite3_s
2b000 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ql(sqlite3_stmt 
2b010 2a 70 53 74 6d 74 29 3b 0a 63 68 61 72 20 2a 73  *pStmt);.char *s
2b020 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f  qlite3_expanded_
2b030 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  sql(sqlite3_stmt
2b040 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
2b050 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72   CAPI3REF: Deter
2b060 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53  mine If An SQL S
2b070 74 61 74 65 6d 65 6e 74 20 57 72 69 74 65 73 20  tatement Writes 
2b080 54 68 65 20 44 61 74 61 62 61 73 65 0a 2a 2a 20  The Database.** 
2b090 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
2b0a0 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  stmt.**.** ^The 
2b0b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
2b0c0 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 66 61  donly(X) interfa
2b0d0 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20  ce returns true 
2b0e0 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a  (non-zero) if.**
2b0f0 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65   and only if the
2b100 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2b110 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f  ment] X makes no
2b120 20 64 69 72 65 63 74 20 63 68 61 6e 67 65 73 20   direct changes 
2b130 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e  to.** the conten
2b140 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  t of the databas
2b150 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  e file..**.** No
2b160 74 65 20 74 68 61 74 20 5b 61 70 70 6c 69 63 61  te that [applica
2b170 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
2b180 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a   functions] or.*
2b190 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  * [virtual table
2b1a0 73 5d 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20  s] might change 
2b1b0 74 68 65 20 64 61 74 61 62 61 73 65 20 69 6e 64  the database ind
2b1c0 69 72 65 63 74 6c 79 20 61 73 20 61 20 73 69 64  irectly as a sid
2b1d0 65 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e  e effect.  .** ^
2b1e0 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66  (For example, if
2b1f0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
2b200 64 65 66 69 6e 65 73 20 61 20 66 75 6e 63 74 69  defines a functi
2b210 6f 6e 20 22 65 76 61 6c 28 29 22 20 74 68 61 74  on "eval()" that
2b220 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69   .** calls [sqli
2b230 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 74 68 65  te3_exec()], the
2b240 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  n the following 
2b250 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 6f  SQL statement wo
2b260 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68  uld.** change th
2b270 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
2b280 74 68 72 6f 75 67 68 20 73 69 64 65 2d 65 66 66  through side-eff
2b290 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  ects:.**.** <blo
2b2a0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
2b2b0 20 20 20 20 53 45 4c 45 43 54 20 65 76 61 6c 28      SELECT eval(
2b2c0 27 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 31 27  'DELETE FROM t1'
2b2d0 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f  ) FROM t2;.** </
2b2e0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
2b2f0 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61  >.**.** But beca
2b300 75 73 65 20 74 68 65 20 5b 53 45 4c 45 43 54 5d  use the [SELECT]
2b310 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20   statement does 
2b320 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 64  not change the d
2b330 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20  atabase file.** 
2b340 64 69 72 65 63 74 6c 79 2c 20 73 71 6c 69 74 65  directly, sqlite
2b350 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
2b360 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65  ) would still re
2b370 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a  turn true.)^.**.
2b380 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20  ** ^Transaction 
2b390 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e  control statemen
2b3a0 74 73 20 73 75 63 68 20 61 73 20 5b 42 45 47 49  ts such as [BEGI
2b3b0 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52  N], [COMMIT], [R
2b3c0 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41  OLLBACK],.** [SA
2b3d0 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52  VEPOINT], and [R
2b3e0 45 4c 45 41 53 45 5d 20 63 61 75 73 65 20 73 71  ELEASE] cause sq
2b3f0 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
2b400 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20  nly() to return 
2b410 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74  true,.** since t
2b420 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68  he statements th
2b430 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20  emselves do not 
2b440 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20  actually modify 
2b450 74 68 65 20 64 61 74 61 62 61 73 65 20 62 75 74  the database but
2b460 0a 2a 2a 20 72 61 74 68 65 72 20 74 68 65 79 20  .** rather they 
2b470 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d 69  control the timi
2b480 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74 68 65 72  ng of when other
2b490 20 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69   statements modi
2b4a0 66 79 20 74 68 65 20 0a 2a 2a 20 64 61 74 61 62  fy the .** datab
2b4b0 61 73 65 2e 20 20 5e 54 68 65 20 5b 41 54 54 41  ase.  ^The [ATTA
2b4c0 43 48 5d 20 61 6e 64 20 5b 44 45 54 41 43 48 5d  CH] and [DETACH]
2b4d0 20 73 74 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f   statements also
2b4e0 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65   cause.** sqlite
2b4f0 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
2b500 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65  ) to return true
2b510 20 73 69 6e 63 65 2c 20 77 68 69 6c 65 20 74 68   since, while th
2b520 6f 73 65 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  ose statements.*
2b530 2a 20 63 68 61 6e 67 65 20 74 68 65 20 63 6f 6e  * change the con
2b540 66 69 67 75 72 61 74 69 6f 6e 20 6f 66 20 61 20  figuration of a 
2b550 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2b560 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74  ion, they do not
2b570 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65   make .** change
2b580 73 20 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74  s to the content
2b590 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
2b5a0 20 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a   files on disk..
2b5b0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
2b5c0 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c  tmt_readonly(sql
2b5d0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
2b5e0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2b5f0 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66  EF: Determine If
2b600 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
2b610 65 6d 65 6e 74 20 48 61 73 20 42 65 65 6e 20 52  ement Has Been R
2b620 65 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  eset.** METHOD: 
2b630 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2b640 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2b650 73 74 6d 74 5f 62 75 73 79 28 53 29 20 69 6e 74  stmt_busy(S) int
2b660 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
2b670 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69  rue (non-zero) i
2b680 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  f the.** [prepar
2b690 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
2b6a0 68 61 73 20 62 65 65 6e 20 73 74 65 70 70 65 64  has been stepped
2b6b0 20 61 74 20 6c 65 61 73 74 20 6f 6e 63 65 20 75   at least once u
2b6c0 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  sing .** [sqlite
2b6d0 33 5f 73 74 65 70 28 53 29 5d 20 62 75 74 20 68  3_step(S)] but h
2b6e0 61 73 20 6e 65 69 74 68 65 72 20 72 75 6e 20 74  as neither run t
2b6f0 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 28 72 65  o completion (re
2b700 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54  turned.** [SQLIT
2b710 45 5f 44 4f 4e 45 5d 20 66 72 6f 6d 20 5b 73 71  E_DONE] from [sq
2b720 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 29 20  lite3_step(S)]) 
2b730 6e 6f 72 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65  nor.** been rese
2b740 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
2b750 5f 72 65 73 65 74 28 53 29 5d 2e 20 20 5e 54 68  _reset(S)].  ^Th
2b760 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62  e sqlite3_stmt_b
2b770 75 73 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66  usy(S).** interf
2b780 61 63 65 20 72 65 74 75 72 6e 73 20 66 61 6c 73  ace returns fals
2b790 65 20 69 66 20 53 20 69 73 20 61 20 4e 55 4c 4c  e if S is a NULL
2b7a0 20 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 53 20   pointer.  If S 
2b7b0 69 73 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c  is not a .** NUL
2b7c0 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 69 73  L pointer and is
2b7d0 20 6e 6f 74 20 61 20 70 6f 69 6e 74 65 72 20 74   not a pointer t
2b7e0 6f 20 61 20 76 61 6c 69 64 20 5b 70 72 65 70 61  o a valid [prepa
2b7f0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
2b800 2a 20 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20 74  * object, then t
2b810 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
2b820 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f  ndefined and pro
2b830 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c  bably undesirabl
2b840 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  e..**.** This in
2b850 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
2b860 73 65 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69  sed in combinati
2b870 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74  on [sqlite3_next
2b880 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c  _stmt()].** to l
2b890 6f 63 61 74 65 20 61 6c 6c 20 70 72 65 70 61 72  ocate all prepar
2b8a0 65 64 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73  ed statements as
2b8b0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20  sociated with a 
2b8c0 64 61 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e  database .** con
2b8d0 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 61 72 65  nection that are
2b8e0 20 69 6e 20 6e 65 65 64 20 6f 66 20 62 65 69 6e   in need of bein
2b8f0 67 20 72 65 73 65 74 2e 20 20 54 68 69 73 20 63  g reset.  This c
2b900 61 6e 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66  an be used,.** f
2b910 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64  or example, in d
2b920 69 61 67 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e  iagnostic routin
2b930 65 73 20 74 6f 20 73 65 61 72 63 68 20 66 6f 72  es to search for
2b940 20 70 72 65 70 61 72 65 64 20 0a 2a 2a 20 73 74   prepared .** st
2b950 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72  atements that ar
2b960 65 20 68 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e  e holding a tran
2b970 73 61 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f  saction open..*/
2b980 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d  .int sqlite3_stm
2b990 74 5f 62 75 73 79 28 73 71 6c 69 74 65 33 5f 73  t_busy(sqlite3_s
2b9a0 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
2b9b0 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61  PI3REF: Dynamica
2b9c0 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65 20  lly Typed Value 
2b9d0 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52  Object.** KEYWOR
2b9e0 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73  DS: {protected s
2b9f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75  qlite3_value} {u
2ba00 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
2ba10 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20  e3_value}.**.** 
2ba20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20  SQLite uses the 
2ba30 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2ba40 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e  ject to represen
2ba50 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20  t all values.** 
2ba60 74 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72  that can be stor
2ba70 65 64 20 69 6e 20 61 20 64 61 74 61 62 61 73 65  ed in a database
2ba80 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75   table. SQLite u
2ba90 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69  ses dynamic typi
2baa0 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61  ng.** for the va
2bab0 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20  lues it stores. 
2bac0 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20   ^Values stored 
2bad0 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  in sqlite3_value
2bae0 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20   objects.** can 
2baf0 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f  be integers, flo
2bb00 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75  ating point valu
2bb10 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f  es, strings, BLO
2bb20 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a  Bs, or NULL..**.
2bb30 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61  ** An sqlite3_va
2bb40 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62  lue object may b
2bb50 65 20 65 69 74 68 65 72 20 22 70 72 6f 74 65 63  e either "protec
2bb60 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65  ted" or "unprote
2bb70 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69  cted"..** Some i
2bb80 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72  nterfaces requir
2bb90 65 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71  e a protected sq
2bba0 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74  lite3_value.  Ot
2bbb0 68 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  her interfaces.*
2bbc0 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69  * will accept ei
2bbd0 74 68 65 72 20 61 20 70 72 6f 74 65 63 74 65 64  ther a protected
2bbe0 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74   or an unprotect
2bbf0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2bc00 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72  ..** Every inter
2bc10 66 61 63 65 20 74 68 61 74 20 61 63 63 65 70 74  face that accept
2bc20 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  s sqlite3_value 
2bc30 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66  arguments specif
2bc40 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f  ies.** whether o
2bc50 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65  r not it require
2bc60 73 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71  s a protected sq
2bc70 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 54 68  lite3_value.  Th
2bc80 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61  e.** [sqlite3_va
2bc90 6c 75 65 5f 64 75 70 28 29 5d 20 69 6e 74 65 72  lue_dup()] inter
2bca0 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64  face can be used
2bcb0 20 74 6f 20 63 6f 6e 73 74 72 75 63 74 20 61 20   to construct a 
2bcc0 6e 65 77 20 0a 2a 2a 20 70 72 6f 74 65 63 74 65  new .** protecte
2bcd0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
2bce0 66 72 6f 6d 20 61 6e 20 75 6e 70 72 6f 74 65 63  from an unprotec
2bcf0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2bd00 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72  e..**.** The ter
2bd10 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22 20 61  ms "protected" a
2bd20 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22  nd "unprotected"
2bd30 20 72 65 66 65 72 20 74 6f 20 77 68 65 74 68 65   refer to whethe
2bd40 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75  r or not.** a mu
2bd50 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e  tex is held.  An
2bd60 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20   internal mutex 
2bd70 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72  is held for a pr
2bd80 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
2bd90 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
2bda0 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20  but no mutex is 
2bdb0 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72  held for an unpr
2bdc0 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
2bdd0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e  e3_value object.
2bde0 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63    If SQLite is c
2bdf0 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69  ompiled to be si
2be00 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a  ngle-threaded.**
2be10 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54   (with [SQLITE_T
2be20 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64  HREADSAFE=0] and
2be30 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74   with [sqlite3_t
2be40 68 72 65 61 64 73 61 66 65 28 29 5d 20 72 65 74  hreadsafe()] ret
2be50 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20  urning 0).** or 
2be60 69 66 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e  if SQLite is run
2be70 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63   in one of reduc
2be80 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a  ed mutex modes .
2be90 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
2bea0 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20  G_SINGLETHREAD] 
2beb0 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
2bec0 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a  G_MULTITHREAD].*
2bed0 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20  * then there is 
2bee0 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62  no distinction b
2bef0 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64  etween protected
2bf00 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64   and unprotected
2bf10 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
2bf20 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68  e objects and th
2bf30 65 79 20 63 61 6e 20 62 65 20 75 73 65 64 20 69  ey can be used i
2bf40 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20  nterchangeably. 
2bf50 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72   However,.** for
2bf60 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f   maximum code po
2bf70 72 74 61 62 69 6c 69 74 79 20 69 74 20 69 73 20  rtability it is 
2bf80 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74  recommended that
2bf90 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
2bfa0 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20   still make the 
2bfb0 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77  distinction betw
2bfc0 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e  een protected an
2bfd0 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a  d unprotected.**
2bfe0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2bff0 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e  bjects even when
2c000 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65   not strictly re
2c010 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  quired..**.** ^T
2c020 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
2c030 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61 72   objects that ar
2c040 65 20 70 61 73 73 65 64 20 61 73 20 70 61 72 61  e passed as para
2c050 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a  meters into the.
2c060 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
2c070 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f  n of [applicatio
2c080 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
2c090 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f  nctions] are pro
2c0a0 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  tected..** ^The 
2c0b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2c0c0 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79  ject returned by
2c0d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
2c0e0 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
2c0f0 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20  unprotected..** 
2c100 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  Unprotected sqli
2c110 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2c120 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73  s may only be us
2c130 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69  ed with.** [sqli
2c140 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
2c150 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2c160 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a  _bind_value()]..
2c170 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
2c180 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c  value_blob | sql
2c190 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28  ite3_value_type(
2c1a0 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20  )] family of.** 
2c1b0 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69  interfaces requi
2c1c0 72 65 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c  re protected sql
2c1d0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2c1e0 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  ts..*/.typedef s
2c1f0 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65  truct Mem sqlite
2c200 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20  3_value;../*.** 
2c210 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75  CAPI3REF: SQL Fu
2c220 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f  nction Context O
2c230 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20  bject.**.** The 
2c240 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68  context in which
2c250 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e   an SQL function
2c260 20 65 78 65 63 75 74 65 73 20 69 73 20 73 74 6f   executes is sto
2c270 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c  red in an.** sql
2c280 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a  ite3_context obj
2c290 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72  ect.  ^A pointer
2c2a0 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63   to an sqlite3_c
2c2b0 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a  ontext object.**
2c2c0 20 69 73 20 61 6c 77 61 79 73 20 66 69 72 73 74   is always first
2c2d0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61   parameter to [a
2c2e0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2c2f0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
2c300 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  ]..** The applic
2c310 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
2c320 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  L function imple
2c330 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70  mentation will p
2c340 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e  ass this.** poin
2c350 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f  ter through into
2c360 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
2c370 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20  e3_result_int | 
2c380 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29  sqlite3_result()
2c390 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61  ],.** [sqlite3_a
2c3a0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
2c3b0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73  ()], [sqlite3_us
2c3c0 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b  er_data()],.** [
2c3d0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f  sqlite3_context_
2c3e0 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73  db_handle()], [s
2c3f0 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
2c400 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72  ta()],.** and/or
2c410 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
2c420 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70  xdata()]..*/.typ
2c430 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
2c440 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69  te3_context sqli
2c450 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a  te3_context;../*
2c460 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69  .** CAPI3REF: Bi
2c470 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20  nding Values To 
2c480 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
2c490 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  nts.** KEYWORDS:
2c4a0 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
2c4b0 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  } {host paramete
2c4c0 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  rs} {host parame
2c4d0 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59  ter name}.** KEY
2c4e0 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61  WORDS: {SQL para
2c4f0 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61  meter} {SQL para
2c500 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74  meters} {paramet
2c510 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 20 4d  er binding}.** M
2c520 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
2c530 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74  tmt.**.** ^(In t
2c540 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
2c550 20 74 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b   text input to [
2c560 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2c570 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61  v2()] and its va
2c580 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72  riants,.** liter
2c590 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61  als may be repla
2c5a0 63 65 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65  ced by a [parame
2c5b0 74 65 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65  ter] that matche
2c5c0 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69  s one of followi
2c5d0 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a  ng.** templates:
2c5e0 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
2c5f0 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20  li>  ?.** <li>  
2c600 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56  ?NNN.** <li>  :V
2c610 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56  VV.** <li>  @VVV
2c620 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a  .** <li>  $VVV.*
2c630 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e  * </ul>.**.** In
2c640 20 74 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61   the templates a
2c650 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73  bove, NNN repres
2c660 65 6e 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20  ents an integer 
2c670 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20  literal,.** and 
2c680 56 56 56 20 72 65 70 72 65 73 65 6e 74 73 20 61  VVV represents a
2c690 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69  n alphanumeric i
2c6a0 64 65 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e 54  dentifier.)^  ^T
2c6b0 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65  he values of the
2c6c0 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73  se.** parameters
2c6d0 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68   (also called "h
2c6e0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61  ost parameter na
2c6f0 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72  mes" or "SQL par
2c700 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e  ameters").** can
2c710 20 62 65 20 73 65 74 20 75 73 69 6e 67 20 74 68   be set using th
2c720 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
2c730 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69  () routines defi
2c740 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20  ned here..**.** 
2c750 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
2c760 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
2c770 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
2c780 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a  ines is always.*
2c790 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  * a pointer to t
2c7a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
2c7b0 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  ] object returne
2c7c0 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74  d from.** [sqlit
2c7d0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2c7e0 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
2c7f0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63  ..**.** ^The sec
2c800 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
2c810 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  the index of the
2c820 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74   SQL parameter t
2c830 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68  o be set..** ^Th
2c840 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70  e leftmost SQL p
2c850 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20  arameter has an 
2c860 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68  index of 1.  ^Wh
2c870 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  en the same name
2c880 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74  d.** SQL paramet
2c890 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20  er is used more 
2c8a0 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e  than once, secon
2c8b0 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74  d and subsequent
2c8c0 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20  .** occurrences 
2c8d0 68 61 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e  have the same in
2c8e0 64 65 78 20 61 73 20 74 68 65 20 66 69 72 73 74  dex as the first
2c8f0 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20   occurrence..** 
2c900 5e 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e  ^The index for n
2c910 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73 20  amed parameters 
2c920 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70  can be looked up
2c930 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
2c940 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2c950 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41  meter_index()] A
2c960 50 49 20 69 66 20 64 65 73 69 72 65 64 2e 20 20  PI if desired.  
2c970 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f  ^The index.** fo
2c980 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74  r "?NNN" paramet
2c990 65 72 73 20 69 73 20 74 68 65 20 76 61 6c 75 65  ers is the value
2c9a0 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65   of NNN..** ^The
2c9b0 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20   NNN value must 
2c9c0 62 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64  be between 1 and
2c9d0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69   the [sqlite3_li
2c9e0 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65  mit()].** parame
2c9f0 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ter [SQLITE_LIMI
2ca00 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
2ca10 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75  R] (default valu
2ca20 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e  e: 999)..**.** ^
2ca30 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
2ca40 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  nt is the value 
2ca50 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70  to bind to the p
2ca60 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66  arameter..** ^If
2ca70 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
2ca80 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
2ca90 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73  bind_text() or s
2caa0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2cab0 31 36 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  16().** or sqlit
2cac0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69  e3_bind_blob() i
2cad0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
2cae0 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68   then the fourth
2caf0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73   parameter.** is
2cb00 20 69 67 6e 6f 72 65 64 20 61 6e 64 20 74 68 65   ignored and the
2cb10 20 65 6e 64 20 72 65 73 75 6c 74 20 69 73 20 74   end result is t
2cb20 68 65 20 73 61 6d 65 20 61 73 20 73 71 6c 69 74  he same as sqlit
2cb30 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a  e3_bind_null()..
2cb40 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65  **.** ^(In those
2cb50 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68   routines that h
2cb60 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 67  ave a fourth arg
2cb70 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65  ument, its value
2cb80 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   is the.** numbe
2cb90 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
2cba0 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f  e parameter.  To
2cbb0 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76   be clear: the v
2cbc0 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e  alue is the.** n
2cbd0 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65  umber of <u>byte
2cbe0 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c  s</u> in the val
2cbf0 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62  ue, not the numb
2cc00 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
2cc10 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .)^.** ^If the f
2cc20 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
2cc30 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
2cc40 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65  text() or sqlite
2cc50 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a  3_bind_text16().
2cc60 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  ** is negative, 
2cc70 74 68 65 6e 20 74 68 65 20 6c 65 6e 67 74 68 20  then the length 
2cc80 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 73  of the string is
2cc90 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
2cca0 66 20 62 79 74 65 73 20 75 70 20 74 6f 20 74 68  f bytes up to th
2ccb0 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72  e first zero ter
2ccc0 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74  minator..** If t
2ccd0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
2cce0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ter to sqlite3_b
2ccf0 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65  ind_blob() is ne
2cd00 67 61 74 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20  gative, then.** 
2cd10 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
2cd20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66  undefined..** If
2cd30 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20   a non-negative 
2cd40 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
2cd50 20 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20   is provided to 
2cd60 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2cd70 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  t().** or sqlite
2cd80 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20  3_bind_text16() 
2cd90 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  or sqlite3_bind_
2cda0 74 65 78 74 36 34 28 29 20 74 68 65 6e 0a 2a 2a  text64() then.**
2cdb0 20 74 68 61 74 20 70 61 72 61 6d 65 74 65 72 20   that parameter 
2cdc0 6d 75 73 74 20 62 65 20 74 68 65 20 62 79 74 65  must be the byte
2cdd0 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65 72 65   offset.** where
2cde0 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61   the NUL termina
2cdf0 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75 72 20  tor would occur 
2ce00 61 73 73 75 6d 69 6e 67 20 74 68 65 20 73 74 72  assuming the str
2ce10 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20  ing were NUL.** 
2ce20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20  terminated.  If 
2ce30 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65  any NUL characte
2ce40 72 73 20 6f 63 63 75 72 20 61 74 20 62 79 74 65  rs occur at byte
2ce50 20 6f 66 66 73 65 74 73 20 6c 65 73 73 20 74 68   offsets less th
2ce60 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65  an .** the value
2ce70 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   of the fourth p
2ce80 61 72 61 6d 65 74 65 72 20 74 68 65 6e 20 74 68  arameter then th
2ce90 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69  e resulting stri
2cea0 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a  ng value will.**
2ceb0 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65   contain embedde
2cec0 64 20 4e 55 4c 73 2e 20 20 54 68 65 20 72 65 73  d NULs.  The res
2ced0 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f  ult of expressio
2cee0 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72  ns involving str
2cef0 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62  ings.** with emb
2cf00 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e  edded NULs is un
2cf10 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
2cf20 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  The fifth argume
2cf30 6e 74 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 61  nt to the BLOB a
2cf40 6e 64 20 73 74 72 69 6e 67 20 62 69 6e 64 69 6e  nd string bindin
2cf50 67 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  g interfaces.** 
2cf60 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  is a destructor 
2cf70 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20  used to dispose 
2cf80 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a  of the BLOB or.*
2cf90 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72 20 53  * string after S
2cfa0 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73 68  QLite has finish
2cfb0 65 64 20 77 69 74 68 20 69 74 2e 20 20 5e 54 68  ed with it.  ^Th
2cfc0 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20  e destructor is 
2cfd0 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73  called.** to dis
2cfe0 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42  pose of the BLOB
2cff0 20 6f 72 20 73 74 72 69 6e 67 20 65 76 65 6e 20   or string even 
2d000 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 62  if the call to b
2d010 69 6e 64 20 41 50 49 20 66 61 69 6c 73 2e 0a 2a  ind API fails..*
2d020 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20  * ^If the fifth 
2d030 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74  argument is.** t
2d040 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65  he special value
2d050 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d   [SQLITE_STATIC]
2d060 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73  , then SQLite as
2d070 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a  sumes that the.*
2d080 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  * information is
2d090 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61   in static, unma
2d0a0 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e 64 20  naged space and 
2d0b0 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
2d0c0 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49   be freed..** ^I
2d0d0 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75  f the fifth argu
2d0e0 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c  ment has the val
2d0f0 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53  ue [SQLITE_TRANS
2d100 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53  IENT], then.** S
2d110 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20  QLite makes its 
2d120 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79  own private copy
2d130 20 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d   of the data imm
2d140 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65  ediately, before
2d150 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f  .** the sqlite3_
2d160 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
2d170 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
2d180 5e 54 68 65 20 73 69 78 74 68 20 61 72 67 75 6d  ^The sixth argum
2d190 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ent to sqlite3_b
2d1a0 69 6e 64 5f 74 65 78 74 36 34 28 29 20 6d 75 73  ind_text64() mus
2d1b0 74 20 62 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 5b  t be one of.** [
2d1c0 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53  SQLITE_UTF8], [S
2d1d0 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 5b 53  QLITE_UTF16], [S
2d1e0 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20  QLITE_UTF16BE], 
2d1f0 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  or [SQLITE_UTF16
2d200 4c 45 5d 0a 2a 2a 20 74 6f 20 73 70 65 63 69 66  LE].** to specif
2d210 79 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f  y the encoding o
2d220 66 20 74 68 65 20 74 65 78 74 20 69 6e 20 74 68  f the text in th
2d230 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
2d240 72 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20 73 69  r.  If.** the si
2d250 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  xth argument to 
2d260 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2d270 74 36 34 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65  t64() is not one
2d280 20 6f 66 20 74 68 65 0a 2a 2a 20 61 6c 6c 6f 77   of the.** allow
2d290 65 64 20 76 61 6c 75 65 73 20 73 68 6f 77 6e 20  ed values shown 
2d2a0 61 62 6f 76 65 2c 20 6f 72 20 69 66 20 74 68 65  above, or if the
2d2b0 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 69   text encoding i
2d2c0 73 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20 66  s different.** f
2d2d0 72 6f 6d 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  rom the encoding
2d2e0 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
2d2f0 65 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65  e sixth paramete
2d300 72 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  r, then the beha
2d310 76 69 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65 66  vior.** is undef
2d320 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ined..**.** ^The
2d330 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65   sqlite3_bind_ze
2d340 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65  roblob() routine
2d350 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66   binds a BLOB of
2d360 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a   length N that.*
2d370 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68  * is filled with
2d380 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72   zeroes.  ^A zer
2d390 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78  oblob uses a fix
2d3a0 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d  ed amount of mem
2d3b0 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20  ory.** (just an 
2d3c0 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20  integer to hold 
2d3d0 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20  its size) while 
2d3e0 69 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63  it is being proc
2d3f0 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c  essed..** Zerobl
2d400 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64  obs are intended
2d410 20 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61   to serve as pla
2d420 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c  ceholders for BL
2d430 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e  OBs whose.** con
2d440 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72  tent is later wr
2d450 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b  itten using.** [
2d460 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
2d470 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20  n | incremental 
2d480 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e  BLOB I/O] routin
2d490 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69  es..** ^A negati
2d4a0 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65  ve value for the
2d4b0 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74   zeroblob result
2d4c0 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67  s in a zero-leng
2d4d0 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e  th BLOB..**.** ^
2d4e0 49 66 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71  If any of the sq
2d4f0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
2d500 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
2d510 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70  ed with a NULL p
2d520 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68  ointer.** for th
2d530 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2d540 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61  ement] or with a
2d550 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2d560 65 6e 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a  ent for which.**
2d570 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2d580 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65  ] has been calle
2d590 64 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20  d more recently 
2d5a0 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65  than [sqlite3_re
2d5b0 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20  set()],.** then 
2d5c0 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65  the call will re
2d5d0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53  turn [SQLITE_MIS
2d5e0 55 53 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71  USE].  If any sq
2d5f0 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a  lite3_bind_().**
2d600 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73   routine is pass
2d610 65 64 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  ed a [prepared s
2d620 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68  tatement] that h
2d630 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65  as been finalize
2d640 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  d, the.** result
2d650 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
2d660 64 20 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66  d probably harmf
2d670 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69  ul..**.** ^Bindi
2d680 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61  ngs are not clea
2d690 72 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  red by the [sqli
2d6a0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75  te3_reset()] rou
2d6b0 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e  tine..** ^Unboun
2d6c0 64 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  d parameters are
2d6d0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
2d6e0 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  NULL..**.** ^The
2d6f0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20   sqlite3_bind_* 
2d700 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
2d710 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73  [SQLITE_OK] on s
2d720 75 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20  uccess or an.** 
2d730 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20  [error code] if 
2d740 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72  anything goes wr
2d750 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ong..** ^[SQLITE
2d760 5f 54 4f 4f 42 49 47 5d 20 6d 69 67 68 74 20 62  _TOOBIG] might b
2d770 65 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68  e returned if th
2d780 65 20 73 69 7a 65 20 6f 66 20 61 20 73 74 72 69  e size of a stri
2d790 6e 67 20 6f 72 20 42 4c 4f 42 0a 2a 2a 20 65 78  ng or BLOB.** ex
2d7a0 63 65 65 64 73 20 6c 69 6d 69 74 73 20 69 6d 70  ceeds limits imp
2d7b0 6f 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  osed by [sqlite3
2d7c0 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f  _limit]([SQLITE_
2d7d0 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 29 20 6f  LIMIT_LENGTH]) o
2d7e0 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58  r.** [SQLITE_MAX
2d7f0 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 20 5e 5b 53  _LENGTH]..** ^[S
2d800 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20  QLITE_RANGE] is 
2d810 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20  returned if the 
2d820 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64  parameter.** ind
2d830 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e  ex is out of ran
2d840 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f  ge.  ^[SQLITE_NO
2d850 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64  MEM] is returned
2d860 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69   if malloc() fai
2d870 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ls..**.** See al
2d880 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
2d890 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
2d8a0 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  t()],.** [sqlite
2d8b0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2d8c0 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73  _name()], and [s
2d8d0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2d8e0 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
2d8f0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
2d900 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  ind_blob(sqlite3
2d910 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
2d920 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c  st void*, int n,
2d930 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
2d940 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
2d950 6e 64 5f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65  nd_blob64(sqlite
2d960 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
2d970 6e 73 74 20 76 6f 69 64 2a 2c 20 73 71 6c 69 74  nst void*, sqlit
2d980 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20  e3_uint64,.     
2d990 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2d9a0 20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a     void(*)(void*
2d9b0 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  ));.int sqlite3_
2d9c0 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69  bind_double(sqli
2d9d0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
2d9e0 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c  double);.int sql
2d9f0 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71  ite3_bind_int(sq
2da00 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2da10 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69  , int);.int sqli
2da20 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73  te3_bind_int64(s
2da30 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2da40 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
2da50 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
2da60 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33  ind_null(sqlite3
2da70 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e  _stmt*, int);.in
2da80 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  t sqlite3_bind_t
2da90 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ext(sqlite3_stmt
2daa0 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72  *,int,const char
2dab0 2a 2c 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f  *,int,void(*)(vo
2dac0 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74  id*));.int sqlit
2dad0 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73  e3_bind_text16(s
2dae0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2daf0 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  t, const void*, 
2db00 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
2db10 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
2db20 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 73 71  3_bind_text64(sq
2db30 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2db40 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73  , const char*, s
2db50 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20  qlite3_uint64,. 
2db60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2db70 20 20 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28          void(*)(
2db80 76 6f 69 64 2a 29 2c 20 75 6e 73 69 67 6e 65 64  void*), unsigned
2db90 20 63 68 61 72 20 65 6e 63 6f 64 69 6e 67 29 3b   char encoding);
2dba0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
2dbb0 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  d_value(sqlite3_
2dbc0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
2dbd0 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t sqlite3_value*
2dbe0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
2dbf0 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c  ind_zeroblob(sql
2dc00 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
2dc10 20 69 6e 74 20 6e 29 3b 0a 69 6e 74 20 73 71 6c   int n);.int sql
2dc20 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c  ite3_bind_zerobl
2dc30 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  ob64(sqlite3_stm
2dc40 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33  t*, int, sqlite3
2dc50 5f 75 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a  _uint64);../*.**
2dc60 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
2dc70 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74  r Of SQL Paramet
2dc80 65 72 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ers.** METHOD: s
2dc90 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
2dca0 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
2dcb0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66  can be used to f
2dcc0 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ind the number o
2dcd0 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  f [SQL parameter
2dce0 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70  s].** in a [prep
2dcf0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
2dd00 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73    SQL parameters
2dd10 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74   are tokens of t
2dd20 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20  he.** form "?", 
2dd30 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20  "?NNN", ":AAA", 
2dd40 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41  "$AAA", or "@AAA
2dd50 22 20 74 68 61 74 20 73 65 72 76 65 20 61 73 0a  " that serve as.
2dd60 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20  ** placeholders 
2dd70 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74 20  for values that 
2dd80 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  are [sqlite3_bin
2dd90 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a  d_blob | bound].
2dda0 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65  ** to the parame
2ddb0 74 65 72 73 20 61 74 20 61 20 6c 61 74 65 72 20  ters at a later 
2ddc0 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  time..**.** ^(Th
2ddd0 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61  is routine actua
2dde0 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 20  lly returns the 
2ddf0 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72  index of the lar
2de00 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29  gest (rightmost)
2de10 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46  .** parameter. F
2de20 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63  or all forms exc
2de30 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77  ept ?NNN, this w
2de40 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74  ill correspond t
2de50 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  o the.** number 
2de60 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65  of unique parame
2de70 74 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65  ters.  If parame
2de80 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e  ters of the ?NNN
2de90 20 66 6f 72 6d 20 61 72 65 20 75 73 65 64 2c 0a   form are used,.
2dea0 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65 20  ** there may be 
2deb0 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74  gaps in the list
2dec0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  .)^.**.** See al
2ded0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
2dee0 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
2def0 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
2df00 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2df10 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a  er_name()], and.
2df20 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
2df30 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
2df40 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
2df50 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2df60 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  er_count(sqlite3
2df70 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
2df80 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f  CAPI3REF: Name O
2df90 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74  f A Host Paramet
2dfa0 65 72 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  er.** METHOD: sq
2dfb0 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
2dfc0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69   ^The sqlite3_bi
2dfd0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
2dfe0 65 28 50 2c 4e 29 20 69 6e 74 65 72 66 61 63 65  e(P,N) interface
2dff0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20   returns.** the 
2e000 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74 68  name of the N-th
2e010 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d   [SQL parameter]
2e020 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65   in the [prepare
2e030 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a  d statement] P..
2e040 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d 65 74  ** ^(SQL paramet
2e050 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  ers of the form 
2e060 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22  "?NNN" or ":AAA"
2e070 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24   or "@AAA" or "$
2e080 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e  AAA".** have a n
2e090 61 6d 65 20 77 68 69 63 68 20 69 73 20 74 68 65  ame which is the
2e0a0 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f   string "?NNN" o
2e0b0 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41  r ":AAA" or "@AA
2e0c0 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20  A" or "$AAA".** 
2e0d0 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
2e0e0 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
2e0f0 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22   the initial ":"
2e100 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f   or "$" or "@" o
2e110 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c  r "?".** is incl
2e120 75 64 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  uded as part of 
2e130 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e  the name.)^.** ^
2e140 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  Parameters of th
2e150 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f  e form "?" witho
2e160 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69  ut a following i
2e170 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e  nteger have no n
2e180 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72  ame.** and are r
2e190 65 66 65 72 72 65 64 20 74 6f 20 61 73 20 22 6e  eferred to as "n
2e1a0 61 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f  ameless" or "ano
2e1b0 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72  nymous parameter
2e1c0 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  s"..**.** ^The f
2e1d0 69 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65  irst host parame
2e1e0 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78  ter has an index
2e1f0 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a   of 1, not 0..**
2e200 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75  .** ^If the valu
2e210 65 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61  e N is out of ra
2e220 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20 4e 2d  nge or if the N-
2e230 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a  th parameter is.
2e240 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65  ** nameless, the
2e250 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e  n NULL is return
2e260 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e  ed.  ^The return
2e270 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20  ed string is.** 
2e280 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20  always in UTF-8 
2e290 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66  encoding even if
2e2a0 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d   the named param
2e2b0 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67  eter was.** orig
2e2c0 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64  inally specified
2e2d0 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73   as UTF-16 in [s
2e2e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2e2f0 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
2e300 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2e310 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  )]..**.** See al
2e320 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
2e330 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
2e340 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
2e350 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2e360 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64  er_count()], and
2e370 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
2e380 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
2e390 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  x()]..*/.const c
2e3a0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e  har *sqlite3_bin
2e3b0 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
2e3c0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2e3d0 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
2e3e0 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20  I3REF: Index Of 
2e3f0 41 20 50 61 72 61 6d 65 74 65 72 20 57 69 74 68  A Parameter With
2e400 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a   A Given Name.**
2e410 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2e420 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74  _stmt.**.** ^Ret
2e430 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66  urn the index of
2e440 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65   an SQL paramete
2e450 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65  r given its name
2e460 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78  .  ^The.** index
2e470 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
2e480 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20  is suitable for 
2e490 75 73 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e  use as the secon
2e4a0 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74  d.** parameter t
2e4b0 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  o [sqlite3_bind_
2e4c0 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
2e4d0 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a  d()].  ^A zero.*
2e4e0 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  * is returned if
2e4f0 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72   no matching par
2e500 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e  ameter is found.
2e510 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72    ^The parameter
2e520 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65  .** name must be
2e530 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20   given in UTF-8 
2e540 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67  even if the orig
2e550 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a  inal statement.*
2e560 2a 20 77 61 73 20 70 72 65 70 61 72 65 64 20 66  * was prepared f
2e570 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20  rom UTF-16 text 
2e580 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  using [sqlite3_p
2e590 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a  repare16_v2()]..
2e5a0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
2e5b0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
2e5c0 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
2e5d0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
2e5e0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
2e5f0 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  ount()], and.** 
2e600 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2e610 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2e  rameter_name()].
2e620 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2e630 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
2e640 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d  ndex(sqlite3_stm
2e650 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  t*, const char *
2e660 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  zName);../*.** C
2e670 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41  API3REF: Reset A
2e680 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41  ll Bindings On A
2e690 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
2e6a0 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ent.** METHOD: s
2e6b0 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
2e6c0 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74  * ^Contrary to t
2e6d0 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20  he intuition of 
2e6e0 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72  many, [sqlite3_r
2e6f0 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74  eset()] does not
2e700 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73   reset.** the [s
2e710 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2e720 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20   | bindings] on 
2e730 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2e740 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20  ement]..** ^Use 
2e750 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20  this routine to 
2e760 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70  reset all host p
2e770 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c  arameters to NUL
2e780 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  L..*/.int sqlite
2e790 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73  3_clear_bindings
2e7a0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
2e7b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2e7c0 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75  : Number Of Colu
2e7d0 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20  mns In A Result 
2e7e0 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  Set.** METHOD: s
2e7f0 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
2e800 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 6e 75  * ^Return the nu
2e810 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
2e820 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  in the result se
2e830 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  t returned by th
2e840 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
2e850 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 73  tatement]. ^This
2e860 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
2e870 20 30 20 69 66 20 70 53 74 6d 74 20 69 73 20 61   0 if pStmt is a
2e880 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65  n SQL.** stateme
2e890 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74  nt that does not
2e8a0 20 72 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f   return data (fo
2e8b0 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50  r example an [UP
2e8c0 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65  DATE])..**.** Se
2e8d0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
2e8e0 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a  _data_count()].*
2e8f0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  /.int sqlite3_co
2e900 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74  lumn_count(sqlit
2e910 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
2e920 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2e930 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49  : Column Names I
2e940 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a  n A Result Set.*
2e950 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2e960 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  3_stmt.**.** ^Th
2e970 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
2e980 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73  urn the name ass
2e990 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69  igned to a parti
2e9a0 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  cular column.** 
2e9b0 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  in the result se
2e9c0 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20  t of a [SELECT] 
2e9d0 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65  statement.  ^The
2e9e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2e9f0 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66  name().** interf
2ea00 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
2ea10 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d  inter to a zero-
2ea20 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
2ea30 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73   string.** and s
2ea40 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
2ea50 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73 20 61  me16() returns a
2ea60 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65   pointer to a ze
2ea70 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
2ea80 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20   UTF-16 string. 
2ea90 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61   ^The first para
2eaa0 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 70 72  meter is the [pr
2eab0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2eac0 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d  ].** that implem
2ead0 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43 54  ents the [SELECT
2eae0 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68  ] statement. ^Th
2eaf0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
2eb00 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c  er is the.** col
2eb10 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68  umn number.  ^Th
2eb20 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d  e leftmost colum
2eb30 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a  n is number 0..*
2eb40 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e  *.** ^The return
2eb50 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65  ed string pointe
2eb60 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c  r is valid until
2eb70 20 65 69 74 68 65 72 20 74 68 65 20 5b 70 72 65   either the [pre
2eb80 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2eb90 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64  .** is destroyed
2eba0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   by [sqlite3_fin
2ebb0 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69  alize()] or unti
2ebc0 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  l the statement 
2ebd0 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  is automatically
2ebe0 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62  .** reprepared b
2ebf0 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c  y the first call
2ec00 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
2ec10 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69  p()] for a parti
2ec20 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20  cular run.** or 
2ec30 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63  until the next c
2ec40 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  all to.** sqlite
2ec50 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20  3_column_name() 
2ec60 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
2ec70 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68  n_name16() on th
2ec80 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a  e same column..*
2ec90 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  *.** ^If sqlite3
2eca0 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20  _malloc() fails 
2ecb0 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65  during the proce
2ecc0 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20  ssing of either 
2ecd0 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20  routine.** (for 
2ece0 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61  example during a
2ecf0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d   conversion from
2ed00 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36   UTF-8 to UTF-16
2ed10 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c  ) then a.** NULL
2ed20 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75   pointer is retu
2ed30 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rned..**.** ^The
2ed40 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c   name of a resul
2ed50 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20  t column is the 
2ed60 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53  value of the "AS
2ed70 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20  " clause for.** 
2ed80 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20  that column, if 
2ed90 74 68 65 72 65 20 69 73 20 61 6e 20 41 53 20 63  there is an AS c
2eda0 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65 72 65  lause.  If there
2edb0 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65   is no AS clause
2edc0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d  .** then the nam
2edd0 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  e of the column 
2ede0 69 73 20 75 6e 73 70 65 63 69 66 69 65 64 20 61  is unspecified a
2edf0 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72  nd may change fr
2ee00 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73  om.** one releas
2ee10 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74  e of SQLite to t
2ee20 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f 6e 73  he next..*/.cons
2ee30 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
2ee40 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69  column_name(sqli
2ee50 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e  te3_stmt*, int N
2ee60 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
2ee70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
2ee80 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
2ee90 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a  t*, int N);../*.
2eea0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75  ** CAPI3REF: Sou
2eeb0 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41  rce Of Data In A
2eec0 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a   Query Result.**
2eed0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2eee0 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _stmt.**.** ^The
2eef0 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76  se routines prov
2ef00 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64  ide a means to d
2ef10 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74  etermine the dat
2ef20 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e  abase, table, an
2ef30 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d  d.** table colum
2ef40 6e 20 74 68 61 74 20 69 73 20 74 68 65 20 6f 72  n that is the or
2ef50 69 67 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63  igin of a partic
2ef60 75 6c 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75  ular result colu
2ef70 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54  mn in.** [SELECT
2ef80 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20  ] statement..** 
2ef90 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65  ^The name of the
2efa0 20 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 62   database or tab
2efb0 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e  le or column can
2efc0 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a   be returned as.
2efd0 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 2d  ** either a UTF-
2efe0 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69  8 or UTF-16 stri
2eff0 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62  ng.  ^The _datab
2f000 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  ase_ routines re
2f010 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61  turn.** the data
2f020 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f  base name, the _
2f030 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20  table_ routines 
2f040 72 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65  return the table
2f050 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68   name, and.** th
2f060 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e  e origin_ routin
2f070 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f  es return the co
2f080 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54  lumn name..** ^T
2f090 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
2f0a0 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69  ng is valid unti
2f0b0 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  l the [prepared 
2f0c0 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65  statement] is de
2f0d0 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67  stroyed.** using
2f0e0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2f0f0 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74  ze()] or until t
2f100 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
2f110 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a  automatically.**
2f120 20 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74   reprepared by t
2f130 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f  he first call to
2f140 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2f150 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  ] for a particul
2f160 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74  ar run.** or unt
2f170 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f  il the same info
2f180 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65  rmation is reque
2f190 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e  sted.** again in
2f1a0 20 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63   a different enc
2f1b0 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  oding..**.** ^Th
2f1c0 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64  e names returned
2f1d0 20 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61   are the origina
2f1e0 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d  l un-aliased nam
2f1f0 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74  es of the.** dat
2f200 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e  abase, table, an
2f210 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20  d column..**.** 
2f220 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
2f230 65 6e 74 20 74 6f 20 74 68 65 73 65 20 69 6e 74  ent to these int
2f240 65 72 66 61 63 65 73 20 69 73 20 61 20 5b 70 72  erfaces is a [pr
2f250 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2f260 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e  ]..** ^These fun
2f270 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e  ctions return in
2f280 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
2f290 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63  the Nth result c
2f2a0 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62  olumn returned b
2f2b0 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65  y.** the stateme
2f2c0 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  nt, where N is t
2f2d0 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69  he second functi
2f2e0 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  on argument..** 
2f2f0 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63  ^The left-most c
2f300 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20  olumn is column 
2f310 30 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74  0 for these rout
2f320 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ines..**.** ^If 
2f330 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72  the Nth column r
2f340 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 73  eturned by the s
2f350 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65  tatement is an e
2f360 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20  xpression or.** 
2f370 73 75 62 71 75 65 72 79 20 61 6e 64 20 69 73 20  subquery and is 
2f380 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c  not a column val
2f390 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20  ue, then all of 
2f3a0 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  these functions 
2f3b0 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20  return.** NULL. 
2f3c0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20   ^These routine 
2f3d0 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72  might also retur
2f3e0 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f  n NULL if a memo
2f3f0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
2f400 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20  ror.** occurs.  
2f410 5e 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 79  ^Otherwise, they
2f420 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65   return the name
2f430 20 6f 66 20 74 68 65 20 61 74 74 61 63 68 65 64   of the attached
2f440 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65   database, table
2f450 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74  ,.** or column t
2f460 68 61 74 20 71 75 65 72 79 20 72 65 73 75 6c 74  hat query result
2f470 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72   column was extr
2f480 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a  acted from..**.*
2f490 2a 20 5e 41 73 20 77 69 74 68 20 61 6c 6c 20 6f  * ^As with all o
2f4a0 74 68 65 72 20 53 51 4c 69 74 65 20 41 50 49 73  ther SQLite APIs
2f4b0 2c 20 74 68 6f 73 65 20 77 68 6f 73 65 20 6e 61  , those whose na
2f4c0 6d 65 73 20 65 6e 64 20 77 69 74 68 20 22 31 36  mes end with "16
2f4d0 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d  " return.** UTF-
2f4e0 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e  16 encoded strin
2f4f0 67 73 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72  gs and the other
2f500 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
2f510 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e  n UTF-8..**.** ^
2f520 54 68 65 73 65 20 41 50 49 73 20 61 72 65 20 6f  These APIs are o
2f530 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
2f540 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73   the library was
2f550 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
2f560 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e  he.** [SQLITE_EN
2f570 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41  ABLE_COLUMN_META
2f580 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65  DATA] C-preproce
2f590 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a  ssor symbol..**.
2f5a0 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72  ** If two or mor
2f5b0 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f  e threads call o
2f5c0 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68  ne or more of th
2f5d0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61  ese routines aga
2f5e0 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a  inst the same.**
2f5f0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2f600 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61  ent and column a
2f610 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
2f620 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
2f630 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65   are.** undefine
2f640 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20  d..**.** If two 
2f650 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  or more threads 
2f660 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  call one or more
2f670 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
2f680 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
2f690 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64  e | column metad
2f6a0 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a  ata interfaces].
2f6b0 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  ** for the same 
2f6c0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2f6d0 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20  ent] and result 
2f6e0 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65  column.** at the
2f6f0 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20   same time then 
2f700 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
2f710 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f  undefined..*/.co
2f720 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
2f730 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
2f740 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  e_name(sqlite3_s
2f750 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
2f760 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
2f770 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
2f780 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
2f790 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
2f7a0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
2f7b0 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28  lumn_table_name(
2f7c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2f7d0 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  t);.const void *
2f7e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2f7f0 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69  able_name16(sqli
2f800 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2f810 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
2f820 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
2f830 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  n_name(sqlite3_s
2f840 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
2f850 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
2f860 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d  olumn_origin_nam
2f870 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
2f880 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  *,int);../*.** C
2f890 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65  API3REF: Declare
2f8a0 64 20 44 61 74 61 74 79 70 65 20 4f 66 20 41 20  d Datatype Of A 
2f8b0 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 20  Query Result.** 
2f8c0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
2f8d0 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  stmt.**.** ^(The
2f8e0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
2f8f0 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20   is a [prepared 
2f900 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49  statement]..** I
2f910 66 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74  f this statement
2f920 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73   is a [SELECT] s
2f930 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65  tatement and the
2f940 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74   Nth column of t
2f950 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72  he.** returned r
2f960 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61  esult set of tha
2f970 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20  t [SELECT] is a 
2f980 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f  table column (no
2f990 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69  t an.** expressi
2f9a0 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29 20  on or subquery) 
2f9b0 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65  then the declare
2f9c0 64 20 74 79 70 65 20 6f 66 20 74 68 65 20 74 61  d type of the ta
2f9d0 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73  ble.** column is
2f9e0 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49   returned.)^  ^I
2f9f0 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
2fa00 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
2fa10 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72  et is an.** expr
2fa20 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65  ession or subque
2fa30 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20  ry, then a NULL 
2fa40 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72  pointer is retur
2fa50 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74  ned..** ^The ret
2fa60 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20  urned string is 
2fa70 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63  always UTF-8 enc
2fa80 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f  oded..**.** ^(Fo
2fa90 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e  r example, given
2faa0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63   the database sc
2fab0 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41  hema:.**.** CREA
2fac0 54 45 20 54 41 42 4c 45 20 74 31 28 63 31 20 56  TE TABLE t1(c1 V
2fad0 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61  ARIANT);.**.** a
2fae0 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  nd the following
2faf0 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65   statement to be
2fb00 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a   compiled:.**.**
2fb10 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20   SELECT c1 + 1, 
2fb20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a  c1 FROM t1;.**.*
2fb30 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  * this routine w
2fb40 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20  ould return the 
2fb50 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22  string "VARIANT"
2fb60 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20   for the second 
2fb70 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e  result.** column
2fb80 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e   (i==1), and a N
2fb90 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20  ULL pointer for 
2fba0 74 68 65 20 66 69 72 73 74 20 72 65 73 75 6c 74  the first result
2fbb0 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29   column (i==0).)
2fbc0 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ^.**.** ^SQLite 
2fbd0 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e  uses dynamic run
2fbe0 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e  -time typing.  ^
2fbf0 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65 20  So just because 
2fc00 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64  a column.** is d
2fc10 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61  eclared to conta
2fc20 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  in a particular 
2fc30 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65  type does not me
2fc40 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64  an that the.** d
2fc50 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68  ata stored in th
2fc60 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20  at column is of 
2fc70 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70  the declared typ
2fc80 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a  e.  SQLite is.**
2fc90 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c   strongly typed,
2fca0 20 62 75 74 20 74 68 65 20 74 79 70 69 6e 67 20   but the typing 
2fcb0 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73  is dynamic not s
2fcc0 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a  tatic.  ^Type.**
2fcd0 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77   is associated w
2fce0 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76  ith individual v
2fcf0 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20  alues, not with 
2fd00 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a  the containers.*
2fd10 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74  * used to hold t
2fd20 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a  hose values..*/.
2fd30 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
2fd40 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74  te3_column_declt
2fd50 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ype(sqlite3_stmt
2fd60 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
2fd70 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
2fd80 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71  mn_decltype16(sq
2fd90 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
2fda0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2fdb0 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53  F: Evaluate An S
2fdc0 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  QL Statement.** 
2fdd0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
2fde0 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72  stmt.**.** After
2fdf0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2fe00 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e  tement] has been
2fe10 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20   prepared using 
2fe20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74  either.** [sqlit
2fe30 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2fe40 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
2fe50 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20  pare16_v2()] or 
2fe60 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63  one of the legac
2fe70 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  y.** interfaces 
2fe80 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2fe90 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2fea0 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68  prepare16()], th
2feb0 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d  is function.** m
2fec0 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e  ust be called on
2fed0 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20  e or more times 
2fee0 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65 20  to evaluate the 
2fef0 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a  statement..**.**
2ff00 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20   The details of 
2ff10 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
2ff20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70  the sqlite3_step
2ff30 28 29 20 69 6e 74 65 72 66 61 63 65 20 64 65 70  () interface dep
2ff40 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65  end.** on whethe
2ff50 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  r the statement 
2ff60 77 61 73 20 70 72 65 70 61 72 65 64 20 75 73 69  was prepared usi
2ff70 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22 76 32  ng the newer "v2
2ff80 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b  " interface.** [
2ff90 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2ffa0 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
2ffb0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2ffc0 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20  )] or the older 
2ffd0 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
2ffe0 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ace [sqlite3_pre
2fff0 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  pare()] and [sql
30000 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
30010 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74  ].  The use of t
30020 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69  he.** new "v2" i
30030 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f  nterface is reco
30040 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20  mmended for new 
30050 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74  applications but
30060 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69   the legacy.** i
30070 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f  nterface will co
30080 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70  ntinue to be sup
30090 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ported..**.** ^I
300a0 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  n the legacy int
300b0 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 74 75  erface, the retu
300c0 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65  rn value will be
300d0 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
300e0 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  BUSY],.** [SQLIT
300f0 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45  E_DONE], [SQLITE
30100 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45  _ROW], [SQLITE_E
30110 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  RROR], or [SQLIT
30120 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57  E_MISUSE]..** ^W
30130 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74  ith the "v2" int
30140 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74  erface, any of t
30150 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74  he other [result
30160 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65   codes] or.** [e
30170 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
30180 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72  odes] might be r
30190 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e  eturned as well.
301a0 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  .**.** ^[SQLITE_
301b0 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74  BUSY] means that
301c0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e   the database en
301d0 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20  gine was unable 
301e0 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a  to acquire the.*
301f0 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73  * database locks
30200 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20   it needs to do 
30210 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68  its job.  ^If th
30220 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
30230 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20   [COMMIT].** or 
30240 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f  occurs outside o
30250 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72  f an explicit tr
30260 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20  ansaction, then 
30270 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74 68  you can retry th
30280 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20  e.** statement. 
30290 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   If the statemen
302a0 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d  t is not a [COMM
302b0 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77  IT] and occurs w
302c0 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c  ithin an.** expl
302d0 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
302e0 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64   then you should
302f0 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72   rollback the tr
30300 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65  ansaction before
30310 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a  .** continuing..
30320 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44  **.** ^[SQLITE_D
30330 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  ONE] means that 
30340 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61  the statement ha
30350 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75  s finished execu
30360 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66  ting.** successf
30370 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73  ully.  sqlite3_s
30380 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74  tep() should not
30390 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   be called again
303a0 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c   on this virtual
303b0 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68  .** machine with
303c0 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e  out first callin
303d0 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
303e0 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65  ()] to reset the
303f0 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68   virtual.** mach
30400 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20  ine back to its 
30410 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a  initial state..*
30420 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c  *.** ^If the SQL
30430 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67   statement being
30440 20 65 78 65 63 75 74 65 64 20 72 65 74 75 72 6e   executed return
30450 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e  s any data, then
30460 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a   [SQLITE_ROW].**
30470 20 69 73 20 72 65 74 75 72 6e 65 64 20 65 61 63   is returned eac
30480 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77  h time a new row
30490 20 6f 66 20 64 61 74 61 20 69 73 20 72 65 61 64   of data is read
304a0 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67  y for processing
304b0 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65   by the.** calle
304c0 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61  r. The values ma
304d0 79 20 62 65 20 61 63 63 65 73 73 65 64 20 75 73  y be accessed us
304e0 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20  ing the [column 
304f0 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73  access functions
30500 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  ]..** sqlite3_st
30510 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61  ep() is called a
30520 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65  gain to retrieve
30530 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66   the next row of
30540 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53   data..**.** ^[S
30550 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61  QLITE_ERROR] mea
30560 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69  ns that a run-ti
30570 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68 20 61  me error (such a
30580 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a  s a constraint.*
30590 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73  * violation) has
305a0 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69   occurred.  sqli
305b0 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c  te3_step() shoul
305c0 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20  d not be called 
305d0 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20  again on.** the 
305e0 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61  VM. More informa
305f0 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e  tion may be foun
30600 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  d by calling [sq
30610 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
30620 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65  .** ^With the le
30630 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
30640 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  a more specific 
30650 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20  error code (for 
30660 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c  example,.** [SQL
30670 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20  ITE_INTERRUPT], 
30680 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c  [SQLITE_SCHEMA],
30690 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54   [SQLITE_CORRUPT
306a0 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29  ], and so forth)
306b0 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69  .** can be obtai
306c0 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  ned by calling [
306d0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
306e0 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   on the.** [prep
306f0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
30700 20 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69    ^In the "v2" i
30710 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65  nterface,.** the
30720 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65   more specific e
30730 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74  rror code is ret
30740 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62  urned directly b
30750 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  y sqlite3_step()
30760 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ..**.** [SQLITE_
30770 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68  MISUSE] means th
30780 61 74 20 74 68 65 20 74 68 69 73 20 72 6f 75 74  at the this rout
30790 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69  ine was called i
307a0 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a  nappropriately..
307b0 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20 77 61  ** Perhaps it wa
307c0 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70  s called on a [p
307d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
307e0 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61  t] that has.** a
307f0 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c  lready been [sql
30800 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20  ite3_finalize | 
30810 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e  finalized] or on
30820 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a   one that had.**
30830 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75   previously retu
30840 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52  rned [SQLITE_ERR
30850 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  OR] or [SQLITE_D
30860 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75  ONE].  Or it cou
30870 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73  ld.** be the cas
30880 65 20 74 68 61 74 20 74 68 65 20 73 61 6d 65 20  e that the same 
30890 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
308a0 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65  ion is being use
308b0 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d  d by two or.** m
308c0 6f 72 65 20 74 68 72 65 61 64 73 20 61 74 20 74  ore threads at t
308d0 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69  he same moment i
308e0 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f  n time..**.** Fo
308f0 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f  r all versions o
30900 66 20 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61  f SQLite up to a
30910 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36  nd including 3.6
30920 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f  .23.1, a call to
30930 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
30940 65 74 28 29 5d 20 77 61 73 20 72 65 71 75 69 72  et()] was requir
30950 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33  ed after sqlite3
30960 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e 65 64  _step() returned
30970 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68   anything.** oth
30980 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
30990 52 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e 79 20  ROW] before any 
309a0 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63  subsequent invoc
309b0 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69  ation of.** sqli
309c0 74 65 33 5f 73 74 65 70 28 29 2e 20 20 46 61 69  te3_step().  Fai
309d0 6c 75 72 65 20 74 6f 20 72 65 73 65 74 20 74 68  lure to reset th
309e0 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
309f0 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b  ment using .** [
30a00 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
30a10 20 77 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e   would result in
30a20 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55   an [SQLITE_MISU
30a30 53 45 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a  SE] return from.
30a40 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
30a50 29 2e 20 20 42 75 74 20 61 66 74 65 72 20 5b 76  ).  But after [v
30a60 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 5d  ersion 3.6.23.1]
30a70 20 28 5b 64 61 74 65 6f 66 3a 33 2e 36 2e 32 33   ([dateof:3.6.23
30a80 2e 31 5d 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  .1],.** sqlite3_
30a90 73 74 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20  step() began.** 
30aa0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
30ab0 5f 72 65 73 65 74 28 29 5d 20 61 75 74 6f 6d 61  _reset()] automa
30ac0 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20  tically in this 
30ad0 63 69 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74  circumstance rat
30ae0 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75  her.** than retu
30af0 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49  rning [SQLITE_MI
30b00 53 55 53 45 5d 2e 20 20 54 68 69 73 20 69 73 20  SUSE].  This is 
30b10 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65 64 20 61  not considered a
30b20 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a   compatibility.*
30b30 2a 20 62 72 65 61 6b 20 62 65 63 61 75 73 65 20  * break because 
30b40 61 6e 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  any application 
30b50 74 68 61 74 20 65 76 65 72 20 72 65 63 65 69 76  that ever receiv
30b60 65 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53  es an SQLITE_MIS
30b70 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20  USE error.** is 
30b80 62 72 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e 69  broken by defini
30b90 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49  tion.  The [SQLI
30ba0 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45  TE_OMIT_AUTORESE
30bb0 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  T] compile-time 
30bc0 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65  option.** can be
30bd0 20 75 73 65 64 20 74 6f 20 72 65 73 74 6f 72 65   used to restore
30be0 20 74 68 65 20 6c 65 67 61 63 79 20 62 65 68 61   the legacy beha
30bf0 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47  vior..**.** <b>G
30c00 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20 41  oofy Interface A
30c10 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65  lert:</b> In the
30c20 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
30c30 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  e, the sqlite3_s
30c40 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77  tep().** API alw
30c50 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 67 65  ays returns a ge
30c60 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65  neric error code
30c70 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  , [SQLITE_ERROR]
30c80 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a  , following any.
30c90 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74  ** error other t
30ca0 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  han [SQLITE_BUSY
30cb0 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49  ] and [SQLITE_MI
30cc0 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74  SUSE].  You must
30cd0 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65   call.** [sqlite
30ce0 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73  3_reset()] or [s
30cf0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
30d00 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66  )] in order to f
30d10 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a  ind one of the.*
30d20 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f  * specific [erro
30d30 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65  r codes] that be
30d40 74 74 65 72 20 64 65 73 63 72 69 62 65 73 20 74  tter describes t
30d50 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20  he error..** We 
30d60 61 64 6d 69 74 20 74 68 61 74 20 74 68 69 73 20  admit that this 
30d70 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67  is a goofy desig
30d80 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20  n.  The problem 
30d90 68 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a  has been fixed.*
30da0 2a 20 77 69 74 68 20 74 68 65 20 22 76 32 22 20  * with the "v2" 
30db0 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20 79  interface.  If y
30dc0 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f  ou prepare all o
30dd0 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65  f your SQL state
30de0 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65  ments.** using e
30df0 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70  ither [sqlite3_p
30e00 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
30e10 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
30e20 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64  16_v2()] instead
30e30 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63  .** of the legac
30e40 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  y [sqlite3_prepa
30e50 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  re()] and [sqlit
30e60 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20  e3_prepare16()] 
30e70 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74  interfaces,.** t
30e80 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65  hen the more spe
30e90 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64  cific [error cod
30ea0 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64  es] are returned
30eb0 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20   directly.** by 
30ec0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20  sqlite3_step(). 
30ed0 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20   The use of the 
30ee0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69  "v2" interface i
30ef0 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a  s recommended..*
30f00 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74  /.int sqlite3_st
30f10 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ep(sqlite3_stmt*
30f20 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
30f30 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f  EF: Number of co
30f40 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c  lumns in a resul
30f50 74 20 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  t set.** METHOD:
30f60 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
30f70 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
30f80 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 69  _data_count(P) i
30f90 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
30fa0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
30fb0 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a  olumns in the.**
30fc0 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20   current row of 
30fd0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f  the result set o
30fe0 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  f [prepared stat
30ff0 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66  ement] P..** ^If
31000 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
31010 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74 20 68  ent P does not h
31020 61 76 65 20 72 65 73 75 6c 74 73 20 72 65 61 64  ave results read
31030 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28  y to return.** (
31040 76 69 61 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  via calls to the
31050 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
31060 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 63  _int | sqlite3_c
31070 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a  olumn_*()] of.**
31080 20 69 6e 74 65 72 66 61 63 65 73 29 20 74 68 65   interfaces) the
31090 6e 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  n sqlite3_data_c
310a0 6f 75 6e 74 28 50 29 20 72 65 74 75 72 6e 73 20  ount(P) returns 
310b0 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  0..** ^The sqlit
310c0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
310d0 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72 65   routine also re
310e0 74 75 72 6e 73 20 30 20 69 66 20 50 20 69 73 20  turns 0 if P is 
310f0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
31100 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
31110 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f  data_count(P) ro
31120 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20  utine returns 0 
31130 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  if the previous 
31140 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
31150 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74  te3_step](P) ret
31160 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f  urned [SQLITE_DO
31170 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  NE].  ^The sqlit
31180 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
31190 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  .** will return 
311a0 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72 65 76  non-zero if prev
311b0 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71  ious call to [sq
311c0 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72  lite3_step](P) r
311d0 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49  eturned.** [SQLI
311e0 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70 74 20  TE_ROW], except 
311f0 69 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20 74  in the case of t
31200 68 65 20 5b 50 52 41 47 4d 41 20 69 6e 63 72 65  he [PRAGMA incre
31210 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a  mental_vacuum].*
31220 2a 20 77 68 65 72 65 20 69 74 20 61 6c 77 61 79  * where it alway
31230 73 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 73  s returns zero s
31240 69 6e 63 65 20 65 61 63 68 20 73 74 65 70 20 6f  ince each step o
31250 66 20 74 68 61 74 20 6d 75 6c 74 69 2d 73 74 65  f that multi-ste
31260 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65 74 75  p.** pragma retu
31270 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66  rns 0 columns of
31280 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   data..**.** See
31290 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
312a0 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a  column_count()].
312b0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64  */.int sqlite3_d
312c0 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ata_count(sqlite
312d0 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
312e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
312f0 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74   Fundamental Dat
31300 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52  atypes.** KEYWOR
31310 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  DS: SQLITE_TEXT.
31320 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61  **.** ^(Every va
31330 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61  lue in SQLite ha
31340 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75  s one of five fu
31350 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79  ndamental dataty
31360 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  pes:.**.** <ul>.
31370 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73  ** <li> 64-bit s
31380 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a  igned integer.**
31390 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45   <li> 64-bit IEE
313a0 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  E floating point
313b0 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20   number.** <li> 
313c0 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42  string.** <li> B
313d0 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c  LOB.** <li> NULL
313e0 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a  .** </ul>)^.**.*
313f0 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
31400 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20  s are codes for 
31410 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79  each of those ty
31420 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  pes..**.** Note 
31430 74 68 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f  that the SQLITE_
31440 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61  TEXT constant wa
31450 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53  s also used in S
31460 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a  QLite version 2.
31470 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74  ** for a complet
31480 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65  ely different me
31490 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65  aning.  Software
314a0 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69   that links agai
314b0 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69  nst both.** SQLi
314c0 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64  te version 2 and
314d0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
314e0 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c  3 should use SQL
314f0 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a  ITE3_TEXT, not.*
31500 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a  * SQLITE_TEXT..*
31510 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
31520 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66  _INTEGER  1.#def
31530 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54  ine SQLITE_FLOAT
31540 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
31550 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a  LITE_BLOB     4.
31560 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
31570 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66  ULL     5.#ifdef
31580 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75   SQLITE_TEXT.# u
31590 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54  ndef SQLITE_TEXT
315a0 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20  .#else.# define 
315b0 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20  SQLITE_TEXT     
315c0 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65  3.#endif.#define
315d0 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20   SQLITE3_TEXT   
315e0 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    3../*.** CAPI3
315f0 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75  REF: Result Valu
31600 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a  es From A Query.
31610 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f  ** KEYWORDS: {co
31620 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63  lumn access func
31630 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44  tions}.** METHOD
31640 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
31650 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
31660 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f  ines return info
31670 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20  rmation about a 
31680 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66  single column of
31690 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
316a0 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20  result row of a 
316b0 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72  query.  ^In ever
316c0 79 20 63 61 73 65 20 74 68 65 20 66 69 72 73 74  y case the first
316d0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
316e0 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ointer.** to the
316f0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
31700 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65  ment] that is be
31710 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28 74  ing evaluated (t
31720 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
31730 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72  *].** that was r
31740 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71  eturned from [sq
31750 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
31760 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74  ()] or one of it
31770 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61  s variants).** a
31780 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  nd the second ar
31790 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e  gument is the in
317a0 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  dex of the colum
317b0 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f  n for which info
317c0 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c  rmation.** shoul
317d0 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e  d be returned. ^
317e0 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c  The leftmost col
317f0 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c  umn of the resul
31800 74 20 73 65 74 20 68 61 73 20 74 68 65 20 69 6e  t set has the in
31810 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e  dex 0..** ^The n
31820 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
31830 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63   in the result c
31840 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64  an be determined
31850 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
31860 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
31870 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  )]..**.** If the
31880 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64   SQL statement d
31890 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c  oes not currentl
318a0 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c  y point to a val
318b0 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68  id row, or if th
318c0 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65  e.** column inde
318d0 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  x is out of rang
318e0 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  e, the result is
318f0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54   undefined..** T
31900 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61  hese routines ma
31910 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64  y only be called
31920 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72   when the most r
31930 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a  ecent call to.**
31940 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
31950 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b  ] has returned [
31960 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20  SQLITE_ROW] and 
31970 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69  neither.** [sqli
31980 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72  te3_reset()] nor
31990 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
319a0 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20  ze()] have been 
319b0 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e  called subsequen
319c0 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f  tly..** If any o
319d0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
319e0 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65   are called afte
319f0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
31a00 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
31a10 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
31a20 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33  r after [sqlite3
31a30 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74  _step()] has ret
31a40 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69  urned.** somethi
31a50 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ng other than [S
31a60 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20  QLITE_ROW], the 
31a70 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
31a80 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71  fined..** If [sq
31a90 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72  lite3_step()] or
31aa0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
31ab0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
31ac0 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72  inalize()].** ar
31ad0 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20  e called from a 
31ae0 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
31af0 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68   while any of th
31b00 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  ese routines.** 
31b10 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65  are pending, the
31b20 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
31b30 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  e undefined..**.
31b40 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
31b50 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f  column_type() ro
31b60 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
31b70 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54  e.** [SQLITE_INT
31b80 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 20  EGER | datatype 
31b90 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e  code] for the in
31ba0 69 74 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a  itial data type.
31bb0 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ** of the result
31bc0 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72   column.  ^The r
31bd0 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73  eturned value is
31be0 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
31bf0 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51  INTEGER],.** [SQ
31c00 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51  LITE_FLOAT], [SQ
31c10 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c  LITE_TEXT], [SQL
31c20 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53  ITE_BLOB], or [S
31c30 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68  QLITE_NULL].  Th
31c40 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72  e value.** retur
31c50 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
31c60 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20  olumn_type() is 
31c70 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20  only meaningful 
31c80 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f  if no type.** co
31c90 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f  nversions have o
31ca0 63 63 75 72 72 65 64 20 61 73 20 64 65 73 63 72  ccurred as descr
31cb0 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74  ibed below.  Aft
31cc0 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  er a type conver
31cd0 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c  sion,.** the val
31ce0 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ue returned by s
31cf0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
31d00 70 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65  pe() is undefine
31d10 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65  d.  Future.** ve
31d20 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
31d30 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65 20   may change the 
31d40 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69  behavior of sqli
31d50 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
31d60 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  ).** following a
31d70 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
31d80 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
31d90 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42  result is a BLOB
31da0 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67   or UTF-8 string
31db0 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
31dc0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
31dd0 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75  .** routine retu
31de0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
31df0 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
31e00 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a  BLOB or string..
31e10 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
31e20 74 20 69 73 20 61 20 55 54 46 2d 31 36 20 73 74  t is a UTF-16 st
31e30 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74  ring, then sqlit
31e40 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
31e50 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68  ) converts.** th
31e60 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d  e string to UTF-
31e70 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72  8 and then retur
31e80 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
31e90 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74   bytes..** ^If t
31ea0 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e  he result is a n
31eb0 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65  umeric value the
31ec0 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
31ed0 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a  _bytes() uses.**
31ee0 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
31ef0 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74  tf()] to convert
31f00 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61   that value to a
31f10 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e   UTF-8 string an
31f20 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65  d returns.** the
31f30 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
31f40 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e   in that string.
31f50 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
31f60 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  lt is NULL, then
31f70 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
31f80 62 79 74 65 73 28 29 20 72 65 74 75 72 6e 73 20  bytes() returns 
31f90 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  zero..**.** ^If 
31fa0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
31fb0 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36 20 73  BLOB or UTF-16 s
31fc0 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73  tring then the s
31fd0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
31fe0 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69  tes16().** routi
31ff0 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
32000 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
32010 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73  n that BLOB or s
32020 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
32030 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54  e result is a UT
32040 46 2d 38 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  F-8 string, then
32050 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
32060 62 79 74 65 73 31 36 28 29 20 63 6f 6e 76 65 72  bytes16() conver
32070 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  ts.** the string
32080 20 74 6f 20 55 54 46 2d 31 36 20 61 6e 64 20 74   to UTF-16 and t
32090 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  hen returns the 
320a0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e  number of bytes.
320b0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
320c0 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20  lt is a numeric 
320d0 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74  value then sqlit
320e0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
320f0 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c  6() uses.** [sql
32100 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
32110 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74   to convert that
32120 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d   value to a UTF-
32130 31 36 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65  16 string and re
32140 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d  turns.** the num
32150 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
32160 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  that string..** 
32170 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
32180 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c  s NULL, then sql
32190 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
321a0 73 31 36 28 29 20 72 65 74 75 72 6e 73 20 7a 65  s16() returns ze
321b0 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76  ro..**.** ^The v
321c0 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62  alues returned b
321d0 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  y [sqlite3_colum
321e0 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 0a  n_bytes()] and .
321f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
32200 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 64 6f  mn_bytes16()] do
32210 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65   not include the
32220 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
32230 73 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20  s at the end.** 
32240 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20  of the string.  
32250 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68  ^For clarity: th
32260 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65  e values returne
32270 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
32280 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d  _column_bytes()]
32290 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f   and [sqlite3_co
322a0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20  lumn_bytes16()] 
322b0 61 72 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  are the number o
322c0 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68  f.** bytes in th
322d0 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68  e string, not th
322e0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
322f0 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53  acters..**.** ^S
32300 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
32310 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
32320 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c  n_text() and sql
32330 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
32340 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d  16(),.** even em
32350 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65  pty strings, are
32360 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72   always zero-ter
32370 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 72  minated.  ^The r
32380 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66  eturn.** value f
32390 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  rom sqlite3_colu
323a0 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20  mn_blob() for a 
323b0 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42  zero-length BLOB
323c0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
323d0 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 57 61 72  er..**.** <b>War
323e0 6e 69 6e 67 3a 3c 2f 62 3e 20 5e 54 68 65 20 6f  ning:</b> ^The o
323f0 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
32400 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  y [sqlite3_colum
32410 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e  n_value()] is an
32420 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  .** [unprotected
32430 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
32440 6f 62 6a 65 63 74 2e 20 20 49 6e 20 61 20 6d 75  object.  In a mu
32450 6c 74 69 74 68 72 65 61 64 65 64 20 65 6e 76 69  ltithreaded envi
32460 72 6f 6e 6d 65 6e 74 2c 0a 2a 2a 20 61 6e 20 75  ronment,.** an u
32470 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
32480 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
32490 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  may only be used
324a0 20 73 61 66 65 6c 79 20 77 69 74 68 0a 2a 2a 20   safely with.** 
324b0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61  [sqlite3_bind_va
324c0 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  lue()] and [sqli
324d0 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
324e0 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b  ()]..** If the [
324f0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
32500 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
32510 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  t returned by.**
32520 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
32530 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65  _value()] is use
32540 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77  d in any other w
32550 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61  ay, including ca
32560 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e  lls.** to routin
32570 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33  es like [sqlite3
32580 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b  _value_int()], [
32590 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
325a0 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71  xt()],.** or [sq
325b0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
325c0 73 28 29 5d 2c 20 74 68 65 20 62 65 68 61 76 69  s()], the behavi
325d0 6f 72 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64  or is not thread
325e0 73 61 66 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  safe..**.** Thes
325f0 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d  e routines attem
32600 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  pt to convert th
32610 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 70  e value where ap
32620 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f 72  propriate.  ^For
32630 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20  .** example, if 
32640 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70  the internal rep
32650 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46  resentation is F
32660 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20  LOAT and a text 
32670 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71  result.** is req
32680 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33  uested, [sqlite3
32690 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20  _snprintf()] is 
326a0 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  used internally 
326b0 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a  to perform the.*
326c0 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74  * conversion aut
326d0 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54  omatically.  ^(T
326e0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62  he following tab
326f0 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 20 63  le details the c
32700 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68  onversions.** th
32710 61 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a  at are applied:.
32720 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
32730 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72  e>.** <table bor
32740 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e  der="1">.** <tr>
32750 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72  <th> Internal<br
32760 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65  >Type <th> Reque
32770 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68  sted<br>Type <th
32780 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a  >  Conversion.**
32790 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
327a0 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  LL    <td> INTEG
327b0 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  ER   <td> Result
327c0 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64   is 0.** <tr><td
327d0 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
327e0 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52   FLOAT    <td> R
327f0 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20  esult is 0.0.** 
32800 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
32810 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
32820 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
32830 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
32840 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
32850 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20      <td>   BLOB 
32860 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
32870 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
32880 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
32890 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41  EGER  <td>  FLOA
328a0 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  T    <td> Conver
328b0 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74  t from integer t
328c0 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c  o float.** <tr><
328d0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
328e0 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
328f0 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67   ASCII rendering
32900 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a   of the integer.
32910 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45  ** <tr><td> INTE
32920 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  GER  <td>   BLOB
32930 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73      <td> Same as
32940 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a   INTEGER->TEXT.*
32950 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
32960 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52  T   <td> INTEGER
32970 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74     <td> [CAST] t
32980 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72  o INTEGER.** <tr
32990 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
329a0 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
329b0 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69  d> ASCII renderi
329c0 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a  ng of the float.
329d0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
329e0 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  AT   <td>   BLOB
329f0 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20      <td> [CAST] 
32a00 74 6f 20 42 4c 4f 42 0a 2a 2a 20 3c 74 72 3e 3c  to BLOB.** <tr><
32a10 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64  td>  TEXT    <td
32a20 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
32a30 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47   [CAST] to INTEG
32a40 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ER.** <tr><td>  
32a50 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c  TEXT    <td>  FL
32a60 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53  OAT    <td> [CAS
32a70 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74  T] to REAL.** <t
32a80 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
32a90 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
32aa0 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a  td> No change.**
32ab0 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
32ac0 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
32ad0 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f    <td> [CAST] to
32ae0 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e   INTEGER.** <tr>
32af0 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
32b00 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
32b10 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c  > [CAST] to REAL
32b20 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
32b30 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58  OB    <td>   TEX
32b40 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20  T    <td> Add a 
32b50 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20  zero terminator 
32b60 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74  if needed.** </t
32b70 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b  able>.** </block
32b80 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e  quote>)^.**.** N
32b90 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 79  ote that when ty
32ba0 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f  pe conversions o
32bb0 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72  ccur, pointers r
32bc0 65 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72  eturned by prior
32bd0 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  .** calls to sql
32be0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
32bf0 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  (), sqlite3_colu
32c00 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f  mn_text(), and/o
32c10 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
32c20 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79  umn_text16() may
32c30 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e   be invalidated.
32c40 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73  .** Type convers
32c50 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72  ions and pointer
32c60 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d   invalidations m
32c70 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e  ight occur.** in
32c80 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63   the following c
32c90 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ases:.**.** <ul>
32ca0 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69  .** <li> The ini
32cb0 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
32cc0 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74  a BLOB and sqlit
32cd0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
32ce0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
32cf0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
32d00 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  6() is called.  
32d10 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f  A zero-terminato
32d20 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20  r might.**      
32d30 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64 65 64  need to be added
32d40 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c   to the string.<
32d50 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  /li>.** <li> The
32d60 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
32d70 20 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 61   is UTF-8 text a
32d80 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
32d90 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a  n_bytes16() or.*
32da0 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63  *      sqlite3_c
32db0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69  olumn_text16() i
32dc0 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63  s called.  The c
32dd0 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63  ontent must be c
32de0 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20  onverted.**     
32df0 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e   to UTF-16.</li>
32e00 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69  .** <li> The ini
32e10 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
32e20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20  UTF-16 text and 
32e30 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
32e40 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20  ytes() or.**    
32e50 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
32e60 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65  _text() is calle
32e70 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20  d.  The content 
32e80 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
32e90 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46  d.**      to UTF
32ea0 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c  -8.</li>.** </ul
32eb0 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73  >.**.** ^Convers
32ec0 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46  ions between UTF
32ed0 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36  -16be and UTF-16
32ee0 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f  le are always do
32ef0 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20  ne in place and 
32f00 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69  do.** not invali
32f10 64 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69  date a prior poi
32f20 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20  nter, though of 
32f30 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65  course the conte
32f40 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  nt of the buffer
32f50 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 69  .** that the pri
32f60 6f 72 20 70 6f 69 6e 74 65 72 20 72 65 66 65 72  or pointer refer
32f70 65 6e 63 65 73 20 77 69 6c 6c 20 68 61 76 65 20  ences will have 
32f80 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20  been modified.  
32f90 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f  Other kinds.** o
32fa0 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65  f conversion are
32fb0 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77   done in place w
32fc0 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62  hen it is possib
32fd0 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65  le, but sometime
32fe0 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f  s they.** are no
32ff0 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69  t possible and i
33000 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20 70 72  n those cases pr
33010 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65  ior pointers are
33020 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a   invalidated..**
33030 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20 70  .** The safest p
33040 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f  olicy is to invo
33050 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  ke these routine
33060 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74  s.** in one of t
33070 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79  he following way
33080 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
33090 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
330a0 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c  lumn_text() foll
330b0 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
330c0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f  column_bytes()</
330d0 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  li>.**  <li>sqli
330e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
330f0 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
33100 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
33110 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c  es()</li>.**  <l
33120 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
33130 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77  _text16() follow
33140 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
33150 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f  lumn_bytes16()</
33160 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  li>.** </ul>.**.
33170 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  ** In other word
33180 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61  s, you should ca
33190 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ll sqlite3_colum
331a0 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c  n_text(),.** sql
331b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
331c0 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  (), or sqlite3_c
331d0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66  olumn_text16() f
331e0 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68  irst to force th
331f0 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f  e result.** into
33200 20 74 68 65 20 64 65 73 69 72 65 64 20 66 6f 72   the desired for
33210 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65  mat, then invoke
33220 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
33230 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71  bytes() or.** sq
33240 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
33250 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74  es16() to find t
33260 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72  he size of the r
33270 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d  esult.  Do not m
33280 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73  ix calls.** to s
33290 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
332a0 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  xt() or sqlite3_
332b0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69  column_blob() wi
332c0 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73  th calls to.** s
332d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
332e0 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20  tes16(), and do 
332f0 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f  not mix calls to
33300 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
33310 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68  text16().** with
33320 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
33330 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
33340 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69  ..**.** ^The poi
33350 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 61  nters returned a
33360 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61  re valid until a
33370 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
33380 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65   occurs as.** de
33390 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f  scribed above, o
333a0 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33  r until [sqlite3
333b0 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c  _step()] or [sql
333c0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
333d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  .** [sqlite3_fin
333e0 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c  alize()] is call
333f0 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79  ed.  ^The memory
33400 20 73 70 61 63 65 20 75 73 65 64 20 74 6f 20 68   space used to h
33410 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61  old strings.** a
33420 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65  nd BLOBs is free
33430 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  d automatically.
33440 20 20 44 6f 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d    Do <em>not</em
33450 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74  > pass the point
33460 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  ers returned.** 
33470 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f  from [sqlite3_co
33480 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73  lumn_blob()], [s
33490 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
334a0 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f  xt()], etc. into
334b0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
334c0 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  e()]..**.** ^(If
334d0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
334e0 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  tion error occur
334f0 73 20 64 75 72 69 6e 67 20 74 68 65 20 65 76 61  s during the eva
33500 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a  luation of any.*
33510 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  * of these routi
33520 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76  nes, a default v
33530 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64  alue is returned
33540 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 76  .  The default v
33550 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65  alue.** is eithe
33560 72 20 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c  r the integer 0,
33570 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f   the floating po
33580 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20  int number 0.0, 
33590 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  or a NULL.** poi
335a0 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e  nter.  Subsequen
335b0 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  t calls to [sqli
335c0 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77  te3_errcode()] w
335d0 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53  ill return.** [S
335e0 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a  QLITE_NOMEM].)^.
335f0 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  */.const void *s
33600 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
33610 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
33620 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
33630 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
33640 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74  bytes(sqlite3_st
33650 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
33660 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
33670 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74  mn_bytes16(sqlit
33680 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
33690 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69  ol);.double sqli
336a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c  te3_column_doubl
336b0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
336c0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20   int iCol);.int 
336d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
336e0 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
336f0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c  , int iCol);.sql
33700 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
33710 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28  e3_column_int64(
33720 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
33730 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20  nt iCol);.const 
33740 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73  unsigned char *s
33750 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
33760 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  xt(sqlite3_stmt*
33770 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e  , int iCol);.con
33780 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
33790 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73  _column_text16(s
337a0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
337b0 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c  t iCol);.int sql
337c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
337d0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
337e0 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74  int iCol);.sqlit
337f0 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65  e3_value *sqlite
33800 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73  3_column_value(s
33810 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
33820 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t iCol);../*.** 
33830 43 41 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f  CAPI3REF: Destro
33840 79 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  y A Prepared Sta
33850 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a  tement Object.**
33860 20 44 45 53 54 52 55 43 54 4f 52 3a 20 73 71 6c   DESTRUCTOR: sql
33870 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
33880 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e  ^The sqlite3_fin
33890 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e  alize() function
338a0 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65   is called to de
338b0 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72 65 64  lete a [prepared
338c0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
338d0 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
338e0 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f  ent evaluation o
338f0 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
33900 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65  encountered no e
33910 72 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74  rrors.** or if t
33920 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
33930 6e 65 76 65 72 20 62 65 65 6e 20 65 76 61 6c 75  never been evalu
33940 61 74 65 64 2c 20 74 68 65 6e 20 73 71 6c 69 74  ated, then sqlit
33950 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72 65  e3_finalize() re
33960 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f  turns.** SQLITE_
33970 4f 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 73  OK.  ^If the mos
33980 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74  t recent evaluat
33990 69 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e 74  ion of statement
339a0 20 53 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a   S failed, then.
339b0 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  ** sqlite3_final
339c0 69 7a 65 28 53 29 20 72 65 74 75 72 6e 73 20 74  ize(S) returns t
339d0 68 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b  he appropriate [
339e0 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a  error code] or.*
339f0 2a 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f  * [extended erro
33a00 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  r code]..**.** ^
33a10 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  The sqlite3_fina
33a20 6c 69 7a 65 28 53 29 20 72 6f 75 74 69 6e 65 20  lize(S) routine 
33a30 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74  can be called at
33a40 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e   any point durin
33a50 67 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20 63 79  g.** the life cy
33a60 63 6c 65 20 6f 66 20 5b 70 72 65 70 61 72 65 64  cle of [prepared
33a70 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a   statement] S:.*
33a80 2a 20 62 65 66 6f 72 65 20 73 74 61 74 65 6d 65  * before stateme
33a90 6e 74 20 53 20 69 73 20 65 76 65 72 20 65 76 61  nt S is ever eva
33aa0 6c 75 61 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a  luated, after.**
33ab0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c   one or more cal
33ac0 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ls to [sqlite3_r
33ad0 65 73 65 74 28 29 5d 2c 20 6f 72 20 61 66 74 65  eset()], or afte
33ae0 72 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f  r any call.** to
33af0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
33b00 5d 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  ] regardless of 
33b10 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
33b20 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73  he statement has
33b30 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78  .** completed ex
33b40 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  ecution..**.** ^
33b50 49 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33  Invoking sqlite3
33b60 5f 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61  _finalize() on a
33b70 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
33b80 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f   a harmless no-o
33b90 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70  p..**.** The app
33ba0 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 66 69  lication must fi
33bb0 6e 61 6c 69 7a 65 20 65 76 65 72 79 20 5b 70 72  nalize every [pr
33bc0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
33bd0 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 61 76  ] in order to av
33be0 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20  oid.** resource 
33bf0 6c 65 61 6b 73 2e 20 20 49 74 20 69 73 20 61 20  leaks.  It is a 
33c00 67 72 69 65 76 6f 75 73 20 65 72 72 6f 72 20 66  grievous error f
33c10 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  or the applicati
33c20 6f 6e 20 74 6f 20 74 72 79 20 74 6f 20 75 73 65  on to try to use
33c30 0a 2a 2a 20 61 20 70 72 65 70 61 72 65 64 20 73  .** a prepared s
33c40 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69  tatement after i
33c50 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c  t has been final
33c60 69 7a 65 64 2e 20 20 41 6e 79 20 75 73 65 20 6f  ized.  Any use o
33c70 66 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20  f a prepared.** 
33c80 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20  statement after 
33c90 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61  it has been fina
33ca0 6c 69 7a 65 64 20 63 61 6e 20 72 65 73 75 6c 74  lized can result
33cb0 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   in undefined an
33cc0 64 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65  d.** undesirable
33cd0 20 62 65 68 61 76 69 6f 72 20 73 75 63 68 20 61   behavior such a
33ce0 73 20 73 65 67 66 61 75 6c 74 73 20 61 6e 64 20  s segfaults and 
33cf0 68 65 61 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e  heap corruption.
33d00 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
33d10 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33  finalize(sqlite3
33d20 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
33d30 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
33d40 52 65 73 65 74 20 41 20 50 72 65 70 61 72 65 64  Reset A Prepared
33d50 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63   Statement Objec
33d60 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
33d70 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
33d80 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65  The sqlite3_rese
33d90 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  t() function is 
33da0 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20  called to reset 
33db0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
33dc0 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74  ement].** object
33dd0 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69   back to its ini
33de0 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64  tial state, read
33df0 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75  y to be re-execu
33e00 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c  ted..** ^Any SQL
33e10 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61   statement varia
33e20 62 6c 65 73 20 74 68 61 74 20 68 61 64 20 76 61  bles that had va
33e30 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68  lues bound to th
33e40 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20  em using.** the 
33e50 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
33e60 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e  ob | sqlite3_bin
33e70 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69  d_*() API] retai
33e80 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a  n their values..
33e90 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f  ** Use [sqlite3_
33ea0 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29  clear_bindings()
33eb0 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 62  ] to reset the b
33ec0 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e  indings..**.** ^
33ed0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
33ee0 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65  et(S)] interface
33ef0 20 72 65 73 65 74 73 20 74 68 65 20 5b 70 72 65   resets the [pre
33f00 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
33f10 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68   S.** back to th
33f20 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69  e beginning of i
33f30 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a  ts program..**.*
33f40 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72  * ^If the most r
33f50 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
33f60 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
33f70 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70  for the.** [prep
33f80 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
33f90 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  S returned [SQLI
33fa0 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49  TE_ROW] or [SQLI
33fb0 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20  TE_DONE],.** or 
33fc0 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  if [sqlite3_step
33fd0 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62  (S)] has never b
33fe0 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65  efore been calle
33ff0 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20  d on S,.** then 
34000 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
34010 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  )] returns [SQLI
34020 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49  TE_OK]..**.** ^I
34030 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
34040 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
34050 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20  e3_step(S)] for 
34060 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
34070 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e   statement] S in
34080 64 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72  dicated an error
34090 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74  , then.** [sqlit
340a0 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74  e3_reset(S)] ret
340b0 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69  urns an appropri
340c0 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ate [error code]
340d0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ..**.** ^The [sq
340e0 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
340f0 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e  interface does n
34100 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61  ot change the va
34110 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b  lues.** of any [
34120 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
34130 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74  b|bindings] on t
34140 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
34150 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e  tement] S..*/.in
34160 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28  t sqlite3_reset(
34170 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
34180 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
34190 49 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72  I3REF: Create Or
341a0 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75   Redefine SQL Fu
341b0 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f  nctions.** KEYWO
341c0 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63  RDS: {function c
341d0 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  reation routines
341e0 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
341f0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
34200 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
34210 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
34220 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
34230 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
34240 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  s}.** METHOD: sq
34250 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lite3.**.** ^The
34260 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f  se functions (co
34270 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e  llectively known
34280 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72   as "function cr
34290 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22  eation routines"
342a0 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f  ).** are used to
342b0 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f   add SQL functio
342c0 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73  ns or aggregates
342d0 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20   or to redefine 
342e0 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20  the behavior.** 
342f0 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20  of existing SQL 
34300 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67  functions or agg
34310 72 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e  regates.  The on
34320 6c 79 20 64 69 66 66 65 72 65 6e 63 65 73 20 62  ly differences b
34330 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20  etween.** these 
34340 72 6f 75 74 69 6e 65 73 20 61 72 65 20 74 68 65  routines are the
34350 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 65   text encoding e
34360 78 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74  xpected for.** t
34370 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
34380 74 65 72 20 28 74 68 65 20 6e 61 6d 65 20 6f 66  ter (the name of
34390 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 65   the function be
343a0 69 6e 67 20 63 72 65 61 74 65 64 29 0a 2a 2a 20  ing created).** 
343b0 61 6e 64 20 74 68 65 20 70 72 65 73 65 6e 63 65  and the presence
343c0 20 6f 72 20 61 62 73 65 6e 63 65 20 6f 66 20 61   or absence of a
343d0 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c   destructor call
343e0 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20  back for.** the 
343f0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
34400 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
34410 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  ^The first param
34420 65 74 65 72 20 69 73 20 74 68 65 20 5b 64 61 74  eter is the [dat
34430 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
34440 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 53  ] to which the S
34450 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69  QL.** function i
34460 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20  s to be added.  
34470 5e 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69  ^If an applicati
34480 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61  on uses more tha
34490 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a  n one database.*
344a0 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65  * connection the
344b0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
344c0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
344d0 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64 65  ons must be adde
344e0 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 74  d.** to each dat
344f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
34500 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a   separately..**.
34510 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  ** ^The second p
34520 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
34530 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20  name of the SQL 
34540 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63  function to be c
34550 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64  reated or.** red
34560 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65  efined.  ^The le
34570 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65  ngth of the name
34580 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32   is limited to 2
34590 35 35 20 62 79 74 65 73 20 69 6e 20 61 20 55 54  55 bytes in a UT
345a0 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74  F-8.** represent
345b0 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65  ation, exclusive
345c0 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74 65 72   of the zero-ter
345d0 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20  minator.  ^Note 
345e0 74 68 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a  that the name.**
345f0 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73   length limit is
34600 20 69 6e 20 55 54 46 2d 38 20 62 79 74 65 73 2c   in UTF-8 bytes,
34610 20 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 20   not characters 
34620 6e 6f 72 20 55 54 46 2d 31 36 20 62 79 74 65 73  nor UTF-16 bytes
34630 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65  .  .** ^Any atte
34640 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 20  mpt to create a 
34650 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20  function with a 
34660 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77  longer name.** w
34670 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53  ill result in [S
34680 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 62 65  QLITE_MISUSE] be
34690 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a  ing returned..**
346a0 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 70  .** ^The third p
346b0 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a  arameter (nArg).
346c0 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  ** is the number
346d0 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68   of arguments th
346e0 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  at the SQL funct
346f0 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
34700 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 74  ate takes. ^If t
34710 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 73  his parameter is
34720 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51   -1, then the SQ
34730 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
34740 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 74   aggregate may t
34750 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f  ake any number o
34760 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77  f arguments betw
34770 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69  een 0 and the li
34780 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73  mit.** set by [s
34790 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53  qlite3_limit]([S
347a0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
347b0 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20  TION_ARG]).  If 
347c0 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72  the third.** par
347d0 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20 74  ameter is less t
347e0 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65  han -1 or greate
347f0 72 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20  r than 127 then 
34800 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a  the behavior is.
34810 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  ** undefined..**
34820 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20  .** ^The fourth 
34830 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74  parameter, eText
34840 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 77  Rep, specifies w
34850 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  hat.** [SQLITE_U
34860 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64  TF8 | text encod
34870 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75  ing] this SQL fu
34880 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66  nction prefers f
34890 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65  or.** its parame
348a0 74 65 72 73 2e 20 20 54 68 65 20 61 70 70 6c 69  ters.  The appli
348b0 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 73 65  cation should se
348c0 74 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72  t this parameter
348d0 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55   to.** [SQLITE_U
348e0 54 46 31 36 4c 45 5d 20 69 66 20 74 68 65 20 66  TF16LE] if the f
348f0 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
34900 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 0a  tation invokes .
34910 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
34920 65 5f 74 65 78 74 31 36 6c 65 28 29 5d 20 6f 6e  e_text16le()] on
34930 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 20 5b 53   an input, or [S
34940 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 20 69  QLITE_UTF16BE] i
34950 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  f the.** impleme
34960 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20  ntation invokes 
34970 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
34980 65 78 74 31 36 62 65 28 29 5d 20 6f 6e 20 61 6e  ext16be()] on an
34990 20 69 6e 70 75 74 2c 20 6f 72 0a 2a 2a 20 5b 53   input, or.** [S
349a0 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 69 66 20  QLITE_UTF16] if 
349b0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
349c0 65 78 74 31 36 28 29 5d 20 69 73 20 75 73 65 64  ext16()] is used
349d0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46  , or [SQLITE_UTF
349e0 38 5d 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 2e  8].** otherwise.
349f0 20 20 5e 54 68 65 20 73 61 6d 65 20 53 51 4c 20    ^The same SQL 
34a00 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20  function may be 
34a10 72 65 67 69 73 74 65 72 65 64 20 6d 75 6c 74 69  registered multi
34a20 70 6c 65 20 74 69 6d 65 73 20 75 73 69 6e 67 0a  ple times using.
34a30 2a 2a 20 64 69 66 66 65 72 65 6e 74 20 70 72 65  ** different pre
34a40 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f  ferred text enco
34a50 64 69 6e 67 73 2c 20 77 69 74 68 20 64 69 66 66  dings, with diff
34a60 65 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61  erent implementa
34a70 74 69 6f 6e 73 20 66 6f 72 0a 2a 2a 20 65 61 63  tions for.** eac
34a80 68 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 20 5e  h encoding..** ^
34a90 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d  When multiple im
34aa0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
34ab0 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
34ac0 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65  on are available
34ad0 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c  , SQLite.** will
34ae0 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68   pick the one th
34af0 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20  at involves the 
34b00 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20  least amount of 
34b10 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e  data conversion.
34b20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72  .**.** ^The four
34b30 74 68 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  th parameter may
34b40 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 62 65 20 4f   optionally be O
34b50 52 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45  Red with [SQLITE
34b60 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 0a  _DETERMINISTIC].
34b70 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 74 68 61  ** to signal tha
34b80 74 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 77  t the function w
34b90 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72  ill always retur
34ba0 6e 20 74 68 65 20 73 61 6d 65 20 72 65 73 75 6c  n the same resul
34bb0 74 20 67 69 76 65 6e 0a 2a 2a 20 74 68 65 20 73  t given.** the s
34bc0 61 6d 65 20 69 6e 70 75 74 73 20 77 69 74 68 69  ame inputs withi
34bd0 6e 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73  n a single SQL s
34be0 74 61 74 65 6d 65 6e 74 2e 20 20 4d 6f 73 74 20  tatement.  Most 
34bf0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 72  SQL functions ar
34c00 65 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 69 73 74  e.** determinist
34c10 69 63 2e 20 20 54 68 65 20 62 75 69 6c 74 2d 69  ic.  The built-i
34c20 6e 20 5b 72 61 6e 64 6f 6d 28 29 5d 20 53 51 4c  n [random()] SQL
34c30 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 6e 20   function is an 
34c40 65 78 61 6d 70 6c 65 20 6f 66 20 61 0a 2a 2a 20  example of a.** 
34c50 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 69 73  function that is
34c60 20 6e 6f 74 20 64 65 74 65 72 6d 69 6e 69 73 74   not determinist
34c70 69 63 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20  ic.  The SQLite 
34c80 71 75 65 72 79 20 70 6c 61 6e 6e 65 72 20 69 73  query planner is
34c90 20 61 62 6c 65 20 74 6f 0a 2a 2a 20 70 65 72 66   able to.** perf
34ca0 6f 72 6d 20 61 64 64 69 74 69 6f 6e 61 6c 20 6f  orm additional o
34cb0 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20 6f 6e 20  ptimizations on 
34cc0 64 65 74 65 72 6d 69 6e 69 73 74 69 63 20 66 75  deterministic fu
34cd0 6e 63 74 69 6f 6e 73 2c 20 73 6f 20 75 73 65 0a  nctions, so use.
34ce0 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54  ** of the [SQLIT
34cf0 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43 5d  E_DETERMINISTIC]
34d00 20 66 6c 61 67 20 69 73 20 72 65 63 6f 6d 6d 65   flag is recomme
34d10 6e 64 65 64 20 77 68 65 72 65 20 70 6f 73 73 69  nded where possi
34d20 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ble..**.** ^(The
34d30 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72   fifth parameter
34d40 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79   is an arbitrary
34d50 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69   pointer.  The i
34d60 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
34d70 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   the.** function
34d80 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73   can gain access
34d90 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72   to this pointer
34da0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
34db0 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a  user_data()].)^.
34dc0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68  **.** ^The sixth
34dd0 2c 20 73 65 76 65 6e 74 68 20 61 6e 64 20 65 69  , seventh and ei
34de0 67 68 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c  ghth parameters,
34df0 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e   xFunc, xStep an
34e00 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a  d xFinal, are.**
34e10 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c   pointers to C-l
34e20 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e  anguage function
34e30 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  s that implement
34e40 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
34e50 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
34e60 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 51 4c  e. ^A scalar SQL
34e70 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
34e80 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  es an implementa
34e90 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e  tion of the xFun
34ea0 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e  c.** callback on
34eb0 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  ly; NULL pointer
34ec0 73 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64  s must be passed
34ed0 20 61 73 20 74 68 65 20 78 53 74 65 70 20 61 6e   as the xStep an
34ee0 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61  d xFinal.** para
34ef0 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 72  meters. ^An aggr
34f00 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
34f10 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69  on requires an i
34f20 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
34f30 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46   xStep.** and xF
34f40 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f  inal and NULL po
34f50 69 6e 74 65 72 20 6d 75 73 74 20 62 65 20 70 61  inter must be pa
34f60 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20  ssed for xFunc. 
34f70 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78  ^To delete an ex
34f80 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75  isting.** SQL fu
34f90 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67  nction or aggreg
34fa0 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70  ate, pass NULL p
34fb0 6f 69 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c 20  ointers for all 
34fc0 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a  three function.*
34fd0 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a  * callbacks..**.
34fe0 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e 69 6e 74  ** ^(If the nint
34ff0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
35000 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
35010 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e  nction_v2() is n
35020 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e  ot NULL,.** then
35030 20 69 74 20 69 73 20 64 65 73 74 72 75 63 74 6f   it is destructo
35040 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63  r for the applic
35050 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74  ation data point
35060 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73 74  er. .** The dest
35070 72 75 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65  ructor is invoke
35080 64 20 77 68 65 6e 20 74 68 65 20 66 75 6e 63 74  d when the funct
35090 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2c 20  ion is deleted, 
350a0 65 69 74 68 65 72 20 62 79 20 62 65 69 6e 67 0a  either by being.
350b0 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72  ** overloaded or
350c0 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   when the databa
350d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c  se connection cl
350e0 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20  oses.)^.** ^The 
350f0 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 61 6c  destructor is al
35100 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 68  so invoked if th
35110 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c  e call to.** sql
35120 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
35130 74 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e  tion_v2() fails.
35140 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 64 65  .** ^When the de
35150 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63  structor callbac
35160 6b 20 6f 66 20 74 68 65 20 74 65 6e 74 68 20 70  k of the tenth p
35170 61 72 61 6d 65 74 65 72 20 69 73 20 69 6e 76 6f  arameter is invo
35180 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61  ked, it.** is pa
35190 73 73 65 64 20 61 20 73 69 6e 67 6c 65 20 61 72  ssed a single ar
351a0 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
351b0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 61 70  a copy of the ap
351c0 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 0a  plication data .
351d0 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68  ** pointer which
351e0 20 77 61 73 20 74 68 65 20 66 69 66 74 68 20 70   was the fifth p
351f0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
35200 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
35210 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20  ion_v2()..**.** 
35220 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74 65 64  ^It is permitted
35230 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c   to register mul
35240 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  tiple implementa
35250 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
35260 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77  e.** functions w
35270 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d  ith the same nam
35280 65 20 62 75 74 20 77 69 74 68 20 65 69 74 68 65  e but with eithe
35290 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62  r differing numb
352a0 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65  ers of.** argume
352b0 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67  nts or differing
352c0 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
352d0 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c  encodings.  ^SQL
352e0 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20  ite will use.** 
352f0 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
35300 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f  on that most clo
35310 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65  sely matches the
35320 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 74 68   way in which th
35330 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f  e.** SQL functio
35340 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41 20 66  n is used.  ^A f
35350 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
35360 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f  tation with a no
35370 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41  n-negative.** nA
35380 72 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rg parameter is 
35390 61 20 62 65 74 74 65 72 20 6d 61 74 63 68 20 74  a better match t
353a0 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69  han a function i
353b0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
353c0 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65  th.** a negative
353d0 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 74   nArg.  ^A funct
353e0 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70 72  ion where the pr
353f0 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63  eferred text enc
35400 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73  oding.** matches
35410 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e   the database en
35420 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74 74  coding is a bett
35430 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e  er.** match than
35440 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72   a function wher
35450 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69  e the encoding i
35460 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a  s different.  .*
35470 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68  * ^A function wh
35480 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ere the encoding
35490 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 20 62   difference is b
354a0 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61  etween UTF16le a
354b0 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73  nd UTF16be.** is
354c0 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20   a closer match 
354d0 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20  than a function 
354e0 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69  where the encodi
354f0 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73  ng difference is
35500 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38  .** between UTF8
35510 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a   and UTF16..**.*
35520 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63  * ^Built-in func
35530 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65  tions may be ove
35540 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61  rloaded by new a
35550 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
35560 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a  ed functions..**
35570 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74  .** ^An applicat
35580 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
35590 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65  tion is permitte
355a0 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a  d to call other.
355b0 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ** SQLite interf
355c0 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20  aces.  However, 
355d0 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20  such calls must 
355e0 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65  not.** close the
355f0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
35600 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a  tion nor finaliz
35610 65 20 6f 72 20 72 65 73 65 74 20 74 68 65 20 70  e or reset the p
35620 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65  repared.** state
35630 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68  ment in which th
35640 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  e function is ru
35650 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71  nning..*/.int sq
35660 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
35670 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33  ction(.  sqlite3
35680 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68   *db,.  const ch
35690 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d  ar *zFunctionNam
356a0 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20  e,.  int nArg,. 
356b0 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20   int eTextRep,. 
356c0 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76   void *pApp,.  v
356d0 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c  oid (*xFunc)(sql
356e0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
356f0 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
35700 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74  *),.  void (*xSt
35710 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ep)(sqlite3_cont
35720 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
35730 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
35740 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69  d (*xFinal)(sqli
35750 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b  te3_context*).);
35760 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
35770 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a  ate_function16(.
35780 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20    sqlite3 *db,. 
35790 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75   const void *zFu
357a0 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e  nctionName,.  in
357b0 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54  t nArg,.  int eT
357c0 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a  extRep,.  void *
357d0 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78  pApp,.  void (*x
357e0 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f  Func)(sqlite3_co
357f0 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
35800 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
35810 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c  oid (*xStep)(sql
35820 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
35830 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
35840 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69  *),.  void (*xFi
35850 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nal)(sqlite3_con
35860 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71  text*).);.int sq
35870 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
35880 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69  ction_v2(.  sqli
35890 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74  te3 *db,.  const
358a0 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e   char *zFunction
358b0 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67  Name,.  int nArg
358c0 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
358d0 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a  ,.  void *pApp,.
358e0 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28    void (*xFunc)(
358f0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
35900 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
35910 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
35920 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63  xStep)(sqlite3_c
35930 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
35940 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
35950 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73  void (*xFinal)(s
35960 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
35970 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72  ,.  void(*xDestr
35980 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f  oy)(void*).);../
35990 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
359a0 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a  ext Encodings.**
359b0 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
359c0 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65  nt define intege
359d0 72 20 63 6f 64 65 73 20 74 68 61 74 20 72 65 70  r codes that rep
359e0 72 65 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f  resent the vario
359f0 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64  us.** text encod
35a00 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20 62  ings supported b
35a10 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65  y SQLite..*/.#de
35a20 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38  fine SQLITE_UTF8
35a30 20 20 20 20 20 20 20 20 20 20 20 31 20 20 20 20             1    
35a40 2f 2a 20 49 4d 50 3a 20 52 2d 33 37 35 31 34 2d  /* IMP: R-37514-
35a50 33 35 35 36 36 20 2a 2f 0a 23 64 65 66 69 6e 65  35566 */.#define
35a60 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20   SQLITE_UTF16LE 
35a70 20 20 20 20 20 20 20 32 20 20 20 20 2f 2a 20 49         2    /* I
35a80 4d 50 3a 20 52 2d 30 33 33 37 31 2d 33 37 36 33  MP: R-03371-3763
35a90 37 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  7 */.#define SQL
35aa0 49 54 45 5f 55 54 46 31 36 42 45 20 20 20 20 20  ITE_UTF16BE     
35ab0 20 20 20 33 20 20 20 20 2f 2a 20 49 4d 50 3a 20     3    /* IMP: 
35ac0 52 2d 35 31 39 37 31 2d 33 34 31 35 34 20 2a 2f  R-51971-34154 */
35ad0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
35ae0 55 54 46 31 36 20 20 20 20 20 20 20 20 20 20 34  UTF16          4
35af0 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76      /* Use nativ
35b00 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a  e byte order */.
35b10 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
35b20 4e 59 20 20 20 20 20 20 20 20 20 20 20 20 35 20  NY            5 
35b30 20 20 20 2f 2a 20 44 65 70 72 65 63 61 74 65 64     /* Deprecated
35b40 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
35b50 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44  TE_UTF16_ALIGNED
35b60 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65    8    /* sqlite
35b70 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
35b80 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a  on only */../*.*
35b90 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63  * CAPI3REF: Func
35ba0 74 69 6f 6e 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a  tion Flags.**.**
35bb0 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
35bc0 20 6d 61 79 20 62 65 20 4f 52 65 64 20 74 6f 67   may be ORed tog
35bd0 65 74 68 65 72 20 77 69 74 68 20 74 68 65 20 0a  ether with the .
35be0 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20  ** [SQLITE_UTF8 
35bf0 7c 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74  | preferred text
35c00 20 65 6e 63 6f 64 69 6e 67 5d 20 61 73 20 74 68   encoding] as th
35c10 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
35c20 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33  t.** to [sqlite3
35c30 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
35c40 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72  ()], [sqlite3_cr
35c50 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
35c60 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  )], or.** [sqlit
35c70 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
35c80 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 23 64 65  on_v2()]..*/.#de
35c90 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 45  fine SQLITE_DETE
35ca0 52 4d 49 4e 49 53 54 49 43 20 20 20 20 30 78 38  RMINISTIC    0x8
35cb0 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  00../*.** CAPI3R
35cc0 45 46 3a 20 44 65 70 72 65 63 61 74 65 64 20 46  EF: Deprecated F
35cd0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52  unctions.** DEPR
35ce0 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65  ECATED.**.** The
35cf0 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  se functions are
35d00 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20   [deprecated].  
35d10 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e  In order to main
35d20 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64  tain.** backward
35d30 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  s compatibility 
35d40 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c  with older code,
35d50 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
35d60 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f   continue .** to
35d70 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20   be supported.  
35d80 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70  However, new app
35d90 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  lications should
35da0 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73   avoid.** the us
35db0 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74  e of these funct
35dc0 69 6f 6e 73 2e 20 20 54 6f 20 65 6e 63 6f 75 72  ions.  To encour
35dd0 61 67 65 20 70 72 6f 67 72 61 6d 6d 65 72 73 20  age programmers 
35de0 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 73  to avoid.** thes
35df0 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20  e functions, we 
35e00 77 69 6c 6c 20 6e 6f 74 20 65 78 70 6c 61 69 6e  will not explain
35e10 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a   what they do..*
35e20 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  /.#ifndef SQLITE
35e30 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44  _OMIT_DEPRECATED
35e40 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
35e50 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 61  ED int sqlite3_a
35e60 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73  ggregate_count(s
35e70 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
35e80 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
35e90 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
35ea0 65 78 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f  expired(sqlite3_
35eb0 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44  stmt*);.SQLITE_D
35ec0 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
35ed0 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62  lite3_transfer_b
35ee0 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f  indings(sqlite3_
35ef0 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73  stmt*, sqlite3_s
35f00 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45  tmt*);.SQLITE_DE
35f10 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
35f20 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f  ite3_global_reco
35f30 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54  ver(void);.SQLIT
35f40 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69  E_DEPRECATED voi
35f50 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64  d sqlite3_thread
35f60 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a  _cleanup(void);.
35f70 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
35f80 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65  D int sqlite3_me
35f90 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28  mory_alarm(void(
35fa0 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
35fb0 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 0a 20 20 20  _int64,int),.   
35fc0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
35fd0 20 20 20 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33     void*,sqlite3
35fe0 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a  _int64);.#endif.
35ff0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
36000 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 56   Obtaining SQL V
36010 61 6c 75 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  alues.** METHOD:
36020 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 0a 2a   sqlite3_value.*
36030 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75  *.** The C-langu
36040 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  age implementati
36050 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69  on of SQL functi
36060 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74  ons and aggregat
36070 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20  es uses.** this 
36080 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65  set of interface
36090 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63   routines to acc
360a0 65 73 73 20 74 68 65 20 70 61 72 61 6d 65 74 65  ess the paramete
360b0 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74  r values on.** t
360c0 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61  he function or a
360d0 67 67 72 65 67 61 74 65 2e 20 20 0a 2a 2a 0a 2a  ggregate.  .**.*
360e0 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72  * The xFunc (for
360f0 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e   scalar function
36100 73 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72  s) or xStep (for
36110 20 61 67 67 72 65 67 61 74 65 73 29 20 70 61 72   aggregates) par
36120 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73  ameters.** to [s
36130 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
36140 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  nction()] and [s
36150 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
36160 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64  nction16()].** d
36170 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20  efine callbacks 
36180 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74  that implement t
36190 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  he SQL functions
361a0 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e   and aggregates.
361b0 0a 2a 2a 20 54 68 65 20 33 72 64 20 70 61 72 61  .** The 3rd para
361c0 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65 20 63  meter to these c
361d0 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61  allbacks is an a
361e0 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
361f0 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65   to.** [protecte
36200 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
36210 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65   objects.  There
36220 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33   is one [sqlite3
36230 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66  _value] object f
36240 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d  or.** each param
36250 65 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20  eter to the SQL 
36260 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65  function.  These
36270 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73   routines are us
36280 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74  ed to.** extract
36290 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65   values from the
362a0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
362b0 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20   objects..**.** 
362c0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77  These routines w
362d0 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70  ork only with [p
362e0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
362f0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
36300 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20  .** Any attempt 
36310 74 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f 75  to use these rou
36320 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70  tines on an [unp
36330 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
36340 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63  _value].** objec
36350 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64  t results in und
36360 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e  efined behavior.
36370 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
36380 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74  utines work just
36390 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73   like the corres
363a0 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20  ponding [column 
363b0 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73  access functions
363c0 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74  ].** except that
363d0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
363e0 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70  take a single [p
363f0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
36400 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a  _value] object.*
36410 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61  * pointer instea
36420 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f  d of a [sqlite3_
36430 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61  stmt*] pointer a
36440 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f  nd an integer co
36450 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a  lumn number..**.
36460 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
36470 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69  value_text16() i
36480 6e 74 65 72 66 61 63 65 20 65 78 74 72 61 63 74  nterface extract
36490 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  s a UTF-16 strin
364a0 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69  g.** in the nati
364b0 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66  ve byte-order of
364c0 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e   the host machin
364d0 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69  e.  ^The.** sqli
364e0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
364f0 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  be() and sqlite3
36500 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28  _value_text16le(
36510 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
36520 65 78 74 72 61 63 74 20 55 54 46 2d 31 36 20 73  extract UTF-16 s
36530 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e  trings as big-en
36540 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d  dian and little-
36550 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69 76  endian respectiv
36560 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ely..**.** ^(The
36570 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e   sqlite3_value_n
36580 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e  umeric_type() in
36590 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
365a0 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d   to apply.** num
365b0 65 72 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f  eric affinity to
365c0 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69   the value.  Thi
365d0 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20  s means that an 
365e0 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61  attempt is.** ma
365f0 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  de to convert th
36600 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e  e value to an in
36610 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e  teger or floatin
36620 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20  g point.  If.** 
36630 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f  such a conversio
36640 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69  n is possible wi
36650 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e  thout loss of in
36660 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74  formation (in ot
36670 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66  her.** words, if
36680 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 61 20   the value is a 
36690 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b  string that look
366a0 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29  s like a number)
366b0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e  .** then the con
366c0 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f  version is perfo
366d0 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65  rmed.  Otherwise
366e0 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f   no conversion o
366f0 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53  ccurs..** The [S
36700 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20  QLITE_INTEGER | 
36710 64 61 74 61 74 79 70 65 5d 20 61 66 74 65 72 20  datatype] after 
36720 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65  conversion is re
36730 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20  turned.)^.**.** 
36740 50 6c 65 61 73 65 20 70 61 79 20 70 61 72 74 69  Please pay parti
36750 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20  cular attention 
36760 74 6f 20 74 68 65 20 66 61 63 74 20 74 68 61 74  to the fact that
36770 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72 65 74   the pointer ret
36780 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  urned.** from [s
36790 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f  qlite3_value_blo
367a0 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  b()], [sqlite3_v
367b0 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72  alue_text()], or
367c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
367d0 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e  ue_text16()] can
367e0 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20   be invalidated 
367f0 62 79 20 61 20 73 75 62 73 65 71 75 65 6e 74 20  by a subsequent 
36800 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
36810 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
36820 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
36830 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b  ue_bytes16()], [
36840 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
36850 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71  xt()],.** or [sq
36860 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
36870 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  16()]..**.** The
36880 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74  se routines must
36890 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
368a0 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
368b0 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75  as.** the SQL fu
368c0 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70  nction that supp
368d0 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65  lied the [sqlite
368e0 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65  3_value*] parame
368f0 74 65 72 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76  ters..*/.const v
36900 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
36910 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  ue_blob(sqlite3_
36920 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
36930 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
36940 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
36950 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
36960 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69  lue_bytes16(sqli
36970 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75  te3_value*);.dou
36980 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ble sqlite3_valu
36990 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  e_double(sqlite3
369a0 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
369b0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28  lite3_value_int(
369c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
369d0 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
369e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
369f0 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  64(sqlite3_value
36a00 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e  *);.const unsign
36a10 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  ed char *sqlite3
36a20 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69  _value_text(sqli
36a30 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
36a40 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
36a50 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71  _value_text16(sq
36a60 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63  lite3_value*);.c
36a70 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
36a80 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
36a90 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
36aa0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
36ab0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
36ac0 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61  t16be(sqlite3_va
36ad0 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
36ae0 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71  e3_value_type(sq
36af0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
36b00 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
36b10 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71  _numeric_type(sq
36b20 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a  lite3_value*);..
36b30 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
36b40 46 69 6e 64 69 6e 67 20 54 68 65 20 53 75 62 74  Finding The Subt
36b50 79 70 65 20 4f 66 20 53 51 4c 20 56 61 6c 75 65  ype Of SQL Value
36b60 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
36b70 69 74 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a  ite3_value.**.**
36b80 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c   The sqlite3_val
36b90 75 65 5f 73 75 62 74 79 70 65 28 56 29 20 66 75  ue_subtype(V) fu
36ba0 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
36bb0 68 65 20 73 75 62 74 79 70 65 20 66 6f 72 0a 2a  he subtype for.*
36bc0 2a 20 61 6e 20 5b 61 70 70 6c 69 63 61 74 69 6f  * an [applicatio
36bd0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
36be0 6e 63 74 69 6f 6e 5d 20 61 72 67 75 6d 65 6e 74  nction] argument
36bf0 20 56 2e 20 20 54 68 65 20 73 75 62 74 79 70 65   V.  The subtype
36c00 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
36c10 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 70  can be used to p
36c20 61 73 73 20 61 20 6c 69 6d 69 74 65 64 20 61 6d  ass a limited am
36c30 6f 75 6e 74 20 6f 66 20 63 6f 6e 74 65 78 74 20  ount of context 
36c40 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 53 51 4c 20  from.** one SQL 
36c50 66 75 6e 63 74 69 6f 6e 20 74 6f 20 61 6e 6f 74  function to anot
36c60 68 65 72 2e 20 20 55 73 65 20 74 68 65 20 5b 73  her.  Use the [s
36c70 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 73 75  qlite3_result_su
36c80 62 74 79 70 65 28 29 5d 0a 2a 2a 20 72 6f 75 74  btype()].** rout
36c90 69 6e 65 20 74 6f 20 73 65 74 20 74 68 65 20 73  ine to set the s
36ca0 75 62 74 79 70 65 20 66 6f 72 20 74 68 65 20 72  ubtype for the r
36cb0 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 61  eturn value of a
36cc0 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a  n SQL function..
36cd0 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b  **.** SQLite mak
36ce0 65 73 20 6e 6f 20 75 73 65 20 6f 66 20 73 75 62  es no use of sub
36cf0 74 79 70 65 20 69 74 73 65 6c 66 2e 20 20 49 74  type itself.  It
36d00 20 6d 65 72 65 6c 79 20 70 61 73 73 65 73 20 74   merely passes t
36d10 68 65 20 73 75 62 74 79 70 65 0a 2a 2a 20 66 72  he subtype.** fr
36d20 6f 6d 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66  om the result of
36d30 20 6f 6e 65 20 5b 61 70 70 6c 69 63 61 74 69 6f   one [applicatio
36d40 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
36d50 6e 63 74 69 6f 6e 5d 20 69 6e 74 6f 20 74 68 65  nction] into the
36d60 0a 2a 2a 20 69 6e 70 75 74 20 6f 66 20 61 6e 6f  .** input of ano
36d70 74 68 65 72 2e 0a 2a 2f 0a 75 6e 73 69 67 6e 65  ther..*/.unsigne
36d80 64 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  d int sqlite3_va
36d90 6c 75 65 5f 73 75 62 74 79 70 65 28 73 71 6c 69  lue_subtype(sqli
36da0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a  te3_value*);../*
36db0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
36dc0 70 79 20 41 6e 64 20 46 72 65 65 20 53 51 4c 20  py And Free SQL 
36dd0 56 61 6c 75 65 73 0a 2a 2a 20 4d 45 54 48 4f 44  Values.** METHOD
36de0 3a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 0a  : sqlite3_value.
36df0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
36e00 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 56 29 20  e3_value_dup(V) 
36e10 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20  interface makes 
36e20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73  a copy of the [s
36e30 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a  qlite3_value].**
36e40 20 6f 62 6a 65 63 74 20 44 20 61 6e 64 20 72 65   object D and re
36e50 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
36e60 74 6f 20 74 68 61 74 20 63 6f 70 79 2e 20 20 5e  to that copy.  ^
36e70 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  The [sqlite3_val
36e80 75 65 5d 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  ue] returned.** 
36e90 69 73 20 61 20 5b 70 72 6f 74 65 63 74 65 64 20  is a [protected 
36ea0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
36eb0 62 6a 65 63 74 20 65 76 65 6e 20 69 66 20 74 68  bject even if th
36ec0 65 20 69 6e 70 75 74 20 69 73 20 6e 6f 74 2e 0a  e input is not..
36ed0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
36ee0 76 61 6c 75 65 5f 64 75 70 28 56 29 20 69 6e 74  value_dup(V) int
36ef0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 4e  erface returns N
36f00 55 4c 4c 20 69 66 20 56 20 69 73 20 4e 55 4c 4c  ULL if V is NULL
36f10 20 6f 72 20 69 66 20 61 0a 2a 2a 20 6d 65 6d 6f   or if a.** memo
36f20 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
36f30 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ils..**.** ^The 
36f40 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 66 72  sqlite3_value_fr
36f50 65 65 28 56 29 20 69 6e 74 65 72 66 61 63 65 20  ee(V) interface 
36f60 66 72 65 65 73 20 61 6e 20 5b 73 71 6c 69 74 65  frees an [sqlite
36f70 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a  3_value] object.
36f80 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62  ** previously ob
36f90 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
36fa0 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 29  ite3_value_dup()
36fb0 5d 2e 20 20 5e 49 66 20 56 20 69 73 20 61 20 4e  ].  ^If V is a N
36fc0 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  ULL pointer.** t
36fd0 68 65 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  hen sqlite3_valu
36fe0 65 5f 66 72 65 65 28 56 29 20 69 73 20 61 20 68  e_free(V) is a h
36ff0 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a  armless no-op..*
37000 2f 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  /.sqlite3_value 
37010 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64  *sqlite3_value_d
37020 75 70 28 63 6f 6e 73 74 20 73 71 6c 69 74 65 33  up(const sqlite3
37030 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73  _value*);.void s
37040 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 66 72 65  qlite3_value_fre
37050 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
37060 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
37070 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65  EF: Obtain Aggre
37080 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f  gate Function Co
37090 6e 74 65 78 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  ntext.** METHOD:
370a0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
370b0 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74  .**.** Implement
370c0 61 74 69 6f 6e 73 20 6f 66 20 61 67 67 72 65 67  ations of aggreg
370d0 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ate SQL function
370e0 73 20 75 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f  s use this.** ro
370f0 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74  utine to allocat
37100 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f  e memory for sto
37110 72 69 6e 67 20 74 68 65 69 72 20 73 74 61 74 65  ring their state
37120 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
37130 73 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69  st time the sqli
37140 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
37150 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69  ntext(C,N) routi
37160 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a  ne is called .**
37170 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
37180 72 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  r aggregate func
37190 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20  tion, SQLite.** 
371a0 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d  allocates N of m
371b0 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75  emory, zeroes ou
371c0 74 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61  t that memory, a
371d0 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  nd returns a poi
371e0 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e  nter.** to the n
371f0 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73  ew memory. ^On s
37200 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71  econd and subseq
37210 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  uent calls to.**
37220 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
37230 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f 72  te_context() for
37240 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67   the same aggreg
37250 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73  ate function ins
37260 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61  tance,.** the sa
37270 6d 65 20 62 75 66 66 65 72 20 69 73 20 72 65 74  me buffer is ret
37280 75 72 6e 65 64 2e 20 20 53 71 6c 69 74 65 33 5f  urned.  Sqlite3_
37290 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
372a0 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a  t() is normally.
372b0 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66  ** called once f
372c0 6f 72 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69  or each invocati
372d0 6f 6e 20 6f 66 20 74 68 65 20 78 53 74 65 70 20  on of the xStep 
372e0 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68 65  callback and the
372f0 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69  n one.** last ti
37300 6d 65 20 77 68 65 6e 20 74 68 65 20 78 46 69 6e  me when the xFin
37310 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  al callback is i
37320 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20  nvoked.  ^(When 
37330 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a  no rows match.**
37340 20 61 6e 20 61 67 67 72 65 67 61 74 65 20 71 75   an aggregate qu
37350 65 72 79 2c 20 74 68 65 20 78 53 74 65 70 28 29  ery, the xStep()
37360 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65   callback of the
37370 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
37380 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ion.** implement
37390 61 74 69 6f 6e 20 69 73 20 6e 65 76 65 72 20 63  ation is never c
373a0 61 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e 61 6c  alled and xFinal
373b0 28 29 20 69 73 20 63 61 6c 6c 65 64 20 65 78 61  () is called exa
373c0 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e  ctly once..** In
373d0 20 74 68 6f 73 65 20 63 61 73 65 73 2c 20 73 71   those cases, sq
373e0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
373f0 63 6f 6e 74 65 78 74 28 29 20 6d 69 67 68 74 20  context() might 
37400 62 65 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68  be called for th
37410 65 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d 65 20  e.** first time 
37420 66 72 6f 6d 20 77 69 74 68 69 6e 20 78 46 69 6e  from within xFin
37430 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  al().)^.**.** ^T
37440 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  he sqlite3_aggre
37450 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e  gate_context(C,N
37460 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
37470 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
37480 20 0a 2a 2a 20 77 68 65 6e 20 66 69 72 73 74 20   .** when first 
37490 63 61 6c 6c 65 64 20 69 66 20 4e 20 69 73 20 6c  called if N is l
374a0 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61  ess than or equa
374b0 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20  l to zero or if 
374c0 61 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  a memory.** allo
374d0 63 61 74 65 20 65 72 72 6f 72 20 6f 63 63 75 72  cate error occur
374e0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61  s..**.** ^(The a
374f0 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63 65 20 61  mount of space a
37500 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69  llocated by sqli
37510 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
37520 6e 74 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a  ntext(C,N) is.**
37530 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74   determined by t
37540 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 6f  he N parameter o
37550 6e 20 66 69 72 73 74 20 73 75 63 63 65 73 73 66  n first successf
37560 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69  ul call.  Changi
37570 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20  ng the.** value 
37580 6f 66 20 4e 20 69 6e 20 73 75 62 73 65 71 75 65  of N in subseque
37590 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  nt call to sqlit
375a0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
375b0 74 65 78 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a  text() within.**
375c0 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67   the same aggreg
375d0 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73  ate function ins
375e0 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72  tance will not r
375f0 65 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79  esize the memory
37600 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29  .** allocation.)
37610 5e 20 20 57 69 74 68 69 6e 20 74 68 65 20 78 46  ^  Within the xF
37620 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 2c 20 69  inal callback, i
37630 74 20 69 73 20 63 75 73 74 6f 6d 61 72 79 20 74  t is customary t
37640 6f 20 73 65 74 0a 2a 2a 20 4e 3d 30 20 69 6e 20  o set.** N=0 in 
37650 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
37660 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
37670 78 74 28 43 2c 4e 29 20 73 6f 20 74 68 61 74 20  xt(C,N) so that 
37680 6e 6f 20 0a 2a 2a 20 70 6f 69 6e 74 6c 65 73 73  no .** pointless
37690 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
376a0 6f 6e 73 20 6f 63 63 75 72 2e 0a 2a 2a 0a 2a 2a  ons occur..**.**
376b0 20 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74   ^SQLite automat
376c0 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65  ically frees the
376d0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65   memory allocate
376e0 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33  d by .** sqlite3
376f0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
37700 78 74 28 29 20 77 68 65 6e 20 74 68 65 20 61 67  xt() when the ag
37710 67 72 65 67 61 74 65 20 71 75 65 72 79 20 63 6f  gregate query co
37720 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  ncludes..**.** T
37730 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
37740 65 72 20 6d 75 73 74 20 62 65 20 61 20 63 6f 70  er must be a cop
37750 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  y of the.** [sql
37760 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53  ite3_context | S
37770 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74  QL function cont
37780 65 78 74 5d 20 74 68 61 74 20 69 73 20 74 68 65  ext] that is the
37790 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
377a0 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53 74 65 70  .** to the xStep
377b0 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62   or xFinal callb
377c0 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74  ack routine that
377d0 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20   implements the 
377e0 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e  aggregate.** fun
377f0 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  ction..**.** Thi
37800 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62  s routine must b
37810 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
37820 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
37830 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67   which.** the ag
37840 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
37850 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
37860 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
37870 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
37880 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ext(sqlite3_cont
37890 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73  ext*, int nBytes
378a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
378b0 45 46 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f  EF: User Data Fo
378c0 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d  r Functions.** M
378d0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63  ETHOD: sqlite3_c
378e0 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  ontext.**.** ^Th
378f0 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64  e sqlite3_user_d
37900 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20  ata() interface 
37910 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f  returns a copy o
37920 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72  f.** the pointer
37930 20 74 68 61 74 20 77 61 73 20 74 68 65 20 70 55   that was the pU
37940 73 65 72 44 61 74 61 20 70 61 72 61 6d 65 74 65  serData paramete
37950 72 20 28 74 68 65 20 35 74 68 20 70 61 72 61 6d  r (the 5th param
37960 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20  eter).** of the 
37970 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
37980 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61  function()].** a
37990 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
379a0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
379b0 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f   routines that o
379c0 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67  riginally.** reg
379d0 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c  istered the appl
379e0 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20  ication defined 
379f0 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
37a00 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73  This routine mus
37a10 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
37a20 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
37a30 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
37a40 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
37a50 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73  ined function is
37a60 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69   running..*/.voi
37a70 64 20 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  d *sqlite3_user_
37a80 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e  data(sqlite3_con
37a90 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  text*);../*.** C
37aa0 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73  API3REF: Databas
37ab0 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72  e Connection For
37ac0 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45   Functions.** ME
37ad0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f  THOD: sqlite3_co
37ae0 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ntext.**.** ^The
37af0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
37b00 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74  _db_handle() int
37b10 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
37b20 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
37b30 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
37b40 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
37b50 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 70 61  ion] (the 1st pa
37b60 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74  rameter).** of t
37b70 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
37b80 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a  te_function()].*
37b90 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  * and [sqlite3_c
37ba0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
37bb0 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61  ()] routines tha
37bc0 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20  t originally.** 
37bd0 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61  registered the a
37be0 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e  pplication defin
37bf0 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a  ed function..*/.
37c00 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33  sqlite3 *sqlite3
37c10 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64  _context_db_hand
37c20 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  le(sqlite3_conte
37c30 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  xt*);../*.** CAP
37c40 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20  I3REF: Function 
37c50 41 75 78 69 6c 69 61 72 79 20 44 61 74 61 0a 2a  Auxiliary Data.*
37c60 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
37c70 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20  3_context.**.** 
37c80 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
37c90 6d 61 79 20 62 65 20 75 73 65 64 20 62 79 20 28  may be used by (
37ca0 6e 6f 6e 2d 61 67 67 72 65 67 61 74 65 29 20 53  non-aggregate) S
37cb0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a  QL functions to.
37cc0 2a 2a 20 61 73 73 6f 63 69 61 74 65 20 6d 65 74  ** associate met
37cd0 61 64 61 74 61 20 77 69 74 68 20 61 72 67 75 6d  adata with argum
37ce0 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 66 20 74  ent values. If t
37cf0 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20 69 73  he same value is
37d00 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75   passed to.** mu
37d10 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f  ltiple invocatio
37d20 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 53  ns of the same S
37d30 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75 72 69  QL function duri
37d40 6e 67 20 71 75 65 72 79 20 65 78 65 63 75 74 69  ng query executi
37d50 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d  on, under.** som
37d60 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20  e circumstances 
37d70 74 68 65 20 61 73 73 6f 63 69 61 74 65 64 20 6d  the associated m
37d80 65 74 61 64 61 74 61 20 6d 61 79 20 62 65 20 70  etadata may be p
37d90 72 65 73 65 72 76 65 64 2e 20 20 41 6e 20 65 78  reserved.  An ex
37da0 61 6d 70 6c 65 0a 2a 2a 20 6f 66 20 77 68 65 72  ample.** of wher
37db0 65 20 74 68 69 73 20 6d 69 67 68 74 20 62 65 20  e this might be 
37dc0 75 73 65 66 75 6c 20 69 73 20 69 6e 20 61 20 72  useful is in a r
37dd0 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f  egular-expressio
37de0 6e 20 6d 61 74 63 68 69 6e 67 0a 2a 2a 20 66 75  n matching.** fu
37df0 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70  nction. The comp
37e00 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20  iled version of 
37e10 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72  the regular expr
37e20 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 73 74  ession can be st
37e30 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64  ored as.** metad
37e40 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 77  ata associated w
37e50 69 74 68 20 74 68 65 20 70 61 74 74 65 72 6e 20  ith the pattern 
37e60 73 74 72 69 6e 67 2e 20 20 0a 2a 2a 20 54 68 65  string.  .** The
37e70 6e 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  n as long as the
37e80 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 20   pattern string 
37e90 72 65 6d 61 69 6e 73 20 74 68 65 20 73 61 6d 65  remains the same
37ea0 2c 0a 2a 2a 20 74 68 65 20 63 6f 6d 70 69 6c 65  ,.** the compile
37eb0 64 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73  d regular expres
37ec0 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73  sion can be reus
37ed0 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a  ed on multiple.*
37ee0 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66  * invocations of
37ef0 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
37f00 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  on..**.** ^The s
37f10 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
37f20 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ta() interface r
37f30 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
37f40 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74 61   to the metadata
37f50 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62  .** associated b
37f60 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65  y the sqlite3_se
37f70 74 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e 63  t_auxdata() func
37f80 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74  tion with the Nt
37f90 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61  h argument.** va
37fa0 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69  lue to the appli
37fb0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
37fc0 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 74 68 65  unction. ^If the
37fd0 72 65 20 69 73 20 6e 6f 20 6d 65 74 61 64 61 74  re is no metadat
37fe0 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  a.** associated 
37ff0 77 69 74 68 20 74 68 65 20 66 75 6e 63 74 69 6f  with the functio
38000 6e 20 61 72 67 75 6d 65 6e 74 2c 20 74 68 69 73  n argument, this
38010 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78   sqlite3_get_aux
38020 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
38030 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 4e 55  .** returns a NU
38040 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
38050 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73  * ^The sqlite3_s
38060 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50  et_auxdata(C,N,P
38070 2c 58 29 20 69 6e 74 65 72 66 61 63 65 20 73 61  ,X) interface sa
38080 76 65 73 20 50 20 61 73 20 6d 65 74 61 64 61 74  ves P as metadat
38090 61 20 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a  a for the N-th.*
380a0 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68  * argument of th
380b0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
380c0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20  fined function. 
380d0 20 5e 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20   ^Subsequent.** 
380e0 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
380f0 5f 67 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e  _get_auxdata(C,N
38100 29 20 72 65 74 75 72 6e 20 50 20 66 72 6f 6d 20  ) return P from 
38110 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a  the most recent.
38120 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  ** sqlite3_set_a
38130 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20  uxdata(C,N,P,X) 
38140 63 61 6c 6c 20 69 66 20 74 68 65 20 6d 65 74 61  call if the meta
38150 64 61 74 61 20 69 73 20 73 74 69 6c 6c 20 76 61  data is still va
38160 6c 69 64 20 6f 72 0a 2a 2a 20 4e 55 4c 4c 20 69  lid or.** NULL i
38170 66 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 68  f the metadata h
38180 61 73 20 62 65 65 6e 20 64 69 73 63 61 72 64 65  as been discarde
38190 64 2e 0a 2a 2a 20 5e 41 66 74 65 72 20 65 61 63  d..** ^After eac
381a0 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  h call to sqlite
381b0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c  3_set_auxdata(C,
381c0 4e 2c 50 2c 58 29 20 77 68 65 72 65 20 58 20 69  N,P,X) where X i
381d0 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 53  s not NULL,.** S
381e0 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b  QLite will invok
381f0 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  e the destructor
38200 20 66 75 6e 63 74 69 6f 6e 20 58 20 77 69 74 68   function X with
38210 20 70 61 72 61 6d 65 74 65 72 20 50 20 65 78 61   parameter P exa
38220 63 74 6c 79 0a 2a 2a 20 6f 6e 63 65 2c 20 77 68  ctly.** once, wh
38230 65 6e 20 74 68 65 20 6d 65 74 61 64 61 74 61 20  en the metadata 
38240 69 73 20 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a  is discarded..**
38250 20 53 51 4c 69 74 65 20 69 73 20 66 72 65 65 20   SQLite is free 
38260 74 6f 20 64 69 73 63 61 72 64 20 74 68 65 20 6d  to discard the m
38270 65 74 61 64 61 74 61 20 61 74 20 61 6e 79 20 74  etadata at any t
38280 69 6d 65 2c 20 69 6e 63 6c 75 64 69 6e 67 3a 20  ime, including: 
38290 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5e 28 77  <ul>.** <li> ^(w
382a0 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f  hen the correspo
382b0 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70  nding function p
382c0 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73  arameter changes
382d0 29 5e 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5e  )^, or.** <li> ^
382e0 28 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72  (when [sqlite3_r
382f0 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  eset()] or [sqli
38300 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
38310 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68  is called for th
38320 65 0a 2a 2a 20 20 20 20 20 20 53 51 4c 20 73 74  e.**      SQL st
38330 61 74 65 6d 65 6e 74 29 5e 2c 20 6f 72 0a 2a 2a  atement)^, or.**
38340 20 3c 6c 69 3e 20 5e 28 77 68 65 6e 20 73 71 6c   <li> ^(when sql
38350 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
38360 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 67  () is invoked ag
38370 61 69 6e 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a  ain on the same.
38380 2a 2a 20 20 20 20 20 20 20 70 61 72 61 6d 65 74  **       paramet
38390 65 72 29 5e 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e  er)^, or.** <li>
383a0 20 5e 28 64 75 72 69 6e 67 20 74 68 65 20 6f 72   ^(during the or
383b0 69 67 69 6e 61 6c 20 73 71 6c 69 74 65 33 5f 73  iginal sqlite3_s
383c0 65 74 5f 61 75 78 64 61 74 61 28 29 20 63 61 6c  et_auxdata() cal
383d0 6c 20 77 68 65 6e 20 61 20 6d 65 6d 6f 72 79 20  l when a memory 
383e0 0a 2a 2a 20 20 20 20 20 20 61 6c 6c 6f 63 61 74  .**      allocat
383f0 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ion error occurs
38400 2e 29 5e 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .)^ </ul>.**.** 
38410 4e 6f 74 65 20 74 68 65 20 6c 61 73 74 20 62 75  Note the last bu
38420 6c 6c 65 74 20 69 6e 20 70 61 72 74 69 63 75 6c  llet in particul
38430 61 72 2e 20 20 54 68 65 20 64 65 73 74 72 75 63  ar.  The destruc
38440 74 6f 72 20 58 20 69 6e 20 0a 2a 2a 20 73 71 6c  tor X in .** sql
38450 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
38460 28 43 2c 4e 2c 50 2c 58 29 20 6d 69 67 68 74 20  (C,N,P,X) might 
38470 62 65 20 63 61 6c 6c 65 64 20 69 6d 6d 65 64 69  be called immedi
38480 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 20 74 68  ately, before th
38490 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74  e.** sqlite3_set
384a0 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72  _auxdata() inter
384b0 66 61 63 65 20 65 76 65 6e 20 72 65 74 75 72 6e  face even return
384c0 73 2e 20 20 48 65 6e 63 65 20 73 71 6c 69 74 65  s.  Hence sqlite
384d0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 0a  3_set_auxdata().
384e0 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 63 61 6c  ** should be cal
384f0 6c 65 64 20 6e 65 61 72 20 74 68 65 20 65 6e 64  led near the end
38500 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
38510 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
38520 61 6e 64 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74  and the.** funct
38530 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
38540 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 6d 61  on should not ma
38550 6b 65 20 61 6e 79 20 75 73 65 20 6f 66 20 50 20  ke any use of P 
38560 61 66 74 65 72 0a 2a 2a 20 73 71 6c 69 74 65 33  after.** sqlite3
38570 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 68  _set_auxdata() h
38580 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 2e 0a  as been called..
38590 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74  **.** ^(In pract
385a0 69 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73  ice, metadata is
385b0 20 70 72 65 73 65 72 76 65 64 20 62 65 74 77 65   preserved betwe
385c0 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c  en function call
385d0 73 20 66 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  s for.** functio
385e0 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74 68 61  n parameters tha
385f0 74 20 61 72 65 20 63 6f 6d 70 69 6c 65 2d 74 69  t are compile-ti
38600 6d 65 20 63 6f 6e 73 74 61 6e 74 73 2c 20 69 6e  me constants, in
38610 63 6c 75 64 69 6e 67 20 6c 69 74 65 72 61 6c 0a  cluding literal.
38620 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 5b 70  ** values and [p
38630 61 72 61 6d 65 74 65 72 73 5d 20 61 6e 64 20 65  arameters] and e
38640 78 70 72 65 73 73 69 6f 6e 73 20 63 6f 6d 70 6f  xpressions compo
38650 73 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  sed from the sam
38660 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  e.)^.**.** These
38670 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
38680 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
38690 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
386a0 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51   which.** the SQ
386b0 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  L function is ru
386c0 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  nning..*/.void *
386d0 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
386e0 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
386f0 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f  ext*, int N);.vo
38700 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  id sqlite3_set_a
38710 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63  uxdata(sqlite3_c
38720 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20  ontext*, int N, 
38730 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28  void*, void (*)(
38740 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a  void*));.../*.**
38750 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74   CAPI3REF: Const
38760 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70  ants Defining Sp
38770 65 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72  ecial Destructor
38780 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20   Behavior.**.** 
38790 54 68 65 73 65 20 61 72 65 20 73 70 65 63 69 61  These are specia
387a0 6c 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65  l values for the
387b0 20 64 65 73 74 72 75 63 74 6f 72 20 74 68 61 74   destructor that
387c0 20 69 73 20 70 61 73 73 65 64 20 69 6e 20 61 73   is passed in as
387d0 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72   the.** final ar
387