/ Hex Artifact Content
Login

Artifact 5894333db09c72e6a0c8b75d1e61f1a5b269ba35:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 64 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a  ed to operate..*
04e0: 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66  *.** The name of
04f0: 20 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72   this file under
0500: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d   configuration m
0510: 61 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71  anagement is "sq
0520: 6c 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54  lite.h.in"..** T
0530: 68 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65  he makefile make
0540: 73 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61  s some minor cha
0550: 6e 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c  nges to this fil
0560: 65 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72  e (such as inser
0570: 74 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73  ting.** the vers
0580: 69 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20  ion number) and 
0590: 63 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65  changes its name
05a0: 20 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20   to "sqlite3.h" 
05b0: 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68  as.** part of th
05c0: 65 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e  e build process.
05d0: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  .*/.#ifndef SQLI
05e0: 54 45 33 5f 48 0a 23 64 65 66 69 6e 65 20 53 51  TE3_H.#define SQ
05f0: 4c 49 54 45 33 5f 48 0a 23 69 6e 63 6c 75 64 65  LITE3_H.#include
0600: 20 3c 73 74 64 61 72 67 2e 68 3e 20 20 20 20 20   <stdarg.h>     
0610: 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72 20 74 68  /* Needed for th
0620: 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 66 20  e definition of 
0630: 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a  va_list */../*.*
0640: 2a 20 4d 61 6b 65 20 73 75 72 65 20 77 65 20 63  * Make sure we c
0650: 61 6e 20 63 61 6c 6c 20 74 68 69 73 20 73 74 75  an call this stu
0660: 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a  ff from C++..*/.
0670: 23 69 66 64 65 66 20 5f 5f 63 70 6c 75 73 70 6c  #ifdef __cpluspl
0680: 75 73 0a 65 78 74 65 72 6e 20 22 43 22 20 7b 0a  us.extern "C" {.
0690: 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 50  #endif.../*.** P
06a0: 72 6f 76 69 64 65 20 74 68 65 20 61 62 69 6c 69  rovide the abili
06b0: 74 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 6c  ty to override l
06c0: 69 6e 6b 61 67 65 20 66 65 61 74 75 72 65 73 20  inkage features 
06d0: 6f 66 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  of the interface
06e0: 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c  ..*/.#ifndef SQL
06f0: 49 54 45 5f 45 58 54 45 52 4e 0a 23 20 64 65 66  ITE_EXTERN.# def
0700: 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 54 45 52  ine SQLITE_EXTER
0710: 4e 20 65 78 74 65 72 6e 0a 23 65 6e 64 69 66 0a  N extern.#endif.
0720: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 41  #ifndef SQLITE_A
0730: 50 49 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  PI.# define SQLI
0740: 54 45 5f 41 50 49 0a 23 65 6e 64 69 66 0a 23 69  TE_API.#endif.#i
0750: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 43 44 45  fndef SQLITE_CDE
0760: 43 4c 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  CL.# define SQLI
0770: 54 45 5f 43 44 45 43 4c 0a 23 65 6e 64 69 66 0a  TE_CDECL.#endif.
0780: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 41  #ifndef SQLITE_A
0790: 50 49 43 41 4c 4c 0a 23 20 64 65 66 69 6e 65 20  PICALL.# define 
07a0: 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a 23  SQLITE_APICALL.#
07b0: 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51  endif.#ifndef SQ
07c0: 4c 49 54 45 5f 53 54 44 43 41 4c 4c 0a 23 20 64  LITE_STDCALL.# d
07d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 44  efine SQLITE_STD
07e0: 43 41 4c 4c 20 53 51 4c 49 54 45 5f 41 50 49 43  CALL SQLITE_APIC
07f0: 41 4c 4c 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64  ALL.#endif.#ifnd
0800: 65 66 20 53 51 4c 49 54 45 5f 43 41 4c 4c 42 41  ef SQLITE_CALLBA
0810: 43 4b 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  CK.# define SQLI
0820: 54 45 5f 43 41 4c 4c 42 41 43 4b 0a 23 65 6e 64  TE_CALLBACK.#end
0830: 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  if.#ifndef SQLIT
0840: 45 5f 53 59 53 41 50 49 0a 23 20 64 65 66 69 6e  E_SYSAPI.# defin
0850: 65 20 53 51 4c 49 54 45 5f 53 59 53 41 50 49 0a  e SQLITE_SYSAPI.
0860: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68  #endif../*.** Th
0870: 65 73 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73  ese no-op macros
0880: 20 61 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f   are used in fro
0890: 6e 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73  nt of interfaces
08a0: 20 74 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a   to mark those.*
08b0: 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 73 20  * interfaces as 
08c0: 65 69 74 68 65 72 20 64 65 70 72 65 63 61 74 65  either deprecate
08d0: 64 20 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61  d or experimenta
08e0: 6c 2e 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74  l.  New applicat
08f0: 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e  ions.** should n
0900: 6f 74 20 75 73 65 20 64 65 70 72 65 63 61 74 65  ot use deprecate
0910: 64 20 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74  d interfaces - t
0920: 68 65 79 20 61 72 65 20 73 75 70 70 6f 72 74 65  hey are supporte
0930: 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a  d for backwards.
0940: 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ** compatibility
0950: 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69 63 61 74   only.  Applicat
0960: 69 6f 6e 20 77 72 69 74 65 72 73 20 73 68 6f 75  ion writers shou
0970: 6c 64 20 62 65 20 61 77 61 72 65 20 74 68 61 74  ld be aware that
0980: 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e 74 61 6c  .** experimental
0990: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
09a0: 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
09b0: 65 20 69 6e 20 70 6f 69 6e 74 20 72 65 6c 65 61  e in point relea
09c0: 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ses..**.** These
09d0: 20 6d 61 63 72 6f 73 20 75 73 65 64 20 74 6f 20   macros used to 
09e0: 72 65 73 6f 6c 76 65 20 74 6f 20 76 61 72 69 6f  resolve to vario
09f0: 75 73 20 6b 69 6e 64 73 20 6f 66 20 63 6f 6d 70  us kinds of comp
0a00: 69 6c 65 72 20 6d 61 67 69 63 20 74 68 61 74 0a  iler magic that.
0a10: 2a 2a 20 77 6f 75 6c 64 20 67 65 6e 65 72 61 74  ** would generat
0a20: 65 20 77 61 72 6e 69 6e 67 20 6d 65 73 73 61 67  e warning messag
0a30: 65 73 20 77 68 65 6e 20 74 68 65 79 20 77 65 72  es when they wer
0a40: 65 20 75 73 65 64 2e 20 20 42 75 74 20 74 68 61  e used.  But tha
0a50: 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72 20 6d 61  t.** compiler ma
0a60: 67 69 63 20 65 6e 64 65 64 20 75 70 20 67 65 6e  gic ended up gen
0a70: 65 72 61 74 69 6e 67 20 73 75 63 68 20 61 20 66  erating such a f
0a80: 6c 75 72 72 79 20 6f 66 20 62 75 67 20 72 65 70  lurry of bug rep
0a90: 6f 72 74 73 0a 2a 2a 20 74 68 61 74 20 77 65 20  orts.** that we 
0aa0: 68 61 76 65 20 74 61 6b 65 6e 20 69 74 20 61 6c  have taken it al
0ab0: 6c 20 6f 75 74 20 61 6e 64 20 67 6f 6e 65 20 62  l out and gone b
0ac0: 61 63 6b 20 74 6f 20 75 73 69 6e 67 20 73 69 6d  ack to using sim
0ad0: 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72  ple.** noop macr
0ae0: 6f 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  os..*/.#define S
0af0: 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
0b00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
0b10: 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a  EXPERIMENTAL../*
0b20: 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68 65 73 65  .** Ensure these
0b30: 20 73 79 6d 62 6f 6c 73 20 77 65 72 65 20 6e 6f   symbols were no
0b40: 74 20 64 65 66 69 6e 65 64 20 62 79 20 73 6f 6d  t defined by som
0b50: 65 20 70 72 65 76 69 6f 75 73 20 68 65 61 64 65  e previous heade
0b60: 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65  r file..*/.#ifde
0b70: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0b80: 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f  .# undef SQLITE_
0b90: 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69 66 0a 23  VERSION.#endif.#
0ba0: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52  ifdef SQLITE_VER
0bb0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 20 75 6e  SION_NUMBER.# un
0bc0: 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49  def SQLITE_VERSI
0bd0: 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e 64 69 66  ON_NUMBER.#endif
0be0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
0bf0: 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 4c  : Compile-Time L
0c00: 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e  ibrary Version N
0c10: 75 6d 62 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54  umbers.**.** ^(T
0c20: 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  he [SQLITE_VERSI
0c30: 4f 4e 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  ON] C preprocess
0c40: 6f 72 20 6d 61 63 72 6f 20 69 6e 20 74 68 65 20  or macro in the 
0c50: 73 71 6c 69 74 65 33 2e 68 20 68 65 61 64 65 72  sqlite3.h header
0c60: 0a 2a 2a 20 65 76 61 6c 75 61 74 65 73 20 74 6f  .** evaluates to
0c70: 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
0c80: 6c 20 74 68 61 74 20 69 73 20 74 68 65 20 53 51  l that is the SQ
0c90: 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 69 6e 20  Lite version in 
0ca0: 74 68 65 0a 2a 2a 20 66 6f 72 6d 61 74 20 22 58  the.** format "X
0cb0: 2e 59 2e 5a 22 20 77 68 65 72 65 20 58 20 69 73  .Y.Z" where X is
0cc0: 20 74 68 65 20 6d 61 6a 6f 72 20 76 65 72 73 69   the major versi
0cd0: 6f 6e 20 6e 75 6d 62 65 72 20 28 61 6c 77 61 79  on number (alway
0ce0: 73 20 33 20 66 6f 72 0a 2a 2a 20 53 51 4c 69 74  s 3 for.** SQLit
0cf0: 65 33 29 20 61 6e 64 20 59 20 69 73 20 74 68 65  e3) and Y is the
0d00: 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f 6e 20 6e   minor version n
0d10: 75 6d 62 65 72 20 61 6e 64 20 5a 20 69 73 20 74  umber and Z is t
0d20: 68 65 20 72 65 6c 65 61 73 65 20 6e 75 6d 62 65  he release numbe
0d30: 72 2e 29 5e 0a 2a 2a 20 5e 28 54 68 65 20 5b 53  r.)^.** ^(The [S
0d40: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
0d50: 4d 42 45 52 5d 20 43 20 70 72 65 70 72 6f 63 65  MBER] C preproce
0d60: 73 73 6f 72 20 6d 61 63 72 6f 20 72 65 73 6f 6c  ssor macro resol
0d70: 76 65 73 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ves to an intege
0d80: 72 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 76 61  r.** with the va
0d90: 6c 75 65 20 28 58 2a 31 30 30 30 30 30 30 20 2b  lue (X*1000000 +
0da0: 20 59 2a 31 30 30 30 20 2b 20 5a 29 20 77 68 65   Y*1000 + Z) whe
0db0: 72 65 20 58 2c 20 59 2c 20 61 6e 64 20 5a 20 61  re X, Y, and Z a
0dc0: 72 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 6e  re the same.** n
0dd0: 75 6d 62 65 72 73 20 75 73 65 64 20 69 6e 20 5b  umbers used in [
0de0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2e  SQLITE_VERSION].
0df0: 29 5e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  )^.** The SQLITE
0e00: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20  _VERSION_NUMBER 
0e10: 66 6f 72 20 61 6e 79 20 67 69 76 65 6e 20 72 65  for any given re
0e20: 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20  lease of SQLite 
0e30: 77 69 6c 6c 20 61 6c 73 6f 0a 2a 2a 20 62 65 20  will also.** be 
0e40: 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20  larger than the 
0e50: 72 65 6c 65 61 73 65 20 66 72 6f 6d 20 77 68 69  release from whi
0e60: 63 68 20 69 74 20 69 73 20 64 65 72 69 76 65 64  ch it is derived
0e70: 2e 20 20 45 69 74 68 65 72 20 59 20 77 69 6c 6c  .  Either Y will
0e80: 0a 2a 2a 20 62 65 20 68 65 6c 64 20 63 6f 6e 73  .** be held cons
0e90: 74 61 6e 74 20 61 6e 64 20 5a 20 77 69 6c 6c 20  tant and Z will 
0ea0: 62 65 20 69 6e 63 72 65 6d 65 6e 74 65 64 20 6f  be incremented o
0eb0: 72 20 65 6c 73 65 20 59 20 77 69 6c 6c 20 62 65  r else Y will be
0ec0: 20 69 6e 63 72 65 6d 65 6e 74 65 64 0a 2a 2a 20   incremented.** 
0ed0: 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 72 65  and Z will be re
0ee0: 73 65 74 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a  set to zero..**.
0ef0: 2a 2a 20 53 69 6e 63 65 20 76 65 72 73 69 6f 6e  ** Since version
0f00: 20 33 2e 36 2e 31 38 2c 20 53 51 4c 69 74 65 20   3.6.18, SQLite 
0f10: 73 6f 75 72 63 65 20 63 6f 64 65 20 68 61 73 20  source code has 
0f20: 62 65 65 6e 20 73 74 6f 72 65 64 20 69 6e 20 74  been stored in t
0f30: 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 68  he.** <a href="h
0f40: 74 74 70 3a 2f 2f 77 77 77 2e 66 6f 73 73 69 6c  ttp://www.fossil
0f50: 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46 6f 73 73 69  -scm.org/">Fossi
0f60: 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  l configuration 
0f70: 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a 2a 20 73 79  management.** sy
0f80: 73 74 65 6d 3c 2f 61 3e 2e 20 20 5e 54 68 65 20  stem</a>.  ^The 
0f90: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
0fa0: 20 6d 61 63 72 6f 20 65 76 61 6c 75 61 74 65 73   macro evaluates
0fb0: 20 74 6f 0a 2a 2a 20 61 20 73 74 72 69 6e 67 20   to.** a string 
0fc0: 77 68 69 63 68 20 69 64 65 6e 74 69 66 69 65 73  which identifies
0fd0: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 68   a particular ch
0fe0: 65 63 6b 2d 69 6e 20 6f 66 20 53 51 4c 69 74 65  eck-in of SQLite
0ff0: 0a 2a 2a 20 77 69 74 68 69 6e 20 69 74 73 20 63  .** within its c
1000: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e  onfiguration man
1010: 61 67 65 6d 65 6e 74 20 73 79 73 74 65 6d 2e 20  agement system. 
1020: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 53 4f 55   ^The SQLITE_SOU
1030: 52 43 45 5f 49 44 0a 2a 2a 20 73 74 72 69 6e 67  RCE_ID.** string
1040: 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61   contains the da
1050: 74 65 20 61 6e 64 20 74 69 6d 65 20 6f 66 20 74  te and time of t
1060: 68 65 20 63 68 65 63 6b 2d 69 6e 20 28 55 54 43  he check-in (UTC
1070: 29 20 61 6e 64 20 61 6e 20 53 48 41 31 0a 2a 2a  ) and an SHA1.**
1080: 20 68 61 73 68 20 6f 66 20 74 68 65 20 65 6e 74   hash of the ent
1090: 69 72 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e  ire source tree.
10a0: 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
10b0: 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72   [sqlite3_libver
10c0: 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  sion()],.** [sql
10d0: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f  ite3_libversion_
10e0: 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73 71 6c 69  number()], [sqli
10f0: 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 5d 2c  te3_sourceid()],
1100: 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76 65 72 73  .** [sqlite_vers
1110: 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ion()] and [sqli
1120: 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d 2e  te_source_id()].
1130: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
1140: 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 20 20 20  TE_VERSION      
1150: 20 20 22 2d 2d 56 45 52 53 2d 2d 22 0a 23 64 65    "--VERS--".#de
1160: 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53  fine SQLITE_VERS
1170: 49 4f 4e 5f 4e 55 4d 42 45 52 20 2d 2d 56 45 52  ION_NUMBER --VER
1180: 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64  SION-NUMBER--.#d
1190: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 4f 55  efine SQLITE_SOU
11a0: 52 43 45 5f 49 44 20 20 20 20 20 20 22 2d 2d 53  RCE_ID      "--S
11b0: 4f 55 52 43 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a  OURCE-ID--"../*.
11c0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
11d0: 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65  -Time Library Ve
11e0: 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a  rsion Numbers.**
11f0: 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74   KEYWORDS: sqlit
1200: 65 33 5f 76 65 72 73 69 6f 6e 2c 20 73 71 6c 69  e3_version, sqli
1210: 74 65 33 5f 73 6f 75 72 63 65 69 64 0a 2a 2a 0a  te3_sourceid.**.
1220: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 72 66 61  ** These interfa
1230: 63 65 73 20 70 72 6f 76 69 64 65 20 74 68 65 20  ces provide the 
1240: 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  same information
1250: 20 61 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   as the [SQLITE_
1260: 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51  VERSION],.** [SQ
1270: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1280: 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54  BER], and [SQLIT
1290: 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 70  E_SOURCE_ID] C p
12a0: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
12b0: 6f 73 0a 2a 2a 20 62 75 74 20 61 72 65 20 61 73  os.** but are as
12c0: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
12d0: 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74 65 61  e library instea
12e0: 64 20 6f 66 20 74 68 65 20 68 65 61 64 65 72 20  d of the header 
12f0: 66 69 6c 65 2e 20 20 5e 28 43 61 75 74 69 6f 75  file.  ^(Cautiou
1300: 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72 73  s.** programmers
1310: 20 6d 69 67 68 74 20 69 6e 63 6c 75 64 65 20 61   might include a
1320: 73 73 65 72 74 28 29 20 73 74 61 74 65 6d 65 6e  ssert() statemen
1330: 74 73 20 69 6e 20 74 68 65 69 72 20 61 70 70 6c  ts in their appl
1340: 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65  ication to.** ve
1350: 72 69 66 79 20 74 68 61 74 20 76 61 6c 75 65 73  rify that values
1360: 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
1370: 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61  se interfaces ma
1380: 74 63 68 20 74 68 65 20 6d 61 63 72 6f 73 20 69  tch the macros i
1390: 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64 65 72 2c  n.** the header,
13a0: 20 61 6e 64 20 74 68 75 73 20 65 6e 73 75 72 65   and thus ensure
13b0: 20 74 68 61 74 20 74 68 65 20 61 70 70 6c 69 63   that the applic
13c0: 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70  ation is.** comp
13d0: 69 6c 65 64 20 77 69 74 68 20 6d 61 74 63 68 69  iled with matchi
13e0: 6e 67 20 6c 69 62 72 61 72 79 20 61 6e 64 20 68  ng library and h
13f0: 65 61 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a  eader files..**.
1400: 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1410: 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28 20  pre>.** assert( 
1420: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1430: 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51 4c  on_number()==SQL
1440: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
1450: 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28  ER );.** assert(
1460: 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f   strcmp(sqlite3_
1470: 73 6f 75 72 63 65 69 64 28 29 2c 53 51 4c 49 54  sourceid(),SQLIT
1480: 45 5f 53 4f 55 52 43 45 5f 49 44 29 3d 3d 30 20  E_SOURCE_ID)==0 
1490: 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74  );.** assert( st
14a0: 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 6c 69 62  rcmp(sqlite3_lib
14b0: 76 65 72 73 69 6f 6e 28 29 2c 53 51 4c 49 54 45  version(),SQLITE
14c0: 5f 56 45 52 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a  _VERSION)==0 );.
14d0: 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
14e0: 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  quote>)^.**.** ^
14f0: 54 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73  The sqlite3_vers
1500: 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e  ion[] string con
1510: 73 74 61 6e 74 20 63 6f 6e 74 61 69 6e 73 20 74  stant contains t
1520: 68 65 20 74 65 78 74 20 6f 66 20 5b 53 51 4c 49  he text of [SQLI
1530: 54 45 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d  TE_VERSION].** m
1540: 61 63 72 6f 2e 20 20 5e 54 68 65 20 73 71 6c 69  acro.  ^The sqli
1550: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29  te3_libversion()
1560: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
1570: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
1580: 68 65 0a 2a 2a 20 74 6f 20 74 68 65 20 73 71 6c  he.** to the sql
1590: 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73  ite3_version[] s
15a0: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20  tring constant. 
15b0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62   The sqlite3_lib
15c0: 76 65 72 73 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e  version().** fun
15d0: 63 74 69 6f 6e 20 69 73 20 70 72 6f 76 69 64 65  ction is provide
15e0: 64 20 66 6f 72 20 75 73 65 20 69 6e 20 44 4c 4c  d for use in DLL
15f0: 73 20 73 69 6e 63 65 20 44 4c 4c 20 75 73 65 72  s since DLL user
1600: 73 20 75 73 75 61 6c 6c 79 20 64 6f 20 6e 6f 74  s usually do not
1610: 20 68 61 76 65 0a 2a 2a 20 64 69 72 65 63 74 20   have.** direct 
1620: 61 63 63 65 73 73 20 74 6f 20 73 74 72 69 6e 67  access to string
1630: 20 63 6f 6e 73 74 61 6e 74 73 20 77 69 74 68 69   constants withi
1640: 6e 20 74 68 65 20 44 4c 4c 2e 20 20 5e 54 68 65  n the DLL.  ^The
1650: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c 69 62 76  .** sqlite3_libv
1660: 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20  ersion_number() 
1670: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1680: 20 61 6e 20 69 6e 74 65 67 65 72 20 65 71 75 61   an integer equa
1690: 6c 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  l to.** [SQLITE_
16a0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e  VERSION_NUMBER].
16b0: 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73    ^The sqlite3_s
16c0: 6f 75 72 63 65 69 64 28 29 20 66 75 6e 63 74 69  ourceid() functi
16d0: 6f 6e 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 61  on returns .** a
16e0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74   pointer to a st
16f0: 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 77 68  ring constant wh
1700: 6f 73 65 20 76 61 6c 75 65 20 69 73 20 74 68 65  ose value is the
1710: 20 73 61 6d 65 20 61 73 20 74 68 65 20 0a 2a 2a   same as the .**
1720: 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f   [SQLITE_SOURCE_
1730: 49 44 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  ID] C preprocess
1740: 6f 72 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20  or macro..**.** 
1750: 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
1760: 65 5f 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64  e_version()] and
1770: 20 5b 73 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f   [sqlite_source_
1780: 69 64 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  id()]..*/.SQLITE
1790: 5f 45 58 54 45 52 4e 20 63 6f 6e 73 74 20 63 68  _EXTERN const ch
17a0: 61 72 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69  ar sqlite3_versi
17b0: 6f 6e 5b 5d 3b 0a 63 6f 6e 73 74 20 63 68 61 72  on[];.const char
17c0: 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72   *sqlite3_libver
17d0: 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 63 6f 6e 73  sion(void);.cons
17e0: 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
17f0: 73 6f 75 72 63 65 69 64 28 76 6f 69 64 29 3b 0a  sourceid(void);.
1800: 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 62 76  int sqlite3_libv
1810: 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f  ersion_number(vo
1820: 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  id);../*.** CAPI
1830: 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c  3REF: Run-Time L
1840: 69 62 72 61 72 79 20 43 6f 6d 70 69 6c 61 74 69  ibrary Compilati
1850: 6f 6e 20 4f 70 74 69 6f 6e 73 20 44 69 61 67 6e  on Options Diagn
1860: 6f 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  ostics.**.** ^Th
1870: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  e sqlite3_compil
1880: 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 20 66  eoption_used() f
1890: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
18a0: 30 20 6f 72 20 31 20 0a 2a 2a 20 69 6e 64 69 63  0 or 1 .** indic
18b0: 61 74 69 6e 67 20 77 68 65 74 68 65 72 20 74 68  ating whether th
18c0: 65 20 73 70 65 63 69 66 69 65 64 20 6f 70 74 69  e specified opti
18d0: 6f 6e 20 77 61 73 20 64 65 66 69 6e 65 64 20 61  on was defined a
18e0: 74 20 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 69  t .** compile ti
18f0: 6d 65 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45  me.  ^The SQLITE
1900: 5f 20 70 72 65 66 69 78 20 6d 61 79 20 62 65 20  _ prefix may be 
1910: 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65  omitted from the
1920: 20 0a 2a 2a 20 6f 70 74 69 6f 6e 20 6e 61 6d 65   .** option name
1930: 20 70 61 73 73 65 64 20 74 6f 20 73 71 6c 69 74   passed to sqlit
1940: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
1950: 5f 75 73 65 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a  _used().  .**.**
1960: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
1970: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
1980: 29 20 66 75 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77  ) function allow
1990: 73 20 69 74 65 72 61 74 69 6e 67 0a 2a 2a 20 6f  s iterating.** o
19a0: 76 65 72 20 74 68 65 20 6c 69 73 74 20 6f 66 20  ver the list of 
19b0: 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 77 65 72  options that wer
19c0: 65 20 64 65 66 69 6e 65 64 20 61 74 20 63 6f 6d  e defined at com
19d0: 70 69 6c 65 20 74 69 6d 65 20 62 79 0a 2a 2a 20  pile time by.** 
19e0: 72 65 74 75 72 6e 69 6e 67 20 74 68 65 20 4e 2d  returning the N-
19f0: 74 68 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20  th compile time 
1a00: 6f 70 74 69 6f 6e 20 73 74 72 69 6e 67 2e 20 20  option string.  
1a10: 5e 49 66 20 4e 20 69 73 20 6f 75 74 20 6f 66 20  ^If N is out of 
1a20: 72 61 6e 67 65 2c 0a 2a 2a 20 73 71 6c 69 74 65  range,.** sqlite
1a30: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
1a40: 67 65 74 28 29 20 72 65 74 75 72 6e 73 20 61 20  get() returns a 
1a50: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e  NULL pointer.  ^
1a60: 54 68 65 20 53 51 4c 49 54 45 5f 20 0a 2a 2a 20  The SQLITE_ .** 
1a70: 70 72 65 66 69 78 20 69 73 20 6f 6d 69 74 74 65  prefix is omitte
1a80: 64 20 66 72 6f 6d 20 61 6e 79 20 73 74 72 69 6e  d from any strin
1a90: 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 0a  gs returned by .
1aa0: 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  ** sqlite3_compi
1ab0: 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 2e 0a  leoption_get()..
1ac0: 2a 2a 0a 2a 2a 20 5e 53 75 70 70 6f 72 74 20 66  **.** ^Support f
1ad0: 6f 72 20 74 68 65 20 64 69 61 67 6e 6f 73 74 69  or the diagnosti
1ae0: 63 20 66 75 6e 63 74 69 6f 6e 73 20 73 71 6c 69  c functions sqli
1af0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
1b00: 6e 5f 75 73 65 64 28 29 0a 2a 2a 20 61 6e 64 20  n_used().** and 
1b10: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f  sqlite3_compileo
1b20: 70 74 69 6f 6e 5f 67 65 74 28 29 20 6d 61 79 20  ption_get() may 
1b30: 62 65 20 6f 6d 69 74 74 65 64 20 62 79 20 73 70  be omitted by sp
1b40: 65 63 69 66 79 69 6e 67 20 74 68 65 20 0a 2a 2a  ecifying the .**
1b50: 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f   [SQLITE_OMIT_CO
1b60: 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47  MPILEOPTION_DIAG
1b70: 53 5d 20 6f 70 74 69 6f 6e 20 61 74 20 63 6f 6d  S] option at com
1b80: 70 69 6c 65 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  pile time..**.**
1b90: 20 53 65 65 20 61 6c 73 6f 3a 20 53 51 4c 20 66   See also: SQL f
1ba0: 75 6e 63 74 69 6f 6e 73 20 5b 73 71 6c 69 74 65  unctions [sqlite
1bb0: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75  _compileoption_u
1bc0: 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73  sed()] and.** [s
1bd0: 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74  qlite_compileopt
1be0: 69 6f 6e 5f 67 65 74 28 29 5d 20 61 6e 64 20 74  ion_get()] and t
1bf0: 68 65 20 5b 63 6f 6d 70 69 6c 65 5f 6f 70 74 69  he [compile_opti
1c00: 6f 6e 73 20 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a  ons pragma]..*/.
1c10: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f  #ifndef SQLITE_O
1c20: 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 4f  MIT_COMPILEOPTIO
1c30: 4e 5f 44 49 41 47 53 0a 69 6e 74 20 73 71 6c 69  N_DIAGS.int sqli
1c40: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
1c50: 6e 5f 75 73 65 64 28 63 6f 6e 73 74 20 63 68 61  n_used(const cha
1c60: 72 20 2a 7a 4f 70 74 4e 61 6d 65 29 3b 0a 63 6f  r *zOptName);.co
1c70: 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
1c80: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
1c90: 67 65 74 28 69 6e 74 20 4e 29 3b 0a 23 65 6e 64  get(int N);.#end
1ca0: 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  if../*.** CAPI3R
1cb0: 45 46 3a 20 54 65 73 74 20 54 6f 20 53 65 65 20  EF: Test To See 
1cc0: 49 66 20 54 68 65 20 4c 69 62 72 61 72 79 20 49  If The Library I
1cd0: 73 20 54 68 72 65 61 64 73 61 66 65 0a 2a 2a 0a  s Threadsafe.**.
1ce0: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1cf0: 74 68 72 65 61 64 73 61 66 65 28 29 20 66 75 6e  threadsafe() fun
1d00: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 7a 65  ction returns ze
1d10: 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  ro if and only i
1d20: 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61 73 20  f.** SQLite was 
1d30: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 75  compiled with mu
1d40: 74 65 78 69 6e 67 20 63 6f 64 65 20 6f 6d 69 74  texing code omit
1d50: 74 65 64 20 64 75 65 20 74 6f 20 74 68 65 0a 2a  ted due to the.*
1d60: 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  * [SQLITE_THREAD
1d70: 53 41 46 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  SAFE] compile-ti
1d80: 6d 65 20 6f 70 74 69 6f 6e 20 62 65 69 6e 67 20  me option being 
1d90: 73 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20  set to 0..**.** 
1da0: 53 51 4c 69 74 65 20 63 61 6e 20 62 65 20 63 6f  SQLite can be co
1db0: 6d 70 69 6c 65 64 20 77 69 74 68 20 6f 72 20 77  mpiled with or w
1dc0: 69 74 68 6f 75 74 20 6d 75 74 65 78 65 73 2e 20  ithout mutexes. 
1dd0: 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b 53 51   When.** the [SQ
1de0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d  LITE_THREADSAFE]
1df0: 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
1e00: 6d 61 63 72 6f 20 69 73 20 31 20 6f 72 20 32 2c  macro is 1 or 2,
1e10: 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20   mutexes.** are 
1e20: 65 6e 61 62 6c 65 64 20 61 6e 64 20 53 51 4c 69  enabled and SQLi
1e30: 74 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65  te is threadsafe
1e40: 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a 20 5b  .  When the.** [
1e50: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1e60: 45 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c 20 0a  E] macro is 0, .
1e70: 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73 20 61  ** the mutexes a
1e80: 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 57 69 74  re omitted.  Wit
1e90: 68 6f 75 74 20 74 68 65 20 6d 75 74 65 78 65 73  hout the mutexes
1ea0: 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 61 66 65  , it is not safe
1eb0: 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c 69 74  .** to use SQLit
1ec0: 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79 20 66  e concurrently f
1ed0: 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  rom more than on
1ee0: 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20  e thread..**.** 
1ef0: 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78 65 73  Enabling mutexes
1f00: 20 69 6e 63 75 72 73 20 61 20 6d 65 61 73 75 72   incurs a measur
1f10: 61 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e 63 65  able performance
1f20: 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20   penalty..** So 
1f30: 69 66 20 73 70 65 65 64 20 69 73 20 6f 66 20 75  if speed is of u
1f40: 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e 63 65  tmost importance
1f50: 2c 20 69 74 20 6d 61 6b 65 73 20 73 65 6e 73 65  , it makes sense
1f60: 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74   to disable.** t
1f70: 68 65 20 6d 75 74 65 78 65 73 2e 20 20 42 75 74  he mutexes.  But
1f80: 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73 61 66   for maximum saf
1f90: 65 74 79 2c 20 6d 75 74 65 78 65 73 20 73 68 6f  ety, mutexes sho
1fa0: 75 6c 64 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a  uld be enabled..
1fb0: 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
1fc0: 62 65 68 61 76 69 6f 72 20 69 73 20 66 6f 72 20  behavior is for 
1fd0: 6d 75 74 65 78 65 73 20 74 6f 20 62 65 20 65 6e  mutexes to be en
1fe0: 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  abled..**.** Thi
1ff0: 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  s interface can 
2000: 62 65 20 75 73 65 64 20 62 79 20 61 6e 20 61 70  be used by an ap
2010: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 6d 61 6b  plication to mak
2020: 65 20 73 75 72 65 20 74 68 61 74 20 74 68 65 0a  e sure that the.
2030: 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51  ** version of SQ
2040: 4c 69 74 65 20 74 68 61 74 20 69 74 20 69 73 20  Lite that it is 
2050: 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73 74 20  linking against 
2060: 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  was compiled wit
2070: 68 0a 2a 2a 20 74 68 65 20 64 65 73 69 72 65 64  h.** the desired
2080: 20 73 65 74 74 69 6e 67 20 6f 66 20 74 68 65 20   setting of the 
2090: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
20a0: 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a  FE] macro..**.**
20b0: 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
20c0: 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f 6e 20  only reports on 
20d0: 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  the compile-time
20e0: 20 6d 75 74 65 78 20 73 65 74 74 69 6e 67 0a 2a   mutex setting.*
20f0: 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45  * of the [SQLITE
2100: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 66 6c 61  _THREADSAFE] fla
2110: 67 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73  g.  If SQLite is
2120: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
2130: 2a 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  * SQLITE_THREADS
2140: 41 46 45 3d 31 20 6f 72 20 3d 32 20 74 68 65 6e  AFE=1 or =2 then
2150: 20 6d 75 74 65 78 65 73 20 61 72 65 20 65 6e 61   mutexes are ena
2160: 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20  bled by default 
2170: 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20 66 75  but.** can be fu
2180: 6c 6c 79 20 6f 72 20 70 61 72 74 69 61 6c 6c 79  lly or partially
2190: 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20   disabled using 
21a0: 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  a call to [sqlit
21b0: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20  e3_config()].** 
21c0: 77 69 74 68 20 74 68 65 20 76 65 72 62 73 20 5b  with the verbs [
21d0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
21e0: 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b 53 51  NGLETHREAD], [SQ
21f0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
2200: 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20  ITHREAD],.** or 
2210: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
2220: 45 52 49 41 4c 49 5a 45 44 5d 2e 20 20 5e 28 54  ERIALIZED].  ^(T
2230: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
2240: 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65  of the.** sqlite
2250: 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 20 66  3_threadsafe() f
2260: 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 20 6f 6e  unction shows on
2270: 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74  ly the compile-t
2280: 69 6d 65 20 73 65 74 74 69 6e 67 20 6f 66 0a 2a  ime setting of.*
2290: 2a 20 74 68 72 65 61 64 20 73 61 66 65 74 79 2c  * thread safety,
22a0: 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74 69 6d   not any run-tim
22b0: 65 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 61  e changes to tha
22c0: 74 20 73 65 74 74 69 6e 67 20 6d 61 64 65 20 62  t setting made b
22d0: 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e  y.** sqlite3_con
22e0: 66 69 67 28 29 2e 20 49 6e 20 6f 74 68 65 72 20  fig(). In other 
22f0: 77 6f 72 64 73 2c 20 74 68 65 20 72 65 74 75 72  words, the retur
2300: 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c  n value from sql
2310: 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
2320: 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61 6e 67 65  ).** is unchange
2330: 64 20 62 79 20 63 61 6c 6c 73 20 74 6f 20 73 71  d by calls to sq
2340: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 29  lite3_config().)
2350: 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68 65 20  ^.**.** See the 
2360: 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
2370: 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66   documentation f
2380: 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  or additional in
2390: 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e  formation..*/.in
23a0: 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64  t sqlite3_thread
23b0: 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a  safe(void);../*.
23c0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74  ** CAPI3REF: Dat
23d0: 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
23e0: 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59 57 4f   Handle.** KEYWO
23f0: 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65 20 63  RDS: {database c
2400: 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 74 61  onnection} {data
2410: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
2420: 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70 65  }.**.** Each ope
2430: 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73  n SQLite databas
2440: 65 20 69 73 20 72 65 70 72 65 73 65 6e 74 65 64  e is represented
2450: 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   by a pointer to
2460: 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 0a   an instance of.
2470: 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20 73 74  ** the opaque st
2480: 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20 22 73  ructure named "s
2490: 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69 73 20  qlite3".  It is 
24a0: 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e 6b 20  useful to think 
24b0: 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a 2a 2a  of an sqlite3.**
24c0: 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e 20 6f   pointer as an o
24d0: 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73 71 6c  bject.  The [sql
24e0: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
24f0: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
2500: 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
2510: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74  3_open_v2()] int
2520: 65 72 66 61 63 65 73 20 61 72 65 20 69 74 73 20  erfaces are its 
2530: 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20 61 6e  constructors, an
2540: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  d [sqlite3_close
2550: 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
2560: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 5d 20  te3_close_v2()] 
2570: 61 72 65 20 69 74 73 20 64 65 73 74 72 75 63 74  are its destruct
2580: 6f 72 73 2e 20 20 54 68 65 72 65 20 61 72 65 20  ors.  There are 
2590: 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 69 6e  many other.** in
25a0: 74 65 72 66 61 63 65 73 20 28 73 75 63 68 20 61  terfaces (such a
25b0: 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  s.** [sqlite3_pr
25c0: 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71  epare_v2()], [sq
25d0: 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
25e0: 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a  ction()], and.**
25f0: 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74   [sqlite3_busy_t
2600: 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20 6e 61 6d  imeout()] to nam
2610: 65 20 62 75 74 20 74 68 72 65 65 29 20 74 68 61  e but three) tha
2620: 74 20 61 72 65 20 6d 65 74 68 6f 64 73 20 6f 6e  t are methods on
2630: 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 20 6f   an.** sqlite3 o
2640: 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65  bject..*/.typede
2650: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
2660: 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a   sqlite3;../*.**
2670: 20 43 41 50 49 33 52 45 46 3a 20 36 34 2d 42 69   CAPI3REF: 64-Bi
2680: 74 20 49 6e 74 65 67 65 72 20 54 79 70 65 73 0a  t Integer Types.
2690: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
26a0: 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  ite_int64 sqlite
26b0: 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65  _uint64.**.** Be
26c0: 63 61 75 73 65 20 74 68 65 72 65 20 69 73 20 6e  cause there is n
26d0: 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f 72 6d  o cross-platform
26e0: 20 77 61 79 20 74 6f 20 73 70 65 63 69 66 79 20   way to specify 
26f0: 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 74  64-bit integer t
2700: 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ypes.** SQLite i
2710: 6e 63 6c 75 64 65 73 20 74 79 70 65 64 65 66 73  ncludes typedefs
2720: 20 66 6f 72 20 36 34 2d 62 69 74 20 73 69 67 6e   for 64-bit sign
2730: 65 64 20 61 6e 64 20 75 6e 73 69 67 6e 65 64 20  ed and unsigned 
2740: 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  integers..**.** 
2750: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  The sqlite3_int6
2760: 34 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 75 69  4 and sqlite3_ui
2770: 6e 74 36 34 20 61 72 65 20 74 68 65 20 70 72 65  nt64 are the pre
2780: 66 65 72 72 65 64 20 74 79 70 65 20 64 65 66 69  ferred type defi
2790: 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20  nitions..** The 
27a0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 61 6e 64  sqlite_int64 and
27b0: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 74   sqlite_uint64 t
27c0: 79 70 65 73 20 61 72 65 20 73 75 70 70 6f 72 74  ypes are support
27d0: 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ed for backwards
27e0: 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  .** compatibilit
27f0: 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54  y only..**.** ^T
2800: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  he sqlite3_int64
2810: 20 61 6e 64 20 73 71 6c 69 74 65 5f 69 6e 74 36   and sqlite_int6
2820: 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72  4 types can stor
2830: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
2840: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 2d 39 32 32  .** between -922
2850: 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30 38  3372036854775808
2860: 20 61 6e 64 20 2b 39 32 32 33 33 37 32 30 33 36   and +9223372036
2870: 38 35 34 37 37 35 38 30 37 20 69 6e 63 6c 75 73  854775807 inclus
2880: 69 76 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71  ive.  ^The.** sq
2890: 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61 6e 64  lite3_uint64 and
28a0: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 74   sqlite_uint64 t
28b0: 79 70 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69  ypes can store i
28c0: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 0a 2a  nteger values .*
28d0: 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20  * between 0 and 
28e0: 2b 31 38 34 34 36 37 34 34 30 37 33 37 30 39 35  +184467440737095
28f0: 35 31 36 31 35 20 69 6e 63 6c 75 73 69 76 65 2e  51615 inclusive.
2900: 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54  .*/.#ifdef SQLIT
2910: 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 74  E_INT64_TYPE.  t
2920: 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f 49 4e  ypedef SQLITE_IN
2930: 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f  T64_TYPE sqlite_
2940: 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66  int64;.  typedef
2950: 20 75 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45   unsigned SQLITE
2960: 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69  _INT64_TYPE sqli
2970: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 69 66  te_uint64;.#elif
2980: 20 64 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45   defined(_MSC_VE
2990: 52 29 20 7c 7c 20 64 65 66 69 6e 65 64 28 5f 5f  R) || defined(__
29a0: 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20 20 74 79  BORLANDC__).  ty
29b0: 70 65 64 65 66 20 5f 5f 69 6e 74 36 34 20 73 71  pedef __int64 sq
29c0: 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79  lite_int64;.  ty
29d0: 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 5f  pedef unsigned _
29e0: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69  _int64 sqlite_ui
29f0: 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20 20 74 79  nt64;.#else.  ty
2a00: 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20  pedef long long 
2a10: 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  int sqlite_int64
2a20: 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69  ;.  typedef unsi
2a30: 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69  gned long long i
2a40: 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  nt sqlite_uint64
2a50: 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65 64 65 66  ;.#endif.typedef
2a60: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71   sqlite_int64 sq
2a70: 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a 74 79 70  lite3_int64;.typ
2a80: 65 64 65 66 20 73 71 6c 69 74 65 5f 75 69 6e 74  edef sqlite_uint
2a90: 36 34 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  64 sqlite3_uint6
2aa0: 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d  4;../*.** If com
2ab0: 70 69 6c 69 6e 67 20 66 6f 72 20 61 20 70 72 6f  piling for a pro
2ac0: 63 65 73 73 6f 72 20 74 68 61 74 20 6c 61 63 6b  cessor that lack
2ad0: 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  s floating point
2ae0: 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20 73 75 62   support,.** sub
2af0: 73 74 69 74 75 74 65 20 69 6e 74 65 67 65 72 20  stitute integer 
2b00: 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d 70 6f 69  for floating-poi
2b10: 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  nt..*/.#ifdef SQ
2b20: 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49  LITE_OMIT_FLOATI
2b30: 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65 66 69 6e  NG_POINT.# defin
2b40: 65 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33  e double sqlite3
2b50: 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66 0a 0a 2f  _int64.#endif../
2b60: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
2b70: 6c 6f 73 69 6e 67 20 41 20 44 61 74 61 62 61 73  losing A Databas
2b80: 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e Connection.** 
2b90: 44 45 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69  DESTRUCTOR: sqli
2ba0: 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  te3.**.** ^The s
2bb0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61  qlite3_close() a
2bc0: 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nd sqlite3_close
2bd0: 5f 76 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61  _v2() routines a
2be0: 72 65 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a  re destructors.*
2bf0: 2a 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  * for the [sqlit
2c00: 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e  e3] object..** ^
2c10: 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  Calls to sqlite3
2c20: 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c  _close() and sql
2c30: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
2c40: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
2c50: 4b 5d 20 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71  K] if.** the [sq
2c60: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73  lite3] object is
2c70: 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65   successfully de
2c80: 73 74 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20  stroyed and all 
2c90: 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65  associated.** re
2ca0: 73 6f 75 72 63 65 73 20 61 72 65 20 64 65 61 6c  sources are deal
2cb0: 6c 6f 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  located..**.** ^
2cc0: 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
2cd0: 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 61 73  connection is as
2ce0: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 75 6e  sociated with un
2cf0: 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72  finalized prepar
2d00: 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73  ed.** statements
2d10: 20 6f 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73   or unfinished s
2d20: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62  qlite3_backup ob
2d30: 6a 65 63 74 73 20 74 68 65 6e 20 73 71 6c 69 74  jects then sqlit
2d40: 65 33 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69  e3_close().** wi
2d50: 6c 6c 20 6c 65 61 76 65 20 74 68 65 20 64 61 74  ll leave the dat
2d60: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2d70: 20 6f 70 65 6e 20 61 6e 64 20 72 65 74 75 72 6e   open and return
2d80: 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a   [SQLITE_BUSY]..
2d90: 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63  ** ^If sqlite3_c
2da0: 6c 6f 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c  lose_v2() is cal
2db0: 6c 65 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c  led with unfinal
2dc0: 69 7a 65 64 20 70 72 65 70 61 72 65 64 20 73 74  ized prepared st
2dd0: 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 2f  atements.** and/
2de0: 6f 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71  or unfinished sq
2df0: 6c 69 74 65 33 5f 62 61 63 6b 75 70 73 2c 20 74  lite3_backups, t
2e00: 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
2e10: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 63 6f   connection beco
2e20: 6d 65 73 0a 2a 2a 20 61 6e 20 75 6e 75 73 61 62  mes.** an unusab
2e30: 6c 65 20 22 7a 6f 6d 62 69 65 22 20 77 68 69 63  le "zombie" whic
2e40: 68 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63  h will automatic
2e50: 61 6c 6c 79 20 62 65 20 64 65 61 6c 6c 6f 63 61  ally be dealloca
2e60: 74 65 64 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20  ted when the.** 
2e70: 6c 61 73 74 20 70 72 65 70 61 72 65 64 20 73 74  last prepared st
2e80: 61 74 65 6d 65 6e 74 20 69 73 20 66 69 6e 61 6c  atement is final
2e90: 69 7a 65 64 20 6f 72 20 74 68 65 20 6c 61 73 74  ized or the last
2ea0: 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20   sqlite3_backup 
2eb0: 69 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 2e 20  is.** finished. 
2ec0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f   The sqlite3_clo
2ed0: 73 65 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  se_v2() interfac
2ee0: 65 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f  e is intended fo
2ef0: 72 20 75 73 65 20 77 69 74 68 0a 2a 2a 20 68 6f  r use with.** ho
2f00: 73 74 20 6c 61 6e 67 75 61 67 65 73 20 74 68 61  st languages tha
2f10: 74 20 61 72 65 20 67 61 72 62 61 67 65 20 63 6f  t are garbage co
2f20: 6c 6c 65 63 74 65 64 2c 20 61 6e 64 20 77 68 65  llected, and whe
2f30: 72 65 20 74 68 65 20 6f 72 64 65 72 20 69 6e 20  re the order in 
2f40: 77 68 69 63 68 0a 2a 2a 20 64 65 73 74 72 75 63  which.** destruc
2f50: 74 6f 72 73 20 61 72 65 20 63 61 6c 6c 65 64 20  tors are called 
2f60: 69 73 20 61 72 62 69 74 72 61 72 79 2e 0a 2a 2a  is arbitrary..**
2f70: 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
2f80: 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69 74 65 33   should [sqlite3
2f90: 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61  _finalize | fina
2fa0: 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70 61  lize] all [prepa
2fb0: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c  red statements],
2fc0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  .** [sqlite3_blo
2fd0: 62 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f 73 65 5d  b_close | close]
2fe0: 20 61 6c 6c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c   all [BLOB handl
2ff0: 65 73 5d 2c 20 61 6e 64 20 0a 2a 2a 20 5b 73 71  es], and .** [sq
3000: 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e  lite3_backup_fin
3010: 69 73 68 20 7c 20 66 69 6e 69 73 68 5d 20 61 6c  ish | finish] al
3020: 6c 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  l [sqlite3_backu
3030: 70 5d 20 6f 62 6a 65 63 74 73 20 61 73 73 6f 63  p] objects assoc
3040: 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68  iated.** with th
3050: 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
3060: 63 74 20 70 72 69 6f 72 20 74 6f 20 61 74 74 65  ct prior to atte
3070: 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20  mpting to close 
3080: 74 68 65 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66  the object.  ^If
3090: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  .** sqlite3_clos
30a0: 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64  e_v2() is called
30b0: 20 6f 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20   on a [database 
30c0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74  connection] that
30d0: 20 73 74 69 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75   still has.** ou
30e0: 74 73 74 61 6e 64 69 6e 67 20 5b 70 72 65 70 61  tstanding [prepa
30f0: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c  red statements],
3100: 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c   [BLOB handles],
3110: 20 61 6e 64 2f 6f 72 0a 2a 2a 20 5b 73 71 6c 69   and/or.** [sqli
3120: 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65  te3_backup] obje
3130: 63 74 73 20 74 68 65 6e 20 69 74 20 72 65 74 75  cts then it retu
3140: 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  rns [SQLITE_OK] 
3150: 61 6e 64 20 74 68 65 20 64 65 61 6c 6c 6f 63 61  and the dealloca
3160: 74 69 6f 6e 0a 2a 2a 20 6f 66 20 72 65 73 6f 75  tion.** of resou
3170: 72 63 65 73 20 69 73 20 64 65 66 65 72 72 65 64  rces is deferred
3180: 20 75 6e 74 69 6c 20 61 6c 6c 20 5b 70 72 65 70   until all [prep
3190: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
31a0: 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d  , [BLOB handles]
31b0: 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ,.** and [sqlite
31c0: 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74  3_backup] object
31d0: 73 20 61 72 65 20 61 6c 73 6f 20 64 65 73 74 72  s are also destr
31e0: 6f 79 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  oyed..**.** ^If 
31f0: 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  an [sqlite3] obj
3200: 65 63 74 20 69 73 20 64 65 73 74 72 6f 79 65 64  ect is destroyed
3210: 20 77 68 69 6c 65 20 61 20 74 72 61 6e 73 61 63   while a transac
3220: 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c 0a 2a 2a  tion is open,.**
3230: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
3240: 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   is automaticall
3250: 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a  y rolled back..*
3260: 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61 72 61 6d  *.** The C param
3270: 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
3280: 5f 63 6c 6f 73 65 28 43 29 5d 20 61 6e 64 20 5b  _close(C)] and [
3290: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
32a0: 28 43 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20  (C)].** must be 
32b0: 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a  either a NULL.**
32c0: 20 70 6f 69 6e 74 65 72 20 6f 72 20 61 6e 20 5b   pointer or an [
32d0: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
32e0: 70 6f 69 6e 74 65 72 20 6f 62 74 61 69 6e 65 64  pointer obtained
32f0: 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
3300: 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
3310: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f  te3_open16()], o
3320: 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r.** [sqlite3_op
3330: 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 6e 6f  en_v2()], and no
3340: 74 20 70 72 65 76 69 6f 75 73 6c 79 20 63 6c 6f  t previously clo
3350: 73 65 64 2e 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  sed..** ^Calling
3360: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
3370: 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73   or sqlite3_clos
3380: 65 5f 76 32 28 29 20 77 69 74 68 20 61 20 4e 55  e_v2() with a NU
3390: 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 61 72  LL pointer.** ar
33a0: 67 75 6d 65 6e 74 20 69 73 20 61 20 68 61 72 6d  gument is a harm
33b0: 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 69  less no-op..*/.i
33c0: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nt sqlite3_close
33d0: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 69 6e 74 20  (sqlite3*);.int 
33e0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
33f0: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
3400: 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f 72 20  ** The type for 
3410: 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
3420: 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20  ion..** This is 
3430: 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70 72 65  legacy and depre
3440: 63 61 74 65 64 2e 20 20 49 74 20 69 73 20 69 6e  cated.  It is in
3450: 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73 74 6f  cluded for histo
3460: 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69  rical.** compati
3470: 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20 6e 6f  bility and is no
3480: 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f  t documented..*/
3490: 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28 2a 73  .typedef int (*s
34a0: 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29  qlite3_callback)
34b0: 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a  (void*,int,char*
34c0: 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a  *, char**);../*.
34d0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 6e 65  ** CAPI3REF: One
34e0: 2d 53 74 65 70 20 51 75 65 72 79 20 45 78 65 63  -Step Query Exec
34f0: 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63 65 0a  ution Interface.
3500: 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
3510: 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e3.**.** The sql
3520: 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65  ite3_exec() inte
3530: 72 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65  rface is a conve
3540: 6e 69 65 6e 63 65 20 77 72 61 70 70 65 72 20 61  nience wrapper a
3550: 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  round.** [sqlite
3560: 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
3570: 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
3580: 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
3590: 66 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20  finalize()],.** 
35a0: 74 68 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61  that allows an a
35b0: 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 75  pplication to ru
35c0: 6e 20 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 65  n multiple state
35d0: 6d 65 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20  ments of SQL.** 
35e0: 77 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74  without having t
35f0: 6f 20 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 43  o use a lot of C
3600: 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54   code. .**.** ^T
3610: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3620: 29 20 69 6e 74 65 72 66 61 63 65 20 72 75 6e 73  ) interface runs
3630: 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54   zero or more UT
3640: 46 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20  F-8 encoded,.** 
3650: 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61  semicolon-separa
3660: 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  te SQL statement
3670: 73 20 70 61 73 73 65 64 20 69 6e 74 6f 20 69 74  s passed into it
3680: 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a  s 2nd argument,.
3690: 2a 2a 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78  ** in the contex
36a0: 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61  t of the [databa
36b0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70  se connection] p
36c0: 61 73 73 65 64 20 69 6e 20 61 73 20 69 74 73 20  assed in as its 
36d0: 31 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e  1st.** argument.
36e0: 20 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61    ^If the callba
36f0: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74  ck function of t
3700: 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20  he 3rd argument 
3710: 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78  to.** sqlite3_ex
3720: 65 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  ec() is not NULL
3730: 2c 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 76  , then it is inv
3740: 6f 6b 65 64 20 66 6f 72 20 65 61 63 68 20 72 65  oked for each re
3750: 73 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69  sult row.** comi
3760: 6e 67 20 6f 75 74 20 6f 66 20 74 68 65 20 65 76  ng out of the ev
3770: 61 6c 75 61 74 65 64 20 53 51 4c 20 73 74 61 74  aluated SQL stat
3780: 65 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 74  ements.  ^The 4t
3790: 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  h argument to.**
37a0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
37b0: 69 73 20 72 65 6c 61 79 65 64 20 74 68 72 6f 75  is relayed throu
37c0: 67 68 20 74 6f 20 74 68 65 20 31 73 74 20 61 72  gh to the 1st ar
37d0: 67 75 6d 65 6e 74 20 6f 66 20 65 61 63 68 0a 2a  gument of each.*
37e0: 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 63  * callback invoc
37f0: 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74 68 65 20  ation.  ^If the 
3800: 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e 74 65 72  callback pointer
3810: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
3820: 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 74  ().** is NULL, t
3830: 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 20  hen no callback 
3840: 69 73 20 65 76 65 72 20 69 6e 76 6f 6b 65 64 20  is ever invoked 
3850: 61 6e 64 20 72 65 73 75 6c 74 20 72 6f 77 73 20  and result rows 
3860: 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a  are.** ignored..
3870: 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72  **.** ^If an err
3880: 6f 72 20 6f 63 63 75 72 73 20 77 68 69 6c 65 20  or occurs while 
3890: 65 76 61 6c 75 61 74 69 6e 67 20 74 68 65 20 53  evaluating the S
38a0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61  QL statements pa
38b0: 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c  ssed into.** sql
38c0: 69 74 65 33 5f 65 78 65 63 28 29 2c 20 74 68 65  ite3_exec(), the
38d0: 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74  n execution of t
38e0: 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65  he current state
38f0: 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e 64 0a 2a  ment stops and.*
3900: 2a 20 73 75 62 73 65 71 75 65 6e 74 20 73 74 61  * subsequent sta
3910: 74 65 6d 65 6e 74 73 20 61 72 65 20 73 6b 69 70  tements are skip
3920: 70 65 64 2e 20 20 5e 49 66 20 74 68 65 20 35 74  ped.  ^If the 5t
3930: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
3940: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
3950: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65   is not NULL the
3960: 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d 65 73 73  n any error mess
3970: 61 67 65 20 69 73 20 77 72 69 74 74 65 6e 20 69  age is written i
3980: 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69  nto memory obtai
3990: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
39a0: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61  ite3_malloc()] a
39b0: 6e 64 20 70 61 73 73 65 64 20 62 61 63 6b 20 74  nd passed back t
39c0: 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70  hrough the 5th p
39d0: 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f 20  arameter..** To 
39e0: 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20 6c 65 61  avoid memory lea
39f0: 6b 73 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74  ks, the applicat
3a00: 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e 76 6f 6b  ion should invok
3a10: 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  e [sqlite3_free(
3a20: 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72 20 6d  )].** on error m
3a30: 65 73 73 61 67 65 20 73 74 72 69 6e 67 73 20 72  essage strings r
3a40: 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67 68 20  eturned through 
3a50: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
3a60: 72 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  r of.** sqlite3_
3a70: 65 78 65 63 28 29 20 61 66 74 65 72 20 74 68 65  exec() after the
3a80: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
3a90: 74 72 69 6e 67 20 69 73 20 6e 6f 20 6c 6f 6e 67  tring is no long
3aa0: 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a 20 5e 49  er needed..** ^I
3ab0: 66 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  f the 5th parame
3ac0: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3ad0: 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c  xec() is not NUL
3ae0: 4c 20 61 6e 64 20 6e 6f 20 65 72 72 6f 72 73 0a  L and no errors.
3af0: 2a 2a 20 6f 63 63 75 72 2c 20 74 68 65 6e 20 73  ** occur, then s
3b00: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 73 65  qlite3_exec() se
3b10: 74 73 20 74 68 65 20 70 6f 69 6e 74 65 72 20 69  ts the pointer i
3b20: 6e 20 69 74 73 20 35 74 68 20 70 61 72 61 6d 65  n its 5th parame
3b30: 74 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c 4c 20 62  ter to.** NULL b
3b40: 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e  efore returning.
3b50: 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 73 71  .**.** ^If an sq
3b60: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c  lite3_exec() cal
3b70: 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
3b80: 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 73 71 6c 69  n-zero, the sqli
3b90: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 72 6f  te3_exec().** ro
3ba0: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 53 51  utine returns SQ
3bb0: 4c 49 54 45 5f 41 42 4f 52 54 20 77 69 74 68 6f  LITE_ABORT witho
3bc0: 75 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  ut invoking the 
3bd0: 63 61 6c 6c 62 61 63 6b 20 61 67 61 69 6e 20 61  callback again a
3be0: 6e 64 0a 2a 2a 20 77 69 74 68 6f 75 74 20 72 75  nd.** without ru
3bf0: 6e 6e 69 6e 67 20 61 6e 79 20 73 75 62 73 65 71  nning any subseq
3c00: 75 65 6e 74 20 53 51 4c 20 73 74 61 74 65 6d 65  uent SQL stateme
3c10: 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
3c20: 32 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  2nd argument to 
3c30: 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  the sqlite3_exec
3c40: 28 29 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  () callback func
3c50: 74 69 6f 6e 20 69 73 20 74 68 65 0a 2a 2a 20 6e  tion is the.** n
3c60: 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
3c70: 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 2e 20   in the result. 
3c80: 20 5e 54 68 65 20 33 72 64 20 61 72 67 75 6d 65   ^The 3rd argume
3c90: 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  nt to the sqlite
3ca0: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 63 61 6c 6c  3_exec().** call
3cb0: 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79  back is an array
3cc0: 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20   of pointers to 
3cd0: 73 74 72 69 6e 67 73 20 6f 62 74 61 69 6e 65 64  strings obtained
3ce0: 20 61 73 20 69 66 20 66 72 6f 6d 0a 2a 2a 20 5b   as if from.** [
3cf0: 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
3d00: 65 78 74 28 29 5d 2c 20 6f 6e 65 20 66 6f 72 20  ext()], one for 
3d10: 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 20 20 5e 49  each column.  ^I
3d20: 66 20 61 6e 20 65 6c 65 6d 65 6e 74 20 6f 66 20  f an element of 
3d30: 61 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20  a.** result row 
3d40: 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65  is NULL then the
3d50: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 73   corresponding s
3d60: 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 66 6f  tring pointer fo
3d70: 72 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33  r the.** sqlite3
3d80: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
3d90: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
3da0: 65 72 2e 20 20 5e 54 68 65 20 34 74 68 20 61 72  er.  ^The 4th ar
3db0: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a  gument to the.**
3dc0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3dd0: 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61  callback is an a
3de0: 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
3df0: 20 74 6f 20 73 74 72 69 6e 67 73 20 77 68 65 72   to strings wher
3e00: 65 20 65 61 63 68 0a 2a 2a 20 65 6e 74 72 79 20  e each.** entry 
3e10: 72 65 70 72 65 73 65 6e 74 73 20 74 68 65 20 6e  represents the n
3e20: 61 6d 65 20 6f 66 20 63 6f 72 72 65 73 70 6f 6e  ame of correspon
3e30: 64 69 6e 67 20 72 65 73 75 6c 74 20 63 6f 6c 75  ding result colu
3e40: 6d 6e 20 61 73 20 6f 62 74 61 69 6e 65 64 0a 2a  mn as obtained.*
3e50: 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
3e60: 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a  column_name()]..
3e70: 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 32 6e  **.** ^If the 2n
3e80: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
3e90: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3ea0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
3eb0: 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
3ec0: 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
3ed0: 2c 20 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74  , or a pointer t
3ee0: 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 6f 6e 6c  hat contains onl
3ef0: 79 20 77 68 69 74 65 73 70 61 63 65 20 61 6e 64  y whitespace and
3f00: 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20 63 6f 6d 6d  /or .** SQL comm
3f10: 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51  ents, then no SQ
3f20: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  L statements are
3f30: 20 65 76 61 6c 75 61 74 65 64 20 61 6e 64 20 74   evaluated and t
3f40: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69  he database.** i
3f50: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a  s not changed..*
3f60: 2a 0a 2a 2a 20 52 65 73 74 72 69 63 74 69 6f 6e  *.** Restriction
3f70: 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
3f80: 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63   <li> The applic
3f90: 61 74 69 6f 6e 20 6d 75 73 74 20 65 6e 73 75 72  ation must ensur
3fa0: 65 20 74 68 61 74 20 74 68 65 20 31 73 74 20 70  e that the 1st p
3fb0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
3fc0: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 20 20  te3_exec().**   
3fd0: 20 20 20 69 73 20 61 20 76 61 6c 69 64 20 61 6e     is a valid an
3fe0: 64 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65  d open [database
3ff0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a   connection]..**
4000: 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63   <li> The applic
4010: 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 63  ation must not c
4020: 6c 6f 73 65 20 74 68 65 20 5b 64 61 74 61 62 61  lose the [databa
4030: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73  se connection] s
4040: 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20  pecified by.**  
4050: 20 20 20 20 74 68 65 20 31 73 74 20 70 61 72 61      the 1st para
4060: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
4070: 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71  _exec() while sq
4080: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
4090: 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e  running..** <li>
40a0: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
40b0: 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 69 66 79   must not modify
40c0: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
40d0: 6e 74 20 74 65 78 74 20 70 61 73 73 65 64 20 69  nt text passed i
40e0: 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65 20  nto.**      the 
40f0: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66  2nd parameter of
4100: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
4110: 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78  while sqlite3_ex
4120: 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e  ec() is running.
4130: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69 6e 74  .** </ul>.*/.int
4140: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a 20   sqlite3_exec(. 
4150: 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20   sqlite3*,      
4160: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4170: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41              /* A
4180: 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20  n open database 
4190: 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
41a0: 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20 20  *sql,           
41b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41c0: 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61  /* SQL to be eva
41d0: 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20  luated */.  int 
41e0: 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64  (*callback)(void
41f0: 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61  *,int,char**,cha
4200: 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61  r**),  /* Callba
4210: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20  ck function */. 
4220: 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 20   void *,        
4230: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4240: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 31              /* 1
4250: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63  st argument to c
4260: 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61  allback */.  cha
4270: 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20  r **errmsg      
4280: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4290: 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72          /* Error
42a0: 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72   msg written her
42b0: 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e */.);../*.** C
42c0: 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20  API3REF: Result 
42d0: 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  Codes.** KEYWORD
42e0: 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 20  S: {result code 
42f0: 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a  definitions}.**.
4300: 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66  ** Many SQLite f
4310: 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
4320: 61 6e 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c  an integer resul
4330: 74 20 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20  t code from the 
4340: 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72  set shown.** her
4350: 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e  e in order to in
4360: 64 69 63 61 74 65 20 73 75 63 63 65 73 73 20 6f  dicate success o
4370: 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a  r failure..**.**
4380: 20 4e 65 77 20 65 72 72 6f 72 20 63 6f 64 65 73   New error codes
4390: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
43a0: 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
43b0: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
43c0: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 65 78 74  * See also: [ext
43d0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
43e0: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 5d 0a 2a  e definitions].*
43f0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4400: 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20  _OK           0 
4410: 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20    /* Successful 
4420: 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67  result */./* beg
4430: 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d  inning-of-error-
4440: 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65  codes */.#define
4450: 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20   SQLITE_ERROR   
4460: 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20       1   /* SQL 
4470: 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67  error or missing
4480: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65   database */.#de
4490: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
44a0: 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20  RNAL     2   /* 
44b0: 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65  Internal logic e
44c0: 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a  rror in SQLite *
44d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
44e0: 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20  _PERM         3 
44f0: 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d    /* Access perm
4500: 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f  ission denied */
4510: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4520: 41 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20  ABORT        4  
4530: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75   /* Callback rou
4540: 74 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61  tine requested a
4550: 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69  n abort */.#defi
4560: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20  ne SQLITE_BUSY  
4570: 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68         5   /* Th
4580: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
4590: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
45a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
45b0: 45 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20  ED       6   /* 
45c0: 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64  A table in the d
45d0: 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65  atabase is locke
45e0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
45f0: 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20  ITE_NOMEM       
4600: 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63   7   /* A malloc
4610: 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65  () failed */.#de
4620: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
4630: 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20  ONLY     8   /* 
4640: 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65  Attempt to write
4650: 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61   a readonly data
4660: 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  base */.#define 
4670: 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
4680: 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61      9   /* Opera
4690: 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20  tion terminated 
46a0: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  by sqlite3_inter
46b0: 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65  rupt()*/.#define
46c0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20   SQLITE_IOERR   
46d0: 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65      10   /* Some
46e0: 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f   kind of disk I/
46f0: 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64  O error occurred
4700: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4710: 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31  TE_CORRUPT     1
4720: 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  1   /* The datab
4730: 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69  ase disk image i
4740: 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23  s malformed */.#
4750: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
4760: 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f  TFOUND    12   /
4770: 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65  * Unknown opcode
4780: 20 69 6e 20 73 71 6c 69 74 65 33 5f 66 69 6c 65   in sqlite3_file
4790: 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f 0a 23 64  _control() */.#d
47a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c  efine SQLITE_FUL
47b0: 4c 20 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a  L        13   /*
47c0: 20 49 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65   Insertion faile
47d0: 64 20 62 65 63 61 75 73 65 20 64 61 74 61 62 61  d because databa
47e0: 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64  se is full */.#d
47f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
4800: 54 4f 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a  TOPEN    14   /*
4810: 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20   Unable to open 
4820: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
4830: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
4840: 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20  ITE_PROTOCOL    
4850: 31 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  15   /* Database
4860: 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65   lock protocol e
4870: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
4880: 53 51 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20  SQLITE_EMPTY    
4890: 20 20 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62     16   /* Datab
48a0: 61 73 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a  ase is empty */.
48b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
48c0: 43 48 45 4d 41 20 20 20 20 20 20 31 37 20 20 20  CHEMA      17   
48d0: 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20  /* The database 
48e0: 73 63 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a  schema changed *
48f0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4900: 5f 54 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20  _TOOBIG      18 
4910: 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42    /* String or B
4920: 4c 4f 42 20 65 78 63 65 65 64 73 20 73 69 7a 65  LOB exceeds size
4930: 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e   limit */.#defin
4940: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
4950: 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f  INT  19   /* Abo
4960: 72 74 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72  rt due to constr
4970: 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a  aint violation *
4980: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4990: 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 32 30 20  _MISMATCH    20 
49a0: 20 20 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d    /* Data type m
49b0: 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69  ismatch */.#defi
49c0: 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  ne SQLITE_MISUSE
49d0: 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69        21   /* Li
49e0: 62 72 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72  brary used incor
49f0: 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  rectly */.#defin
4a00: 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20  e SQLITE_NOLFS  
4a10: 20 20 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65       22   /* Use
4a20: 73 20 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f  s OS features no
4a30: 74 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68  t supported on h
4a40: 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ost */.#define S
4a50: 51 4c 49 54 45 5f 41 55 54 48 20 20 20 20 20 20  QLITE_AUTH      
4a60: 20 20 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72    23   /* Author
4a70: 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a  ization denied *
4a80: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4a90: 5f 46 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20  _FORMAT      24 
4aa0: 20 20 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64    /* Auxiliary d
4ab0: 61 74 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65  atabase format e
4ac0: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
4ad0: 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20  SQLITE_RANGE    
4ae0: 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70     25   /* 2nd p
4af0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
4b00: 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20  te3_bind out of 
4b10: 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65  range */.#define
4b20: 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20   SQLITE_NOTADB  
4b30: 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65      26   /* File
4b40: 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20   opened that is 
4b50: 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66  not a database f
4b60: 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ile */.#define S
4b70: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 20 20 20  QLITE_NOTICE    
4b80: 20 20 32 37 20 20 20 2f 2a 20 4e 6f 74 69 66 69    27   /* Notifi
4b90: 63 61 74 69 6f 6e 73 20 66 72 6f 6d 20 73 71 6c  cations from sql
4ba0: 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64  ite3_log() */.#d
4bb0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52  efine SQLITE_WAR
4bc0: 4e 49 4e 47 20 20 20 20 20 32 38 20 20 20 2f 2a  NING     28   /*
4bd0: 20 57 61 72 6e 69 6e 67 73 20 66 72 6f 6d 20 73   Warnings from s
4be0: 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a  qlite3_log() */.
4bf0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
4c00: 4f 57 20 20 20 20 20 20 20 20 20 31 30 30 20 20  OW         100  
4c10: 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  /* sqlite3_step(
4c20: 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f  ) has another ro
4c30: 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69  w ready */.#defi
4c40: 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20  ne SQLITE_DONE  
4c50: 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71        101  /* sq
4c60: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73  lite3_step() has
4c70: 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74   finished execut
4c80: 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66  ing */./* end-of
4c90: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
4ca0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
4cb0: 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74   Extended Result
4cc0: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
4cd0: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65  DS: {extended re
4ce0: 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69  sult code defini
4cf0: 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20  tions}.**.** In 
4d00: 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  its default conf
4d10: 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74  iguration, SQLit
4d20: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72  e API routines r
4d30: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 33 30 20  eturn one of 30 
4d40: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 72 65 73 75  integer.** [resu
4d50: 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65  lt codes].  Howe
4d60: 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20  ver, experience 
4d70: 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d  has shown that m
4d80: 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20  any of.** these 
4d90: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4da0: 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69   too coarse-grai
4db0: 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f  ned.  They do no
4dc0: 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20  t provide as.** 
4dd0: 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  much information
4de0: 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20   about problems 
4df0: 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d  as programmers m
4e00: 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61  ight like.  In a
4e10: 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61  n effort to.** a
4e20: 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77  ddress this, new
4e30: 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  er versions of S
4e40: 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33  QLite (version 3
4e50: 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65 72 29 20  .3.8 and later) 
4e60: 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f  include.** suppo
4e70: 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  rt for additiona
4e80: 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 74  l result codes t
4e90: 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 65  hat provide more
4ea0: 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d   detailed inform
4eb0: 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65  ation.** about e
4ec0: 72 72 6f 72 73 2e 20 54 68 65 73 65 20 5b 65 78  rrors. These [ex
4ed0: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
4ee0: 64 65 73 5d 20 61 72 65 20 65 6e 61 62 6c 65 64  des] are enabled
4ef0: 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20   or disabled.** 
4f00: 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62 61 73  on a per databas
4f10: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73  e connection bas
4f20: 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  is using the.** 
4f30: 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65  [sqlite3_extende
4f40: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
4f50: 5d 20 41 50 49 2e 20 20 4f 72 2c 20 74 68 65 20  ] API.  Or, the 
4f60: 65 78 74 65 6e 64 65 64 20 63 6f 64 65 20 66 6f  extended code fo
4f70: 72 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20 72 65  r.** the most re
4f80: 63 65 6e 74 20 65 72 72 6f 72 20 63 61 6e 20 62  cent error can b
4f90: 65 20 6f 62 74 61 69 6e 65 64 20 75 73 69 6e 67  e obtained using
4fa0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74  .** [sqlite3_ext
4fb0: 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 5d  ended_errcode()]
4fc0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
4fd0: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20  ITE_IOERR_READ  
4fe0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
4ff0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c  ITE_IOERR | (1<<
5000: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5010: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
5020: 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  EAD        (SQLI
5030: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38  TE_IOERR | (2<<8
5040: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5050: 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20  E_IOERR_WRITE   
5060: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5070: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29  E_IOERR | (3<<8)
5080: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5090: 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20  _IOERR_FSYNC    
50a0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
50b0: 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29  _IOERR | (4<<8))
50c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
50d0: 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20  IOERR_DIR_FSYNC 
50e0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
50f0: 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a  IOERR | (5<<8)).
5100: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5110: 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20  OERR_TRUNCATE   
5120: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5130: 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23  OERR | (6<<8)).#
5140: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5150: 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20  ERR_FSTAT       
5160: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5170: 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64  ERR | (7<<8)).#d
5180: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5190: 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20  RR_UNLOCK       
51a0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
51b0: 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65  RR | (8<<8)).#de
51c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
51d0: 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_RDLOCK        
51e0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
51f0: 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66  R | (9<<8)).#def
5200: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5210: 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
5220: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5230: 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66   | (10<<8)).#def
5240: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5250: 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20  _BLOCKED        
5260: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5270: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66   | (11<<8)).#def
5280: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5290: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20  _NOMEM          
52a0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
52b0: 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66   | (12<<8)).#def
52c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
52d0: 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20  _ACCESS         
52e0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
52f0: 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66   | (13<<8)).#def
5300: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5310: 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f  _CHECKRESERVEDLO
5320: 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52  CK (SQLITE_IOERR
5330: 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66   | (14<<8)).#def
5340: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5350: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  _LOCK           
5360: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5370: 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66   | (15<<8)).#def
5380: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5390: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20  _CLOSE          
53a0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
53b0: 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66   | (16<<8)).#def
53c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
53d0: 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20  _DIR_CLOSE      
53e0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
53f0: 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66   | (17<<8)).#def
5400: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5410: 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20  _SHMOPEN        
5420: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5430: 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66   | (18<<8)).#def
5440: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5450: 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20  _SHMSIZE        
5460: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5470: 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66   | (19<<8)).#def
5480: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5490: 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20  _SHMLOCK        
54a0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
54b0: 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66   | (20<<8)).#def
54c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
54d0: 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20  _SHMMAP         
54e0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
54f0: 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66   | (21<<8)).#def
5500: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5510: 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20  _SEEK           
5520: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5530: 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66   | (22<<8)).#def
5540: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5550: 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20  _DELETE_NOENT   
5560: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5570: 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66   | (23<<8)).#def
5580: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5590: 5f 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20  _MMAP           
55a0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
55b0: 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66   | (24<<8)).#def
55c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
55d0: 5f 47 45 54 54 45 4d 50 50 41 54 48 20 20 20 20  _GETTEMPPATH    
55e0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
55f0: 20 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66   | (25<<8)).#def
5600: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5610: 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20  _CONVPATH       
5620: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5630: 20 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66   | (26<<8)).#def
5640: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5650: 5f 56 4e 4f 44 45 20 20 20 20 20 20 20 20 20 20  _VNODE          
5660: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5670: 20 7c 20 28 32 37 3c 3c 38 29 29 0a 23 64 65 66   | (27<<8)).#def
5680: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5690: 5f 41 55 54 48 20 20 20 20 20 20 20 20 20 20 20  _AUTH           
56a0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
56b0: 20 7c 20 28 32 38 3c 3c 38 29 29 0a 23 64 65 66   | (28<<8)).#def
56c0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
56d0: 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20  D_SHAREDCACHE   
56e0: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45     (SQLITE_LOCKE
56f0: 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65  D |  (1<<8)).#de
5700: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
5710: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20  _RECOVERY       
5720: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
5730: 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64     |  (1<<8)).#d
5740: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
5750: 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20 20  Y_SNAPSHOT      
5760: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53       (SQLITE_BUS
5770: 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23  Y   |  (2<<8)).#
5780: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
5790: 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52  NTOPEN_NOTEMPDIR
57a0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
57b0: 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29  NTOPEN | (1<<8))
57c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
57d0: 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20  CANTOPEN_ISDIR  
57e0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
57f0: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38  CANTOPEN | (2<<8
5800: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5810: 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50  E_CANTOPEN_FULLP
5820: 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54  ATH       (SQLIT
5830: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c  E_CANTOPEN | (3<
5840: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5850: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e  ITE_CANTOPEN_CON
5860: 56 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c  VPATH       (SQL
5870: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
5880: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
5890: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54  QLITE_CORRUPT_VT
58a0: 41 42 20 20 20 20 20 20 20 20 20 20 20 20 28 53  AB            (S
58b0: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20  QLITE_CORRUPT | 
58c0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
58d0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f  SQLITE_READONLY_
58e0: 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 28  RECOVERY       (
58f0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
5900: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5910: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
5920: 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20  Y_CANTLOCK      
5930: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   (SQLITE_READONL
5940: 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  Y | (2<<8)).#def
5950: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
5960: 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20  NLY_ROLLBACK    
5970: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f     (SQLITE_READO
5980: 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64  NLY | (3<<8)).#d
5990: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
59a0: 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20 20 20  DONLY_DBMOVED   
59b0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
59c0: 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29 29 0a  DONLY | (4<<8)).
59d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
59e0: 42 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20  BORT_ROLLBACK   
59f0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41         (SQLITE_A
5a00: 42 4f 52 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23  BORT | (2<<8)).#
5a10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5a20: 4e 53 54 52 41 49 4e 54 5f 43 48 45 43 4b 20 20  NSTRAINT_CHECK  
5a30: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5a40: 4e 53 54 52 41 49 4e 54 20 7c 20 28 31 3c 3c 38  NSTRAINT | (1<<8
5a50: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5a60: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 4f 4d  E_CONSTRAINT_COM
5a70: 4d 49 54 48 4f 4f 4b 20 20 20 28 53 51 4c 49 54  MITHOOK   (SQLIT
5a80: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5a90: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
5aa0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5ab0: 5f 46 4f 52 45 49 47 4e 4b 45 59 20 20 20 28 53  _FOREIGNKEY   (S
5ac0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5ad0: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69   | (3<<8)).#defi
5ae0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5af0: 41 49 4e 54 5f 46 55 4e 43 54 49 4f 4e 20 20 20  AINT_FUNCTION   
5b00: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5b10: 41 49 4e 54 20 7c 20 28 34 3c 3c 38 29 29 0a 23  AINT | (4<<8)).#
5b20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5b30: 4e 53 54 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c  NSTRAINT_NOTNULL
5b40: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5b50: 4e 53 54 52 41 49 4e 54 20 7c 20 28 35 3c 3c 38  NSTRAINT | (5<<8
5b60: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5b70: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 50 52 49  E_CONSTRAINT_PRI
5b80: 4d 41 52 59 4b 45 59 20 20 20 28 53 51 4c 49 54  MARYKEY   (SQLIT
5b90: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5ba0: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
5bb0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5bc0: 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 28 53  _TRIGGER      (S
5bd0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5be0: 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69   | (7<<8)).#defi
5bf0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5c00: 41 49 4e 54 5f 55 4e 49 51 55 45 20 20 20 20 20  AINT_UNIQUE     
5c10: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5c20: 41 49 4e 54 20 7c 20 28 38 3c 3c 38 29 29 0a 23  AINT | (8<<8)).#
5c30: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5c40: 4e 53 54 52 41 49 4e 54 5f 56 54 41 42 20 20 20  NSTRAINT_VTAB   
5c50: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5c60: 4e 53 54 52 41 49 4e 54 20 7c 20 28 39 3c 3c 38  NSTRAINT | (9<<8
5c70: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5c80: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 52 4f 57  E_CONSTRAINT_ROW
5c90: 49 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  ID        (SQLIT
5ca0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 28 31  E_CONSTRAINT |(1
5cb0: 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  0<<8)).#define S
5cc0: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43  QLITE_NOTICE_REC
5cd0: 4f 56 45 52 5f 57 41 4c 20 20 20 20 20 20 28 53  OVER_WAL      (S
5ce0: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28  QLITE_NOTICE | (
5cf0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5d00: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43  QLITE_NOTICE_REC
5d10: 4f 56 45 52 5f 52 4f 4c 4c 42 41 43 4b 20 28 53  OVER_ROLLBACK (S
5d20: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28  QLITE_NOTICE | (
5d30: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
5d40: 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 5f 41 55  QLITE_WARNING_AU
5d50: 54 4f 49 4e 44 45 58 20 20 20 20 20 20 20 28 53  TOINDEX       (S
5d60: 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 7c 20  QLITE_WARNING | 
5d70: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
5d80: 53 51 4c 49 54 45 5f 41 55 54 48 5f 55 53 45 52  SQLITE_AUTH_USER
5d90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28                 (
5da0: 53 51 4c 49 54 45 5f 41 55 54 48 20 7c 20 28 31  SQLITE_AUTH | (1
5db0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5dc0: 4c 49 54 45 5f 4f 4b 5f 4c 4f 41 44 5f 50 45 52  LITE_OK_LOAD_PER
5dd0: 4d 41 4e 45 4e 54 4c 59 20 20 20 20 20 28 53 51  MANENTLY     (SQ
5de0: 4c 49 54 45 5f 4f 4b 20 7c 20 28 31 3c 3c 38 29  LITE_OK | (1<<8)
5df0: 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  )../*.** CAPI3RE
5e00: 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69 6c  F: Flags For Fil
5e10: 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e  e Open Operation
5e20: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69  s.**.** These bi
5e30: 74 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 74  t values are int
5e40: 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e  ended for use in
5e50: 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72 61   the.** 3rd para
5e60: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  meter to the [sq
5e70: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
5e80: 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a 2a   interface and.*
5e90: 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70 61 72  * in the 4th par
5ea0: 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ameter to the [s
5eb0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
5ec0: 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23 64 65  ] method..*/.#de
5ed0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5ee0: 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20  _READONLY       
5ef0: 20 20 30 78 30 30 30 30 30 30 30 31 20 20 2f 2a    0x00000001  /*
5f00: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
5f10: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
5f20: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5f30: 5f 52 45 41 44 57 52 49 54 45 20 20 20 20 20 20  _READWRITE      
5f40: 20 20 30 78 30 30 30 30 30 30 30 32 20 20 2f 2a    0x00000002  /*
5f50: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
5f60: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
5f70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5f80: 5f 43 52 45 41 54 45 20 20 20 20 20 20 20 20 20  _CREATE         
5f90: 20 20 30 78 30 30 30 30 30 30 30 34 20 20 2f 2a    0x00000004  /*
5fa0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
5fb0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
5fc0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5fd0: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20  _DELETEONCLOSE  
5fe0: 20 20 30 78 30 30 30 30 30 30 30 38 20 20 2f 2a    0x00000008  /*
5ff0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6000: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6010: 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 20  _EXCLUSIVE      
6020: 20 20 30 78 30 30 30 30 30 30 31 30 20 20 2f 2a    0x00000010  /*
6030: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6040: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6050: 5f 41 55 54 4f 50 52 4f 58 59 20 20 20 20 20 20  _AUTOPROXY      
6060: 20 20 30 78 30 30 30 30 30 30 32 30 20 20 2f 2a    0x00000020  /*
6070: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6080: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6090: 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 20 20  _URI            
60a0: 20 20 30 78 30 30 30 30 30 30 34 30 20 20 2f 2a    0x00000040  /*
60b0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
60c0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
60d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
60e0: 5f 4d 45 4d 4f 52 59 20 20 20 20 20 20 20 20 20  _MEMORY         
60f0: 20 20 30 78 30 30 30 30 30 30 38 30 20 20 2f 2a    0x00000080  /*
6100: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
6110: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
6120: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6130: 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20  _MAIN_DB        
6140: 20 20 30 78 30 30 30 30 30 31 30 30 20 20 2f 2a    0x00000100  /*
6150: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6160: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6170: 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20  _TEMP_DB        
6180: 20 20 30 78 30 30 30 30 30 32 30 30 20 20 2f 2a    0x00000200  /*
6190: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
61a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
61b0: 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20  _TRANSIENT_DB   
61c0: 20 20 30 78 30 30 30 30 30 34 30 30 20 20 2f 2a    0x00000400  /*
61d0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
61e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
61f0: 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20  _MAIN_JOURNAL   
6200: 20 20 30 78 30 30 30 30 30 38 30 30 20 20 2f 2a    0x00000800  /*
6210: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6220: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6230: 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20  _TEMP_JOURNAL   
6240: 20 20 30 78 30 30 30 30 31 30 30 30 20 20 2f 2a    0x00001000  /*
6250: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6260: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6270: 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20  _SUBJOURNAL     
6280: 20 20 30 78 30 30 30 30 32 30 30 30 20 20 2f 2a    0x00002000  /*
6290: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
62a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
62b0: 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20  _MASTER_JOURNAL 
62c0: 20 20 30 78 30 30 30 30 34 30 30 30 20 20 2f 2a    0x00004000  /*
62d0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
62e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
62f0: 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20  _NOMUTEX        
6300: 20 20 30 78 30 30 30 30 38 30 30 30 20 20 2f 2a    0x00008000  /*
6310: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
6320: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
6330: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6340: 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20  _FULLMUTEX      
6350: 20 20 30 78 30 30 30 31 30 30 30 30 20 20 2f 2a    0x00010000  /*
6360: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
6370: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
6380: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6390: 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20  _SHAREDCACHE    
63a0: 20 20 30 78 30 30 30 32 30 30 30 30 20 20 2f 2a    0x00020000  /*
63b0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
63c0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
63d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
63e0: 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 20 20  _PRIVATECACHE   
63f0: 20 20 30 78 30 30 30 34 30 30 30 30 20 20 2f 2a    0x00040000  /*
6400: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
6410: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
6420: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6430: 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20  _WAL            
6440: 20 20 30 78 30 30 30 38 30 30 30 30 20 20 2f 2a    0x00080000  /*
6450: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6460: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6470: 5f 46 49 4c 45 50 52 4f 54 45 43 54 49 4f 4e 5f  _FILEPROTECTION_
6480: 4d 41 53 4b 20 20 20 20 20 20 20 20 20 20 20 20  MASK            
6490: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
64a0: 20 20 20 20 20 30 78 30 30 37 30 30 30 30 30 0a       0x00700000.
64b0: 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a 20 20 20  ./* Reserved:   
64c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
64d0: 20 20 20 20 20 20 30 78 30 30 46 30 30 30 30 30        0x00F00000
64e0: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
64f0: 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61 72  REF: Device Char
6500: 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a  acteristics.**.*
6510: 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61  * The xDeviceCha
6520: 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74  racteristics met
6530: 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  hod of the [sqli
6540: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a  te3_io_methods].
6550: 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  ** object return
6560: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
6570: 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f  ch is a vector o
6580: 66 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 76  f these.** bit v
6590: 61 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e 67  alues expressing
65a0: 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69 73   I/O characteris
65b0: 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73 73  tics of the mass
65c0: 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69   storage.** devi
65d0: 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68  ce that holds th
65e0: 65 20 66 69 6c 65 20 74 68 61 74 20 74 68 65 20  e file that the 
65f0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
6600: 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74  ods].** refers t
6610: 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  o..**.** The SQL
6620: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6630: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
6640: 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20  that all writes 
6650: 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61  of.** any size a
6660: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
6670: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6680: 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a  MICnnn values.**
6690: 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65   mean that write
66a0: 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74  s of blocks that
66b0: 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69   are nnn bytes i
66c0: 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72  n size and.** ar
66d0: 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
66e0: 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73  address which is
66f0: 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74   an integer mult
6700: 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61  iple of.** nnn a
6710: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
6720: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
6730: 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d  E_APPEND value m
6740: 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65  eans.** that whe
6750: 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  n data is append
6760: 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68  ed to a file, th
6770: 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  e data is append
6780: 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e  ed.** first then
6790: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
67a0: 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65   file is extende
67b0: 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68  d, never the oth
67c0: 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64  er.** way around
67d0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
67e0: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70  CAP_SEQUENTIAL p
67f0: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
6800: 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  at.** informatio
6810: 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20  n is written to 
6820: 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65  disk in the same
6830: 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a   order as calls.
6840: 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 20  ** to xWrite(). 
6850: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6860: 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  P_POWERSAFE_OVER
6870: 57 52 49 54 45 20 70 72 6f 70 65 72 74 79 20 6d  WRITE property m
6880: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 61 66 74  eans that.** aft
6890: 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77  er reboot follow
68a0: 69 6e 67 20 61 20 63 72 61 73 68 20 6f 72 20 70  ing a crash or p
68b0: 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68 65 20 6f  ower loss, the o
68c0: 6e 6c 79 20 62 79 74 65 73 20 69 6e 20 61 0a 2a  nly bytes in a.*
68d0: 2a 20 66 69 6c 65 20 74 68 61 74 20 77 65 72 65  * file that were
68e0: 20 77 72 69 74 74 65 6e 20 61 74 20 74 68 65 20   written at the 
68f0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c 65 76 65  application leve
6900: 6c 20 6d 69 67 68 74 20 68 61 76 65 20 63 68 61  l might have cha
6910: 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74 68 61 74  nged.** and that
6920: 20 61 64 6a 61 63 65 6e 74 20 62 79 74 65 73 2c   adjacent bytes,
6930: 20 65 76 65 6e 20 62 79 74 65 73 20 77 69 74 68   even bytes with
6940: 69 6e 20 74 68 65 20 73 61 6d 65 20 73 65 63 74  in the same sect
6950: 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61 72 61 6e  or are.** guaran
6960: 74 65 65 64 20 74 6f 20 62 65 20 75 6e 63 68 61  teed to be uncha
6970: 6e 67 65 64 2e 20 20 54 68 65 20 53 51 4c 49 54  nged.  The SQLIT
6980: 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41  E_IOCAP_UNDELETA
6990: 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 0a 2a 2a  BLE_WHEN_OPEN.**
69a0: 20 66 6c 61 67 20 69 6e 64 69 63 61 74 65 20 74   flag indicate t
69b0: 68 61 74 20 61 20 66 69 6c 65 20 63 61 6e 6e 6f  hat a file canno
69c0: 74 20 62 65 20 64 65 6c 65 74 65 64 20 77 68 65  t be deleted whe
69d0: 6e 20 6f 70 65 6e 2e 20 20 54 68 65 0a 2a 2a 20  n open.  The.** 
69e0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d  SQLITE_IOCAP_IMM
69f0: 55 54 41 42 4c 45 20 66 6c 61 67 20 69 6e 64 69  UTABLE flag indi
6a00: 63 61 74 65 73 20 74 68 61 74 20 74 68 65 20 66  cates that the f
6a10: 69 6c 65 20 69 73 20 6f 6e 0a 2a 2a 20 72 65 61  ile is on.** rea
6a20: 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 20 61 6e 64  d-only media and
6a30: 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67   cannot be chang
6a40: 65 64 20 65 76 65 6e 20 62 79 20 70 72 6f 63 65  ed even by proce
6a50: 73 73 65 73 20 77 69 74 68 0a 2a 2a 20 65 6c 65  sses with.** ele
6a60: 76 61 74 65 64 20 70 72 69 76 69 6c 65 67 65 73  vated privileges
6a70: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
6a80: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6a90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6aa0: 20 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 66   0x00000001.#def
6ab0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6ac0: 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20  _ATOMIC512      
6ad0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6ae0: 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  02.#define SQLIT
6af0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b  E_IOCAP_ATOMIC1K
6b00: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
6b10: 78 30 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e  x00000004.#defin
6b20: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6b30: 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20 20  TOMIC2K         
6b40: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 38        0x00000008
6b50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6b60: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20  IOCAP_ATOMIC4K  
6b70: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6b80: 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20  0000010.#define 
6b90: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6ba0: 4d 49 43 38 4b 20 20 20 20 20 20 20 20 20 20 20  MIC8K           
6bb0: 20 20 20 20 30 78 30 30 30 30 30 30 32 30 0a 23      0x00000020.#
6bc0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6bd0: 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20  CAP_ATOMIC16K   
6be0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6bf0: 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51  00040.#define SQ
6c00: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6c10: 43 33 32 4b 20 20 20 20 20 20 20 20 20 20 20 20  C32K            
6c20: 20 20 30 78 30 30 30 30 30 30 38 30 0a 23 64 65    0x00000080.#de
6c30: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6c40: 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20  P_ATOMIC64K     
6c50: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6c60: 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  100.#define SQLI
6c70: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
6c80: 50 45 4e 44 20 20 20 20 20 20 20 20 20 20 20 20  PEND            
6c90: 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 69  0x00000200.#defi
6ca0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6cb0: 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20  SEQUENTIAL      
6cc0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 34 30         0x0000040
6cd0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6ce0: 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42  _IOCAP_UNDELETAB
6cf0: 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78  LE_WHEN_OPEN  0x
6d00: 30 30 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65  00000800.#define
6d10: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f   SQLITE_IOCAP_PO
6d20: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
6d30: 45 20 20 20 20 30 78 30 30 30 30 31 30 30 30 0a  E    0x00001000.
6d40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6d50: 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 20  OCAP_IMMUTABLE  
6d60: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6d70: 30 30 32 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41  002000../*.** CA
6d80: 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63  PI3REF: File Loc
6d90: 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a  king Levels.**.*
6da0: 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e  * SQLite uses on
6db0: 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67  e of these integ
6dc0: 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65  er values as the
6dd0: 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d   second.** argum
6de0: 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20  ent to calls it 
6df0: 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f  makes to the xLo
6e00: 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b  ck() and xUnlock
6e10: 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66  () methods.** of
6e20: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f   an [sqlite3_io_
6e30: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e  methods] object.
6e40: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
6e50: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20  TE_LOCK_NONE    
6e60: 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20        0.#define 
6e70: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
6e80: 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65 66  ED        1.#def
6e90: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
6ea0: 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32 0a  RESERVED      2.
6eb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
6ec0: 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20  OCK_PENDING     
6ed0: 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
6ee0: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56  TE_LOCK_EXCLUSIV
6ef0: 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43  E     4../*.** C
6f00: 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f  API3REF: Synchro
6f10: 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c  nization Type Fl
6f20: 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53  ags.**.** When S
6f30: 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68  QLite invokes th
6f40: 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64  e xSync() method
6f50: 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74   of an.** [sqlit
6f60: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
6f70: 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61 20  bject it uses a 
6f80: 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a  combination of.*
6f90: 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20  * these integer 
6fa0: 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65  values as the se
6fb0: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  cond argument..*
6fc0: 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51  *.** When the SQ
6fd0: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e  LITE_SYNC_DATAON
6fe0: 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c  LY flag is used,
6ff0: 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74   it means that t
7000: 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61  he.** sync opera
7010: 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20  tion only needs 
7020: 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f  to flush data to
7030: 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20   mass storage.  
7040: 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61  Inode.** informa
7050: 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65  tion need not be
7060: 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68 65   flushed. If the
7070: 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73   lower four bits
7080: 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20   of the flag.** 
7090: 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e  equal SQLITE_SYN
70a0: 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d  C_NORMAL, that m
70b0: 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d  eans to use norm
70c0: 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e  al fsync() seman
70d0: 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20  tics..** If the 
70e0: 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20  lower four bits 
70f0: 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e  equal SQLITE_SYN
7100: 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61  C_FULL, that mea
7110: 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63  ns.** to use Mac
7120: 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c   OS X style full
7130: 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20  sync instead of 
7140: 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44  fsync()..**.** D
7150: 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74 68  o not confuse th
7160: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  e SQLITE_SYNC_NO
7170: 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f  RMAL and SQLITE_
7180: 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a  SYNC_FULL flags.
7190: 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52 41  ** with the [PRA
71a0: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d  GMA synchronous]
71b0: 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41  =NORMAL and [PRA
71c0: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d  GMA synchronous]
71d0: 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67  =FULL.** setting
71e0: 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72 6f  s.  The [synchro
71f0: 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65 74  nous pragma] det
7200: 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61 6c  ermines when cal
7210: 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79  ls to the.** xSy
7220: 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f 63  nc VFS method oc
7230: 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73 20  cur and applies 
7240: 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73  uniformly across
7250: 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a   all platforms..
7260: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59  ** The SQLITE_SY
7270: 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51  NC_NORMAL and SQ
7280: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66  LITE_SYNC_FULL f
7290: 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20 68  lags determine h
72a0: 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63 20  ow.** energetic 
72b0: 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20 66  or rigorous or f
72c0: 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e 63  orceful the sync
72d0: 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20   operations are 
72e0: 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65  and.** only make
72f0: 20 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e   a difference on
7300: 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68 65   Mac OSX for the
7310: 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65 20   default SQLite 
7320: 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d  code..** (Third-
7330: 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65 6d  party VFS implem
7340: 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74 20  entations might 
7350: 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64 69  also make the di
7360: 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74  stinction.** bet
7370: 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43  ween SQLITE_SYNC
7380: 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49  _NORMAL and SQLI
7390: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75  TE_SYNC_FULL, bu
73a0: 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f  t among the.** o
73b0: 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 73  perating systems
73c0: 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f 72   natively suppor
73d0: 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20 6f  ted by SQLite, o
73e0: 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63  nly Mac OSX.** c
73f0: 61 72 65 73 20 61 62 6f 75 74 20 74 68 65 20 64  ares about the d
7400: 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23  ifference.).*/.#
7410: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59  define SQLITE_SY
7420: 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20  NC_NORMAL       
7430: 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65   0x00002.#define
7440: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
7450: 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  L          0x000
7460: 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  03.#define SQLIT
7470: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20  E_SYNC_DATAONLY 
7480: 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a       0x00010../*
7490: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
74a0: 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20   Interface Open 
74b0: 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a  File Handle.**.*
74c0: 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  * An [sqlite3_fi
74d0: 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65  le] object repre
74e0: 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69  sents an open fi
74f0: 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73  le in the .** [s
7500: 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53 20  qlite3_vfs | OS 
7510: 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 5d  interface layer]
7520: 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53  .  Individual OS
7530: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d   interface.** im
7540: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69  plementations wi
7550: 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75  ll.** want to su
7560: 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65  bclass this obje
7570: 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20  ct by appending 
7580: 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64  additional field
7590: 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f  s.** for their o
75a0: 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65  wn use.  The pMe
75b0: 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61  thods entry is a
75c0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
75d0: 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  * [sqlite3_io_me
75e0: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68  thods] object th
75f0: 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f  at defines metho
7600: 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e  ds for performin
7610: 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69  g.** I/O operati
7620: 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20  ons on the open 
7630: 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  file..*/.typedef
7640: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
7650: 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c  file sqlite3_fil
7660: 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  e;.struct sqlite
7670: 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74  3_file {.  const
7680: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
7690: 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74  io_methods *pMet
76a0: 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64  hods;  /* Method
76b0: 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69  s for an open fi
76c0: 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  le */.};../*.** 
76d0: 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74  CAPI3REF: OS Int
76e0: 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72 74  erface File Virt
76f0: 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65  ual Methods Obje
7700: 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66  ct.**.** Every f
7710: 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68  ile opened by th
7720: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
7730: 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70  Open] method pop
7740: 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71  ulates an.** [sq
7750: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
7760: 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d  ct (or, more com
7770: 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73  monly, a subclas
7780: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  s of the.** [sql
7790: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
77a0: 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65  t) with a pointe
77b0: 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
77c0: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e   of this object.
77d0: 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20  .** This object 
77e0: 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68  defines the meth
77f0: 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72 66  ods used to perf
7800: 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72  orm various oper
7810: 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73  ations.** agains
7820: 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20  t the open file 
7830: 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 74  represented by t
7840: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
7850: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  ] object..**.** 
7860: 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  If the [sqlite3_
7870: 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f  vfs.xOpen] metho
7880: 64 20 73 65 74 73 20 74 68 65 20 73 71 6c 69 74  d sets the sqlit
7890: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
78a0: 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20   element .** to 
78b0: 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
78c0: 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c  er, then the sql
78d0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e  ite3_io_methods.
78e0: 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a  xClose method.**
78f0: 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20   may be invoked 
7900: 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71 6c  even if the [sql
7910: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
7920: 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 69 74  reported that it
7930: 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a   failed.  The.**
7940: 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 65   only way to pre
7950: 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 78  vent a call to x
7960: 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  Close following 
7970: 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74 65  a failed [sqlite
7980: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20  3_vfs.xOpen].** 
7990: 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69  is for the [sqli
79a0: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74  te3_vfs.xOpen] t
79b0: 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65  o set the sqlite
79c0: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
79d0: 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55  element.** to NU
79e0: 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c  LL..**.** The fl
79f0: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
7a00: 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65  xSync may be one
7a10: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43   of [SQLITE_SYNC
7a20: 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b  _NORMAL] or.** [
7a30: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
7a40: 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63 68  ].  The first ch
7a50: 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d  oice is the norm
7a60: 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54  al fsync()..** T
7a70: 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65  he second choice
7a80: 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73   is a Mac OS X s
7a90: 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20  tyle fullsync.  
7aa0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43  The [SQLITE_SYNC
7ab0: 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c  _DATAONLY].** fl
7ac0: 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69  ag may be ORed i
7ad0: 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  n to indicate th
7ae0: 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61  at only the data
7af0: 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20   of the file.** 
7b00: 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64  and not its inod
7b10: 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79  e needs to be sy
7b20: 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nced..**.** The 
7b30: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 74  integer values t
7b40: 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55  o xLock() and xU
7b50: 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20  nlock() are one 
7b60: 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  of.** <ul>.** <l
7b70: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
7b80: 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  NONE],.** <li> [
7b90: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
7ba0: 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  ED],.** <li> [SQ
7bb0: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56  LITE_LOCK_RESERV
7bc0: 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  ED],.** <li> [SQ
7bd0: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e  LITE_LOCK_PENDIN
7be0: 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b  G], or.** <li> [
7bf0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
7c00: 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e  USIVE]..** </ul>
7c10: 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72  .** xLock() incr
7c20: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20  eases the lock. 
7c30: 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61  xUnlock() decrea
7c40: 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a  ses the lock..**
7c50: 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65 72   The xCheckReser
7c60: 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64  vedLock() method
7c70: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
7c80: 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e  any database con
7c90: 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68  nection,.** eith
7ca0: 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65  er in this proce
7cb0: 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74  ss or in some ot
7cc0: 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20  her process, is 
7cd0: 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56  holding a RESERV
7ce0: 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20  ED,.** PENDING, 
7cf0: 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63  or EXCLUSIVE loc
7d00: 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20  k on the file.  
7d10: 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a  It returns true.
7d20: 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63  ** if such a loc
7d30: 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c  k exists and fal
7d40: 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a  se otherwise..**
7d50: 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e  .** The xFileCon
7d60: 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73  trol() method is
7d70: 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72   a generic inter
7d80: 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73  face that allows
7d90: 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69   custom.** VFS i
7da0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74  mplementations t
7db0: 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72  o directly contr
7dc0: 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  ol an open file 
7dd0: 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
7de0: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
7df0: 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ol()] interface.
7e00: 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70    The second "op
7e10: 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  " argument is an
7e20: 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f  .** integer opco
7e30: 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 20 61  de.  The third a
7e40: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e  rgument is a gen
7e50: 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74  eric pointer int
7e60: 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e  ended to.** poin
7e70: 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 65  t to a structure
7e80: 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69   that may contai
7e90: 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73  n arguments or s
7ea0: 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f  pace in which to
7eb0: 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e  .** write return
7ec0: 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74   values.  Potent
7ed0: 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69  ial uses for xFi
7ee0: 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68  leControl() migh
7ef0: 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  t be.** function
7f00: 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63  s to enable bloc
7f10: 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20  king locks with 
7f20: 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61  timeouts, to cha
7f30: 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69  nge the.** locki
7f40: 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f 72  ng strategy (for
7f50: 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20   example to use 
7f60: 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c  dot-file locks),
7f70: 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61   to inquire.** a
7f80: 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73 20  bout the status 
7f90: 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f  of a lock, or to
7fa0: 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63   break stale loc
7fb0: 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a  ks.  The SQLite.
7fc0: 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65 73  ** core reserves
7fd0: 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73   all opcodes les
7fe0: 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69  s than 100 for i
7ff0: 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41  ts own use..** A
8000: 20 5b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f   [file control o
8010: 70 63 6f 64 65 73 20 7c 20 6c 69 73 74 20 6f 66  pcodes | list of
8020: 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74   opcodes] less t
8030: 68 61 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c  han 100 is avail
8040: 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61  able..** Applica
8050: 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e  tions that defin
8060: 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65  e a custom xFile
8070: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73  Control method s
8080: 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65  hould use opcode
8090: 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61  s.** greater tha
80a0: 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63  n 100 to avoid c
80b0: 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46 53 20 69  onflicts.  VFS i
80c0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73  mplementations s
80d0: 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20  hould.** return 
80e0: 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44  [SQLITE_NOTFOUND
80f0: 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72  ] for file contr
8100: 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68 61 74 20  ol opcodes that 
8110: 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72  they do not.** r
8120: 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20  ecognize..**.** 
8130: 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28  The xSectorSize(
8140: 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  ) method returns
8150: 20 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65   the sector size
8160: 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63   of the.** devic
8170: 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73  e that underlies
8180: 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20   the file.  The 
8190: 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74  sector size is t
81a0: 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72  he.** minimum wr
81b0: 69 74 65 20 74 68 61 74 20 63 61 6e 20 62 65 20  ite that can be 
81c0: 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75  performed withou
81d0: 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20  t disturbing.** 
81e0: 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e 20 74  other bytes in t
81f0: 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44  he file.  The xD
8200: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
8210: 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64  tics().** method
8220: 20 72 65 74 75 72 6e 73 20 61 20 62 69 74 20 76   returns a bit v
8230: 65 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67  ector describing
8240: 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68   behaviors of th
8250: 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20  e.** underlying 
8260: 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75  device:.**.** <u
8270: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
8280: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d  TE_IOCAP_ATOMIC]
8290: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
82a0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32  _IOCAP_ATOMIC512
82b0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
82c0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b  E_IOCAP_ATOMIC1K
82d0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
82e0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b  E_IOCAP_ATOMIC2K
82f0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
8300: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b  E_IOCAP_ATOMIC4K
8310: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
8320: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b  E_IOCAP_ATOMIC8K
8330: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
8340: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36  E_IOCAP_ATOMIC16
8350: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
8360: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33  TE_IOCAP_ATOMIC3
8370: 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  2K].** <li> [SQL
8380: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
8390: 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  64K].** <li> [SQ
83a0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
83b0: 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20  APPEND].** <li> 
83c0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45  [SQLITE_IOCAP_SE
83d0: 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75  QUENTIAL].** </u
83e0: 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  l>.**.** The SQL
83f0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
8400: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
8410: 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20  that all writes 
8420: 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61  of.** any size a
8430: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
8440: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8450: 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a  MICnnn values.**
8460: 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65   mean that write
8470: 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74  s of blocks that
8480: 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69   are nnn bytes i
8490: 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72  n size and.** ar
84a0: 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
84b0: 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73  address which is
84c0: 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74   an integer mult
84d0: 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61  iple of.** nnn a
84e0: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
84f0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
8500: 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d  E_APPEND value m
8510: 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65  eans.** that whe
8520: 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  n data is append
8530: 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68  ed to a file, th
8540: 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  e data is append
8550: 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e  ed.** first then
8560: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
8570: 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65   file is extende
8580: 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68  d, never the oth
8590: 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64  er.** way around
85a0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
85b0: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70  CAP_SEQUENTIAL p
85c0: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
85d0: 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  at.** informatio
85e0: 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20  n is written to 
85f0: 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65  disk in the same
8600: 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a   order as calls.
8610: 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a  ** to xWrite()..
8620: 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29  **.** If xRead()
8630: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f   returns SQLITE_
8640: 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44  IOERR_SHORT_READ
8650: 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69   it must also fi
8660: 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72  ll.** in the unr
8670: 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20  ead portions of 
8680: 74 68 65 20 62 75 66 66 65 72 20 77 69 74 68 20  the buffer with 
8690: 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68  zeros.  A VFS th
86a0: 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a  at.** fails to z
86b0: 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72  ero-fill short r
86c0: 65 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20  eads might seem 
86d0: 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65  to work.  Howeve
86e0: 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f  r,.** failure to
86f0: 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74   zero-fill short
8700: 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e   reads will even
8710: 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a  tually lead to.*
8720: 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 75  * database corru
8730: 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65  ption..*/.typede
8740: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
8750: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69  _io_methods sqli
8760: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a  te3_io_methods;.
8770: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
8780: 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e  o_methods {.  in
8790: 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e  t iVersion;.  in
87a0: 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69  t (*xClose)(sqli
87b0: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
87c0: 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74  t (*xRead)(sqlit
87d0: 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c  e3_file*, void*,
87e0: 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74   int iAmt, sqlit
87f0: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b  e3_int64 iOfst);
8800: 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29  .  int (*xWrite)
8810: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8820: 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
8830: 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69   iAmt, sqlite3_i
8840: 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69  nt64 iOfst);.  i
8850: 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28  nt (*xTruncate)(
8860: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
8870: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a  qlite3_int64 siz
8880: 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e  e);.  int (*xSyn
8890: 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  c)(sqlite3_file*
88a0: 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20  , int flags);.  
88b0: 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29  int (*xFileSize)
88c0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
88d0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70  sqlite3_int64 *p
88e0: 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78  Size);.  int (*x
88f0: 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69  Lock)(sqlite3_fi
8900: 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74  le*, int);.  int
8910: 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69   (*xUnlock)(sqli
8920: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b  te3_file*, int);
8930: 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52  .  int (*xCheckR
8940: 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c  eservedLock)(sql
8950: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
8960: 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74  *pResOut);.  int
8970: 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29   (*xFileControl)
8980: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8990: 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41  int op, void *pA
89a0: 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65  rg);.  int (*xSe
89b0: 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65  ctorSize)(sqlite
89c0: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
89d0: 28 2a 78 44 65 76 69 63 65 43 68 61 72 61 63 74  (*xDeviceCharact
89e0: 65 72 69 73 74 69 63 73 29 28 73 71 6c 69 74 65  eristics)(sqlite
89f0: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d  3_file*);.  /* M
8a00: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
8a10: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69   valid for versi
8a20: 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  on 1 */.  int (*
8a30: 78 53 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33  xShmMap)(sqlite3
8a40: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c  _file*, int iPg,
8a50: 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20   int pgsz, int, 
8a60: 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29  void volatile**)
8a70: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f  ;.  int (*xShmLo
8a80: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
8a90: 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69  *, int offset, i
8aa0: 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29  nt n, int flags)
8ab0: 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42  ;.  void (*xShmB
8ac0: 61 72 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f  arrier)(sqlite3_
8ad0: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  file*);.  int (*
8ae0: 78 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74  xShmUnmap)(sqlit
8af0: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65  e3_file*, int de
8b00: 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20  leteFlag);.  /* 
8b10: 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  Methods above ar
8b20: 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73  e valid for vers
8b30: 69 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20 28  ion 2 */.  int (
8b40: 2a 78 46 65 74 63 68 29 28 73 71 6c 69 74 65 33  *xFetch)(sqlite3
8b50: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
8b60: 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 69 6e 74  int64 iOfst, int
8b70: 20 69 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70 70   iAmt, void **pp
8b80: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66 65  );.  int (*xUnfe
8b90: 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  tch)(sqlite3_fil
8ba0: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  e*, sqlite3_int6
8bb0: 34 20 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a 70  4 iOfst, void *p
8bc0: 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  );.  /* Methods 
8bd0: 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20  above are valid 
8be0: 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 2a 2f  for version 3 */
8bf0: 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c  .  /* Additional
8c00: 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20   methods may be 
8c10: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
8c20: 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a  releases */.};..
8c30: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
8c40: 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f  Standard File Co
8c50: 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a  ntrol Opcodes.**
8c60: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 69 6c 65   KEYWORDS: {file
8c70: 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73   control opcodes
8c80: 7d 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  } {file control 
8c90: 6f 70 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68  opcode}.**.** Th
8ca0: 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
8cb0: 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65  tants are opcode
8cc0: 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43  s for the xFileC
8cd0: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a  ontrol method.**
8ce0: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
8cf0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
8d00: 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20  ect and for the 
8d10: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
8d20: 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65  ntrol()].** inte
8d30: 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c  rface..**.** <ul
8d40: 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  >.** <li>[[SQLIT
8d50: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
8d60: 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  E]].** The [SQLI
8d70: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41  TE_FCNTL_LOCKSTA
8d80: 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  TE] opcode is us
8d90: 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67  ed for debugging
8da0: 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64  .  This.** opcod
8db0: 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69  e causes the xFi
8dc0: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
8dd0: 20 74 6f 20 77 72 69 74 65 20 74 68 65 20 63 75   to write the cu
8de0: 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a  rrent state of.*
8df0: 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20  * the lock (one 
8e00: 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  of [SQLITE_LOCK_
8e10: 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c  NONE], [SQLITE_L
8e20: 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20  OCK_SHARED],.** 
8e30: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53  [SQLITE_LOCK_RES
8e40: 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f  ERVED], [SQLITE_
8e50: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f  LOCK_PENDING], o
8e60: 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  r [SQLITE_LOCK_E
8e70: 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e  XCLUSIVE]).** in
8e80: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68  to an integer th
8e90: 61 74 20 74 68 65 20 70 41 72 67 20 61 72 67 75  at the pArg argu
8ea0: 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20  ment points to. 
8eb0: 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a  This capability.
8ec0: 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72 69 6e  ** is used durin
8ed0: 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20 69 73  g testing and is
8ee0: 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
8ef0: 77 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f  when the SQLITE_
8f00: 54 45 53 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d  TEST.** compile-
8f10: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 75  time option is u
8f20: 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  sed..**.** <li>[
8f30: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49  [SQLITE_FCNTL_SI
8f40: 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65  ZE_HINT]].** The
8f50: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53   [SQLITE_FCNTL_S
8f60: 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65  IZE_HINT] opcode
8f70: 20 69 73 20 75 73 65 64 20 62 79 20 53 51 4c 69   is used by SQLi
8f80: 74 65 20 74 6f 20 67 69 76 65 20 74 68 65 20 56  te to give the V
8f90: 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69  FS.** layer a hi
8fa0: 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20  nt of how large 
8fb0: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
8fc0: 65 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62  e will grow to b
8fd0: 65 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20  e during the.** 
8fe0: 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74  current transact
8ff0: 69 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20  ion.  This hint 
9000: 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65  is not guarantee
9010: 64 20 74 6f 20 62 65 20 61 63 63 75 72 61 74 65  d to be accurate
9020: 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66   but it.** is of
9030: 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20  ten close.  The 
9040: 75 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d  underlying VFS m
9050: 69 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70  ight choose to p
9060: 72 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62  reallocate datab
9070: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63  ase.** file spac
9080: 65 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20  e based on this 
9090: 68 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f  hint in order to
90a0: 20 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20   help writes to 
90b0: 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
90c0: 66 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e  file run faster.
90d0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
90e0: 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f  ITE_FCNTL_CHUNK_
90f0: 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  SIZE]].** The [S
9100: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e  QLITE_FCNTL_CHUN
9110: 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69  K_SIZE] opcode i
9120: 73 20 75 73 65 64 20 74 6f 20 72 65 71 75 65 73  s used to reques
9130: 74 20 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a  t that the VFS.*
9140: 2a 20 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72  * extends and tr
9150: 75 6e 63 61 74 65 73 20 74 68 65 20 64 61 74 61  uncates the data
9160: 62 61 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75  base file in chu
9170: 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70  nks of a size sp
9180: 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68  ecified.** by th
9190: 65 20 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72  e user. The four
91a0: 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b  th argument to [
91b0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
91c0: 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a  trol()] should .
91d0: 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69  ** point to an i
91e0: 6e 74 65 67 65 72 20 28 74 79 70 65 20 69 6e 74  nteger (type int
91f0: 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  ) containing the
9200: 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20   new chunk-size 
9210: 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68  to use.** for th
9220: 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61  e nominated data
9230: 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67  base. Allocating
9240: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 73   database file s
9250: 70 61 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a  pace in large.**
9260: 20 63 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42   chunks (say 1MB
9270: 20 61 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79   at a time), may
9280: 20 72 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73   reduce file-sys
9290: 74 65 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f  tem fragmentatio
92a0: 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65  n and.** improve
92b0: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20   performance on 
92c0: 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a  some systems..**
92d0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
92e0: 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e  _FCNTL_FILE_POIN
92f0: 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  TER]].** The [SQ
9300: 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f  LITE_FCNTL_FILE_
9310: 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20  POINTER] opcode 
9320: 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  is used to obtai
9330: 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  n a pointer.** t
9340: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  o the [sqlite3_f
9350: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f  ile] object asso
9360: 63 69 61 74 65 64 20 77 69 74 68 20 61 20 70 61  ciated with a pa
9370: 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73  rticular databas
9380: 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  e.** connection.
9390: 20 20 53 65 65 20 61 6c 73 6f 20 5b 53 51 4c 49    See also [SQLI
93a0: 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c  TE_FCNTL_JOURNAL
93b0: 5f 50 4f 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a  _POINTER]..**.**
93c0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
93d0: 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e  NTL_JOURNAL_POIN
93e0: 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  TER]].** The [SQ
93f0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e  LITE_FCNTL_JOURN
9400: 41 4c 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f  AL_POINTER] opco
9410: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62  de is used to ob
9420: 74 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a  tain a pointer.*
9430: 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  * to the [sqlite
9440: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61  3_file] object a
9450: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
9460: 68 65 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20  he journal file 
9470: 28 65 69 74 68 65 72 0a 2a 2a 20 74 68 65 20 5b  (either.** the [
9480: 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c  rollback journal
9490: 5d 20 6f 72 20 74 68 65 20 5b 77 72 69 74 65 2d  ] or the [write-
94a0: 61 68 65 61 64 20 6c 6f 67 5d 29 20 66 6f 72 20  ahead log]) for 
94b0: 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 74  a particular dat
94c0: 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
94d0: 69 6f 6e 2e 20 20 53 65 65 20 61 6c 73 6f 20 5b  ion.  See also [
94e0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c  SQLITE_FCNTL_FIL
94f0: 45 5f 50 4f 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a  E_POINTER]..**.*
9500: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
9510: 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45  CNTL_SYNC_OMITTE
9520: 44 5d 5d 0a 2a 2a 20 4e 6f 20 6c 6f 6e 67 65 72  D]].** No longer
9530: 20 69 6e 20 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c   in use..**.** <
9540: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
9550: 4c 5f 53 59 4e 43 5d 5d 0a 2a 2a 20 54 68 65 20  L_SYNC]].** The 
9560: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59  [SQLITE_FCNTL_SY
9570: 4e 43 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65  NC] opcode is ge
9580: 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c  nerated internal
9590: 6c 79 20 62 79 20 53 51 4c 69 74 65 20 61 6e 64  ly by SQLite and
95a0: 0a 2a 2a 20 73 65 6e 74 20 74 6f 20 74 68 65 20  .** sent to the 
95b0: 56 46 53 20 69 6d 6d 65 64 69 61 74 65 6c 79 20  VFS immediately 
95c0: 62 65 66 6f 72 65 20 74 68 65 20 78 53 79 6e 63  before the xSync
95d0: 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b   method is invok
95e0: 65 64 20 6f 6e 20 61 0a 2a 2a 20 64 61 74 61 62  ed on a.** datab
95f0: 61 73 65 20 66 69 6c 65 20 64 65 73 63 72 69 70  ase file descrip
9600: 74 6f 72 2e 20 4f 72 2c 20 69 66 20 74 68 65 20  tor. Or, if the 
9610: 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20  xSync method is 
9620: 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 0a 2a 2a 20  not invoked .** 
9630: 62 65 63 61 75 73 65 20 74 68 65 20 75 73 65 72  because the user
9640: 20 68 61 73 20 63 6f 6e 66 69 67 75 72 65 64 20   has configured 
9650: 53 51 4c 69 74 65 20 77 69 74 68 20 0a 2a 2a 20  SQLite with .** 
9660: 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e  [PRAGMA synchron
9670: 6f 75 73 20 7c 20 50 52 41 47 4d 41 20 73 79 6e  ous | PRAGMA syn
9680: 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 74  chronous=OFF] it
9690: 20 69 73 20 69 6e 76 6f 6b 65 64 20 69 6e 20 70   is invoked in p
96a0: 6c 61 63 65 20 0a 2a 2a 20 6f 66 20 74 68 65 20  lace .** of the 
96b0: 78 53 79 6e 63 20 6d 65 74 68 6f 64 2e 20 49 6e  xSync method. In
96c0: 20 6d 6f 73 74 20 63 61 73 65 73 2c 20 74 68 65   most cases, the
96d0: 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e   pointer argumen
96e0: 74 20 70 61 73 73 65 64 20 77 69 74 68 0a 2a 2a  t passed with.**
96f0: 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72   this file-contr
9700: 6f 6c 20 69 73 20 4e 55 4c 4c 2e 20 48 6f 77 65  ol is NULL. Howe
9710: 76 65 72 2c 20 69 66 20 74 68 65 20 64 61 74 61  ver, if the data
9720: 62 61 73 65 20 66 69 6c 65 20 69 73 20 62 65 69  base file is bei
9730: 6e 67 20 73 79 6e 63 65 64 0a 2a 2a 20 61 73 20  ng synced.** as 
9740: 70 61 72 74 20 6f 66 20 61 20 6d 75 6c 74 69 2d  part of a multi-
9750: 64 61 74 61 62 61 73 65 20 63 6f 6d 6d 69 74 2c  database commit,
9760: 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 70 6f   the argument po
9770: 69 6e 74 73 20 74 6f 20 61 20 6e 75 6c 2d 74 65  ints to a nul-te
9780: 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69  rminated.** stri
9790: 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  ng containing th
97a0: 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 6d  e transactions m
97b0: 61 73 74 65 72 2d 6a 6f 75 72 6e 61 6c 20 66 69  aster-journal fi
97c0: 6c 65 20 6e 61 6d 65 2e 20 56 46 53 65 73 20 74  le name. VFSes t
97d0: 68 61 74 20 0a 2a 2a 20 64 6f 20 6e 6f 74 20 6e  hat .** do not n
97e0: 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20  eed this signal 
97f0: 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20  should silently 
9800: 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f  ignore this opco
9810: 64 65 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  de. Applications
9820: 20 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74 20   .** should not 
9830: 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69  call [sqlite3_fi
9840: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69  le_control()] wi
9850: 74 68 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61  th this opcode a
9860: 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 0a  s doing so may .
9870: 2a 2a 20 64 69 73 72 75 70 74 20 74 68 65 20 6f  ** disrupt the o
9880: 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  peration of the 
9890: 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65  specialized VFSe
98a0: 73 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72  s that do requir
98b0: 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c  e it.  .**.** <l
98c0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
98d0: 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f  _COMMIT_PHASETWO
98e0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
98f0: 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50  E_FCNTL_COMMIT_P
9900: 48 41 53 45 54 57 4f 5d 20 6f 70 63 6f 64 65 20  HASETWO] opcode 
9910: 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74  is generated int
9920: 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74  ernally by SQLit
9930: 65 0a 2a 2a 20 61 6e 64 20 73 65 6e 74 20 74 6f  e.** and sent to
9940: 20 74 68 65 20 56 46 53 20 61 66 74 65 72 20 61   the VFS after a
9950: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 68 61 73   transaction has
9960: 20 62 65 65 6e 20 63 6f 6d 6d 69 74 74 65 64 20   been committed 
9970: 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20 62  immediately.** b
9980: 75 74 20 62 65 66 6f 72 65 20 74 68 65 20 64 61  ut before the da
9990: 74 61 62 61 73 65 20 69 73 20 75 6e 6c 6f 63 6b  tabase is unlock
99a0: 65 64 2e 20 56 46 53 65 73 20 74 68 61 74 20 64  ed. VFSes that d
99b0: 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20  o not need this 
99c0: 73 69 67 6e 61 6c 0a 2a 2a 20 73 68 6f 75 6c 64  signal.** should
99d0: 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65   silently ignore
99e0: 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 41 70   this opcode. Ap
99f0: 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c  plications shoul
9a00: 64 20 6e 6f 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73  d not call.** [s
9a10: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
9a20: 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73  rol()] with this
9a30: 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67   opcode as doing
9a40: 20 73 6f 20 6d 61 79 20 64 69 73 72 75 70 74 20   so may disrupt 
9a50: 74 68 65 20 0a 2a 2a 20 6f 70 65 72 61 74 69 6f  the .** operatio
9a60: 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c  n of the special
9a70: 69 7a 65 64 20 56 46 53 65 73 20 74 68 61 74 20  ized VFSes that 
9a80: 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e 20 20  do require it.  
9a90: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
9aa0: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
9ab0: 41 56 5f 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54  AV_RETRY]].** ^T
9ac0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
9ad0: 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d  _WIN32_AV_RETRY]
9ae0: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
9af0: 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 61 75 74  to configure aut
9b00: 6f 6d 61 74 69 63 0a 2a 2a 20 72 65 74 72 79 20  omatic.** retry 
9b10: 63 6f 75 6e 74 73 20 61 6e 64 20 69 6e 74 65 72  counts and inter
9b20: 76 61 6c 73 20 66 6f 72 20 63 65 72 74 61 69 6e  vals for certain
9b30: 20 64 69 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74   disk I/O operat
9b40: 69 6f 6e 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20  ions for the.** 
9b50: 77 69 6e 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e  windows [VFS] in
9b60: 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64   order to provid
9b70: 65 20 72 6f 62 75 73 74 6e 65 73 73 20 69 6e 20  e robustness in 
9b80: 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 0a  the presence of.
9b90: 2a 2a 20 61 6e 74 69 2d 76 69 72 75 73 20 70 72  ** anti-virus pr
9ba0: 6f 67 72 61 6d 73 2e 20 20 42 79 20 64 65 66 61  ograms.  By defa
9bb0: 75 6c 74 2c 20 74 68 65 20 77 69 6e 64 6f 77 73  ult, the windows
9bc0: 20 56 46 53 20 77 69 6c 6c 20 72 65 74 72 79 20   VFS will retry 
9bd0: 66 69 6c 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69  file read,.** fi
9be0: 6c 65 20 77 72 69 74 65 2c 20 61 6e 64 20 66 69  le write, and fi
9bf0: 6c 65 20 64 65 6c 65 74 65 20 6f 70 65 72 61 74  le delete operat
9c00: 69 6f 6e 73 20 75 70 20 74 6f 20 31 30 20 74 69  ions up to 10 ti
9c10: 6d 65 73 2c 20 77 69 74 68 20 61 20 64 65 6c 61  mes, with a dela
9c20: 79 0a 2a 2a 20 6f 66 20 32 35 20 6d 69 6c 6c 69  y.** of 25 milli
9c30: 73 65 63 6f 6e 64 73 20 62 65 66 6f 72 65 20 74  seconds before t
9c40: 68 65 20 66 69 72 73 74 20 72 65 74 72 79 20 61  he first retry a
9c50: 6e 64 20 77 69 74 68 20 74 68 65 20 64 65 6c 61  nd with the dela
9c60: 79 20 69 6e 63 72 65 61 73 69 6e 67 0a 2a 2a 20  y increasing.** 
9c70: 62 79 20 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c  by an additional
9c80: 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   25 milliseconds
9c90: 20 77 69 74 68 20 65 61 63 68 20 73 75 62 73 65   with each subse
9ca0: 71 75 65 6e 74 20 72 65 74 72 79 2e 20 20 54 68  quent retry.  Th
9cb0: 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 6c 6c  is.** opcode all
9cc0: 6f 77 73 20 74 68 65 73 65 20 74 77 6f 20 76 61  ows these two va
9cd0: 6c 75 65 73 20 28 31 30 20 72 65 74 72 69 65 73  lues (10 retries
9ce0: 20 61 6e 64 20 32 35 20 6d 69 6c 6c 69 73 65 63   and 25 millisec
9cf0: 6f 6e 64 73 20 6f 66 20 64 65 6c 61 79 29 0a 2a  onds of delay).*
9d00: 2a 20 74 6f 20 62 65 20 61 64 6a 75 73 74 65 64  * to be adjusted
9d10: 2e 20 20 54 68 65 20 76 61 6c 75 65 73 20 61 72  .  The values ar
9d20: 65 20 63 68 61 6e 67 65 64 20 66 6f 72 20 61 6c  e changed for al
9d30: 6c 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  l database conne
9d40: 63 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 69 6e  ctions.** within
9d50: 20 74 68 65 20 73 61 6d 65 20 70 72 6f 63 65 73   the same proces
9d60: 73 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74  s.  The argument
9d70: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
9d80: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f   an array of two
9d90: 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20 77 68 65  .** integers whe
9da0: 72 65 20 74 68 65 20 66 69 72 73 74 20 69 6e 74  re the first int
9db0: 65 67 65 72 20 69 20 74 68 65 20 6e 65 77 20 72  eger i the new r
9dc0: 65 74 72 79 20 63 6f 75 6e 74 20 61 6e 64 20 74  etry count and t
9dd0: 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74  he second.** int
9de0: 65 67 65 72 20 69 73 20 74 68 65 20 64 65 6c 61  eger is the dela
9df0: 79 2e 20 20 49 66 20 65 69 74 68 65 72 20 69 6e  y.  If either in
9e00: 74 65 67 65 72 20 69 73 20 6e 65 67 61 74 69 76  teger is negativ
9e10: 65 2c 20 74 68 65 6e 20 74 68 65 20 73 65 74 74  e, then the sett
9e20: 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68  ing.** is not ch
9e30: 61 6e 67 65 64 20 62 75 74 20 69 6e 73 74 65 61  anged but instea
9e40: 64 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75  d the prior valu
9e50: 65 20 6f 66 20 74 68 61 74 20 73 65 74 74 69 6e  e of that settin
9e60: 67 20 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20  g is written.** 
9e70: 69 6e 74 6f 20 74 68 65 20 61 72 72 61 79 20 65  into the array e
9e80: 6e 74 72 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 74  ntry, allowing t
9e90: 68 65 20 63 75 72 72 65 6e 74 20 72 65 74 72 79  he current retry
9ea0: 20 73 65 74 74 69 6e 67 73 20 74 6f 20 62 65 0a   settings to be.
9eb0: 2a 2a 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e  ** interrogated.
9ec0: 20 20 54 68 65 20 7a 44 62 4e 61 6d 65 20 70 61    The zDbName pa
9ed0: 72 61 6d 65 74 65 72 20 69 73 20 69 67 6e 6f 72  rameter is ignor
9ee0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ed..**.** <li>[[
9ef0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52  SQLITE_FCNTL_PER
9f00: 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54  SIST_WAL]].** ^T
9f10: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
9f20: 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 20 6f 70  _PERSIST_WAL] op
9f30: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
9f40: 73 65 74 20 6f 72 20 71 75 65 72 79 20 74 68 65  set or query the
9f50: 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20 5b  .** persistent [
9f60: 57 41 4c 20 7c 20 57 72 69 74 65 20 41 68 65 61  WAL | Write Ahea
9f70: 64 20 4c 6f 67 5d 20 73 65 74 74 69 6e 67 2e 20  d Log] setting. 
9f80: 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65   By default, the
9f90: 20 61 75 78 69 6c 69 61 72 79 0a 2a 2a 20 77 72   auxiliary.** wr
9fa0: 69 74 65 20 61 68 65 61 64 20 6c 6f 67 20 61 6e  ite ahead log an
9fb0: 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20  d shared memory 
9fc0: 66 69 6c 65 73 20 75 73 65 64 20 66 6f 72 20 74  files used for t
9fd0: 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72  ransaction contr
9fe0: 6f 6c 0a 2a 2a 20 61 72 65 20 61 75 74 6f 6d 61  ol.** are automa
9ff0: 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20  tically deleted 
a000: 77 68 65 6e 20 74 68 65 20 6c 61 74 65 73 74 20  when the latest 
a010: 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 74 68  connection to th
a020: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6c  e database.** cl
a030: 6f 73 65 73 2e 20 20 53 65 74 74 69 6e 67 20 70  oses.  Setting p
a040: 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f  ersistent WAL mo
a050: 64 65 20 63 61 75 73 65 73 20 74 68 6f 73 65 20  de causes those 
a060: 66 69 6c 65 73 20 74 6f 20 70 65 72 73 69 73 74  files to persist
a070: 20 61 66 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e   after.** close.
a080: 20 20 50 65 72 73 69 73 74 69 6e 67 20 74 68 65    Persisting the
a090: 20 66 69 6c 65 73 20 69 73 20 75 73 65 66 75 6c   files is useful
a0a0: 20 77 68 65 6e 20 6f 74 68 65 72 20 70 72 6f 63   when other proc
a0b0: 65 73 73 65 73 20 74 68 61 74 20 64 6f 20 6e 6f  esses that do no
a0c0: 74 0a 2a 2a 20 68 61 76 65 20 77 72 69 74 65 20  t.** have write 
a0d0: 70 65 72 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 68  permission on th
a0e0: 65 20 64 69 72 65 63 74 6f 72 79 20 63 6f 6e 74  e directory cont
a0f0: 61 69 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62  aining the datab
a100: 61 73 65 20 66 69 6c 65 20 77 61 6e 74 0a 2a 2a  ase file want.**
a110: 20 74 6f 20 72 65 61 64 20 74 68 65 20 64 61 74   to read the dat
a120: 61 62 61 73 65 20 66 69 6c 65 2c 20 61 73 20 74  abase file, as t
a130: 68 65 20 57 41 4c 20 61 6e 64 20 73 68 61 72 65  he WAL and share
a140: 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 6d  d memory files m
a150: 75 73 74 20 65 78 69 73 74 0a 2a 2a 20 69 6e 20  ust exist.** in 
a160: 6f 72 64 65 72 20 66 6f 72 20 74 68 65 20 64 61  order for the da
a170: 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 61  tabase to be rea
a180: 64 61 62 6c 65 2e 20 20 54 68 65 20 66 6f 75 72  dable.  The four
a190: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  th parameter to.
a1a0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
a1b0: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20  _control()] for 
a1c0: 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75  this opcode shou
a1d0: 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  ld be a pointer 
a1e0: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a  to an integer..*
a1f0: 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20 69  * That integer i
a200: 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 70  s 0 to disable p
a210: 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f  ersistent WAL mo
a220: 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c  de or 1 to enabl
a230: 65 20 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20  e persistent.** 
a240: 57 41 4c 20 6d 6f 64 65 2e 20 20 49 66 20 74 68  WAL mode.  If th
a250: 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c  e integer is -1,
a260: 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72   then it is over
a270: 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65  written with the
a280: 20 63 75 72 72 65 6e 74 0a 2a 2a 20 57 41 4c 20   current.** WAL 
a290: 70 65 72 73 69 73 74 65 6e 63 65 20 73 65 74 74  persistence sett
a2a0: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ing..**.** <li>[
a2b0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f  [SQLITE_FCNTL_PO
a2c0: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
a2d0: 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  E]].** ^The [SQL
a2e0: 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53  ITE_FCNTL_POWERS
a2f0: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f  AFE_OVERWRITE] o
a300: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
a310: 20 73 65 74 20 6f 72 20 71 75 65 72 79 20 74 68   set or query th
a320: 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20  e.** persistent 
a330: 22 70 6f 77 65 72 73 61 66 65 2d 6f 76 65 72 77  "powersafe-overw
a340: 72 69 74 65 22 20 6f 72 20 22 50 53 4f 57 22 20  rite" or "PSOW" 
a350: 73 65 74 74 69 6e 67 2e 20 20 54 68 65 20 50 53  setting.  The PS
a360: 4f 57 20 73 65 74 74 69 6e 67 0a 2a 2a 20 64 65  OW setting.** de
a370: 74 65 72 6d 69 6e 65 73 20 74 68 65 20 5b 53 51  termines the [SQ
a380: 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52  LITE_IOCAP_POWER
a390: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20  SAFE_OVERWRITE] 
a3a0: 62 69 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78 44  bit of the.** xD
a3b0: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
a3c0: 74 69 63 73 20 6d 65 74 68 6f 64 73 2e 20 54 68  tics methods. Th
a3d0: 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
a3e0: 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  er to.** [sqlite
a3f0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
a400: 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64  ] for this opcod
a410: 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f  e should be a po
a420: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
a430: 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74  ger..** That int
a440: 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 73  eger is 0 to dis
a450: 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65  able zero-damage
a460: 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e   mode or 1 to en
a470: 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65  able zero-damage
a480: 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49 66 20 74 68  .** mode.  If th
a490: 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c  e integer is -1,
a4a0: 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72   then it is over
a4b0: 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65  written with the
a4c0: 20 63 75 72 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f   current.** zero
a4d0: 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 73 65 74  -damage mode set
a4e0: 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ting..**.** <li>
a4f0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f  [[SQLITE_FCNTL_O
a500: 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54  VERWRITE]].** ^T
a510: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
a520: 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f  _OVERWRITE] opco
a530: 64 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79  de is invoked by
a540: 20 53 51 4c 69 74 65 20 61 66 74 65 72 20 6f 70   SQLite after op
a550: 65 6e 69 6e 67 0a 2a 2a 20 61 20 77 72 69 74 65  ening.** a write
a560: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20   transaction to 
a570: 69 6e 64 69 63 61 74 65 20 74 68 61 74 2c 20 75  indicate that, u
a580: 6e 6c 65 73 73 20 69 74 20 69 73 20 72 6f 6c 6c  nless it is roll
a590: 65 64 20 62 61 63 6b 20 66 6f 72 20 73 6f 6d 65  ed back for some
a5a0: 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20 74 68 65 20  .** reason, the 
a5b0: 65 6e 74 69 72 65 20 64 61 74 61 62 61 73 65 20  entire database 
a5c0: 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 6f 76 65  file will be ove
a5d0: 72 77 72 69 74 74 65 6e 20 62 79 20 74 68 65 20  rwritten by the 
a5e0: 63 75 72 72 65 6e 74 20 0a 2a 2a 20 74 72 61 6e  current .** tran
a5f0: 73 61 63 74 69 6f 6e 2e 20 54 68 69 73 20 69 73  saction. This is
a600: 20 75 73 65 64 20 62 79 20 56 41 43 55 55 4d 20   used by VACUUM 
a610: 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  operations..**.*
a620: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
a630: 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a  CNTL_VFSNAME]].*
a640: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
a650: 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f 70  CNTL_VFSNAME] op
a660: 63 6f 64 65 20 63 61 6e 20 62 65 20 75 73 65 64  code can be used
a670: 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6e   to obtain the n
a680: 61 6d 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b  ames of.** all [
a690: 56 46 53 65 73 5d 20 69 6e 20 74 68 65 20 56 46  VFSes] in the VF
a6a0: 53 20 73 74 61 63 6b 2e 20 20 54 68 65 20 6e 61  S stack.  The na
a6b0: 6d 65 73 20 61 72 65 20 6f 66 20 61 6c 6c 20 56  mes are of all V
a6c0: 46 53 20 73 68 69 6d 73 20 61 6e 64 20 74 68 65  FS shims and the
a6d0: 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f 74 74 6f 6d  .** final bottom
a6e0: 2d 6c 65 76 65 6c 20 56 46 53 20 61 72 65 20 77  -level VFS are w
a6f0: 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f  ritten into memo
a700: 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
a710: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61   .** [sqlite3_ma
a720: 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 74 68 65 20  lloc()] and the 
a730: 72 65 73 75 6c 74 20 69 73 20 73 74 6f 72 65 64  result is stored
a740: 20 69 6e 20 74 68 65 20 63 68 61 72 2a 20 76 61   in the char* va
a750: 72 69 61 62 6c 65 0a 2a 2a 20 74 68 61 74 20 74  riable.** that t
a760: 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
a770: 74 65 72 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ter of [sqlite3_
a780: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
a790: 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54 68  points to..** Th
a7a0: 65 20 63 61 6c 6c 65 72 20 69 73 20 72 65 73 70  e caller is resp
a7b0: 6f 6e 73 69 62 6c 65 20 66 6f 72 20 66 72 65 65  onsible for free
a7c0: 69 6e 67 20 74 68 65 20 6d 65 6d 6f 72 79 20 77  ing the memory w
a7d0: 68 65 6e 20 64 6f 6e 65 2e 20 20 41 73 20 77 69  hen done.  As wi
a7e0: 74 68 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d 63  th.** all file-c
a7f0: 6f 6e 74 72 6f 6c 20 61 63 74 69 6f 6e 73 2c 20  ontrol actions, 
a800: 74 68 65 72 65 20 69 73 20 6e 6f 20 67 75 61 72  there is no guar
a810: 61 6e 74 65 65 20 74 68 61 74 20 74 68 69 73 20  antee that this 
a820: 77 69 6c 6c 20 61 63 74 75 61 6c 6c 79 0a 2a 2a  will actually.**
a830: 20 64 6f 20 61 6e 79 74 68 69 6e 67 2e 20 20 43   do anything.  C
a840: 61 6c 6c 65 72 73 20 73 68 6f 75 6c 64 20 69 6e  allers should in
a850: 69 74 69 61 6c 69 7a 65 20 74 68 65 20 63 68 61  itialize the cha
a860: 72 2a 20 76 61 72 69 61 62 6c 65 20 74 6f 20 61  r* variable to a
a870: 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72   NULL.** pointer
a880: 20 69 6e 20 63 61 73 65 20 74 68 69 73 20 66 69   in case this fi
a890: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f  le-control is no
a8a0: 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 20  t implemented.  
a8b0: 54 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  This file-contro
a8c0: 6c 0a 2a 2a 20 69 73 20 69 6e 74 65 6e 64 65 64  l.** is intended
a8d0: 20 66 6f 72 20 64 69 61 67 6e 6f 73 74 69 63 20   for diagnostic 
a8e0: 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20  use only..**.** 
a8f0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
a900: 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 5d 5d  TL_VFS_POINTER]]
a910: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
a920: 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54  _FCNTL_VFS_POINT
a930: 45 52 5d 20 6f 70 63 6f 64 65 20 66 69 6e 64 73  ER] opcode finds
a940: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
a950: 65 20 74 6f 70 2d 6c 65 76 65 6c 0a 2a 2a 20 5b  e top-level.** [
a960: 56 46 53 65 73 5d 20 63 75 72 72 65 6e 74 6c 79  VFSes] currently
a970: 20 69 6e 20 75 73 65 2e 20 20 5e 28 54 68 65 20   in use.  ^(The 
a980: 61 72 67 75 6d 65 6e 74 20 58 20 69 6e 0a 2a 2a  argument X in.**
a990: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f   sqlite3_file_co
a9a0: 6e 74 72 6f 6c 28 64 62 2c 53 51 4c 49 54 45 5f  ntrol(db,SQLITE_
a9b0: 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45  FCNTL_VFS_POINTE
a9c0: 52 2c 58 29 20 6d 75 73 74 20 62 65 0a 2a 2a 20  R,X) must be.** 
a9d0: 6f 66 20 74 79 70 65 20 22 5b 73 71 6c 69 74 65  of type "[sqlite
a9e0: 33 5f 76 66 73 5d 20 2a 2a 22 2e 20 20 54 68 69  3_vfs] **".  Thi
a9f0: 73 20 6f 70 63 6f 64 65 73 20 77 69 6c 6c 20 73  s opcodes will s
aa00: 65 74 20 2a 58 0a 2a 2a 20 74 6f 20 61 20 70 6f  et *X.** to a po
aa10: 69 6e 74 65 72 20 74 6f 20 74 68 65 20 74 6f 70  inter to the top
aa20: 2d 6c 65 76 65 6c 20 56 46 53 2e 29 5e 0a 2a 2a  -level VFS.)^.**
aa30: 20 5e 57 68 65 6e 20 74 68 65 72 65 20 61 72 65   ^When there are
aa40: 20 6d 75 6c 74 69 70 6c 65 20 56 46 53 20 73 68   multiple VFS sh
aa50: 69 6d 73 20 69 6e 20 74 68 65 20 73 74 61 63 6b  ims in the stack
aa60: 2c 20 74 68 69 73 20 6f 70 63 6f 64 65 20 66 69  , this opcode fi
aa70: 6e 64 73 20 74 68 65 0a 2a 2a 20 75 70 70 65 72  nds the.** upper
aa80: 2d 6d 6f 73 74 20 73 68 69 6d 20 6f 6e 6c 79 2e  -most shim only.
aa90: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
aaa0: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
aab0: 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20  ]].** ^Whenever 
aac0: 61 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65  a [PRAGMA] state
aad0: 6d 65 6e 74 20 69 73 20 70 61 72 73 65 64 2c 20  ment is parsed, 
aae0: 61 6e 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  an [SQLITE_FCNTL
aaf0: 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c  _PRAGMA] .** fil
ab00: 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e  e control is sen
ab10: 74 20 74 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73  t to the open [s
ab20: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
ab30: 65 63 74 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  ect correspondin
ab40: 67 0a 2a 2a 20 74 6f 20 74 68 65 20 64 61 74 61  g.** to the data
ab50: 62 61 73 65 20 66 69 6c 65 20 74 6f 20 77 68 69  base file to whi
ab60: 63 68 20 74 68 65 20 70 72 61 67 6d 61 20 73 74  ch the pragma st
ab70: 61 74 65 6d 65 6e 74 20 72 65 66 65 72 73 2e 20  atement refers. 
ab80: 5e 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  ^The argument.**
ab90: 20 74 6f 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   to the [SQLITE_
aba0: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69  FCNTL_PRAGMA] fi
abb0: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e  le control is an
abc0: 20 61 72 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69   array of.** poi
abd0: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
abe0: 20 28 63 68 61 72 2a 2a 29 20 69 6e 20 77 68 69   (char**) in whi
abf0: 63 68 20 74 68 65 20 73 65 63 6f 6e 64 20 65 6c  ch the second el
ac00: 65 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 72 72  ement of the arr
ac10: 61 79 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d  ay.** is the nam
ac20: 65 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20  e of the pragma 
ac30: 61 6e 64 20 74 68 65 20 74 68 69 72 64 20 65 6c  and the third el
ac40: 65 6d 65 6e 74 20 69 73 20 74 68 65 20 61 72 67  ement is the arg
ac50: 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20  ument to the.** 
ac60: 70 72 61 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69  pragma or NULL i
ac70: 66 20 74 68 65 20 70 72 61 67 6d 61 20 68 61 73  f the pragma has
ac80: 20 6e 6f 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e   no argument.  ^
ac90: 54 68 65 20 68 61 6e 64 6c 65 72 20 66 6f 72 20  The handler for 
aca0: 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43  an.** [SQLITE_FC
acb0: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65  NTL_PRAGMA] file
acc0: 20 63 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74   control can opt
acd0: 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65  ionally make the
ace0: 20 66 69 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a   first element.*
acf0: 2a 20 6f 66 20 74 68 65 20 63 68 61 72 2a 2a 20  * of the char** 
ad00: 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74  argument point t
ad10: 6f 20 61 20 73 74 72 69 6e 67 20 6f 62 74 61 69  o a string obtai
ad20: 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
ad30: 33 5f 6d 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20  3_mprintf()].** 
ad40: 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e  or the equivalen
ad50: 74 20 61 6e 64 20 74 68 61 74 20 73 74 72 69 6e  t and that strin
ad60: 67 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68  g will become th
ad70: 65 20 72 65 73 75 6c 74 20 6f 66 20 74 68 65 20  e result of the 
ad80: 70 72 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65  pragma or.** the
ad90: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69   error message i
ada0: 66 20 74 68 65 20 70 72 61 67 6d 61 20 66 61 69  f the pragma fai
adb0: 6c 73 2e 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b  ls. ^If the.** [
adc0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
add0: 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  GMA] file contro
ade0: 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  l returns [SQLIT
adf0: 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65  E_NOTFOUND], the
ae00: 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52  n normal .** [PR
ae10: 41 47 4d 41 5d 20 70 72 6f 63 65 73 73 69 6e 67  AGMA] processing
ae20: 20 63 6f 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66   continues.  ^If
ae30: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   the [SQLITE_FCN
ae40: 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69  TL_PRAGMA].** fi
ae50: 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72  le control retur
ae60: 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ns [SQLITE_OK], 
ae70: 74 68 65 6e 20 74 68 65 20 70 61 72 73 65 72 20  then the parser 
ae80: 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
ae90: 0a 2a 2a 20 56 46 53 20 68 61 73 20 68 61 6e 64  .** VFS has hand
aea0: 6c 65 64 20 74 68 65 20 50 52 41 47 4d 41 20 69  led the PRAGMA i
aeb0: 74 73 65 6c 66 20 61 6e 64 20 74 68 65 20 70 61  tself and the pa
aec0: 72 73 65 72 20 67 65 6e 65 72 61 74 65 73 20 61  rser generates a
aed0: 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72   no-op.** prepar
aee0: 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 66 20  ed statement if 
aef0: 72 65 73 75 6c 74 20 73 74 72 69 6e 67 20 69 73  result string is
af00: 20 4e 55 4c 4c 2c 20 6f 72 20 74 68 61 74 20 72   NULL, or that r
af10: 65 74 75 72 6e 73 20 61 20 63 6f 70 79 0a 2a 2a  eturns a copy.**
af20: 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
af30: 74 72 69 6e 67 20 69 66 20 74 68 65 20 73 74 72  tring if the str
af40: 69 6e 67 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 2e  ing is non-NULL.
af50: 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c  .** ^If the [SQL
af60: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
af70: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72  ] file control r
af80: 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65  eturns.** any re
af90: 73 75 6c 74 20 63 6f 64 65 20 6f 74 68 65 72 20  sult code other 
afa0: 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  than [SQLITE_OK]
afb0: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46   or [SQLITE_NOTF
afc0: 4f 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e  OUND], that mean
afd0: 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 56 46  s.** that the VF
afe0: 53 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e  S encountered an
aff0: 20 65 72 72 6f 72 20 77 68 69 6c 65 20 68 61 6e   error while han
b000: 64 6c 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d  dling the [PRAGM
b010: 41 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f  A] and the.** co
b020: 6d 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65  mpilation of the
b030: 20 50 52 41 47 4d 41 20 66 61 69 6c 73 20 77 69   PRAGMA fails wi
b040: 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54  th an error.  ^T
b050: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
b060: 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65  _PRAGMA].** file
b070: 20 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20   control occurs 
b080: 61 74 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  at the beginning
b090: 20 6f 66 20 70 72 61 67 6d 61 20 73 74 61 74 65   of pragma state
b0a0: 6d 65 6e 74 20 61 6e 61 6c 79 73 69 73 20 61 6e  ment analysis an
b0b0: 64 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62  d so.** it is ab
b0c0: 6c 65 20 74 6f 20 6f 76 65 72 72 69 64 65 20 62  le to override b
b0d0: 75 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d  uilt-in [PRAGMA]
b0e0: 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
b0f0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
b100: 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45  FCNTL_BUSYHANDLE
b110: 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  R]].** ^The [SQL
b120: 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41  ITE_FCNTL_BUSYHA
b130: 4e 44 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63  NDLER].** file-c
b140: 6f 6e 74 72 6f 6c 20 6d 61 79 20 62 65 20 69 6e  ontrol may be in
b150: 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20  voked by SQLite 
b160: 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  on the database 
b170: 66 69 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 73  file handle.** s
b180: 68 6f 72 74 6c 79 20 61 66 74 65 72 20 69 74 20  hortly after it 
b190: 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 6f 72 64  is opened in ord
b1a0: 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 61 20  er to provide a 
b1b0: 63 75 73 74 6f 6d 20 56 46 53 20 77 69 74 68 20  custom VFS with 
b1c0: 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 74 68 65  access.** to the
b1d0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 75 73   connections bus
b1e0: 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  y-handler callba
b1f0: 63 6b 2e 20 54 68 65 20 61 72 67 75 6d 65 6e 74  ck. The argument
b200: 20 69 73 20 6f 66 20 74 79 70 65 20 28 76 6f 69   is of type (voi
b210: 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61 72  d **).** - an ar
b220: 72 61 79 20 6f 66 20 74 77 6f 20 28 76 6f 69 64  ray of two (void
b230: 20 2a 29 20 76 61 6c 75 65 73 2e 20 54 68 65 20   *) values. The 
b240: 66 69 72 73 74 20 28 76 6f 69 64 20 2a 29 20 61  first (void *) a
b250: 63 74 75 61 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a  ctually points.*
b260: 2a 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20  * to a function 
b270: 6f 66 20 74 79 70 65 20 28 69 6e 74 20 28 2a 29  of type (int (*)
b280: 28 76 6f 69 64 20 2a 29 29 2e 20 49 6e 20 6f 72  (void *)). In or
b290: 64 65 72 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68  der to invoke th
b2a0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a  e connections.**
b2b0: 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 2c 20 74   busy-handler, t
b2c0: 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f  his function sho
b2d0: 75 6c 64 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  uld be invoked w
b2e0: 69 74 68 20 74 68 65 20 73 65 63 6f 6e 64 20 28  ith the second (
b2f0: 76 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a 20 74 68  void *) in.** th
b300: 65 20 61 72 72 61 79 20 61 73 20 74 68 65 20 6f  e array as the o
b310: 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20 49 66  nly argument. If
b320: 20 69 74 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d   it returns non-
b330: 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 6f  zero, then the o
b340: 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75  peration.** shou
b350: 6c 64 20 62 65 20 72 65 74 72 69 65 64 2e 20 49  ld be retried. I
b360: 66 20 69 74 20 72 65 74 75 72 6e 73 20 7a 65 72  f it returns zer
b370: 6f 2c 20 74 68 65 20 63 75 73 74 6f 6d 20 56 46  o, the custom VF
b380: 53 20 73 68 6f 75 6c 64 20 61 62 61 6e 64 6f 6e  S should abandon
b390: 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20   the.** current 
b3a0: 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  operation..**.**
b3b0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
b3c0: 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45  NTL_TEMPFILENAME
b3d0: 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63 61 74 69  ]].** ^Applicati
b3e0: 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b 65 20 74 68  on can invoke th
b3f0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
b400: 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 20 66 69  TEMPFILENAME] fi
b410: 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f  le-control.** to
b420: 20 68 61 76 65 20 53 51 4c 69 74 65 20 67 65 6e   have SQLite gen
b430: 65 72 61 74 65 20 61 0a 2a 2a 20 74 65 6d 70 6f  erate a.** tempo
b440: 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 20 75 73  rary filename us
b450: 69 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67  ing the same alg
b460: 6f 72 69 74 68 6d 20 74 68 61 74 20 69 73 20 66  orithm that is f
b470: 6f 6c 6c 6f 77 65 64 20 74 6f 20 67 65 6e 65 72  ollowed to gener
b480: 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79  ate.** temporary
b490: 20 66 69 6c 65 6e 61 6d 65 73 20 66 6f 72 20 54   filenames for T
b4a0: 45 4d 50 20 74 61 62 6c 65 73 20 61 6e 64 20 6f  EMP tables and o
b4b0: 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 20 75 73  ther internal us
b4c0: 65 73 2e 20 20 54 68 65 0a 2a 2a 20 61 72 67 75  es.  The.** argu
b4d0: 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 61  ment should be a
b4e0: 20 63 68 61 72 2a 2a 20 77 68 69 63 68 20 77 69   char** which wi
b4f0: 6c 6c 20 62 65 20 66 69 6c 6c 65 64 20 77 69 74  ll be filled wit
b500: 68 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a  h the filename.*
b510: 2a 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d  * written into m
b520: 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
b530: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
b540: 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20 63 61 6c  loc()].  The cal
b550: 6c 65 72 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e  ler should.** in
b560: 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72  voke [sqlite3_fr
b570: 65 65 28 29 5d 20 6f 6e 20 74 68 65 20 72 65 73  ee()] on the res
b580: 75 6c 74 20 74 6f 20 61 76 6f 69 64 20 61 20 6d  ult to avoid a m
b590: 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a  emory leak..**.*
b5a0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
b5b0: 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d  CNTL_MMAP_SIZE]]
b5c0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
b5d0: 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d  FCNTL_MMAP_SIZE]
b5e0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
b5f0: 20 75 73 65 64 20 74 6f 20 71 75 65 72 79 20 6f   used to query o
b600: 72 20 73 65 74 20 74 68 65 0a 2a 2a 20 6d 61 78  r set the.** max
b610: 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62  imum number of b
b620: 79 74 65 73 20 74 68 61 74 20 77 69 6c 6c 20 62  ytes that will b
b630: 65 20 75 73 65 64 20 66 6f 72 20 6d 65 6d 6f 72  e used for memor
b640: 79 2d 6d 61 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a  y-mapped I/O..**
b650: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   The argument is
b660: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
b670: 76 61 6c 75 65 20 6f 66 20 74 79 70 65 20 73 71  value of type sq
b680: 6c 69 74 65 33 5f 69 6e 74 36 34 20 74 68 61 74  lite3_int64 that
b690: 0a 2a 2a 20 69 73 20 61 6e 20 61 64 76 69 73 6f  .** is an adviso
b6a0: 72 79 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  ry maximum numbe
b6b0: 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
b6c0: 65 20 66 69 6c 65 20 74 6f 20 6d 65 6d 6f 72 79  e file to memory
b6d0: 20 6d 61 70 2e 20 20 54 68 65 0a 2a 2a 20 70 6f   map.  The.** po
b6e0: 69 6e 74 65 72 20 69 73 20 6f 76 65 72 77 72 69  inter is overwri
b6f0: 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 6f 6c  tten with the ol
b700: 64 20 76 61 6c 75 65 2e 20 20 54 68 65 20 6c 69  d value.  The li
b710: 6d 69 74 20 69 73 20 6e 6f 74 20 63 68 61 6e 67  mit is not chang
b720: 65 64 20 69 66 0a 2a 2a 20 74 68 65 20 76 61 6c  ed if.** the val
b730: 75 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 70 6f  ue originally po
b740: 69 6e 74 65 64 20 74 6f 20 69 73 20 6e 65 67 61  inted to is nega
b750: 74 69 76 65 2c 20 61 6e 64 20 73 6f 20 74 68 65  tive, and so the
b760: 20 63 75 72 72 65 6e 74 20 6c 69 6d 69 74 20 0a   current limit .
b770: 2a 2a 20 63 61 6e 20 62 65 20 71 75 65 72 69 65  ** can be querie
b780: 64 20 62 79 20 70 61 73 73 69 6e 67 20 69 6e 20  d by passing in 
b790: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e  a pointer to a n
b7a0: 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2e 20  egative number. 
b7b0: 20 54 68 69 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f   This.** file-co
b7c0: 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20 69 6e  ntrol is used in
b7d0: 74 65 72 6e 61 6c 6c 79 20 74 6f 20 69 6d 70 6c  ternally to impl
b7e0: 65 6d 65 6e 74 20 5b 50 52 41 47 4d 41 20 6d 6d  ement [PRAGMA mm
b7f0: 61 70 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20  ap_size]..**.** 
b800: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
b810: 54 4c 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20 54 68  TL_TRACE]].** Th
b820: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
b830: 54 52 41 43 45 5d 20 66 69 6c 65 20 63 6f 6e 74  TRACE] file cont
b840: 72 6f 6c 20 70 72 6f 76 69 64 65 73 20 61 64 76  rol provides adv
b850: 69 73 6f 72 79 20 69 6e 66 6f 72 6d 61 74 69 6f  isory informatio
b860: 6e 0a 2a 2a 20 74 6f 20 74 68 65 20 56 46 53 20  n.** to the VFS 
b870: 61 62 6f 75 74 20 77 68 61 74 20 74 68 65 20 68  about what the h
b880: 69 67 68 65 72 20 6c 61 79 65 72 73 20 6f 66 20  igher layers of 
b890: 74 68 65 20 53 51 4c 69 74 65 20 73 74 61 63 6b  the SQLite stack
b8a0: 20 61 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54   are doing..** T
b8b0: 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  his file control
b8c0: 20 69 73 20 75 73 65 64 20 62 79 20 73 6f 6d 65   is used by some
b8d0: 20 56 46 53 20 61 63 74 69 76 69 74 79 20 74 72   VFS activity tr
b8e0: 61 63 69 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a  acing [shims]..*
b8f0: 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69  * The argument i
b900: 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  s a zero-termina
b910: 74 65 64 20 73 74 72 69 6e 67 2e 20 20 48 69 67  ted string.  Hig
b920: 68 65 72 20 6c 61 79 65 72 73 20 69 6e 20 74 68  her layers in th
b930: 65 0a 2a 2a 20 53 51 4c 69 74 65 20 73 74 61 63  e.** SQLite stac
b940: 6b 20 6d 61 79 20 67 65 6e 65 72 61 74 65 20 69  k may generate i
b950: 6e 73 74 61 6e 63 65 73 20 6f 66 20 74 68 69 73  nstances of this
b960: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 66   file control if
b970: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
b980: 55 53 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d  USE_FCNTL_TRACE]
b990: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
b9a0: 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e  tion is enabled.
b9b0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
b9c0: 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f  ITE_FCNTL_HAS_MO
b9d0: 56 45 44 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  VED]].** The [SQ
b9e0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d  LITE_FCNTL_HAS_M
b9f0: 4f 56 45 44 5d 20 66 69 6c 65 20 63 6f 6e 74 72  OVED] file contr
ba00: 6f 6c 20 69 6e 74 65 72 70 72 65 74 73 20 69 74  ol interprets it
ba10: 73 20 61 72 67 75 6d 65 6e 74 20 61 73 20 61 0a  s argument as a.
ba20: 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e  ** pointer to an
ba30: 20 69 6e 74 65 67 65 72 20 61 6e 64 20 69 74 20   integer and it 
ba40: 77 72 69 74 65 73 20 61 20 62 6f 6f 6c 65 61 6e  writes a boolean
ba50: 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67   into that integ
ba60: 65 72 20 64 65 70 65 6e 64 69 6e 67 0a 2a 2a 20  er depending.** 
ba70: 6f 6e 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  on whether or no
ba80: 74 20 74 68 65 20 66 69 6c 65 20 68 61 73 20 62  t the file has b
ba90: 65 65 6e 20 72 65 6e 61 6d 65 64 2c 20 6d 6f 76  een renamed, mov
baa0: 65 64 2c 20 6f 72 20 64 65 6c 65 74 65 64 20 73  ed, or deleted s
bab0: 69 6e 63 65 20 69 74 0a 2a 2a 20 77 61 73 20 66  ince it.** was f
bac0: 69 72 73 74 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a  irst opened..**.
bad0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
bae0: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f  FCNTL_WIN32_SET_
baf0: 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20  HANDLE]].** The 
bb00: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49  [SQLITE_FCNTL_WI
bb10: 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 20  N32_SET_HANDLE] 
bb20: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66  opcode is used f
bb30: 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54  or debugging.  T
bb40: 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61  his.** opcode ca
bb50: 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f  uses the xFileCo
bb60: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20  ntrol method to 
bb70: 73 77 61 70 20 74 68 65 20 66 69 6c 65 20 68 61  swap the file ha
bb80: 6e 64 6c 65 20 77 69 74 68 20 74 68 65 20 6f 6e  ndle with the on
bb90: 65 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20  e.** pointed to 
bba0: 62 79 20 74 68 65 20 70 41 72 67 20 61 72 67 75  by the pArg argu
bbb0: 6d 65 6e 74 2e 20 20 54 68 69 73 20 63 61 70 61  ment.  This capa
bbc0: 62 69 6c 69 74 79 20 69 73 20 75 73 65 64 20 64  bility is used d
bbd0: 75 72 69 6e 67 20 74 65 73 74 69 6e 67 0a 2a 2a  uring testing.**
bbe0: 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20   and only needs 
bbf0: 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20  to be supported 
bc00: 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54  when SQLITE_TEST
bc10: 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a   is defined..**.
bc20: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
bc30: 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d  FCNTL_WAL_BLOCK]
bc40: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
bc50: 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b  _FCNTL_WAL_BLOCK
bc60: 5d 20 69 73 20 61 20 73 69 67 6e 61 6c 20 74 6f  ] is a signal to
bc70: 20 74 68 65 20 56 46 53 20 6c 61 79 65 72 20 74   the VFS layer t
bc80: 68 61 74 20 69 74 20 6d 69 67 68 74 0a 2a 2a 20  hat it might.** 
bc90: 62 65 20 61 64 76 61 6e 74 61 67 65 6f 75 73 20  be advantageous 
bca0: 74 6f 20 62 6c 6f 63 6b 20 6f 6e 20 74 68 65 20  to block on the 
bcb0: 6e 65 78 74 20 57 41 4c 20 6c 6f 63 6b 20 69 66  next WAL lock if
bcc0: 20 74 68 65 20 6c 6f 63 6b 20 69 73 20 6e 6f 74   the lock is not
bcd0: 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20   immediately.** 
bce0: 61 76 61 69 6c 61 62 6c 65 2e 20 20 54 68 65 20  available.  The 
bcf0: 57 41 4c 20 73 75 62 73 79 73 74 65 6d 20 69 73  WAL subsystem is
bd00: 73 75 65 73 20 74 68 69 73 20 73 69 67 6e 61 6c  sues this signal
bd10: 20 64 75 72 69 6e 67 20 72 61 72 65 0a 2a 2a 20   during rare.** 
bd20: 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 69 6e  circumstances in
bd30: 20 6f 72 64 65 72 20 74 6f 20 66 69 78 20 61 20   order to fix a 
bd40: 70 72 6f 62 6c 65 6d 20 77 69 74 68 20 70 72 69  problem with pri
bd50: 6f 72 69 74 79 20 69 6e 76 65 72 73 69 6f 6e 2e  ority inversion.
bd60: 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
bd70: 20 73 68 6f 75 6c 64 20 3c 65 6d 3e 6e 6f 74 3c   should <em>not<
bd80: 2f 65 6d 3e 20 75 73 65 20 74 68 69 73 20 66 69  /em> use this fi
bd90: 6c 65 2d 63 6f 6e 74 72 6f 6c 2e 0a 2a 2a 0a 2a  le-control..**.*
bda0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
bdb0: 43 4e 54 4c 5f 5a 49 50 56 46 53 5d 5d 0a 2a 2a  CNTL_ZIPVFS]].**
bdc0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
bdd0: 54 4c 5f 5a 49 50 56 46 53 5d 20 6f 70 63 6f 64  TL_ZIPVFS] opcod
bde0: 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64  e is implemented
bdf0: 20 62 79 20 7a 69 70 76 66 73 20 6f 6e 6c 79 2e   by zipvfs only.
be00: 20 41 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 56 46   All other.** VF
be10: 53 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20  S should return 
be20: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20  SQLITE_NOTFOUND 
be30: 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 2e  for this opcode.
be40: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
be50: 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d 5d 0a  ITE_FCNTL_RBU]].
be60: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
be70: 43 4e 54 4c 5f 52 42 55 5d 20 6f 70 63 6f 64 65  CNTL_RBU] opcode
be80: 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20   is implemented 
be90: 62 79 20 74 68 65 20 73 70 65 63 69 61 6c 20 56  by the special V
bea0: 46 53 20 75 73 65 64 20 62 79 0a 2a 2a 20 74 68  FS used by.** th
beb0: 65 20 52 42 55 20 65 78 74 65 6e 73 69 6f 6e 20  e RBU extension 
bec0: 6f 6e 6c 79 2e 20 20 41 6c 6c 20 6f 74 68 65 72  only.  All other
bed0: 20 56 46 53 20 73 68 6f 75 6c 64 20 72 65 74 75   VFS should retu
bee0: 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  rn SQLITE_NOTFOU
bef0: 4e 44 20 66 6f 72 0a 2a 2a 20 74 68 69 73 20 6f  ND for.** this o
bf00: 70 63 6f 64 65 2e 20 20 0a 2a 2a 20 3c 2f 75 6c  pcode.  .** </ul
bf10: 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
bf20: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54  ITE_FCNTL_LOCKST
bf30: 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ATE             
bf40: 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
bf50: 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43  TE_FCNTL_GET_LOC
bf60: 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20  KPROXYFILE      
bf70: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
bf80: 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b  E_FCNTL_SET_LOCK
bf90: 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20  PROXYFILE       
bfa0: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
bfb0: 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e  _FCNTL_LAST_ERRN
bfc0: 4f 20 20 20 20 20 20 20 20 20 20 20 20 20 20 34  O              4
bfd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
bfe0: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20  FCNTL_SIZE_HINT 
bff0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a                5.
c000: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c010: 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20  CNTL_CHUNK_SIZE 
c020: 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23               6.#
c030: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
c040: 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52  NTL_FILE_POINTER
c050: 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64              7.#d
c060: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
c070: 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20  TL_SYNC_OMITTED 
c080: 20 20 20 20 20 20 20 20 20 20 20 38 0a 23 64 65             8.#de
c090: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c0a0: 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59  L_WIN32_AV_RETRY
c0b0: 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66            9.#def
c0c0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c0d0: 5f 50 45 52 53 49 53 54 5f 57 41 4c 20 20 20 20  _PERSIST_WAL    
c0e0: 20 20 20 20 20 20 20 20 31 30 0a 23 64 65 66 69          10.#defi
c0f0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c100: 4f 56 45 52 57 52 49 54 45 20 20 20 20 20 20 20  OVERWRITE       
c110: 20 20 20 20 20 20 20 31 31 0a 23 64 65 66 69 6e         11.#defin
c120: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56  e SQLITE_FCNTL_V
c130: 46 53 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20  FSNAME          
c140: 20 20 20 20 20 20 31 32 0a 23 64 65 66 69 6e 65        12.#define
c150: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f   SQLITE_FCNTL_PO
c160: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
c170: 45 20 20 20 20 31 33 0a 23 64 65 66 69 6e 65 20  E    13.#define 
c180: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
c190: 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20  GMA             
c1a0: 20 20 20 20 31 34 0a 23 64 65 66 69 6e 65 20 53      14.#define S
c1b0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59  QLITE_FCNTL_BUSY
c1c0: 48 41 4e 44 4c 45 52 20 20 20 20 20 20 20 20 20  HANDLER         
c1d0: 20 20 20 31 35 0a 23 64 65 66 69 6e 65 20 53 51     15.#define SQ
c1e0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46  LITE_FCNTL_TEMPF
c1f0: 49 4c 45 4e 41 4d 45 20 20 20 20 20 20 20 20 20  ILENAME         
c200: 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c    16.#define SQL
c210: 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53  ITE_FCNTL_MMAP_S
c220: 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20  IZE             
c230: 20 31 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   18.#define SQLI
c240: 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 20 20  TE_FCNTL_TRACE  
c250: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
c260: 31 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  19.#define SQLIT
c270: 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45  E_FCNTL_HAS_MOVE
c280: 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32  D              2
c290: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
c2a0: 5f 46 43 4e 54 4c 5f 53 59 4e 43 20 20 20 20 20  _FCNTL_SYNC     
c2b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31                21
c2c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c2d0: 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41  FCNTL_COMMIT_PHA
c2e0: 53 45 54 57 4f 20 20 20 20 20 20 20 20 32 32 0a  SETWO        22.
c2f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c300: 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48  CNTL_WIN32_SET_H
c310: 41 4e 44 4c 45 20 20 20 20 20 20 20 32 33 0a 23  ANDLE       23.#
c320: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
c330: 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 20 20 20  NTL_WAL_BLOCK   
c340: 20 20 20 20 20 20 20 20 20 20 20 32 34 0a 23 64             24.#d
c350: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
c360: 54 4c 5f 5a 49 50 56 46 53 20 20 20 20 20 20 20  TL_ZIPVFS       
c370: 20 20 20 20 20 20 20 20 20 20 32 35 0a 23 64 65            25.#de
c380: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c390: 4c 5f 52 42 55 20 20 20 20 20 20 20 20 20 20 20  L_RBU           
c3a0: 20 20 20 20 20 20 20 20 20 32 36 0a 23 64 65 66           26.#def
c3b0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c3c0: 5f 56 46 53 5f 50 4f 49 4e 54 45 52 20 20 20 20  _VFS_POINTER    
c3d0: 20 20 20 20 20 20 20 20 32 37 0a 23 64 65 66 69          27.#defi
c3e0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c3f0: 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 20  JOURNAL_POINTER 
c400: 20 20 20 20 20 20 20 32 38 0a 0a 2f 2a 20 64 65         28../* de
c410: 70 72 65 63 61 74 65 64 20 6e 61 6d 65 73 20 2a  precated names *
c420: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
c430: 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _GET_LOCKPROXYFI
c440: 4c 45 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46  LE      SQLITE_F
c450: 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f  CNTL_GET_LOCKPRO
c460: 58 59 46 49 4c 45 0a 23 64 65 66 69 6e 65 20 53  XYFILE.#define S
c470: 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52  QLITE_SET_LOCKPR
c480: 4f 58 59 46 49 4c 45 20 20 20 20 20 20 53 51 4c  OXYFILE      SQL
c490: 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f  ITE_FCNTL_SET_LO
c4a0: 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 66  CKPROXYFILE.#def
c4b0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f  ine SQLITE_LAST_
c4c0: 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20  ERRNO           
c4d0: 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c    SQLITE_FCNTL_L
c4e0: 41 53 54 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a 0a 2a  AST_ERRNO.../*.*
c4f0: 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65  * CAPI3REF: Mute
c500: 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54  x Handle.**.** T
c510: 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20  he mutex module 
c520: 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65  within SQLite de
c530: 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d  fines [sqlite3_m
c540: 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a  utex] to be an.*
c550: 2a 20 61 62 73 74 72 61 63 74 20 74 79 70 65 20  * abstract type 
c560: 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65  for a mutex obje
c570: 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20  ct.  The SQLite 
c580: 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73  core never looks
c590: 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72  .** at the inter
c5a0: 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69  nal representati
c5b0: 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65  on of an [sqlite
c5c0: 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e  3_mutex].  It on
c5d0: 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68  ly.** deals with
c5e0: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65   pointers to the
c5f0: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d   [sqlite3_mutex]
c600: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d   object..**.** M
c610: 75 74 65 78 65 73 20 61 72 65 20 63 72 65 61 74  utexes are creat
c620: 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
c630: 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d  3_mutex_alloc()]
c640: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
c650: 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  uct sqlite3_mute
c660: 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b  x sqlite3_mutex;
c670: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
c680: 3a 20 4c 6f 61 64 61 62 6c 65 20 45 78 74 65 6e  : Loadable Exten
c690: 73 69 6f 6e 20 54 68 75 6e 6b 0a 2a 2a 0a 2a 2a  sion Thunk.**.**
c6a0: 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   A pointer to th
c6b0: 65 20 6f 70 61 71 75 65 20 73 71 6c 69 74 65 33  e opaque sqlite3
c6c0: 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73 20 73 74  _api_routines st
c6d0: 72 75 63 74 75 72 65 20 69 73 20 70 61 73 73 65  ructure is passe
c6e0: 64 20 61 73 0a 2a 2a 20 74 68 65 20 74 68 69 72  d as.** the thir
c6f0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 65  d parameter to e
c700: 6e 74 72 79 20 70 6f 69 6e 74 73 20 6f 66 20 5b  ntry points of [
c710: 6c 6f 61 64 61 62 6c 65 20 65 78 74 65 6e 73 69  loadable extensi
c720: 6f 6e 73 5d 2e 20 20 54 68 69 73 0a 2a 2a 20 73  ons].  This.** s
c730: 74 72 75 63 74 75 72 65 20 6d 75 73 74 20 62 65  tructure must be
c740: 20 74 79 70 65 64 65 66 65 64 20 69 6e 20 6f 72   typedefed in or
c750: 64 65 72 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75  der to work arou
c760: 6e 64 20 63 6f 6d 70 69 6c 65 72 20 77 61 72 6e  nd compiler warn
c770: 69 6e 67 73 0a 2a 2a 20 6f 6e 20 73 6f 6d 65 20  ings.** on some 
c780: 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2f 0a 74 79  platforms..*/.ty
c790: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
c7a0: 69 74 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65  ite3_api_routine
c7b0: 73 20 73 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f  s sqlite3_api_ro
c7c0: 75 74 69 6e 65 73 3b 0a 0a 2f 2a 0a 2a 2a 20 43  utines;../*.** C
c7d0: 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65  API3REF: OS Inte
c7e0: 72 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a  rface Object.**.
c7f0: 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ** An instance o
c800: 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  f the sqlite3_vf
c810: 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73  s object defines
c820: 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62   the interface b
c830: 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51  etween.** the SQ
c840: 4c 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68  Lite core and th
c850: 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65  e underlying ope
c860: 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20  rating system.  
c870: 54 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20  The "vfs".** in 
c880: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
c890: 6f 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f  object stands fo
c8a0: 72 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20  r "virtual file 
c8b0: 73 79 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a  system".  See.**
c8c0: 20 74 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20   the [VFS | VFS 
c8d0: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66  documentation] f
c8e0: 6f 72 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72  or further infor
c8f0: 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  mation..**.** Th
c900: 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69  e value of the i
c910: 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73  Version field is
c920: 20 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74   initially 1 but
c930: 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20 69   may be larger i
c940: 6e 0a 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73  n.** future vers
c950: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20  ions of SQLite. 
c960: 20 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   Additional fiel
c970: 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64  ds may be append
c980: 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62  ed to this.** ob
c990: 6a 65 63 74 20 77 68 65 6e 20 74 68 65 20 69 56  ject when the iV
c9a0: 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20  ersion value is 
c9b0: 69 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65  increased.  Note
c9c0: 20 74 68 61 74 20 74 68 65 20 73 74 72 75 63 74   that the struct
c9d0: 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71  ure.** of the sq
c9e0: 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74  lite3_vfs object
c9f0: 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20   changes in the 
ca00: 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77  transaction betw
ca10: 65 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65  een.** SQLite ve
ca20: 72 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20  rsion 3.5.9 and 
ca30: 33 2e 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68  3.6.0 and yet th
ca40: 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64  e iVersion field
ca50: 20 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69   was not.** modi
ca60: 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fied..**.** The 
ca70: 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69  szOsFile field i
ca80: 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  s the size of th
ca90: 65 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71  e subclassed [sq
caa0: 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73  lite3_file].** s
cab0: 74 72 75 63 74 75 72 65 20 75 73 65 64 20 62 79  tructure used by
cac0: 20 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61   this VFS.  mxPa
cad0: 74 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61  thname is the ma
cae0: 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a  ximum length of.
caf0: 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e  ** a pathname in
cb00: 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a   this VFS..**.**
cb10: 20 52 65 67 69 73 74 65 72 65 64 20 73 71 6c 69   Registered sqli
cb20: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20  te3_vfs objects 
cb30: 61 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69  are kept on a li
cb40: 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64  nked list formed
cb50: 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74   by.** the pNext
cb60: 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b   pointer.  The [
cb70: 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69  sqlite3_vfs_regi
cb80: 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  ster()].** and [
cb90: 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65  sqlite3_vfs_unre
cba0: 67 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66  gister()] interf
cbb0: 61 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73  aces manage this
cbc0: 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68   list.** in a th
cbd0: 72 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20  read-safe way.  
cbe0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  The [sqlite3_vfs
cbf0: 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61  _find()] interfa
cc00: 63 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74  ce.** searches t
cc10: 68 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65  he list.  Neithe
cc20: 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
cc30: 6e 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56  n code nor the V
cc40: 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  FS.** implementa
cc50: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20  tion should use 
cc60: 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65  the pNext pointe
cc70: 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65  r..**.** The pNe
cc80: 78 74 20 66 69 65 6c 64 20 69 73 20 74 68 65 20  xt field is the 
cc90: 6f 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68  only field in th
cca0: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a  e sqlite3_vfs.**
ccb0: 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20   structure that 
ccc0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72  SQLite will ever
ccd0: 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65   modify.  SQLite
cce0: 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73   will only acces
ccf0: 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74  s.** or modify t
cd00: 68 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20  his field while 
cd10: 68 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63  holding a partic
cd20: 75 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 65  ular static mute
cd30: 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  x..** The applic
cd40: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76  ation should nev
cd50: 65 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69  er modify anythi
cd60: 6e 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 71  ng within the sq
cd70: 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a  lite3_vfs.** obj
cd80: 65 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a  ect once the obj
cd90: 65 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 67  ect has been reg
cda0: 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  istered..**.** T
cdb0: 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68  he zName field h
cdc0: 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  olds the name of
cdd0: 20 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e   the VFS module.
cde0: 20 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a    The name must.
cdf0: 2a 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 72  ** be unique acr
ce00: 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75  oss all VFS modu
ce10: 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c  les..**.** [[sql
ce20: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d  ite3_vfs.xOpen]]
ce30: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72  .** ^SQLite guar
ce40: 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20  antees that the 
ce50: 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  zFilename parame
ce60: 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20  ter to xOpen.** 
ce70: 69 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c  is either a NULL
ce80: 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69   pointer or stri
ce90: 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  ng obtained.** f
cea0: 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d  rom xFullPathnam
ceb0: 65 28 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69  e() with an opti
cec0: 6f 6e 61 6c 20 73 75 66 66 69 78 20 61 64 64 65  onal suffix adde
ced0: 64 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66  d..** ^If a suff
cee0: 69 78 20 69 73 20 61 64 64 65 64 20 74 6f 20 74  ix is added to t
cef0: 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72  he zFilename par
cf00: 61 6d 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a  ameter, it will.
cf10: 2a 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20  ** consist of a 
cf20: 73 69 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61  single "-" chara
cf30: 63 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79  cter followed by
cf40: 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a   no more than.**
cf50: 20 31 31 20 61 6c 70 68 61 6e 75 6d 65 72 69 63   11 alphanumeric
cf60: 20 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72   and/or "-" char
cf70: 61 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69  acters..** ^SQLi
cf80: 74 65 20 66 75 72 74 68 65 72 20 67 75 61 72 61  te further guara
cf90: 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68  ntees that.** th
cfa0: 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65  e string will be
cfb0: 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61   valid and uncha
cfc0: 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73  nged until xClos
cfd0: 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64  e() is.** called
cfe0: 2e 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65  . Because of the
cff0: 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e   previous senten
d000: 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  ce,.** the [sqli
d010: 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61  te3_file] can sa
d020: 66 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69  fely store a poi
d030: 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66  nter to the.** f
d040: 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65  ilename if it ne
d050: 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20  eds to remember 
d060: 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72  the filename for
d070: 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a   some reason..**
d080: 20 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d   If the zFilenam
d090: 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78  e parameter to x
d0a0: 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70  Open is a NULL p
d0b0: 6f 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65  ointer then xOpe
d0c0: 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74  n.** must invent
d0d0: 20 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61   its own tempora
d0e0: 72 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20  ry name for the 
d0f0: 66 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72  file.  ^Whenever
d100: 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61   the .** xFilena
d110: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  me parameter is 
d120: 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73  NULL it will als
d130: 6f 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68  o be the case th
d140: 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20  at the.** flags 
d150: 70 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69  parameter will i
d160: 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f  nclude [SQLITE_O
d170: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
d180: 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c  E]..**.** The fl
d190: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
d1a0: 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73  xOpen() includes
d1b0: 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e   all bits set in
d1c0: 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72  .** the flags ar
d1d0: 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74  gument to [sqlit
d1e0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20  e3_open_v2()].  
d1f0: 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f  Or if [sqlite3_o
d200: 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71  pen()].** or [sq
d210: 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20  lite3_open16()] 
d220: 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c  is used, then fl
d230: 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20  ags includes at 
d240: 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45  least.** [SQLITE
d250: 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
d260: 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   | [SQLITE_OPEN_
d270: 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20  CREATE]. .** If 
d280: 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20  xOpen() opens a 
d290: 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74  file read-only t
d2a0: 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75  hen it sets *pOu
d2b0: 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63  tFlags to.** inc
d2c0: 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  lude [SQLITE_OPE
d2d0: 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74  N_READONLY].  Ot
d2e0: 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75  her bits in *pOu
d2f0: 74 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65  tFlags may be se
d300: 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74  t..**.** ^(SQLit
d310: 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20  e will also add 
d320: 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  one of the follo
d330: 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68  wing flags to th
d340: 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c  e xOpen().** cal
d350: 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  l, depending on 
d360: 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67  the object being
d370: 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c   opened:.**.** <
d380: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  ul>.** <li>  [SQ
d390: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44  LITE_OPEN_MAIN_D
d3a0: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  B].** <li>  [SQL
d3b0: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f  ITE_OPEN_MAIN_JO
d3c0: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
d3d0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d  [SQLITE_OPEN_TEM
d3e0: 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  P_DB].** <li>  [
d3f0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
d400: 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  _JOURNAL].** <li
d410: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
d420: 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a  TRANSIENT_DB].**
d430: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
d440: 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a  PEN_SUBJOURNAL].
d450: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
d460: 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55  _OPEN_MASTER_JOU
d470: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
d480: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d  SQLITE_OPEN_WAL]
d490: 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a  .** </ul>)^.**.*
d4a0: 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69  * The file I/O i
d4b0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61  mplementation ca
d4c0: 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74  n use the object
d4d0: 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a   type flags to.*
d4e0: 2a 20 63 68 61 6e 67 65 20 74 68 65 20 77 61 79  * change the way
d4f0: 20 69 74 20 64 65 61 6c 73 20 77 69 74 68 20 66   it deals with f
d500: 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70  iles.  For examp
d510: 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69  le, an applicati
d520: 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20  on.** that does 
d530: 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20 63  not care about c
d540: 72 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72  rash recovery or
d550: 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20   rollback might 
d560: 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e  make.** the open
d570: 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69   of a journal fi
d580: 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69  le a no-op.  Wri
d590: 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72  tes to this jour
d5a0: 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73  nal would.** als
d5b0: 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64  o be no-ops, and
d5c0: 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20   any attempt to 
d5d0: 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c  read the journal
d5e0: 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a   would return.**
d5f0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20   SQLITE_IOERR.  
d600: 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  Or the implement
d610: 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f  ation might reco
d620: 67 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61 74  gnize that a dat
d630: 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69  abase.** file wi
d640: 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65  ll be doing page
d650: 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20  -aligned sector 
d660: 72 65 61 64 73 20 61 6e 64 20 77 72 69 74 65 73  reads and writes
d670: 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20   in a random.** 
d680: 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20 75 70  order and set up
d690: 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74   its I/O subsyst
d6a0: 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a  em accordingly..
d6b0: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67  **.** SQLite mig
d6c0: 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20  ht also add one 
d6d0: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
d6e0: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f   flags to the xO
d6f0: 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a  pen method:.**.*
d700: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
d710: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
d720: 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c  TEONCLOSE].** <l
d730: 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  i> [SQLITE_OPEN_
d740: 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f  EXCLUSIVE].** </
d750: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53  ul>.**.** The [S
d760: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
d770: 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d  EONCLOSE] flag m
d780: 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68  eans the file sh
d790: 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74  ould be.** delet
d7a0: 65 64 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c  ed when it is cl
d7b0: 6f 73 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c  osed.  ^The [SQL
d7c0: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
d7d0: 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20  NCLOSE].** will 
d7e0: 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20  be set for TEMP 
d7f0: 64 61 74 61 62 61 73 65 73 20 61 6e 64 20 74 68  databases and th
d800: 65 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72  eir journals, tr
d810: 61 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62  ansient.** datab
d820: 61 73 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75  ases, and subjou
d830: 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  rnals..**.** ^Th
d840: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  e [SQLITE_OPEN_E
d850: 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69  XCLUSIVE] flag i
d860: 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e  s always used in
d870: 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20   conjunction.** 
d880: 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
d890: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c  _OPEN_CREATE] fl
d8a0: 61 67 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f  ag, which are bo
d8b0: 74 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61  th directly.** a
d8c0: 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20  nalogous to the 
d8d0: 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45  O_EXCL and O_CRE
d8e0: 41 54 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20  AT flags of the 
d8f0: 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20  POSIX open().** 
d900: 41 50 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45  API.  The SQLITE
d910: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20  _OPEN_EXCLUSIVE 
d920: 66 6c 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65  flag, when paire
d930: 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53  d with the .** S
d940: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
d950: 45 2c 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e  E, is used to in
d960: 64 69 63 61 74 65 20 74 68 61 74 20 66 69 6c 65  dicate that file
d970: 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a   should always.*
d980: 2a 20 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e  * be created, an
d990: 64 20 74 68 61 74 20 69 74 20 69 73 20 61 6e 20  d that it is an 
d9a0: 65 72 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65  error if it alre
d9b0: 61 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49  ady exists..** I
d9c0: 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20  t is <i>not</i> 
d9d0: 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65  used to indicate
d9e0: 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64   the file should
d9f0: 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66   be opened .** f
da00: 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61 63 63  or exclusive acc
da10: 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c  ess..**.** ^At l
da20: 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79  east szOsFile by
da30: 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72  tes of memory ar
da40: 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53  e allocated by S
da50: 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64  QLite.** to hold
da60: 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66   the  [sqlite3_f
da70: 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20 70  ile] structure p
da80: 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69  assed as the thi
da90: 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74  rd.** argument t
daa0: 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f  o xOpen.  The xO
dab0: 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20  pen method does 
dac0: 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61  not have to.** a
dad0: 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72 75  llocate the stru
dae0: 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64  cture; it should
daf0: 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e   just fill it in
db00: 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20  .  Note that.** 
db10: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  the xOpen method
db20: 20 6d 75 73 74 20 73 65 74 20 74 68 65 20 73 71   must set the sq
db30: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
db40: 6f 64 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a  ods to either.**
db50: 20 61 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65   a valid [sqlite
db60: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
db70: 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e  ject or to NULL.
db80: 20 20 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a    xOpen must do.
db90: 2a 2a 20 74 68 69 73 20 65 76 65 6e 20 69 66 20  ** this even if 
dba0: 74 68 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20  the open fails. 
dbb0: 20 53 51 4c 69 74 65 20 65 78 70 65 63 74 73 20   SQLite expects 
dbc0: 74 68 61 74 20 74 68 65 20 73 71 6c 69 74 65 33  that the sqlite3
dbd0: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a  _file.pMethods.*
dbe0: 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62  * element will b
dbf0: 65 20 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f  e valid after xO
dc00: 70 65 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61  pen returns rega
dc10: 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75  rdless of the su
dc20: 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c  ccess.** or fail
dc30: 75 72 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e  ure of the xOpen
dc40: 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73   call..**.** [[s
dc50: 71 6c 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65  qlite3_vfs.xAcce
dc60: 73 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61  ss]].** ^The fla
dc70: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
dc80: 41 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20  Access() may be 
dc90: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45  [SQLITE_ACCESS_E
dca0: 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73  XISTS].** to tes
dcb0: 74 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 65  t for the existe
dcc0: 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f  nce of a file, o
dcd0: 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  r [SQLITE_ACCESS
dce0: 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a  _READWRITE] to.*
dcf0: 2a 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61  * test whether a
dd00: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c   file is readabl
dd10: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20  e and writable, 
dd20: 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  or [SQLITE_ACCES
dd30: 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65  S_READ].** to te
dd40: 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c  st whether a fil
dd50: 65 20 69 73 20 61 74 20 6c 65 61 73 74 20 72 65  e is at least re
dd60: 61 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69  adable.   The fi
dd70: 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64  le can be a.** d
dd80: 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20  irectory..**.** 
dd90: 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77  ^SQLite will alw
dda0: 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20  ays allocate at 
ddb0: 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65  least mxPathname
ddc0: 2b 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65  +1 bytes for the
ddd0: 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65  .** output buffe
dde0: 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e  r xFullPathname.
ddf0: 20 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65    The exact size
de00: 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62   of the output b
de10: 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f  uffer.** is also
de20: 20 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72   passed as a par
de30: 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20  ameter to both  
de40: 6d 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20  methods. If the 
de50: 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a  output buffer.**
de60: 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e   is not large en
de70: 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41  ough, [SQLITE_CA
de80: 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62  NTOPEN] should b
de90: 65 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63  e returned. Sinc
dea0: 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e  e this is.** han
deb0: 64 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20  dled as a fatal 
dec0: 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c  error by SQLite,
ded0: 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74   vfs implementat
dee0: 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65  ions should ende
def0: 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65  avor.** to preve
df00: 6e 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69  nt this by setti
df10: 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f  ng mxPathname to
df20: 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20   a sufficiently 
df30: 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a  large value..**.
df40: 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65  ** The xRandomne
df50: 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20  ss(), xSleep(), 
df60: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20  xCurrentTime(), 
df70: 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65  and xCurrentTime
df80: 49 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72  Int64().** inter
df90: 66 61 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74  faces are not st
dfa0: 72 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66  rictly a part of
dfb0: 20 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c   the filesystem,
dfc0: 20 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a   but they are.**
dfd0: 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65   included in the
dfe0: 20 56 46 53 20 73 74 72 75 63 74 75 72 65 20 66   VFS structure f
dff0: 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e  or completeness.
e000: 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e  .** The xRandomn
e010: 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61  ess() function a
e020: 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72  ttempts to retur
e030: 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a  n nBytes bytes.*
e040: 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74  * of good-qualit
e050: 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74  y randomness int
e060: 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74  o zOut.  The ret
e070: 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20  urn value is.** 
e080: 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65  the actual numbe
e090: 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61  r of bytes of ra
e0a0: 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65  ndomness obtaine
e0b0: 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70  d..** The xSleep
e0c0: 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73  () method causes
e0d0: 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72   the calling thr
e0e0: 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72  ead to sleep for
e0f0: 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65   at.** least the
e100: 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f   number of micro
e110: 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20  seconds given.  
e120: 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d  ^The xCurrentTim
e130: 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65  e().** method re
e140: 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44  turns a Julian D
e150: 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68  ay Number for th
e160: 65 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 61  e current date a
e170: 6e 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20  nd time as.** a 
e180: 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
e190: 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43  alue..** ^The xC
e1a0: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
e1b0: 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  ) method returns
e1c0: 2c 20 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c  , as an integer,
e1d0: 20 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44   the Julian.** D
e1e0: 61 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70  ay Number multip
e1f0: 6c 69 65 64 20 62 79 20 38 36 34 30 30 30 30 30  lied by 86400000
e200: 20 28 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20   (the number of 
e210: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20  milliseconds in 
e220: 0a 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61  .** a 24-hour da
e230: 79 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65  y).  .** ^SQLite
e240: 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43   will use the xC
e250: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
e260: 29 20 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20  ) method to get 
e270: 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64  the current.** d
e280: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20  ate and time if 
e290: 74 68 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61  that method is a
e2a0: 76 61 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65  vailable (if iVe
e2b0: 72 73 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a  rsion is 2 or .*
e2c0: 2a 20 67 72 65 61 74 65 72 20 61 6e 64 20 74 68  * greater and th
e2d0: 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74  e function point
e2e0: 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20  er is not NULL) 
e2f0: 61 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61  and will fall ba
e300: 63 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e  ck.** to xCurren
e310: 74 54 69 6d 65 28 29 20 69 66 20 78 43 75 72 72  tTime() if xCurr
e320: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69  entTimeInt64() i
e330: 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a  s unavailable..*
e340: 2a 0a 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79  *.** ^The xSetSy
e350: 73 74 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74  stemCall(), xGet
e360: 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e  SystemCall(), an
e370: 64 20 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c  d xNestSystemCal
e380: 6c 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  l() interfaces.*
e390: 2a 20 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62  * are not used b
e3a0: 79 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72  y the SQLite cor
e3b0: 65 2e 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e  e.  These option
e3c0: 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  al interfaces ar
e3d0: 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79  e provided.** by
e3e0: 20 73 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66   some VFSes to f
e3f0: 61 63 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e  acilitate testin
e400: 67 20 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64  g of the VFS cod
e410: 65 2e 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67  e. By overriding
e420: 20 0a 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c   .** system call
e430: 73 20 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73  s with functions
e440: 20 75 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72   under its contr
e450: 6f 6c 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72  ol, a test progr
e460: 61 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61  am can.** simula
e470: 74 65 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72  te faults and er
e480: 72 6f 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74  ror conditions t
e490: 68 61 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77  hat would otherw
e4a0: 69 73 65 20 62 65 20 64 69 66 66 69 63 75 6c 74  ise be difficult
e4b0: 0a 2a 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c  .** or impossibl
e4c0: 65 20 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68  e to induce.  Th
e4d0: 65 20 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20  e set of system 
e4e0: 63 61 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62  calls that can b
e4f0: 65 20 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20  e overridden.** 
e500: 76 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20  varies from one 
e510: 56 46 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20  VFS to another, 
e520: 61 6e 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72  and from one ver
e530: 73 69 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65  sion of the same
e540: 20 56 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e   VFS to the.** n
e550: 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ext.  Applicatio
e560: 6e 73 20 74 68 61 74 20 75 73 65 20 74 68 65 73  ns that use thes
e570: 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73  e interfaces mus
e580: 74 20 62 65 20 70 72 65 70 61 72 65 64 20 66 6f  t be prepared fo
e590: 72 20 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20  r any.** or all 
e5a0: 6f 66 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  of these interfa
e5b0: 63 65 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f  ces to be NULL o
e5c0: 72 20 66 6f 72 20 74 68 65 69 72 20 62 65 68 61  r for their beha
e5d0: 76 69 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a  vior to change.*
e5e0: 2a 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61  * from one relea
e5f0: 73 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20  se to the next. 
e600: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75   Applications mu
e610: 73 74 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74  st not attempt t
e620: 6f 20 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20  o access.** any 
e630: 6f 66 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73  of these methods
e640: 20 69 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e   if the iVersion
e650: 20 6f 66 20 74 68 65 20 56 46 53 20 69 73 20 6c   of the VFS is l
e660: 65 73 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74  ess than 3..*/.t
e670: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
e680: 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65  lite3_vfs sqlite
e690: 33 5f 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76  3_vfs;.typedef v
e6a0: 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79  oid (*sqlite3_sy
e6b0: 73 63 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29  scall_ptr)(void)
e6c0: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
e6d0: 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65  _vfs {.  int iVe
e6e0: 72 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20  rsion;          
e6f0: 20 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76    /* Structure v
e700: 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63  ersion number (c
e710: 75 72 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20  urrently 3) */. 
e720: 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20   int szOsFile;  
e730: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a            /* Siz
e740: 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20  e of subclassed 
e750: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a  sqlite3_file */.
e760: 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65    int mxPathname
e770: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61  ;          /* Ma
e780: 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e  ximum file pathn
e790: 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20  ame length */.  
e7a0: 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65  sqlite3_vfs *pNe
e7b0: 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74  xt;      /* Next
e7c0: 20 72 65 67 69 73 74 65 72 65 64 20 56 46 53 20   registered VFS 
e7d0: 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
e7e0: 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a  *zName;       /*
e7f0: 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69   Name of this vi
e800: 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65  rtual file syste
e810: 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70  m */.  void *pAp
e820: 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20  pData;          
e830: 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70  /* Pointer to ap
e840: 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66  plication-specif
e850: 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74  ic data */.  int
e860: 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65   (*xOpen)(sqlite
e870: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
e880: 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74  ar *zName, sqlit
e890: 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20  e3_file*,.      
e8a0: 20 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61           int fla
e8b0: 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61  gs, int *pOutFla
e8c0: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65  gs);.  int (*xDe
e8d0: 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66  lete)(sqlite3_vf
e8e0: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
e8f0: 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44  zName, int syncD
e900: 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63  ir);.  int (*xAc
e910: 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66  cess)(sqlite3_vf
e920: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
e930: 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73  zName, int flags
e940: 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b  , int *pResOut);
e950: 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61  .  int (*xFullPa
e960: 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f  thname)(sqlite3_
e970: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
e980: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75   *zName, int nOu
e990: 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a  t, char *zOut);.
e9a0: 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65    void *(*xDlOpe
e9b0: 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  n)(sqlite3_vfs*,
e9c0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69   const char *zFi
e9d0: 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20  lename);.  void 
e9e0: 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69  (*xDlError)(sqli
e9f0: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42  te3_vfs*, int nB
ea00: 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d  yte, char *zErrM
ea10: 73 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a  sg);.  void (*(*
ea20: 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f  xDlSym)(sqlite3_
ea30: 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73  vfs*,void*, cons
ea40: 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29  t char *zSymbol)
ea50: 29 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20  )(void);.  void 
ea60: 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69  (*xDlClose)(sqli
ea70: 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29  te3_vfs*, void*)
ea80: 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f  ;.  int (*xRando
ea90: 6d 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76  mness)(sqlite3_v
eaa0: 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20  fs*, int nByte, 
eab0: 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69  char *zOut);.  i
eac0: 6e 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c  nt (*xSleep)(sql
ead0: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d  ite3_vfs*, int m
eae0: 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20  icroseconds);.  
eaf0: 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69  int (*xCurrentTi
eb00: 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  me)(sqlite3_vfs*
eb10: 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e  , double*);.  in
eb20: 74 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f  t (*xGetLastErro
eb30: 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  r)(sqlite3_vfs*,
eb40: 20 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20   int, char *);. 
eb50: 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74   /*.  ** The met
eb60: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
eb70: 6e 20 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74  n version 1 of t
eb80: 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62  he sqlite_vfs ob
eb90: 6a 65 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69  ject.  ** defini
eba0: 74 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61  tion.  Those tha
ebb0: 74 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64  t follow are add
ebc0: 65 64 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20  ed in version 2 
ebd0: 6f 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20  or later.  */.  
ebe0: 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69  int (*xCurrentTi
ebf0: 6d 65 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33  meInt64)(sqlite3
ec00: 5f 76 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69  _vfs*, sqlite3_i
ec10: 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a  nt64*);.  /*.  *
ec20: 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62  * The methods ab
ec30: 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69  ove are in versi
ec40: 6f 6e 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74  ons 1 and 2 of t
ec50: 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62  he sqlite_vfs ob
ec60: 6a 65 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65  ject..  ** Those
ec70: 20 62 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76   below are for v
ec80: 65 72 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65  ersion 3 and gre
ec90: 61 74 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74  ater..  */.  int
eca0: 20 28 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c   (*xSetSystemCal
ecb0: 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  l)(sqlite3_vfs*,
ecc0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
ecd0: 6d 65 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63  me, sqlite3_sysc
ece0: 61 6c 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69  all_ptr);.  sqli
ecf0: 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20  te3_syscall_ptr 
ed00: 28 2a 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c  (*xGetSystemCall
ed10: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
ed20: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
ed30: 65 29 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  e);.  const char
ed40: 20 2a 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43   *(*xNextSystemC
ed50: 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73  all)(sqlite3_vfs
ed60: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
ed70: 4e 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a  Name);.  /*.  **
ed80: 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f   The methods abo
ed90: 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f  ve are in versio
eda0: 6e 73 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f  ns 1 through 3 o
edb0: 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73  f the sqlite_vfs
edc0: 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65   object..  ** Ne
edd0: 77 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20  w fields may be 
ede0: 61 70 70 65 6e 64 65 64 20 69 6e 20 66 75 74 75  appended in futu
edf0: 72 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68  re versions.  Th
ee00: 65 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20  e iVersion.  ** 
ee10: 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65  value will incre
ee20: 6d 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68  ment whenever th
ee30: 69 73 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a  is happens. .  *
ee40: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
ee50: 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20  3REF: Flags for 
ee60: 74 68 65 20 78 41 63 63 65 73 73 20 56 46 53 20  the xAccess VFS 
ee70: 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65  method.**.** The
ee80: 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
ee90: 61 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65 64  ants can be used
eea0: 20 61 73 20 74 68 65 20 74 68 69 72 64 20 70 61   as the third pa
eeb0: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68  rameter to.** th
eec0: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
eed0: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
eee0: 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68  vfs] object.  Th
eef0: 65 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20  ey determine.** 
ef00: 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72  what kind of per
ef10: 6d 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63  missions the xAc
ef20: 63 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c  cess method is l
ef30: 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57  ooking for..** W
ef40: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
ef50: 53 5f 45 58 49 53 54 53 2c 20 74 68 65 20 78 41  S_EXISTS, the xA
ef60: 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20  ccess method.** 
ef70: 73 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68  simply checks wh
ef80: 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 65  ether the file e
ef90: 78 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53  xists..** With S
efa0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
efb0: 44 57 52 49 54 45 2c 20 74 68 65 20 78 41 63 63  DWRITE, the xAcc
efc0: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68  ess method.** ch
efd0: 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65  ecks whether the
efe0: 20 6e 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79   named directory
eff0: 20 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c   is both readabl
f000: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a  e and writable.*
f010: 2a 20 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64  * (in other word
f020: 73 2c 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20  s, if files can 
f030: 62 65 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65  be added, remove
f040: 64 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77  d, and renamed w
f050: 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72  ithin.** the dir
f060: 65 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20  ectory)..** The 
f070: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
f080: 41 44 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74  ADWRITE constant
f090: 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73   is currently us
f0a0: 65 64 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a  ed only by the.*
f0b0: 2a 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69  * [temp_store_di
f0c0: 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c  rectory pragma],
f0d0: 20 74 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75   though this cou
f0e0: 6c 64 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66  ld change in a f
f0f0: 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65  uture.** release
f100: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57   of SQLite..** W
f110: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
f120: 53 5f 52 45 41 44 2c 20 74 68 65 20 78 41 63 63  S_READ, the xAcc
f130: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68  ess method.** ch
f140: 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65  ecks whether the
f150: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c   file is readabl
f160: 65 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41  e.  The SQLITE_A
f170: 43 43 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74  CCESS_READ const
f180: 61 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e  ant is.** curren
f190: 74 6c 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75  tly unused, thou
f1a0: 67 68 20 69 74 20 6d 69 67 68 74 20 62 65 20 75  gh it might be u
f1b0: 73 65 64 20 69 6e 20 61 20 66 75 74 75 72 65 20  sed in a future 
f1c0: 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51  release of.** SQ
f1d0: 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  Lite..*/.#define
f1e0: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45   SQLITE_ACCESS_E
f1f0: 58 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 69  XISTS    0.#defi
f200: 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  ne SQLITE_ACCESS
f210: 5f 52 45 41 44 57 52 49 54 45 20 31 20 20 20 2f  _READWRITE 1   /
f220: 2a 20 55 73 65 64 20 62 79 20 50 52 41 47 4d 41  * Used by PRAGMA
f230: 20 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65   temp_store_dire
f240: 63 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65  ctory */.#define
f250: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
f260: 45 41 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20  EAD      2   /* 
f270: 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  Unused */../*.**
f280: 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73   CAPI3REF: Flags
f290: 20 66 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63   for the xShmLoc
f2a0: 6b 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a  k VFS method.**.
f2b0: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72  ** These integer
f2c0: 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e   constants defin
f2d0: 65 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f  e the various lo
f2e0: 63 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73  cking operations
f2f0: 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74  .** allowed by t
f300: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  he xShmLock meth
f310: 6f 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69  od of [sqlite3_i
f320: 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65  o_methods].  The
f330: 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72  .** following ar
f340: 65 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c  e the only legal
f350: 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66   combinations of
f360: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a   flags to the.**
f370: 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
f380: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
f390: 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d  <li>  SQLITE_SHM
f3a0: 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53  _LOCK | SQLITE_S
f3b0: 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69  HM_SHARED.** <li
f3c0: 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f  >  SQLITE_SHM_LO
f3d0: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
f3e0: 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69  EXCLUSIVE.** <li
f3f0: 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e  >  SQLITE_SHM_UN
f400: 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48  LOCK | SQLITE_SH
f410: 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e  M_SHARED.** <li>
f420: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c    SQLITE_SHM_UNL
f430: 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d  OCK | SQLITE_SHM
f440: 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f  _EXCLUSIVE.** </
f450: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75  ul>.**.** When u
f460: 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61  nlocking, the sa
f470: 6d 65 20 53 48 41 52 45 44 20 6f 72 20 45 58 43  me SHARED or EXC
f480: 4c 55 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74  LUSIVE flag must
f490: 20 62 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a   be supplied as.
f4a0: 2a 2a 20 77 61 73 20 67 69 76 65 6e 20 6f 6e 20  ** was given on 
f4b0: 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
f4c0: 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20  g lock.  .**.** 
f4d0: 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74  The xShmLock met
f4e0: 68 6f 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69  hod can transiti
f4f0: 6f 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63  on between unloc
f500: 6b 65 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f  ked and SHARED o
f510: 72 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c  r.** between unl
f520: 6f 63 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53  ocked and EXCLUS
f530: 49 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20  IVE.  It cannot 
f540: 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65  transition betwe
f550: 65 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64  en SHARED.** and
f560: 20 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23   EXCLUSIVE..*/.#
f570: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
f580: 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31  M_UNLOCK       1
f590: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
f5a0: 53 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20  SHM_LOCK        
f5b0: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
f5c0: 45 5f 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20  E_SHM_SHARED    
f5d0: 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
f5e0: 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56  ITE_SHM_EXCLUSIV
f5f0: 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41  E    8../*.** CA
f600: 50 49 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20  PI3REF: Maximum 
f610: 78 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a  xShmLock index.*
f620: 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63  *.** The xShmLoc
f630: 6b 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c  k method on [sql
f640: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
f650: 20 6d 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a   may use values.
f660: 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64  ** between 0 and
f670: 20 74 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e   this upper boun
f680: 64 20 61 73 20 69 74 73 20 22 6f 66 66 73 65 74  d as its "offset
f690: 22 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54  " argument..** T
f6a0: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77  he SQLite core w
f6b0: 69 6c 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70  ill never attemp
f6c0: 74 20 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20  t to acquire or 
f6d0: 72 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63  release a.** loc
f6e0: 6b 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69  k outside of thi
f6f0: 73 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69  s range.*/.#defi
f700: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c  ne SQLITE_SHM_NL
f710: 4f 43 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f  OCK        8.../
f720: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
f730: 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51  nitialize The SQ
f740: 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a  Lite Library.**.
f750: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
f760: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
f770: 74 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73  tine initializes
f780: 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c   the.** SQLite l
f790: 69 62 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71  ibrary.  ^The sq
f7a0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
f7b0: 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c   routine.** deal
f7c0: 6c 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f  locates any reso
f7d0: 75 72 63 65 73 20 74 68 61 74 20 77 65 72 65 20  urces that were 
f7e0: 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c  allocated by sql
f7f0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
f800: 29 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  )..** These rout
f810: 69 6e 65 73 20 61 72 65 20 64 65 73 69 67 6e 65  ines are designe
f820: 64 20 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63  d to aid in proc
f830: 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  ess initializati
f840: 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f  on and.** shutdo
f850: 77 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73  wn on embedded s
f860: 79 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61  ystems.  Worksta
f870: 74 69 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  tion application
f880: 73 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74  s using.** SQLit
f890: 65 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f  e normally do no
f8a0: 74 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65  t need to invoke
f8b0: 20 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65   either of these
f8c0: 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
f8d0: 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74   A call to sqlit
f8e0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
f8f0: 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65  is an "effective
f900: 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a  " call if it is.
f910: 2a 2a 20 74 68 65 20 66 69 72 73 74 20 74 69 6d  ** the first tim
f920: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
f930: 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
f940: 64 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66  d during the lif
f950: 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20  etime of.** the 
f960: 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69  process, or if i
f970: 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20 74  t is the first t
f980: 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  ime sqlite3_init
f990: 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f  ialize() is invo
f9a0: 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  ked.** following
f9b0: 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74   a call to sqlit
f9c0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20  e3_shutdown().  
f9d0: 5e 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74  ^(Only an effect
f9e0: 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73  ive call.** of s
f9f0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
fa00: 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69  e() does any ini
fa10: 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c  tialization.  Al
fa20: 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a  l other calls.**
fa30: 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f   are harmless no
fa40: 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20  -ops.)^.**.** A 
fa50: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
fa60: 73 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e  shutdown() is an
fa70: 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c   "effective" cal
fa80: 6c 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66  l if it is the f
fa90: 69 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20  irst.** call to 
faa0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
fab0: 28 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73  () since the las
fac0: 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  t sqlite3_initia
fad0: 6c 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a  lize().  ^(Only.
fae0: 2a 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65 20  ** an effective 
faf0: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
fb00: 73 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20  shutdown() does 
fb10: 61 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61  any deinitializa
fb20: 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68  tion..** All oth
fb30: 65 72 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74  er valid calls t
fb40: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
fb50: 77 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73  wn() are harmles
fb60: 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a  s no-ops.)^.**.*
fb70: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  * The sqlite3_in
fb80: 69 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72  itialize() inter
fb90: 66 61 63 65 20 69 73 20 74 68 72 65 61 64 73 61  face is threadsa
fba0: 66 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f  fe, but sqlite3_
fbb0: 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73  shutdown().** is
fbc0: 20 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74   not.  The sqlit
fbd0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e  e3_shutdown() in
fbe0: 74 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c  terface must onl
fbf0: 79 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  y be called from
fc00: 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72   a.** single thr
fc10: 65 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b  ead.  All open [
fc20: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
fc30: 69 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c  ions] must be cl
fc40: 6f 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20  osed and all.** 
fc50: 6f 74 68 65 72 20 53 51 4c 69 74 65 20 72 65 73  other SQLite res
fc60: 6f 75 72 63 65 73 20 6d 75 73 74 20 62 65 20 64  ources must be d
fc70: 65 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72  eallocated prior
fc80: 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20   to invoking.** 
fc90: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
fca0: 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20  ()..**.** Among 
fcb0: 6f 74 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73  other things, ^s
fcc0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
fcd0: 65 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a  e() will invoke.
fce0: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  ** sqlite3_os_in
fcf0: 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79  it().  Similarly
fd00: 2c 20 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64  , ^sqlite3_shutd
fd10: 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e  own().** will in
fd20: 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f  voke sqlite3_os_
fd30: 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  end()..**.** ^Th
fd40: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
fd50: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72  lize() routine r
fd60: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
fd70: 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a  K] on success..*
fd80: 2a 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72  * ^If for some r
fd90: 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69  eason, sqlite3_i
fda0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75  nitialize() is u
fdb0: 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c  nable to initial
fdc0: 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61  ize.** the libra
fdd0: 72 79 20 28 70 65 72 68 61 70 73 20 69 74 20 69  ry (perhaps it i
fde0: 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  s unable to allo
fdf0: 63 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 65  cate a needed re
fe00: 73 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61  source such.** a
fe10: 73 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 65  s a mutex) it re
fe20: 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20  turns an [error 
fe30: 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e  code] other than
fe40: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a   [SQLITE_OK]..**
fe50: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
fe60: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f  _initialize() ro
fe70: 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20  utine is called 
fe80: 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61  internally by ma
fe90: 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69  ny other.** SQLi
fea0: 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f  te interfaces so
feb0: 20 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61   that an applica
fec0: 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65  tion usually doe
fed0: 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a  s not need to.**
fee0: 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
fef0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72  initialize() dir
ff00: 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d  ectly.  For exam
ff10: 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ple, [sqlite3_op
ff20: 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73  en()].** calls s
ff30: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
ff40: 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74  e() so the SQLit
ff50: 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62  e library will b
ff60: 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a  e automatically.
ff70: 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77  ** initialized w
ff80: 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  hen [sqlite3_ope
ff90: 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69  n()] is called i
ffa0: 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20  f it has not be 
ffb0: 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61  initialized.** a
ffc0: 6c 72 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65  lready.  ^Howeve
ffd0: 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  r, if SQLite is 
ffe0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
fff0: 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41  e [SQLITE_OMIT_A
10000 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70  UTOINIT].** comp
10010 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c  ile-time option,
10020 20 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61   then the automa
10030 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  tic calls to sql
10040 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
10050 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64  ).** are omitted
10060 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61   and the applica
10070 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73  tion must call s
10080 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
10090 65 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  e() directly.** 
100a0 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61  prior to using a
100b0 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ny other SQLite 
100c0 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20  interface.  For 
100d0 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c  maximum portabil
100e0 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65  ity,.** it is re
100f0 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61  commended that a
10100 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61  pplications alwa
10110 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ys invoke sqlite
10120 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a  3_initialize().*
10130 2a 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72  * directly prior
10140 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74   to using any ot
10150 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
10160 66 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 65  face.  Future re
10170 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c  leases.** of SQL
10180 69 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 20  ite may require 
10190 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20  this.  In other 
101a0 77 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 76  words, the behav
101b0 69 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a  ior exhibited.**
101c0 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20   when SQLite is 
101d0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53  compiled with [S
101e0 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49  QLITE_OMIT_AUTOI
101f0 4e 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d  NIT] might becom
10200 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74  e the.** default
10210 20 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d   behavior in som
10220 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  e future release
10230 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
10240 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73  * The sqlite3_os
10250 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20  _init() routine 
10260 64 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73  does operating-s
10270 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a  ystem specific.*
10280 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  * initialization
10290 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c   of the SQLite l
102a0 69 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c  ibrary.  The sql
102b0 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
102c0 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20   routine undoes 
102d0 74 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71  the effect of sq
102e0 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e  lite3_os_init().
102f0 20 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a    Typical tasks.
10300 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20  ** performed by 
10310 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69  these routines i
10320 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f  nclude allocatio
10330 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f  n or deallocatio
10340 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72  n.** of static r
10350 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61  esources, initia
10360 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62  lization of glob
10370 61 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a  al variables,.**
10380 20 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65   setting up a de
10390 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
103a0 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73  fs] module, or s
103b0 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64  etting up.** a d
103c0 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61  efault configura
103d0 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69  tion using [sqli
103e0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a  te3_config()]..*
103f0 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  *.** The applica
10400 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65  tion should neve
10410 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20  r invoke either 
10420 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
10430 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
10440 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c  os_end() directl
10450 79 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74  y.  The applicat
10460 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20  ion should only 
10470 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  invoke.** sqlite
10480 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61  3_initialize() a
10490 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  nd sqlite3_shutd
104a0 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69  own().  The sqli
104b0 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a  te3_os_init().**
104c0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61   interface is ca
104d0 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c  lled automatical
104e0 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ly by sqlite3_in
104f0 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a  itialize() and.*
10500 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  * sqlite3_os_end
10510 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20  () is called by 
10520 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
10530 28 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65  ().  Appropriate
10540 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
10550 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  ons for sqlite3_
10560 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71  os_init() and sq
10570 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a  lite3_os_end().*
10580 2a 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f  * are built into
10590 20 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20   SQLite when it 
105a0 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20  is compiled for 
105b0 55 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f  Unix, Windows, o
105c0 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20  r OS/2..** When 
105d0 5b 63 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c  [custom builds |
105e0 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72   built for other
105f0 20 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28   platforms].** (
10600 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54  using the [SQLIT
10610 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f  E_OS_OTHER=1] co
10620 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70  mpile-time.** op
10630 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63  tion) the applic
10640 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c  ation must suppl
10650 79 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70  y a suitable imp
10660 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a  lementation for.
10670 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  ** sqlite3_os_in
10680 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  it() and sqlite3
10690 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61  _os_end().  An a
106a0 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c  pplication-suppl
106b0 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ied.** implement
106c0 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  ation of sqlite3
106d0 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71  _os_init() or sq
106e0 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a  lite3_os_end().*
106f0 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53  * must return [S
10700 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
10710 63 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74  cess and some ot
10720 68 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  her [error code]
10730 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65   upon.** failure
10740 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
10750 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64  _initialize(void
10760 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  );.int sqlite3_s
10770 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69  hutdown(void);.i
10780 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  nt sqlite3_os_in
10790 69 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71  it(void);.int sq
107a0 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69  lite3_os_end(voi
107b0 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  d);../*.** CAPI3
107c0 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67  REF: Configuring
107d0 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72   The SQLite Libr
107e0 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ary.**.** The sq
107f0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
10800 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
10810 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20   to make global 
10820 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a  configuration.**
10830 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69   changes to SQLi
10840 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74  te in order to t
10850 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68  une SQLite to th
10860 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73  e specific needs
10870 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   of.** the appli
10880 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66  cation.  The def
10890 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69  ault configurati
108a0 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  on is recommende
108b0 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70  d for most.** ap
108c0 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73  plications and s
108d0 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  o this routine i
108e0 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65  s usually not ne
108f0 63 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a  cessary.  It is.
10900 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73  ** provided to s
10910 75 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c  upport rare appl
10920 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e  ications with un
10930 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a  usual needs..**.
10940 2a 2a 20 3c 62 3e 54 68 65 20 73 71 6c 69 74 65  ** <b>The sqlite
10950 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  3_config() inter
10960 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65  face is not thre
10970 61 64 73 61 66 65 2e 20 54 68 65 20 61 70 70 6c  adsafe. The appl
10980 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20  ication.** must 
10990 65 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f  ensure that no o
109a0 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
109b0 72 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b  rfaces are invok
109c0 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74  ed by other.** t
109d0 68 72 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c  hreads while sql
109e0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73  ite3_config() is
109f0 20 72 75 6e 6e 69 6e 67 2e 3c 2f 62 3e 0a 2a 2a   running.</b>.**
10a00 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
10a10 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
10a20 63 65 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62  ce.** may only b
10a30 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20  e invoked prior 
10a40 74 6f 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69  to library initi
10a50 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a  alization using.
10a60 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74  ** [sqlite3_init
10a70 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74  ialize()] or aft
10a80 65 72 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b  er shutdown by [
10a90 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
10aa0 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  ()]..** ^If sqli
10ab0 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20  te3_config() is 
10ac0 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71  called after [sq
10ad0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
10ae0 28 29 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a  ()] and before.*
10af0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  * [sqlite3_shutd
10b00 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77  own()] then it w
10b10 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54  ill return SQLIT
10b20 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74  E_MISUSE..** Not
10b30 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74  e, however, that
10b40 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   ^sqlite3_config
10b50 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64  () can be called
10b60 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a   as part of the.
10b70 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
10b80 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74  n of an applicat
10b90 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c  ion-defined [sql
10ba0 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e  ite3_os_init()].
10bb0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
10bc0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
10bd0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73  ite3_config() is
10be0 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b   an integer.** [
10bf0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
10c00 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72  tion] that deter
10c10 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72  mines.** what pr
10c20 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65  operty of SQLite
10c30 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67   is to be config
10c40 75 72 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e  ured.  Subsequen
10c50 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76  t arguments.** v
10c60 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ary depending on
10c70 20 74 68 65 20 5b 63 6f 6e 66 69 67 75 72 61 74   the [configurat
10c80 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69  ion option].** i
10c90 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
10ca0 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65  ment..**.** ^Whe
10cb0 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  n a configuratio
10cc0 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c  n option is set,
10cd0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
10ce0 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  ) returns [SQLIT
10cf0 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68  E_OK]..** ^If th
10d00 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e  e option is unkn
10d10 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73  own or SQLite is
10d20 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74   unable to set t
10d30 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65  he option.** the
10d40 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72  n this routine r
10d50 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72  eturns a non-zer
10d60 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a  o [error code]..
10d70 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
10d80 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b  onfig(int, ...);
10d90 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
10da0 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61  : Configure data
10db0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
10dc0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
10dd0 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  te3.**.** The sq
10de0 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
10df0 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75  ) interface is u
10e00 73 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66  sed to make conf
10e10 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61  iguration.** cha
10e20 6e 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62  nges to a [datab
10e30 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
10e40 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20    The interface 
10e50 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a  is similar to.**
10e60 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
10e70 28 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20  ()] except that 
10e80 74 68 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c  the changes appl
10e90 79 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a  y to a single.**
10ea0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
10eb0 63 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65  ction] (specifie
10ec0 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  d in the first a
10ed0 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20  rgument)..**.** 
10ee0 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
10ef0 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64  ent to sqlite3_d
10f00 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e  b_config(D,V,...
10f10 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51  )  is the.** [SQ
10f20 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
10f30 4f 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66 69 67  OKASIDE | config
10f40 75 72 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20  uration verb] - 
10f50 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20  an integer code 
10f60 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74  .** that indicat
10f70 65 73 20 77 68 61 74 20 61 73 70 65 63 74 20 6f  es what aspect o
10f80 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  f the [database 
10f90 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62  connection] is b
10fa0 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e  eing configured.
10fb0 0a 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20 61  .** Subsequent a
10fc0 72 67 75 6d 65 6e 74 73 20 76 61 72 79 20 64 65  rguments vary de
10fd0 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63  pending on the c
10fe0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72  onfiguration ver
10ff0 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20  b..**.** ^Calls 
11000 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  to sqlite3_db_co
11010 6e 66 69 67 28 29 20 72 65 74 75 72 6e 20 53 51  nfig() return SQ
11020 4c 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f  LITE_OK if and o
11030 6e 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 61  nly if.** the ca
11040 6c 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64  ll is considered
11050 20 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a   successful..*/.
11060 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63  int sqlite3_db_c
11070 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20  onfig(sqlite3*, 
11080 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f  int op, ...);../
11090 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
110a0 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e  emory Allocation
110b0 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20   Routines.**.** 
110c0 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
110d0 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e  his object defin
110e0 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
110f0 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a   between SQLite.
11100 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c  ** and low-level
11110 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
11120 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  on routines..**.
11130 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69  ** This object i
11140 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f  s used in only o
11150 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20  ne place in the 
11160 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
11170 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74  ..** A pointer t
11180 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
11190 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   this object is 
111a0 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  the argument to.
111b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
111c0 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63  ig()] when the c
111d0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
111e0 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54  ion is.** [SQLIT
111f0 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
11200 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   or [SQLITE_CONF
11210 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20  IG_GETMALLOC].  
11220 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20  .** By creating 
11230 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
11240 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e  his object.** an
11250 64 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20  d passing it to 
11260 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d  [sqlite3_config]
11270 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ([SQLITE_CONFIG_
11280 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69  MALLOC]).** duri
11290 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ng configuration
112a0 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
112b0 20 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20   can specify an 
112c0 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d  alternative.** m
112d0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
112e0 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53   subsystem for S
112f0 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72  QLite to use for
11300 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64   all of its.** d
11310 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65  ynamic memory ne
11320 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  eds..**.** Note 
11330 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65  that SQLite come
11340 73 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b  s with several [
11350 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
11360 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74  allocators].** t
11370 68 61 74 20 61 72 65 20 70 65 72 66 65 63 74 6c  hat are perfectl
11380 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74  y adequate for t
11390 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20  he overwhelming 
113a0 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c  majority of appl
113b0 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20  ications.** and 
113c0 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74  that this object
113d0 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20   is only useful 
113e0 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69  to a tiny minori
113f0 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f  ty of applicatio
11400 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69  ns.** with speci
11410 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c  alized memory al
11420 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65  location require
11430 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a  ments.  This obj
11440 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75  ect is.** also u
11450 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69  sed during testi
11460 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20  ng of SQLite in 
11470 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79  order to specify
11480 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a   an alternative.
11490 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
114a0 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74  tor that simulat
114b0 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66  es memory out-of
114c0 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f  -memory conditio
114d0 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74  ns in.** order t
114e0 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51  o verify that SQ
114f0 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72  Lite recovers gr
11500 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75  acefully from su
11510 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73  ch.** conditions
11520 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c  ..**.** The xMal
11530 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61  loc, xRealloc, a
11540 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73  nd xFree methods
11550 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20   must work like 
11560 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c  the.** malloc(),
11570 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66   realloc() and f
11580 72 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20  ree() functions 
11590 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72  from the standar
115a0 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20  d C library..** 
115b0 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65  ^SQLite guarante
115c0 65 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f  es that the seco
115d0 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  nd argument to.*
115e0 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c  * xRealloc is al
115f0 77 61 79 73 20 61 20 76 61 6c 75 65 20 72 65 74  ways a value ret
11600 75 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72  urned by a prior
11610 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75   call to xRoundu
11620 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73  p..**.** xSize s
11630 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65  hould return the
11640 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20   allocated size 
11650 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  of a memory allo
11660 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f  cation.** previo
11670 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72  usly obtained fr
11680 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52  om xMalloc or xR
11690 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c  ealloc.  The all
116a0 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69  ocated size.** i
116b0 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73  s always at leas
116c0 74 20 61 73 20 62 69 67 20 61 73 20 74 68 65 20  t as big as the 
116d0 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 20 62  requested size b
116e0 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72  ut may be larger
116f0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75  ..**.** The xRou
11700 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75  ndup method retu
11710 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62  rns what would b
11720 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20  e the allocated 
11730 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d  size of.** a mem
11740 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67  ory allocation g
11750 69 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61  iven a particula
11760 72 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65  r requested size
11770 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a  .  Most memory.*
11780 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75  * allocators rou
11790 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c  nd up memory all
117a0 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73  ocations at leas
117b0 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75  t to the next mu
117c0 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20  ltiple.** of 8. 
117d0 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73   Some allocators
117e0 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c   round up to a l
117f0 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f  arger multiple o
11800 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20  r to a power of 
11810 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f  2..** Every memo
11820 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65  ry allocation re
11830 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20  quest coming in 
11840 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65 33  through [sqlite3
11850 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72  _malloc()].** or
11860 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
11870 63 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c 73  c()] first calls
11880 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20 78   xRoundup.  If x
11890 52 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73 20  Roundup returns 
118a0 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75 73  0, .** that caus
118b0 65 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  es the correspon
118c0 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ding memory allo
118d0 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a  cation to fail..
118e0 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20  **.** The xInit 
118f0 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a  method initializ
11900 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  es the memory al
11910 6c 6f 63 61 74 6f 72 2e 20 20 46 6f 72 20 65 78  locator.  For ex
11920 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67  ample,.** it mig
11930 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20  ht allocate any 
11940 72 65 71 75 69 72 65 20 6d 75 74 65 78 65 73 20  require mutexes 
11950 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e  or initialize in
11960 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73  ternal data.** s
11970 74 72 75 63 74 75 72 65 73 2e 20 20 54 68 65 20  tructures.  The 
11980 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64  xShutdown method
11990 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64   is invoked (ind
119a0 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b  irectly) by.** [
119b0 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
119c0 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64  ()] and should d
119d0 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65  eallocate any re
119e0 73 6f 75 72 63 65 73 20 61 63 71 75 69 72 65 64  sources acquired
119f0 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54  .** by xInit.  T
11a00 68 65 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e  he pAppData poin
11a10 74 65 72 20 69 73 20 75 73 65 64 20 61 73 20 74  ter is used as t
11a20 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65  he only paramete
11a30 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e  r to.** xInit an
11a40 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a  d xShutdown..**.
11a50 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20  ** SQLite holds 
11a60 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45  the [SQLITE_MUTE
11a70 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d  X_STATIC_MASTER]
11a80 20 6d 75 74 65 78 20 77 68 65 6e 20 69 74 20 69   mutex when it i
11a90 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49  nvokes.** the xI
11aa0 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74  nit method, so t
11ab0 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20  he xInit method 
11ac0 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65  need not be thre
11ad0 61 64 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20  adsafe.  The.** 
11ae0 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64  xShutdown method
11af0 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20   is only called 
11b00 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68  from [sqlite3_sh
11b10 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20  utdown()] so it 
11b20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64  does.** not need
11b30 20 74 6f 20 62 65 20 74 68 72 65 61 64 73 61 66   to be threadsaf
11b40 65 20 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61  e either.  For a
11b50 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73  ll other methods
11b60 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64  , SQLite.** hold
11b70 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55  s the [SQLITE_MU
11b80 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20  TEX_STATIC_MEM] 
11b90 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73  mutex as long as
11ba0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
11bb0 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
11bc0 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  ] configuration 
11bd0 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64  option is turned
11be0 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74   on (which.** it
11bf0 20 69 73 20 62 79 20 64 65 66 61 75 6c 74 29 20   is by default) 
11c00 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f  and so the metho
11c10 64 73 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63  ds are automatic
11c20 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e  ally serialized.
11c30 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20  .** However, if 
11c40 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
11c50 45 4d 53 54 41 54 55 53 5d 20 69 73 20 64 69 73  EMSTATUS] is dis
11c60 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20  abled, then the 
11c70 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73  other.** methods
11c80 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73   must be threads
11c90 61 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65  afe or else make
11ca0 20 74 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e   their own arran
11cb0 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73  gements for.** s
11cc0 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a  erialization..**
11cd0 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  .** SQLite will 
11ce0 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e  never invoke xIn
11cf0 69 74 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f  it() more than o
11d00 6e 63 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69  nce without an i
11d10 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61  ntervening.** ca
11d20 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28  ll to xShutdown(
11d30 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  )..*/.typedef st
11d40 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d  ruct sqlite3_mem
11d50 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33  _methods sqlite3
11d60 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74  _mem_methods;.st
11d70 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d  ruct sqlite3_mem
11d80 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69  _methods {.  voi
11d90 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e  d *(*xMalloc)(in
11da0 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d  t);         /* M
11db0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
11dc0 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76   function */.  v
11dd0 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69  oid (*xFree)(voi
11de0 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  d*);          /*
11df0 20 46 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c   Free a prior al
11e00 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f  location */.  vo
11e10 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28  id *(*xRealloc)(
11e20 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20  void*,int);  /* 
11e30 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61  Resize an alloca
11e40 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  tion */.  int (*
11e50 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20  xSize)(void*);  
11e60 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75           /* Retu
11e70 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61  rn the size of a
11e80 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a  n allocation */.
11e90 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70    int (*xRoundup
11ea0 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20  )(int);         
11eb0 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71   /* Round up req
11ec0 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c  uest size to all
11ed0 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a  ocation size */.
11ee0 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76    int (*xInit)(v
11ef0 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
11f00 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74   /* Initialize t
11f10 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
11f20 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a  tor */.  void (*
11f30 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a  xShutdown)(void*
11f40 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69  );      /* Deini
11f50 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f  tialize the memo
11f60 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a  ry allocator */.
11f70 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61    void *pAppData
11f80 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ;               
11f90 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20   /* Argument to 
11fa0 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75  xInit() and xShu
11fb0 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f  tdown() */.};../
11fc0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
11fd0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74  onfiguration Opt
11fe0 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ions.** KEYWORDS
11ff0 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  : {configuration
12000 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54   option}.**.** T
12010 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
12020 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65  re the available
12030 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75   integer configu
12040 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74  ration options t
12050 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61  hat.** can be pa
12060 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73  ssed as the firs
12070 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
12080 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e [sqlite3_confi
12090 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  g()] interface..
120a0 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67  **.** New config
120b0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
120c0 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
120d0 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
120e0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78  of SQLite..** Ex
120f0 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61  isting configura
12100 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67  tion options mig
12110 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75  ht be discontinu
12120 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  ed.  Application
12130 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63  s.** should chec
12140 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64  k the return cod
12150 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  e from [sqlite3_
12160 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b  config()] to mak
12170 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74  e sure that.** t
12180 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20  he call worked. 
12190 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
121a0 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
121b0 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a  e will return a.
121c0 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72  ** non-zero [err
121d0 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69  or code] if a di
121e0 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e  scontinued or un
121f0 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67  supported config
12200 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a  uration option.*
12210 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  * is invoked..**
12220 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51  .** <dl>.** [[SQ
12230 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
12240 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53  LETHREAD]] <dt>S
12250 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
12260 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a  GLETHREAD</dt>.*
12270 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
12280 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
12290 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54  this option.  ^T
122a0 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20  his option sets 
122b0 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e  the.** [threadin
122c0 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c  g mode] to Singl
122d0 65 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74  e-thread.  In ot
122e0 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69  her words, it di
122f0 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75  sables.** all mu
12300 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20  texing and puts 
12310 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f  SQLite into a mo
12320 64 65 20 77 68 65 72 65 20 69 74 20 63 61 6e 20  de where it can 
12330 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20  only be used.** 
12340 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65  by a single thre
12350 61 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65  ad.   ^If SQLite
12360 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
12370 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
12380 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
12390 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
123a0 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
123b0 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69  option then.** i
123c0 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c  t is not possibl
123d0 65 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  e to change the 
123e0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
123f0 20 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c   from its defaul
12400 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69  t.** value of Si
12410 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20  ngle-thread and 
12420 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  so [sqlite3_conf
12430 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ig()] will retur
12440 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52  n .** [SQLITE_ER
12450 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77  ROR] if called w
12460 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43  ith the SQLITE_C
12470 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
12480 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74  AD.** configurat
12490 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e  ion option.</dd>
124a0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
124b0 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
124c0 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  AD]] <dt>SQLITE_
124d0 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
124e0 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  AD</dt>.** <dd>T
124f0 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75  here are no argu
12500 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
12510 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74  tion.  ^This opt
12520 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
12530 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
12540 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64   to Multi-thread
12550 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
12560 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a  s, it disables.*
12570 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64  * mutexing on [d
12580 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
12590 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  on] and [prepare
125a0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a  d statement] obj
125b0 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70  ects..** The app
125c0 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70  lication is resp
125d0 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69  onsible for seri
125e0 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74  alizing access t
125f0 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  o.** [database c
12600 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20  onnections] and 
12610 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
12620 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65  ents].  But othe
12630 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65  r mutexes.** are
12640 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74   enabled so that
12650 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20   SQLite will be 
12660 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61  safe to use in a
12670 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a   multi-threaded.
12680 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61  ** environment a
12690 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f  s long as no two
126a0 20 74 68 72 65 61 64 73 20 61 74 74 65 6d 70 74   threads attempt
126b0 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65   to use the same
126c0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
126d0 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65  nnection] at the
126e0 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66   same time.  ^If
126f0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
12700 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
12710 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
12720 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
12730 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
12740 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
12750 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20  en.** it is not 
12760 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20  possible to set 
12770 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 64  the Multi-thread
12780 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
12790 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
127a0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c  3_config()] will
127b0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
127c0 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64  ERROR] if called
127d0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c   with the.** SQL
127e0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
127f0 54 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72 61  THREAD configura
12800 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64  tion option.</dd
12810 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
12820 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
12830 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ED]] <dt>SQLITE_
12840 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
12850 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
12860 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
12870 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
12880 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
12890 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
128a0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
128b0 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49  to Serialized. I
128c0 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
128d0 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c  his option enabl
128e0 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65  es.** all mutexe
128f0 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20  s including the 
12900 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74  recursive.** mut
12910 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73  exes on [databas
12920 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
12930 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
12940 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a  ement] objects..
12950 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20  ** In this mode 
12960 28 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65  (which is the de
12970 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74  fault when SQLit
12980 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
12990 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48  th.** [SQLITE_TH
129a0 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65  READSAFE=1]) the
129b0 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20   SQLite library 
129c0 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69  will itself seri
129d0 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20  alize access.** 
129e0 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  to [database con
129f0 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70  nections] and [p
12a00 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
12a10 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a  ts] so that the.
12a20 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  ** application i
12a30 73 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68  s free to use th
12a40 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
12a50 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20   connection] or 
12a60 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65  the.** same [pre
12a70 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
12a80 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68   in different th
12a90 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d  reads at the sam
12aa0 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53  e time..** ^If S
12ab0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
12ac0 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
12ad0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
12ae0 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
12af0 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
12b00 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
12b10 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f  .** it is not po
12b20 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68  ssible to set th
12b30 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e Serialized [th
12b40 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e  reading mode] an
12b50 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d.** [sqlite3_co
12b60 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
12b70 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
12b80 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74  R] if called wit
12b90 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f  h the.** SQLITE_
12ba0 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
12bb0 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  D configuration 
12bc0 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a  option.</dd>.**.
12bd0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
12be0 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e  IG_MALLOC]] <dt>
12bf0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
12c00 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LLOC</dt>.** <dd
12c10 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43  > ^(The SQLITE_C
12c20 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 6f 70 74  ONFIG_MALLOC opt
12c30 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
12c40 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
12c50 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74  h is .** a point
12c60 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
12c70 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
12c80 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73  3_mem_methods] s
12c90 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65  tructure..** The
12ca0 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66   argument specif
12cb0 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69  ies.** alternati
12cc0 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d  ve low-level mem
12cd0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
12ce0 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73  outines to be us
12cf0 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  ed in place of.*
12d00 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  * the memory all
12d10 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
12d20 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69   built into SQLi
12d30 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61  te.)^ ^SQLite ma
12d40 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70  kes.** its own p
12d50 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
12d60 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
12d70 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
12d80 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
12d90 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20  e.** before the 
12da0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
12db0 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e  )] call returns.
12dc0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
12dd0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
12de0 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49  ALLOC]] <dt>SQLI
12df0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
12e00 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOC</dt>.** <dd>
12e10 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
12e20 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 6f  NFIG_GETMALLOC o
12e30 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
12e40 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
12e50 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e  ich.** is a poin
12e60 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
12e70 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
12e80 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20  e3_mem_methods] 
12e90 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68  structure..** Th
12ea0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
12eb0 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63  ethods].** struc
12ec0 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77  ture is filled w
12ed0 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c  ith the currentl
12ee0 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79  y defined memory
12ef0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
12f00 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20  ines.)^.** This 
12f10 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  option can be us
12f20 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74  ed to overload t
12f30 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72  he default memor
12f40 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
12f50 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20  routines with a 
12f60 77 72 61 70 70 65 72 20 74 68 61 74 20 73 69 6d  wrapper that sim
12f70 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20  ulations memory 
12f80 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75  allocation failu
12f90 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20  re or.** tracks 
12fa0 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f  memory usage, fo
12fb0 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e  r example. </dd>
12fc0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
12fd0 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
12fe0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
12ff0 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f  NFIG_MEMSTATUS</
13000 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65  dt>.** <dd> ^The
13010 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
13020 45 4d 53 54 41 54 55 53 20 6f 70 74 69 6f 6e 20  EMSTATUS option 
13030 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67  takes single arg
13040 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e  ument of type in
13050 74 2c 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 65  t,.** interprete
13060 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 2c 20  d as a boolean, 
13070 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72  which enables or
13080 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 6f   disables the co
13090 6c 6c 65 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20 6d  llection of.** m
130a0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
130b0 20 73 74 61 74 69 73 74 69 63 73 2e 20 5e 28 57   statistics. ^(W
130c0 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  hen memory alloc
130d0 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73  ation statistics
130e0 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64   are.** disabled
130f0 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  , the following 
13100 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
13110 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65  s become non-ope
13120 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c  rational:.**   <
13130 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ul>.**   <li> [s
13140 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
13150 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20  ed()].**   <li> 
13160 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
13170 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20  highwater()].** 
13180 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
13190 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36  soft_heap_limit6
131a0 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  4()].**   <li> [
131b0 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 36 34  sqlite3_status64
131c0 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e  ()].**   </ul>)^
131d0 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f  .** ^Memory allo
131e0 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
131f0 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79  s are enabled by
13200 20 64 65 66 61 75 6c 74 20 75 6e 6c 65 73 73 20   default unless 
13210 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d  SQLite is.** com
13220 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49  piled with [SQLI
13230 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54  TE_DEFAULT_MEMST
13240 41 54 55 53 5d 3d 30 20 69 6e 20 77 68 69 63 68  ATUS]=0 in which
13250 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20   case memory.** 
13260 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
13270 73 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c  stics are disabl
13280 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  ed by default..*
13290 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  * </dd>.**.** [[
132a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
132b0 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49  RATCH]] <dt>SQLI
132c0 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
132d0 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  H</dt>.** <dd> ^
132e0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
132f0 47 5f 53 43 52 41 54 43 48 20 6f 70 74 69 6f 6e  G_SCRATCH option
13300 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61   specifies a sta
13310 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  tic memory buffe
13320 72 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65  r.** that SQLite
13330 20 63 61 6e 20 75 73 65 20 66 6f 72 20 73 63 72   can use for scr
13340 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 5e 28  atch memory.  ^(
13350 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20  There are three 
13360 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 74 6f 20  arguments.** to 
13370 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
13380 52 41 54 43 48 3a 20 20 41 20 70 6f 69 6e 74 65  RATCH:  A pointe
13390 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61  r an 8-byte.** a
133a0 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75  ligned memory bu
133b0 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20  ffer from which 
133c0 74 68 65 20 73 63 72 61 74 63 68 20 61 6c 6c 6f  the scratch allo
133d0 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a  cations will be.
133e0 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69  ** drawn, the si
133f0 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72 61 74  ze of each scrat
13400 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73  ch allocation (s
13410 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d  z),.** and the m
13420 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
13430 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
13440 69 6f 6e 73 20 28 4e 29 2e 29 5e 0a 2a 2a 20 54  ions (N).)^.** T
13450 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
13460 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f 69 6e  t must be a poin
13470 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ter to an 8-byte
13480 20 61 6c 69 67 6e 65 64 20 62 75 66 66 65 72 0a   aligned buffer.
13490 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73  ** of at least s
134a0 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d  z*N bytes of mem
134b0 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ory..** ^SQLite 
134c0 77 69 6c 6c 20 6e 6f 74 20 75 73 65 20 6d 6f 72  will not use mor
134d0 65 20 74 68 61 6e 20 6f 6e 65 20 73 63 72 61 74  e than one scrat
134e0 63 68 20 62 75 66 66 65 72 73 20 70 65 72 20 74  ch buffers per t
134f0 68 72 65 61 64 2e 0a 2a 2a 20 5e 53 51 4c 69 74  hread..** ^SQLit
13500 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 72 65 71  e will never req
13510 75 65 73 74 20 61 20 73 63 72 61 74 63 68 20 62  uest a scratch b
13520 75 66 66 65 72 20 74 68 61 74 20 69 73 20 6d 6f  uffer that is mo
13530 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d  re than 6.** tim
13540 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
13550 70 61 67 65 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49  page size..** ^I
13560 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73 20 6e  f SQLite needs n
13570 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a  eeds additional.
13580 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72  ** scratch memor
13590 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73  y beyond what is
135a0 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69   provided by thi
135b0 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  s configuration 
135c0 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a  option, then .**
135d0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
135e0 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 64  ()] will be used
135f0 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d   to obtain the m
13600 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c 70 3e  emory needed.<p>
13610 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 61 70  .** ^When the ap
13620 70 6c 69 63 61 74 69 6f 6e 20 70 72 6f 76 69 64  plication provid
13630 65 73 20 61 6e 79 20 61 6d 6f 75 6e 74 20 6f 66  es any amount of
13640 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20   scratch memory 
13650 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 49 54 45 5f  using.** SQLITE_
13660 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 2c 20  CONFIG_SCRATCH, 
13670 53 51 4c 69 74 65 20 61 76 6f 69 64 73 20 75 6e  SQLite avoids un
13680 6e 65 63 65 73 73 61 72 79 20 6c 61 72 67 65 0a  necessary large.
13690 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
136a0 6f 63 7c 68 65 61 70 20 61 6c 6c 6f 63 61 74 69  oc|heap allocati
136b0 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 69 73 20 63 61  ons]..** This ca
136c0 6e 20 68 65 6c 70 20 5b 52 6f 62 73 6f 6e 20 70  n help [Robson p
136d0 72 6f 6f 66 7c 70 72 65 76 65 6e 74 20 6d 65 6d  roof|prevent mem
136e0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
136f0 61 69 6c 75 72 65 73 5d 20 64 75 65 20 74 6f 20  ailures] due to 
13700 68 65 61 70 0a 2a 2a 20 66 72 61 67 6d 65 6e 74  heap.** fragment
13710 61 74 69 6f 6e 20 69 6e 20 6c 6f 77 2d 6d 65 6d  ation in low-mem
13720 6f 72 79 20 65 6d 62 65 64 64 65 64 20 73 79 73  ory embedded sys
13730 74 65 6d 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a  tems..** </dd>.*
13740 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
13750 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 5d  NFIG_PAGECACHE]]
13760 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
13770 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74  IG_PAGECACHE</dt
13780 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53  >.** <dd> ^The S
13790 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
137a0 45 43 41 43 48 45 20 6f 70 74 69 6f 6e 20 73 70  ECACHE option sp
137b0 65 63 69 66 69 65 73 20 61 20 6d 65 6d 6f 72 79  ecifies a memory
137c0 20 70 6f 6f 6c 0a 2a 2a 20 74 68 61 74 20 53 51   pool.** that SQ
137d0 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72  Lite can use for
137e0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61   the database pa
137f0 67 65 20 63 61 63 68 65 20 77 69 74 68 20 74 68  ge cache with th
13800 65 20 64 65 66 61 75 6c 74 20 70 61 67 65 0a 2a  e default page.*
13810 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  * cache implemen
13820 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69  tation.  .** Thi
13830 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  s configuration 
13840 6f 70 74 69 6f 6e 20 69 73 20 61 20 6e 6f 2d 6f  option is a no-o
13850 70 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74  p if an applicat
13860 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67 65 0a  ion-define page.
13870 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65  ** cache impleme
13880 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65  ntation is loade
13890 64 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c  d using the [SQL
138a0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
138b0 45 32 5d 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 61  E2]..** ^There a
138c0 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e  re three argumen
138d0 74 73 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e  ts to SQLITE_CON
138e0 46 49 47 5f 50 41 47 45 43 41 43 48 45 3a 20 41  FIG_PAGECACHE: A
138f0 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 38   pointer to.** 8
13900 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 6d 65  -byte aligned me
13910 6d 6f 72 79 20 28 70 4d 65 6d 29 2c 20 74 68 65  mory (pMem), the
13920 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61   size of each pa
13930 67 65 20 63 61 63 68 65 20 6c 69 6e 65 20 28 73  ge cache line (s
13940 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6e  z),.** and the n
13950 75 6d 62 65 72 20 6f 66 20 63 61 63 68 65 20 6c  umber of cache l
13960 69 6e 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65  ines (N)..** The
13970 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f   sz argument sho
13980 75 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65 20  uld be the size 
13990 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 64  of the largest d
139a0 61 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20  atabase page.** 
139b0 28 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20  (a power of two 
139c0 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20  between 512 and 
139d0 36 35 35 33 36 29 20 70 6c 75 73 20 73 6f 6d 65  65536) plus some
139e0 20 65 78 74 72 61 20 62 79 74 65 73 20 66 6f 72   extra bytes for
139f0 20 65 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65   each.** page he
13a00 61 64 65 72 2e 20 20 5e 54 68 65 20 6e 75 6d 62  ader.  ^The numb
13a10 65 72 20 6f 66 20 65 78 74 72 61 20 62 79 74 65  er of extra byte
13a20 73 20 6e 65 65 64 65 64 20 62 79 20 74 68 65 20  s needed by the 
13a30 70 61 67 65 20 68 65 61 64 65 72 0a 2a 2a 20 63  page header.** c
13a40 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64  an be determined
13a50 20 75 73 69 6e 67 20 5b 53 51 4c 49 54 45 5f 43   using [SQLITE_C
13a60 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52  ONFIG_PCACHE_HDR
13a70 53 5a 5d 2e 0a 2a 2a 20 5e 49 74 20 69 73 20 68  SZ]..** ^It is h
13a80 61 72 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 66  armless, apart f
13a90 72 6f 6d 20 74 68 65 20 77 61 73 74 65 64 20 6d  rom the wasted m
13aa0 65 6d 6f 72 79 2c 0a 2a 2a 20 66 6f 72 20 74 68  emory,.** for th
13ab0 65 20 73 7a 20 70 61 72 61 6d 65 74 65 72 20 74  e sz parameter t
13ac0 6f 20 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e  o be larger than
13ad0 20 6e 65 63 65 73 73 61 72 79 2e 20 20 54 68 65   necessary.  The
13ae0 20 70 4d 65 6d 0a 2a 2a 20 61 72 67 75 6d 65 6e   pMem.** argumen
13af0 74 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72  t must be either
13b00 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
13b10 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  or a pointer to 
13b20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69  an 8-byte.** ali
13b30 67 6e 65 64 20 62 6c 6f 63 6b 20 6f 66 20 6d 65  gned block of me
13b40 6d 6f 72 79 20 6f 66 20 61 74 20 6c 65 61 73 74  mory of at least
13b50 20 73 7a 2a 4e 20 62 79 74 65 73 2c 20 6f 74 68   sz*N bytes, oth
13b60 65 72 77 69 73 65 0a 2a 2a 20 73 75 62 73 65 71  erwise.** subseq
13b70 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 69 73  uent behavior is
13b80 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e   undefined..** ^
13b90 57 68 65 6e 20 70 4d 65 6d 20 69 73 20 6e 6f 74  When pMem is not
13ba0 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69   NULL, SQLite wi
13bb0 6c 6c 20 73 74 72 69 76 65 20 74 6f 20 75 73 65  ll strive to use
13bc0 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76   the memory prov
13bd0 69 64 65 64 0a 2a 2a 20 74 6f 20 73 61 74 69 73  ided.** to satis
13be0 66 79 20 70 61 67 65 20 63 61 63 68 65 20 6e 65  fy page cache ne
13bf0 65 64 73 2c 20 66 61 6c 6c 69 6e 67 20 62 61 63  eds, falling bac
13c00 6b 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61  k to [sqlite3_ma
13c10 6c 6c 6f 63 28 29 5d 20 69 66 0a 2a 2a 20 61 20  lloc()] if.** a 
13c20 70 61 67 65 20 63 61 63 68 65 20 6c 69 6e 65 20  page cache line 
13c30 69 73 20 6c 61 72 67 65 72 20 74 68 61 6e 20 73  is larger than s
13c40 7a 20 62 79 74 65 73 20 6f 72 20 69 66 20 61 6c  z bytes or if al
13c50 6c 20 6f 66 20 74 68 65 20 70 4d 65 6d 20 62 75  l of the pMem bu
13c60 66 66 65 72 0a 2a 2a 20 69 73 20 65 78 68 61 75  ffer.** is exhau
13c70 73 74 65 64 2e 0a 2a 2a 20 5e 49 66 20 70 4d 65  sted..** ^If pMe
13c80 6d 20 69 73 20 4e 55 4c 4c 20 61 6e 64 20 4e 20  m is NULL and N 
13c90 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  is non-zero, the
13ca0 6e 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  n each database 
13cb0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 64 6f  connection.** do
13cc0 65 73 20 61 6e 20 69 6e 69 74 69 61 6c 20 62 75  es an initial bu
13cd0 6c 6b 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f  lk allocation fo
13ce0 72 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d  r page cache mem
13cf0 6f 72 79 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ory.** from [sql
13d00 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 73  ite3_malloc()] s
13d10 75 66 66 69 63 69 65 6e 74 20 66 6f 72 20 4e 20  ufficient for N 
13d20 63 61 63 68 65 20 6c 69 6e 65 73 20 69 66 20 4e  cache lines if N
13d30 20 69 73 20 70 6f 73 69 74 69 76 65 20 6f 72 0a   is positive or.
13d40 2a 2a 20 6f 66 20 2d 31 30 32 34 2a 4e 20 62 79  ** of -1024*N by
13d50 74 65 73 20 69 66 20 4e 20 69 73 20 6e 65 67 61  tes if N is nega
13d60 74 69 76 65 2c 20 2e 20 5e 49 66 20 61 64 64 69  tive, . ^If addi
13d70 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63  tional.** page c
13d80 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e  ache memory is n
13d90 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61  eeded beyond wha
13da0 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79  t is provided by
13db0 20 74 68 65 20 69 6e 69 74 69 61 6c 0a 2a 2a 20   the initial.** 
13dc0 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e  allocation, then
13dd0 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20   SQLite goes to 
13de0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
13df0 29 5d 20 73 65 70 61 72 61 74 65 6c 79 20 66 6f  )] separately fo
13e00 72 20 65 61 63 68 0a 2a 2a 20 61 64 64 69 74 69  r each.** additi
13e10 6f 6e 61 6c 20 63 61 63 68 65 20 6c 69 6e 65 2e  onal cache line.
13e20 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
13e30 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
13e40 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  P]] <dt>SQLITE_C
13e50 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a  ONFIG_HEAP</dt>.
13e60 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c  ** <dd> ^The SQL
13e70 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20  ITE_CONFIG_HEAP 
13e80 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73  option specifies
13e90 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79   a static memory
13ea0 20 62 75 66 66 65 72 20 0a 2a 2a 20 74 68 61 74   buffer .** that
13eb0 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65   SQLite will use
13ec0 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20   for all of its 
13ed0 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61  dynamic memory a
13ee0 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 0a  llocation needs.
13ef0 2a 2a 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20  ** beyond those 
13f00 70 72 6f 76 69 64 65 64 20 66 6f 72 20 62 79 20  provided for by 
13f10 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
13f20 43 52 41 54 43 48 5d 20 61 6e 64 0a 2a 2a 20 5b  CRATCH] and.** [
13f30 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
13f40 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 5e 54 68  GECACHE]..** ^Th
13f50 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
13f60 48 45 41 50 20 6f 70 74 69 6f 6e 20 69 73 20 6f  HEAP option is o
13f70 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
13f80 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
13f90 6c 65 64 0a 2a 2a 20 77 69 74 68 20 65 69 74 68  led.** with eith
13fa0 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  er [SQLITE_ENABL
13fb0 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 20 5b 53  E_MEMSYS3] or [S
13fc0 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
13fd0 53 59 53 35 5d 20 61 6e 64 20 72 65 74 75 72 6e  SYS5] and return
13fe0 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52  s.** [SQLITE_ERR
13ff0 4f 52 5d 20 69 66 20 69 6e 76 6f 6b 65 64 20 6f  OR] if invoked o
14000 74 68 65 72 77 69 73 65 2e 0a 2a 2a 20 5e 54 68  therwise..** ^Th
14010 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
14020 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54  guments to SQLIT
14030 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3a 0a 2a  E_CONFIG_HEAP:.*
14040 2a 20 41 6e 20 38 2d 62 79 74 65 20 61 6c 69 67  * An 8-byte alig
14050 6e 65 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  ned pointer to t
14060 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68  he memory,.** th
14070 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
14080 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20  s in the memory 
14090 62 75 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20  buffer, and the 
140a0 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69  minimum allocati
140b0 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20  on size..** ^If 
140c0 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65  the first pointe
140d0 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f  r (the memory po
140e0 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20  inter) is NULL, 
140f0 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65  then SQLite reve
14100 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20  rts.** to using 
14110 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f  its default memo
14120 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68  ry allocator (th
14130 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28  e system malloc(
14140 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  ) implementation
14150 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e  ),.** undoing an
14160 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69  y prior invocati
14170 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f  on of [SQLITE_CO
14180 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e  NFIG_MALLOC].  ^
14190 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79  If the.** memory
141a0 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
141b0 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 61 6c  NULL then the al
141c0 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79  ternative memory
141d0 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73  .** allocator is
141e0 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64   engaged to hand
141f0 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65  le all of SQLite
14200 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  s memory allocat
14210 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68  ion needs..** Th
14220 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20  e first pointer 
14230 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  (the memory poin
14240 74 65 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69  ter) must be ali
14250 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74  gned to an 8-byt
14260 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72  e.** boundary or
14270 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61   subsequent beha
14280 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77  vior of SQLite w
14290 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64  ill be undefined
142a0 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d  ..** The minimum
142b0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
142c0 20 69 73 20 63 61 70 70 65 64 20 61 74 20 32 2a   is capped at 2*
142d0 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20  *12. Reasonable 
142e0 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68  values.** for th
142f0 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61  e minimum alloca
14300 74 69 6f 6e 20 73 69 7a 65 20 61 72 65 20 32 2a  tion size are 2*
14310 2a 35 20 74 68 72 6f 75 67 68 20 32 2a 2a 38 2e  *5 through 2**8.
14320 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
14330 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
14340 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  X]] <dt>SQLITE_C
14350 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e  ONFIG_MUTEX</dt>
14360 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
14370 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
14380 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  EX option takes 
14390 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
143a0 74 20 77 68 69 63 68 20 69 73 20 61 0a 2a 2a 20  t which is a.** 
143b0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
143c0 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
143d0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
143e0 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
143f0 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74  .** The argument
14400 20 73 70 65 63 69 66 69 65 73 20 61 6c 74 65 72   specifies alter
14410 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c  native low-level
14420 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20   mutex routines 
14430 74 6f 20 62 65 20 75 73 65 64 0a 2a 2a 20 69 6e  to be used.** in
14440 20 70 6c 61 63 65 20 74 68 65 20 6d 75 74 65 78   place the mutex
14450 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20   routines built 
14460 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20  into SQLite.)^  
14470 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20  ^SQLite makes a 
14480 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63  copy of.** the c
14490 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73  ontent of the [s
144a0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
144b0 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 20  hods] structure 
144c0 62 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20  before the call 
144d0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
144e0 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73  onfig()] returns
144f0 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20  . ^If SQLite is 
14500 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
14510 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
14520 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
14530 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
14540 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
14550 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65  on then.** the e
14560 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73  ntire mutexing s
14570 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74  ubsystem is omit
14580 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69  ted from the bui
14590 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c  ld and hence cal
145a0 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ls to.** [sqlite
145b0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68  3_config()] with
145c0 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
145d0 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75  IG_MUTEX configu
145e0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69  ration option wi
145f0 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ll.** return [SQ
14600 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64  LITE_ERROR].</dd
14610 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
14620 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
14630 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
14640 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64  NFIG_GETMUTEX</d
14650 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
14660 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
14670 45 54 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74  ETMUTEX option t
14680 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
14690 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20  gument which.** 
146a0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
146b0 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
146c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
146d0 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
146e0 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73  ture.  The.** [s
146f0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
14700 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75  hods].** structu
14710 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74  re is filled wit
14720 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20  h the currently 
14730 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f  defined mutex ro
14740 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69  utines.)^.** Thi
14750 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  s option can be 
14760 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64  used to overload
14770 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74   the default mut
14780 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ex allocation.**
14790 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61   routines with a
147a0 20 77 72 61 70 70 65 72 20 75 73 65 64 20 74 6f   wrapper used to
147b0 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61   track mutex usa
147c0 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e  ge for performan
147d0 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20  ce.** profiling 
147e0 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20  or testing, for 
147f0 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53  example.   ^If S
14800 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
14810 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
14820 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
14830 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
14840 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
14850 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
14860 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d  .** the entire m
14870 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65  utexing subsyste
14880 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  m is omitted fro
14890 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20  m the build and 
148a0 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a  hence calls to.*
148b0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
148c0 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51  g()] with the SQ
148d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
148e0 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69  UTEX configurati
148f0 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a  on option will.*
14900 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
14910 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a  _ERROR].</dd>.**
14920 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
14930 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20  FIG_LOOKASIDE]] 
14940 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
14950 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e  G_LOOKASIDE</dt>
14960 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
14970 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
14980 4b 41 53 49 44 45 20 6f 70 74 69 6f 6e 20 74 61  KASIDE option ta
14990 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  kes two argument
149a0 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  s that determine
149b0 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 20  .** the default 
149c0 73 69 7a 65 20 6f 66 20 6c 6f 6f 6b 61 73 69 64  size of lookasid
149d0 65 20 6d 65 6d 6f 72 79 20 6f 6e 20 65 61 63 68  e memory on each
149e0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
149f0 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66  ction]..** The f
14a00 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
14a10 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20   the.** size of 
14a20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62  each lookaside b
14a30 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74  uffer slot and t
14a40 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65  he second is the
14a50 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c   number of.** sl
14a60 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f  ots allocated to
14a70 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63   each database c
14a80 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28  onnection.)^  ^(
14a90 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
14aa0 4f 4b 41 53 49 44 45 0a 2a 2a 20 73 65 74 73 20  OKASIDE.** sets 
14ab0 74 68 65 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f  the <i>default</
14ac0 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a  i> lookaside siz
14ad0 65 2e 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 44  e. The [SQLITE_D
14ae0 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
14af0 45 5d 0a 2a 2a 20 6f 70 74 69 6f 6e 20 74 6f 20  E].** option to 
14b00 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
14b10 69 67 28 29 5d 20 63 61 6e 20 62 65 20 75 73 65  ig()] can be use
14b20 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  d to change the 
14b30 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e  lookaside.** con
14b40 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e  figuration on in
14b50 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74  dividual connect
14b60 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a  ions.)^ </dd>.**
14b70 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
14b80 46 49 47 5f 50 43 41 43 48 45 32 5d 5d 20 3c 64  FIG_PCACHE2]] <d
14b90 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
14ba0 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20  PCACHE2</dt>.** 
14bb0 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54  <dd> ^(The SQLIT
14bc0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32  E_CONFIG_PCACHE2
14bd0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
14be0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
14bf0 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 61 20 70  which is .** a p
14c00 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71  ointer to an [sq
14c10 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
14c20 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20  hods2] object.  
14c30 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63  This object spec
14c40 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 69 6e 74  ifies.** the int
14c50 65 72 66 61 63 65 20 74 6f 20 61 20 63 75 73 74  erface to a cust
14c60 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  om page cache im
14c70 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 0a  plementation.)^.
14c80 2a 2a 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73  ** ^SQLite makes
14c90 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b   a copy of the [
14ca0 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
14cb0 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e  ethods2] object.
14cc0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
14cd0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
14ce0 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c  CACHE2]] <dt>SQL
14cf0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
14d00 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ACHE2</dt>.** <d
14d10 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  d> ^(The SQLITE_
14d20 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
14d30 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  2 option takes a
14d40 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
14d50 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70   which.** is a p
14d60 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71  ointer to an [sq
14d70 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
14d80 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20  hods2] object.  
14d90 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66  SQLite copies of
14da0 0a 2a 2a 20 74 68 65 20 63 75 72 72 65 6e 74 20  .** the current 
14db0 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65  page cache imple
14dc0 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74  mentation into t
14dd0 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f  hat object.)^ </
14de0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
14df0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20  TE_CONFIG_LOG]] 
14e00 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
14e10 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  G_LOG</dt>.** <d
14e20 64 3e 20 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  d> The SQLITE_CO
14e30 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20  NFIG_LOG option 
14e40 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69  is used to confi
14e50 67 75 72 65 20 74 68 65 20 53 51 4c 69 74 65 0a  gure the SQLite.
14e60 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65 72 72 6f 72  ** global [error
14e70 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 68 65 20   log]..** (^The 
14e80 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
14e90 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74  G option takes t
14ea0 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 20  wo arguments: a 
14eb0 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20  pointer to a.** 
14ec0 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20  function with a 
14ed0 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 6f  call signature o
14ee0 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c  f void(*)(void*,
14ef0 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  int,const char*)
14f00 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e  , .** and a poin
14f10 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66  ter to void. ^If
14f20 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f   the function po
14f30 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c  inter is not NUL
14f40 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f  L, it is.** invo
14f50 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ked by [sqlite3_
14f60 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 73  log()] to proces
14f70 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 65  s each logging e
14f80 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a  vent.  ^If the.*
14f90 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74  * function point
14fa0 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20  er is NULL, the 
14fb0 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20  [sqlite3_log()] 
14fc0 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f 6d 65  interface become
14fd0 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54  s a no-op..** ^T
14fe0 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20  he void pointer 
14ff0 74 68 61 74 20 69 73 20 74 68 65 20 73 65 63 6f  that is the seco
15000 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 53  nd argument to S
15010 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
15020 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68   is.** passed th
15030 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72  rough as the fir
15040 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
15050 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
15060 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a  defined logger.*
15070 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65  * function whene
15080 76 65 72 20 74 68 61 74 20 66 75 6e 63 74 69 6f  ver that functio
15090 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e  n is invoked.  ^
150a0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
150b0 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c  eter to.** the l
150c0 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 69  ogger function i
150d0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
150e0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
150f0 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  to the correspon
15100 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ding.** [sqlite3
15110 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64  _log()] call and
15120 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20   is intended to 
15130 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64  be a [result cod
15140 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74  e] or an.** [ext
15150 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
15160 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20  e].  ^The third 
15170 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64  parameter passed
15180 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 69   to the logger i
15190 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65  s.** log message
151a0 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74 69 6e   after formattin
151b0 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 73  g via [sqlite3_s
151c0 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54  nprintf()]..** T
151d0 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e  he SQLite loggin
151e0 67 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  g interface is n
151f0 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 68  ot reentrant; th
15200 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f  e logger functio
15210 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 79  n.** supplied by
15220 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
15230 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65   must not invoke
15240 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65   any SQLite inte
15250 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d  rface..** In a m
15260 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61 70  ulti-threaded ap
15270 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 61  plication, the a
15280 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
15290 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e  ed logger.** fun
152a0 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 68  ction must be th
152b0 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a  readsafe. </dd>.
152c0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
152d0 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e  ONFIG_URI]] <dt>
152e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
152f0 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 65 20 53  I.** <dd>^(The S
15300 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
15310 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
15320 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
15330 6f 66 20 74 79 70 65 20 69 6e 74 2e 0a 2a 2a 20  of type int..** 
15340 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  If non-zero, the
15350 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  n URI handling i
15360 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c  s globally enabl
15370 65 64 2e 20 49 66 20 74 68 65 20 70 61 72 61 6d  ed. If the param
15380 65 74 65 72 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a  eter is zero,.**
15390 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69   then URI handli
153a0 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64  ng is globally d
153b0 69 73 61 62 6c 65 64 2e 29 5e 20 5e 49 66 20 55  isabled.)^ ^If U
153c0 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67  RI handling is g
153d0 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 65 6e 61 62 6c  lobally.** enabl
153e0 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65  ed, all filename
153f0 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c  s passed to [sql
15400 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
15410 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
15420 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f  ],.** [sqlite3_o
15430 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73  pen16()] or.** s
15440 70 65 63 69 66 69 65 64 20 61 73 20 70 61 72 74  pecified as part
15450 20 6f 66 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d   of [ATTACH] com
15460 6d 61 6e 64 73 20 61 72 65 20 69 6e 74 65 72 70  mands are interp
15470 72 65 74 65 64 20 61 73 20 55 52 49 73 2c 20 72  reted as URIs, r
15480 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20  egardless.** of 
15490 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
154a0 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
154b0 55 52 49 5d 20 66 6c 61 67 20 69 73 20 73 65 74  URI] flag is set
154c0 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   when the databa
154d0 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
154e0 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 49 66 20   is opened. ^If 
154f0 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64  it is globally d
15500 69 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d  isabled, filenam
15510 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69  es are.** only i
15520 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52  nterpreted as UR
15530 49 73 20 69 66 20 74 68 65 20 53 51 4c 49 54 45  Is if the SQLITE
15540 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67 20 69  _OPEN_URI flag i
15550 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 0a 2a  s set when the.*
15560 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
15570 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e  ction is opened.
15580 20 5e 28 42 79 20 64 65 66 61 75 6c 74 2c 20 55   ^(By default, U
15590 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67  RI handling is g
155a0 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62  lobally.** disab
155b0 6c 65 64 2e 20 54 68 65 20 64 65 66 61 75 6c 74  led. The default
155c0 20 76 61 6c 75 65 20 6d 61 79 20 62 65 20 63 68   value may be ch
155d0 61 6e 67 65 64 20 62 79 20 63 6f 6d 70 69 6c 69  anged by compili
155e0 6e 67 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  ng with the.** [
155f0 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20  SQLITE_USE_URI] 
15600 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 29  symbol defined.)
15610 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
15620 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47  _CONFIG_COVERING
15630 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 5d 20 3c 64  _INDEX_SCAN]] <d
15640 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
15650 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53  COVERING_INDEX_S
15660 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20  CAN.** <dd>^The 
15670 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f  SQLITE_CONFIG_CO
15680 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
15690 4e 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  N option takes a
156a0 20 73 69 6e 67 6c 65 20 69 6e 74 65 67 65 72 0a   single integer.
156b0 2a 2a 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  ** argument whic
156c0 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  h is interpreted
156d0 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e   as a boolean in
156e0 20 6f 72 64 65 72 20 74 6f 20 65 6e 61 62 6c 65   order to enable
156f0 20 6f 72 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74   or disable.** t
15700 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69  he use of coveri
15710 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20 66  ng indices for f
15720 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 20  ull table scans 
15730 69 6e 20 74 68 65 20 71 75 65 72 79 20 6f 70 74  in the query opt
15740 69 6d 69 7a 65 72 2e 0a 2a 2a 20 5e 54 68 65 20  imizer..** ^The 
15750 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20  default setting 
15760 69 73 20 64 65 74 65 72 6d 69 6e 65 64 0a 2a 2a  is determined.**
15770 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   by the [SQLITE_
15780 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e 47 5f 49  ALLOW_COVERING_I
15790 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f 6d 70 69  NDEX_SCAN] compi
157a0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20  le-time option, 
157b0 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a 20 69 66  or is "on".** if
157c0 20 74 68 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69   that compile-ti
157d0 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6d 69  me option is omi
157e0 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20 61 62 69  tted..** The abi
157f0 6c 69 74 79 20 74 6f 20 64 69 73 61 62 6c 65 20  lity to disable 
15800 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72  the use of cover
15810 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20  ing indices for 
15820 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73  full table scans
15830 0a 2a 2a 20 69 73 20 62 65 63 61 75 73 65 20 73  .** is because s
15840 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74 6c 79 20  ome incorrectly 
15850 63 6f 64 65 64 20 6c 65 67 61 63 79 20 61 70 70  coded legacy app
15860 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67 68 74 20  lications might 
15870 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77  malfunction.** w
15880 68 65 6e 20 74 68 65 20 6f 70 74 69 6d 69 7a 61  hen the optimiza
15890 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e  tion is enabled.
158a0 20 20 50 72 6f 76 69 64 69 6e 67 20 74 68 65 20    Providing the 
158b0 61 62 69 6c 69 74 79 20 74 6f 0a 2a 2a 20 64 69  ability to.** di
158c0 73 61 62 6c 65 20 74 68 65 20 6f 70 74 69 6d 69  sable the optimi
158d0 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 74 68  zation allows th
158e0 65 20 6f 6c 64 65 72 2c 20 62 75 67 67 79 20 61  e older, buggy a
158f0 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20  pplication code 
15900 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f  to work.** witho
15910 75 74 20 63 68 61 6e 67 65 20 65 76 65 6e 20 77  ut change even w
15920 69 74 68 20 6e 65 77 65 72 20 76 65 72 73 69 6f  ith newer versio
15930 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  ns of SQLite..**
15940 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
15950 46 49 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53  FIG_PCACHE]] [[S
15960 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
15970 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e  PCACHE]].** <dt>
15980 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
15990 41 43 48 45 20 61 6e 64 20 53 51 4c 49 54 45 5f  ACHE and SQLITE_
159a0 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
159b0 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73 65 20 6f  .** <dd> These o
159c0 70 74 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c  ptions are obsol
159d0 65 74 65 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e  ete and should n
159e0 6f 74 20 62 65 20 75 73 65 64 20 62 79 20 6e 65  ot be used by ne
159f0 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20  w code..** They 
15a00 61 72 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72  are retained for
15a10 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
15a20 74 69 62 69 6c 69 74 79 20 62 75 74 20 61 72 65  tibility but are
15a30 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20   now no-ops..** 
15a40 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
15a50 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c  LITE_CONFIG_SQLL
15a60 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  OG]].** <dt>SQLI
15a70 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47  TE_CONFIG_SQLLOG
15a80 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74  .** <dd>This opt
15a90 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69  ion is only avai
15aa0 6c 61 62 6c 65 20 69 66 20 73 71 6c 69 74 65 20  lable if sqlite 
15ab0 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
15ac0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
15ad0 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70  ENABLE_SQLLOG] p
15ae0 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  re-processor mac
15af0 72 6f 20 64 65 66 69 6e 65 64 2e 20 54 68 65 20  ro defined. The 
15b00 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 73  first argument s
15b10 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 61 20 70 6f  hould.** be a po
15b20 69 6e 74 65 72 20 74 6f 20 61 20 66 75 6e 63 74  inter to a funct
15b30 69 6f 6e 20 6f 66 20 74 79 70 65 20 76 6f 69 64  ion of type void
15b40 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65  (*)(void*,sqlite
15b50 33 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  3*,const char*, 
15b60 69 6e 74 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63  int)..** The sec
15b70 6f 6e 64 20 73 68 6f 75 6c 64 20 62 65 20 6f 66  ond should be of
15b80 20 74 79 70 65 20 28 76 6f 69 64 2a 29 2e 20 54   type (void*). T
15b90 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  he callback is i
15ba0 6e 76 6f 6b 65 64 20 62 79 20 74 68 65 20 6c 69  nvoked by the li
15bb0 62 72 61 72 79 0a 2a 2a 20 69 6e 20 74 68 72 65  brary.** in thre
15bc0 65 20 73 65 70 61 72 61 74 65 20 63 69 72 63 75  e separate circu
15bd0 6d 73 74 61 6e 63 65 73 2c 20 69 64 65 6e 74 69  mstances, identi
15be0 66 69 65 64 20 62 79 20 74 68 65 20 76 61 6c 75  fied by the valu
15bf0 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 0a  e passed as the.
15c00 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  ** fourth parame
15c10 74 65 72 2e 20 49 66 20 74 68 65 20 66 6f 75 72  ter. If the four
15c20 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
15c30 30 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  0, then the data
15c40 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
15c50 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ** passed as the
15c60 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
15c70 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 6f   has just been o
15c80 70 65 6e 65 64 2e 20 54 68 65 20 74 68 69 72 64  pened. The third
15c90 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69   argument.** poi
15ca0 6e 74 73 20 74 6f 20 61 20 62 75 66 66 65 72 20  nts to a buffer 
15cb0 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e  containing the n
15cc0 61 6d 65 20 6f 66 20 74 68 65 20 6d 61 69 6e 20  ame of the main 
15cd0 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20 49  database file. I
15ce0 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20  f the.** fourth 
15cf0 70 61 72 61 6d 65 74 65 72 20 69 73 20 31 2c 20  parameter is 1, 
15d00 74 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61  then the SQL sta
15d10 74 65 6d 65 6e 74 20 74 68 61 74 20 74 68 65 20  tement that the 
15d20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 0a  third parameter.
15d30 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 68 61 73  ** points to has
15d40 20 6a 75 73 74 20 62 65 65 6e 20 65 78 65 63 75   just been execu
15d50 74 65 64 2e 20 4f 72 2c 20 69 66 20 74 68 65 20  ted. Or, if the 
15d60 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
15d70 20 69 73 20 32 2c 20 74 68 65 6e 0a 2a 2a 20 74   is 2, then.** t
15d80 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65  he connection be
15d90 69 6e 67 20 70 61 73 73 65 64 20 61 73 20 74 68  ing passed as th
15da0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
15db0 65 72 20 69 73 20 62 65 69 6e 67 20 63 6c 6f 73  er is being clos
15dc0 65 64 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64  ed. The.** third
15dd0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 61   parameter is pa
15de0 73 73 65 64 20 4e 55 4c 4c 20 49 6e 20 74 68 69  ssed NULL In thi
15df0 73 20 63 61 73 65 2e 20 20 41 6e 20 65 78 61 6d  s case.  An exam
15e00 70 6c 65 20 6f 66 20 75 73 69 6e 67 20 74 68 69  ple of using thi
15e10 73 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  s.** configurati
15e20 6f 6e 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65  on option can be
15e30 20 73 65 65 6e 20 69 6e 20 74 68 65 20 22 74 65   seen in the "te
15e40 73 74 5f 73 71 6c 6c 6f 67 2e 63 22 20 73 6f 75  st_sqllog.c" sou
15e50 72 63 65 20 66 69 6c 65 20 69 6e 0a 2a 2a 20 74  rce file in.** t
15e60 68 65 20 63 61 6e 6f 6e 69 63 61 6c 20 53 51 4c  he canonical SQL
15e70 69 74 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e  ite source tree.
15e80 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
15e90 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50  LITE_CONFIG_MMAP
15ea0 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  _SIZE]].** <dt>S
15eb0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41  QLITE_CONFIG_MMA
15ec0 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 53  P_SIZE.** <dd>^S
15ed0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41  QLITE_CONFIG_MMA
15ee0 50 5f 53 49 5a 45 20 74 61 6b 65 73 20 74 77 6f  P_SIZE takes two
15ef0 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20   64-bit integer 
15f00 28 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 20  (sqlite3_int64) 
15f10 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 61  values.** that a
15f20 72 65 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d  re the default m
15f30 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 20 28  map size limit (
15f40 74 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74  the default sett
15f50 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b 50 52 41 47  ing for.** [PRAG
15f60 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 29 20 61  MA mmap_size]) a
15f70 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 61  nd the maximum a
15f80 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65  llowed mmap size
15f90 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20   limit..** ^The 
15fa0 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20  default setting 
15fb0 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65  can be overridde
15fc0 6e 20 62 79 20 65 61 63 68 20 64 61 74 61 62 61  n by each databa
15fd0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 75 73  se connection us
15fe0 69 6e 67 0a 2a 2a 20 65 69 74 68 65 72 20 74 68  ing.** either th
15ff0 65 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73  e [PRAGMA mmap_s
16000 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72  ize] command, or
16010 20 62 79 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a   by using the.**
16020 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d   [SQLITE_FCNTL_M
16030 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63  MAP_SIZE] file c
16040 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54 68 65 20 6d  ontrol.  ^(The m
16050 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d  aximum allowed m
16060 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 77 69 6c 6c  map size.** will
16070 20 62 65 20 73 69 6c 65 6e 74 6c 79 20 74 72 75   be silently tru
16080 6e 63 61 74 65 64 20 69 66 20 6e 65 63 65 73 73  ncated if necess
16090 61 72 79 20 73 6f 20 74 68 61 74 20 69 74 20 64  ary so that it d
160a0 6f 65 73 20 6e 6f 74 20 65 78 63 65 65 64 20 74  oes not exceed t
160b0 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69  he.** compile-ti
160c0 6d 65 20 6d 61 78 69 6d 75 6d 20 6d 6d 61 70 20  me maximum mmap 
160d0 73 69 7a 65 20 73 65 74 20 62 79 20 74 68 65 0a  size set by the.
160e0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4d  ** [SQLITE_MAX_M
160f0 4d 41 50 5f 53 49 5a 45 5d 20 63 6f 6d 70 69 6c  MAP_SIZE] compil
16100 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 29 5e  e-time option.)^
16110 0a 2a 2a 20 5e 49 66 20 65 69 74 68 65 72 20 61  .** ^If either a
16120 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20  rgument to this 
16130 6f 70 74 69 6f 6e 20 69 73 20 6e 65 67 61 74 69  option is negati
16140 76 65 2c 20 74 68 65 6e 20 74 68 61 74 20 61 72  ve, then that ar
16150 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 63 68 61  gument is.** cha
16160 6e 67 65 64 20 74 6f 20 69 74 73 20 63 6f 6d 70  nged to its comp
16170 69 6c 65 2d 74 69 6d 65 20 64 65 66 61 75 6c 74  ile-time default
16180 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
16190 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45  _CONFIG_WIN32_HE
161a0 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e  APSIZE]].** <dt>
161b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49  SQLITE_CONFIG_WI
161c0 4e 33 32 5f 48 45 41 50 53 49 5a 45 0a 2a 2a 20  N32_HEAPSIZE.** 
161d0 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f  <dd>^The SQLITE_
161e0 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41  CONFIG_WIN32_HEA
161f0 50 53 49 5a 45 20 6f 70 74 69 6f 6e 20 69 73 20  PSIZE option is 
16200 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69  only available i
16210 66 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63  f SQLite is.** c
16220 6f 6d 70 69 6c 65 64 20 66 6f 72 20 57 69 6e 64  ompiled for Wind
16230 6f 77 73 20 77 69 74 68 20 74 68 65 20 5b 53 51  ows with the [SQ
16240 4c 49 54 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f  LITE_WIN32_MALLO
16250 43 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72  C] pre-processor
16260 20 6d 61 63 72 6f 0a 2a 2a 20 64 65 66 69 6e 65   macro.** define
16270 64 2e 20 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  d. ^SQLITE_CONFI
16280 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45  G_WIN32_HEAPSIZE
16290 20 74 61 6b 65 73 20 61 20 33 32 2d 62 69 74 20   takes a 32-bit 
162a0 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  unsigned integer
162b0 20 76 61 6c 75 65 0a 2a 2a 20 74 68 61 74 20 73   value.** that s
162c0 70 65 63 69 66 69 65 73 20 74 68 65 20 6d 61 78  pecifies the max
162d0 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 74 68 65  imum size of the
162e0 20 63 72 65 61 74 65 64 20 68 65 61 70 2e 0a 2a   created heap..*
162f0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
16300 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53  NFIG_PCACHE_HDRS
16310 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  Z]].** <dt>SQLIT
16320 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f  E_CONFIG_PCACHE_
16330 48 44 52 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68  HDRSZ.** <dd>^Th
16340 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16350 50 43 41 43 48 45 5f 48 44 52 53 5a 20 6f 70 74  PCACHE_HDRSZ opt
16360 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
16370 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 69  le parameter whi
16380 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74  ch.** is a point
16390 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
163a0 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 74 6f   and writes into
163b0 20 74 68 61 74 20 69 6e 74 65 67 65 72 20 74 68   that integer th
163c0 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72  e number of extr
163d0 61 0a 2a 2a 20 62 79 74 65 73 20 70 65 72 20 70  a.** bytes per p
163e0 61 67 65 20 72 65 71 75 69 72 65 64 20 66 6f 72  age required for
163f0 20 65 61 63 68 20 70 61 67 65 20 69 6e 20 5b 53   each page in [S
16400 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
16410 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 20  ECACHE]..** The 
16420 61 6d 6f 75 6e 74 20 6f 66 20 65 78 74 72 61 20  amount of extra 
16430 73 70 61 63 65 20 72 65 71 75 69 72 65 64 20 63  space required c
16440 61 6e 20 63 68 61 6e 67 65 20 64 65 70 65 6e 64  an change depend
16450 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69  ing on the compi
16460 6c 65 72 2c 0a 2a 2a 20 74 61 72 67 65 74 20 70  ler,.** target p
16470 6c 61 74 66 6f 72 6d 2c 20 61 6e 64 20 53 51 4c  latform, and SQL
16480 69 74 65 20 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a  ite version..**.
16490 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
164a0 49 47 5f 50 4d 41 53 5a 5d 5d 0a 2a 2a 20 3c 64  IG_PMASZ]].** <d
164b0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
164c0 50 4d 41 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68  PMASZ.** <dd>^Th
164d0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
164e0 50 4d 41 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b  PMASZ option tak
164f0 65 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61  es a single para
16500 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69  meter which.** i
16510 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 69 6e  s an unsigned in
16520 74 65 67 65 72 20 61 6e 64 20 73 65 74 73 20 74  teger and sets t
16530 68 65 20 22 4d 69 6e 69 6d 75 6d 20 50 4d 41 20  he "Minimum PMA 
16540 53 69 7a 65 22 20 66 6f 72 20 74 68 65 20 6d 75  Size" for the mu
16550 6c 74 69 74 68 72 65 61 64 65 64 0a 2a 2a 20 73  ltithreaded.** s
16560 6f 72 74 65 72 20 74 6f 20 74 68 61 74 20 69 6e  orter to that in
16570 74 65 67 65 72 2e 20 20 54 68 65 20 64 65 66 61  teger.  The defa
16580 75 6c 74 20 6d 69 6e 69 6d 75 6d 20 50 4d 41 20  ult minimum PMA 
16590 53 69 7a 65 20 69 73 20 73 65 74 20 62 79 20 74  Size is set by t
165a0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f  he.** [SQLITE_SO
165b0 52 54 45 52 5f 50 4d 41 53 5a 5d 20 63 6f 6d 70  RTER_PMASZ] comp
165c0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e  ile-time option.
165d0 20 20 4e 65 77 20 74 68 72 65 61 64 73 20 61 72    New threads ar
165e0 65 20 6c 61 75 6e 63 68 65 64 0a 2a 2a 20 74 6f  e launched.** to
165f0 20 68 65 6c 70 20 77 69 74 68 20 73 6f 72 74 20   help with sort 
16600 6f 70 65 72 61 74 69 6f 6e 73 20 77 68 65 6e 20  operations when 
16610 6d 75 6c 74 69 74 68 72 65 61 64 65 64 20 73 6f  multithreaded so
16620 72 74 69 6e 67 0a 2a 2a 20 69 73 20 65 6e 61 62  rting.** is enab
16630 6c 65 64 20 28 75 73 69 6e 67 20 74 68 65 20 5b  led (using the [
16640 50 52 41 47 4d 41 20 74 68 72 65 61 64 73 5d 20  PRAGMA threads] 
16650 63 6f 6d 6d 61 6e 64 29 20 61 6e 64 20 74 68 65  command) and the
16660 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 74 65   amount of conte
16670 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 73 6f 72 74  nt.** to be sort
16680 65 64 20 65 78 63 65 65 64 73 20 74 68 65 20 70  ed exceeds the p
16690 61 67 65 20 73 69 7a 65 20 74 69 6d 65 73 20 74  age size times t
166a0 68 65 20 6d 69 6e 69 6d 75 6d 20 6f 66 20 74 68  he minimum of th
166b0 65 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 63 61 63  e.** [PRAGMA cac
166c0 68 65 5f 73 69 7a 65 5d 20 73 65 74 74 69 6e 67  he_size] setting
166d0 20 61 6e 64 20 74 68 69 73 20 76 61 6c 75 65 2e   and this value.
166e0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
166f0 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f  CONFIG_STMTJRNL_
16700 53 50 49 4c 4c 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  SPILL]].** <dt>S
16710 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d  QLITE_CONFIG_STM
16720 54 4a 52 4e 4c 5f 53 50 49 4c 4c 0a 2a 2a 20 3c  TJRNL_SPILL.** <
16730 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  dd>^The SQLITE_C
16740 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53  ONFIG_STMTJRNL_S
16750 50 49 4c 4c 20 6f 70 74 69 6f 6e 20 74 61 6b 65  PILL option take
16760 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d  s a single param
16770 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 62 65  eter which.** be
16780 63 6f 6d 65 73 20 74 68 65 20 5b 73 74 61 74 65  comes the [state
16790 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 5d 20 73 70  ment journal] sp
167a0 69 6c 6c 2d 74 6f 2d 64 69 73 6b 20 74 68 72 65  ill-to-disk thre
167b0 73 68 6f 6c 64 2e 20 20 0a 2a 2a 20 5b 53 74 61  shold.  .** [Sta
167c0 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 5d  tement journals]
167d0 20 61 72 65 20 68 65 6c 64 20 69 6e 20 6d 65 6d   are held in mem
167e0 6f 72 79 20 75 6e 74 69 6c 20 74 68 65 69 72 20  ory until their 
167f0 73 69 7a 65 20 28 69 6e 20 62 79 74 65 73 29 0a  size (in bytes).
16800 2a 2a 20 65 78 63 65 65 64 73 20 74 68 69 73 20  ** exceeds this 
16810 74 68 72 65 73 68 6f 6c 64 2c 20 61 74 20 77 68  threshold, at wh
16820 69 63 68 20 70 6f 69 6e 74 20 74 68 65 79 20 61  ich point they a
16830 72 65 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69  re written to di
16840 73 6b 2e 0a 2a 2a 20 4f 72 20 69 66 20 74 68 65  sk..** Or if the
16850 20 74 68 72 65 73 68 6f 6c 64 20 69 73 20 2d 31   threshold is -1
16860 2c 20 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72  , statement jour
16870 6e 61 6c 73 20 61 72 65 20 61 6c 77 61 79 73 20  nals are always 
16880 68 65 6c 64 0a 2a 2a 20 65 78 63 6c 75 73 69 76  held.** exclusiv
16890 65 6c 79 20 69 6e 20 6d 65 6d 6f 72 79 2e 0a 2a  ely in memory..*
168a0 2a 20 53 69 6e 63 65 20 6d 61 6e 79 20 73 74 61  * Since many sta
168b0 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 20  tement journals 
168c0 6e 65 76 65 72 20 62 65 63 6f 6d 65 20 6c 61 72  never become lar
168d0 67 65 2c 20 73 65 74 74 69 6e 67 20 74 68 65 20  ge, setting the 
168e0 73 70 69 6c 6c 0a 2a 2a 20 74 68 72 65 73 68 6f  spill.** thresho
168f0 6c 64 20 74 6f 20 61 20 76 61 6c 75 65 20 73 75  ld to a value su
16900 63 68 20 61 73 20 36 34 4b 69 42 20 63 61 6e 20  ch as 64KiB can 
16910 67 72 65 61 74 6c 79 20 72 65 64 75 63 65 20 74  greatly reduce t
16920 68 65 20 61 6d 6f 75 6e 74 20 6f 66 0a 2a 2a 20  he amount of.** 
16930 49 2f 4f 20 72 65 71 75 69 72 65 64 20 74 6f 20  I/O required to 
16940 73 75 70 70 6f 72 74 20 73 74 61 74 65 6d 65 6e  support statemen
16950 74 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54  t rollback..** T
16960 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65  he default value
16970 20 66 6f 72 20 74 68 69 73 20 73 65 74 74 69 6e   for this settin
16980 67 20 69 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20  g is controlled 
16990 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  by the.** [SQLIT
169a0 45 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c  E_STMTJRNL_SPILL
169b0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
169c0 70 74 69 6f 6e 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  ption..** </dl>.
169d0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
169e0 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
169f0 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c  HREAD  1  /* nil
16a00 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16a10 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
16a20 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69  HREAD   2  /* ni
16a30 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
16a40 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
16a50 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e  LIZED    3  /* n
16a60 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  il */.#define SQ
16a70 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
16a80 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20  OC        4  /* 
16a90 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
16aa0 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
16ab0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
16ac0 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f  TMALLOC     5  /
16ad0 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  * sqlite3_mem_me
16ae0 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
16af0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16b00 53 43 52 41 54 43 48 20 20 20 20 20 20 20 36 20  SCRATCH       6 
16b10 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73   /* void*, int s
16b20 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66  z, int N */.#def
16b30 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
16b40 47 5f 50 41 47 45 43 41 43 48 45 20 20 20 20 20  G_PAGECACHE     
16b50 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  7  /* void*, int
16b60 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64   sz, int N */.#d
16b70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
16b80 46 49 47 5f 48 45 41 50 20 20 20 20 20 20 20 20  FIG_HEAP        
16b90 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69    8  /* void*, i
16ba0 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69  nt nByte, int mi
16bb0 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  n */.#define SQL
16bc0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
16bd0 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62  ATUS     9  /* b
16be0 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e  oolean */.#defin
16bf0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16c00 4d 55 54 45 58 20 20 20 20 20 20 20 20 31 30 20  MUTEX        10 
16c10 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   /* sqlite3_mute
16c20 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  x_methods* */.#d
16c30 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
16c40 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20  FIG_GETMUTEX    
16c50 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   11  /* sqlite3_
16c60 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a  mutex_methods* *
16c70 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  /./* previously 
16c80 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48  SQLITE_CONFIG_CH
16c90 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63  UNKALLOC 12 whic
16ca0 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e  h is now unused.
16cb0 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c   */ .#define SQL
16cc0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
16cd0 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69  SIDE    13  /* i
16ce0 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e  nt int */.#defin
16cf0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16d00 50 43 41 43 48 45 20 20 20 20 20 20 20 31 34 20  PCACHE       14 
16d10 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65   /* no-op */.#de
16d20 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16d30 49 47 5f 47 45 54 50 43 41 43 48 45 20 20 20 20  IG_GETPCACHE    
16d40 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a  15  /* no-op */.
16d50 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16d60 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20  ONFIG_LOG       
16d70 20 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c     16  /* xFunc,
16d80 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e   void* */.#defin
16d90 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16da0 55 52 49 20 20 20 20 20 20 20 20 20 20 31 37 20  URI          17 
16db0 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69   /* int */.#defi
16dc0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
16dd0 5f 50 43 41 43 48 45 32 20 20 20 20 20 20 31 38  _PCACHE2      18
16de0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61    /* sqlite3_pca
16df0 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f  che_methods2* */
16e00 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16e10 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
16e20 32 20 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74  2   19  /* sqlit
16e30 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
16e40 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  s2* */.#define S
16e50 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56  QLITE_CONFIG_COV
16e60 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e  ERING_INDEX_SCAN
16e70 20 32 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23   20  /* int */.#
16e80 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
16e90 4e 46 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20  NFIG_SQLLOG     
16ea0 20 20 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67    21  /* xSqllog
16eb0 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69  , void* */.#defi
16ec0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
16ed0 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 32 32  _MMAP_SIZE    22
16ee0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74    /* sqlite3_int
16ef0 36 34 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  64, sqlite3_int6
16f00 34 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  4 */.#define SQL
16f10 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32  ITE_CONFIG_WIN32
16f20 5f 48 45 41 50 53 49 5a 45 20 20 20 20 20 20 32  _HEAPSIZE      2
16f30 33 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20  3  /* int nByte 
16f40 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16f50 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f  E_CONFIG_PCACHE_
16f60 48 44 52 53 5a 20 20 20 20 20 20 20 20 32 34 20  HDRSZ        24 
16f70 20 2f 2a 20 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a   /* int *psz */.
16f80 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16f90 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 20 20 20 20  ONFIG_PMASZ     
16fa0 20 20 20 20 20 20 20 20 20 20 32 35 20 20 2f 2a            25  /*
16fb0 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 73 7a   unsigned int sz
16fc0 50 6d 61 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  Pma */.#define S
16fd0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d  QLITE_CONFIG_STM
16fe0 54 4a 52 4e 4c 5f 53 50 49 4c 4c 20 20 20 20 20  TJRNL_SPILL     
16ff0 20 32 36 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74   26  /* int nByt
17000 65 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  e */../*.** CAPI
17010 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43  3REF: Database C
17020 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67  onnection Config
17030 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a  uration Options.
17040 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
17050 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76  tants are the av
17060 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20  ailable integer 
17070 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
17080 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61  tions that.** ca
17090 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  n be passed as t
170a0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
170b0 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  nt to the [sqlit
170c0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
170d0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
170e0 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69   New configurati
170f0 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62  on options may b
17100 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
17110 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
17120 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e  Lite..** Existin
17130 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  g configuration 
17140 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65  options might be
17150 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20   discontinued.  
17160 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  Applications.** 
17170 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65  should check the
17180 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f   return code fro
17190 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  m [sqlite3_db_co
171a0 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20  nfig()] to make 
171b0 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  sure that.** the
171c0 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e   call worked.  ^
171d0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  The [sqlite3_db_
171e0 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
171f0 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ace will return 
17200 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  a.** non-zero [e
17210 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20  rror code] if a 
17220 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20  discontinued or 
17230 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66  unsupported conf
17240 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
17250 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a  .** is invoked..
17260 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64  **.** <dl>.** <d
17270 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
17280 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e  G_LOOKASIDE</dt>
17290 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
172a0 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65  ption takes thre
172b0 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  e additional arg
172c0 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65  uments that dete
172d0 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c  rmine the .** [l
172e0 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
172f0 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69  allocator] confi
17300 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65  guration for the
17310 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
17320 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20  ction]..** ^The 
17330 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28  first argument (
17340 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
17350 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
17360 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20  db_config()] is 
17370 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20  a.** pointer to 
17380 61 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  a memory buffer 
17390 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61  to use for looka
173a0 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20  side memory..** 
173b0 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
173c0 65 6e 74 20 61 66 74 65 72 20 74 68 65 20 53 51  ent after the SQ
173d0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
173e0 4f 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20  OKASIDE verb.** 
173f0 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77  may be NULL in w
17400 68 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 65  hich case SQLite
17410 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74   will allocate t
17420 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20  he.** lookaside 
17430 62 75 66 66 65 72 20 69 74 73 65 6c 66 20 75 73  buffer itself us
17440 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  ing [sqlite3_mal
17450 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63  loc()]. ^The sec
17460 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
17470 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65  the.** size of e
17480 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75  ach lookaside bu
17490 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65  ffer slot.  ^The
174a0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
174b0 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
174c0 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20  .** slots.  The 
174d0 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66  size of the buff
174e0 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  er in the first 
174f0 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65  argument must be
17500 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a   greater than.**
17510 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65   or equal to the
17520 20 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20   product of the 
17530 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64  second and third
17540 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65   arguments.  The
17550 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20   buffer.** must 
17560 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  be aligned to an
17570 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79   8-byte boundary
17580 2e 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e  .  ^If the secon
17590 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
175a0 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
175b0 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f  _LOOKASIDE is no
175c0 74 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20  t a multiple of 
175d0 38 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61  8, it is interna
175e0 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64  lly.** rounded d
175f0 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20  own to the next 
17600 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65  smaller multiple
17610 20 6f 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f   of 8.  ^(The lo
17620 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a  okaside memory.*
17630 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
17640 66 6f 72 20 61 20 64 61 74 61 62 61 73 65 20 63  for a database c
17650 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e  onnection can on
17660 6c 79 20 62 65 20 63 68 61 6e 67 65 64 20 77 68  ly be changed wh
17670 65 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65  en that.** conne
17680 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72  ction is not cur
17690 72 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f  rently using loo
176a0 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f  kaside memory, o
176b0 72 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  r in other words
176c0 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75  .** when the "cu
176d0 72 72 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74  rrent value" ret
176e0 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
176f0 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28  ite3_db_status](
17700 44 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  D,[SQLITE_CONFIG
17710 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29  _LOOKASIDE],...)
17720 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79   is zero..** Any
17730 20 61 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e   attempt to chan
17740 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65  ge the lookaside
17750 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72   memory configur
17760 61 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61  ation when looka
17770 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69  side.** memory i
17780 73 20 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20  s in use leaves 
17790 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
177a0 6e 20 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20  n unchanged and 
177b0 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c  returns .** [SQL
177c0 49 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64  ITE_BUSY].)^</dd
177d0 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
177e0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
177f0 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20  LE_FKEY</dt>.** 
17800 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
17810 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61  n is used to ena
17820 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74  ble or disable t
17830 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f  he enforcement o
17840 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65  f.** [foreign ke
17850 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20  y constraints]. 
17860 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65   There should be
17870 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
17880 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68  arguments..** Th
17890 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
178a0 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77   is an integer w
178b0 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73  hich is 0 to dis
178c0 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d  able FK enforcem
178d0 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65  ent,.** positive
178e0 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e   to enable FK en
178f0 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67  forcement or neg
17900 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46  ative to leave F
17910 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a  K enforcement.**
17920 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65   unchanged.  The
17930 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
17940 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  r is a pointer t
17950 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74  o an integer int
17960 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72  o which.** is wr
17970 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20  itten 0 or 1 to 
17980 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72  indicate whether
17990 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20   FK enforcement 
179a0 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20  is off or on.** 
179b0 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63  following this c
179c0 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  all.  The second
179d0 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
179e0 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  e a NULL pointer
179f0 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61  , in.** which ca
17a00 73 65 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63  se the FK enforc
17a10 65 6d 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73  ement setting is
17a20 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61   not reported ba
17a30 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ck. </dd>.**.** 
17a40 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
17a50 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47  FIG_ENABLE_TRIGG
17a60 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  ER</dt>.** <dd> 
17a70 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20  ^This option is 
17a80 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f  used to enable o
17a90 72 20 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54  r disable [CREAT
17aa0 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67  E TRIGGER | trig
17ab0 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20  gers]..** There 
17ac0 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64  should be two ad
17ad0 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
17ae0 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ts..** The first
17af0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20   argument is an 
17b00 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73  integer which is
17b10 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72   0 to disable tr
17b20 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74  iggers,.** posit
17b30 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72  ive to enable tr
17b40 69 67 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69  iggers or negati
17b50 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20  ve to leave the 
17b60 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65  setting unchange
17b70 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  d..** The second
17b80 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
17b90 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
17ba0 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68  teger into which
17bb0 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30  .** is written 0
17bc0 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74   or 1 to indicat
17bd0 65 20 77 68 65 74 68 65 72 20 74 72 69 67 67 65  e whether trigge
17be0 72 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  rs are disabled 
17bf0 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f  or enabled.** fo
17c00 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c  llowing this cal
17c10 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70  l.  The second p
17c20 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
17c30 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
17c40 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65  in.** which case
17c50 20 74 68 65 20 74 72 69 67 67 65 72 20 73 65 74   the trigger set
17c60 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f  ting is not repo
17c70 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e  rted back. </dd>
17c80 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
17c90 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
17ca0 45 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a 45 52  E_FTS3_TOKENIZER
17cb0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
17cc0 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  his option is us
17cd0 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20  ed to enable or 
17ce0 64 69 73 61 62 6c 65 20 74 68 65 20 74 77 6f 2d  disable the two-
17cf0 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 65 72 73  argument.** vers
17d00 69 6f 6e 20 6f 66 20 74 68 65 20 5b 66 74 73 33  ion of the [fts3
17d10 5f 74 6f 6b 65 6e 69 7a 65 72 28 29 5d 20 66 75  _tokenizer()] fu
17d20 6e 63 74 69 6f 6e 20 77 68 69 63 68 20 69 73 20  nction which is 
17d30 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  part of the.** [
17d40 46 54 53 33 5d 20 66 75 6c 6c 2d 74 65 78 74 20  FTS3] full-text 
17d50 73 65 61 72 63 68 20 65 6e 67 69 6e 65 20 65 78  search engine ex
17d60 74 65 6e 73 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72  tension..** Ther
17d70 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20  e should be two 
17d80 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
17d90 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72  ents..** The fir
17da0 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  st argument is a
17db0 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
17dc0 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
17dd0 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28 29  fts3_tokenizer()
17de0 20 6f 72 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20   or.** positive 
17df0 74 6f 20 65 6e 61 62 6c 65 20 66 74 73 33 5f 74  to enable fts3_t
17e00 6f 6b 65 6e 69 7a 65 72 28 29 20 6f 72 20 6e 65  okenizer() or ne
17e10 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20  gative to leave 
17e20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 75  the setting.** u
17e30 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65  nchanged..** The
17e40 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
17e50 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  r is a pointer t
17e60 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74  o an integer int
17e70 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72  o which.** is wr
17e80 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20  itten 0 or 1 to 
17e90 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72  indicate whether
17ea0 20 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 20   fts3_tokenizer 
17eb0 69 73 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65  is disabled or e
17ec0 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77  nabled.** follow
17ed0 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20  ing this call.  
17ee0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
17ef0 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55  eter may be a NU
17f00 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a  LL pointer, in.*
17f10 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  * which case the
17f20 20 6e 65 77 20 73 65 74 74 69 6e 67 20 69 73 20   new setting is 
17f30 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63  not reported bac
17f40 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  k. </dd>.**.** <
17f50 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
17f60 49 47 5f 45 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45  IG_ENABLE_LOAD_E
17f70 58 54 45 4e 53 49 4f 4e 3c 2f 64 74 3e 0a 2a 2a  XTENSION</dt>.**
17f80 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
17f90 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e  on is used to en
17fa0 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20  able or disable 
17fb0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61  the [sqlite3_loa
17fc0 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 0a 2a  d_extension()].*
17fd0 2a 20 69 6e 74 65 72 66 61 63 65 20 69 6e 64 65  * interface inde
17fe0 70 65 6e 64 65 6e 74 6c 79 20 6f 66 20 74 68 65  pendently of the
17ff0 20 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e   [load_extension
18000 28 29 5d 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ()] SQL function
18010 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  ..** The [sqlite
18020 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78  3_enable_load_ex
18030 74 65 6e 73 69 6f 6e 28 29 5d 20 41 50 49 20 65  tension()] API e
18040 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
18050 65 73 20 62 6f 74 68 20 74 68 65 0a 2a 2a 20 43  es both the.** C
18060 2d 41 50 49 20 5b 73 71 6c 69 74 65 33 5f 6c 6f  -API [sqlite3_lo
18070 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20  ad_extension()] 
18080 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63  and the SQL func
18090 74 69 6f 6e 20 5b 6c 6f 61 64 5f 65 78 74 65 6e  tion [load_exten
180a0 73 69 6f 6e 28 29 5d 2e 0a 2a 2a 20 54 68 65 72  sion()]..** Ther
180b0 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20  e should be two 
180c0 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
180d0 65 6e 74 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68  ents..** When th
180e0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
180f0 20 74 6f 20 74 68 69 73 20 69 6e 74 65 72 66 61   to this interfa
18100 63 65 20 69 73 20 31 2c 20 74 68 65 6e 20 6f 6e  ce is 1, then on
18110 6c 79 20 74 68 65 20 43 2d 41 50 49 20 69 73 0a  ly the C-API is.
18120 2a 2a 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 74  ** enabled and t
18130 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
18140 72 65 6d 61 69 6e 73 20 64 69 73 61 62 6c 65 64  remains disabled
18150 2e 20 20 49 66 20 74 68 65 20 66 69 72 73 74 20  .  If the first 
18160 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74  argument to.** t
18170 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73  his interface is
18180 20 30 2c 20 74 68 65 6e 20 62 6f 74 68 20 74 68   0, then both th
18190 65 20 43 2d 41 50 49 20 61 6e 64 20 74 68 65 20  e C-API and the 
181a0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 61 72 65  SQL function are
181b0 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 20 49 66   disabled..** If
181c0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
181d0 65 6e 74 20 69 73 20 2d 31 2c 20 74 68 65 6e 20  ent is -1, then 
181e0 6e 6f 20 63 68 61 6e 67 65 73 20 61 72 65 20 6d  no changes are m
181f0 61 64 65 20 74 6f 20 73 74 61 74 65 20 6f 66 20  ade to state of 
18200 65 69 74 68 65 72 20 74 68 65 0a 2a 2a 20 43 2d  either the.** C-
18210 41 50 49 20 6f 72 20 74 68 65 20 53 51 4c 20 66  API or the SQL f
18220 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20  unction..** The 
18230 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
18240 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
18250 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f   an integer into
18260 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69   which.** is wri
18270 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69  tten 0 or 1 to i
18280 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20  ndicate whether 
18290 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78  [sqlite3_load_ex
182a0 74 65 6e 73 69 6f 6e 28 29 5d 20 69 6e 74 65 72  tension()] inter
182b0 66 61 63 65 0a 2a 2a 20 69 73 20 64 69 73 61 62  face.** is disab
182c0 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 20 66  led or enabled f
182d0 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61  ollowing this ca
182e0 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ll.  The second 
182f0 70 61 72 61 6d 65 74 65 72 20 6d 61 79 0a 2a 2a  parameter may.**
18300 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   be a NULL point
18310 65 72 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73  er, in which cas
18320 65 20 74 68 65 20 6e 65 77 20 73 65 74 74 69 6e  e the new settin
18330 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65  g is not reporte
18340 64 20 62 61 63 6b 2e 0a 2a 2a 20 3c 2f 64 64 3e  d back..** </dd>
18350 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  .**.** </dl>.*/.
18360 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
18370 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
18380 45 20 20 20 20 20 20 20 20 20 20 20 20 20 31 30  E             10
18390 30 31 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20  01 /* void* int 
183a0 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  int */.#define S
183b0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
183c0 4e 41 42 4c 45 5f 46 4b 45 59 20 20 20 20 20 20  NABLE_FKEY      
183d0 20 20 20 20 20 31 30 30 32 20 2f 2a 20 69 6e 74       1002 /* int
183e0 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65   int* */.#define
183f0 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
18400 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 20  _ENABLE_TRIGGER 
18410 20 20 20 20 20 20 20 31 30 30 33 20 2f 2a 20 69         1003 /* i
18420 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69  nt int* */.#defi
18430 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
18440 49 47 5f 45 4e 41 42 4c 45 5f 46 54 53 33 5f 54  IG_ENABLE_FTS3_T
18450 4f 4b 45 4e 49 5a 45 52 20 31 30 30 34 20 2f 2a  OKENIZER 1004 /*
18460 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65   int int* */.#de
18470 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
18480 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 4c 4f 41 44  NFIG_ENABLE_LOAD
18490 5f 45 58 54 45 4e 53 49 4f 4e 20 31 30 30 35 20  _EXTENSION 1005 
184a0 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a  /* int int* */..
184b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
184c0 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62   Enable Or Disab
184d0 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65 73 75  le Extended Resu
184e0 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4d 45 54 48  lt Codes.** METH
184f0 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
18500 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
18510 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
18520 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65  odes() routine e
18530 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
18540 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e  es the.** [exten
18550 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
18560 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c  ] feature of SQL
18570 69 74 65 2e 20 5e 54 68 65 20 65 78 74 65 6e 64  ite. ^The extend
18580 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64  ed result.** cod
18590 65 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  es are disabled 
185a0 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68  by default for h
185b0 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74  istorical compat
185c0 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20  ibility..*/.int 
185d0 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
185e0 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71  _result_codes(sq
185f0 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66  lite3*, int onof
18600 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  f);../*.** CAPI3
18610 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74  REF: Last Insert
18620 20 52 6f 77 69 64 0a 2a 2a 20 4d 45 54 48 4f 44   Rowid.** METHOD
18630 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
18640 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20 6d  ^Each entry in m
18650 6f 73 74 20 53 51 4c 69 74 65 20 74 61 62 6c 65  ost SQLite table
18660 73 20 28 65 78 63 65 70 74 20 66 6f 72 20 5b 57  s (except for [W
18670 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61  ITHOUT ROWID] ta
18680 62 6c 65 73 29 0a 2a 2a 20 68 61 73 20 61 20 75  bles).** has a u
18690 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73 69 67  nique 64-bit sig
186a0 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b  ned.** integer k
186b0 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b 52  ey called the [R
186c0 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e  OWID | "rowid"].
186d0 20 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20 61   ^The rowid is a
186e0 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a  lways available.
186f0 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61  ** as an undecla
18700 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64  red column named
18710 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20   ROWID, OID, or 
18720 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20  _ROWID_ as long 
18730 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65  as those.** name
18740 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75  s are not also u
18750 73 65 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c  sed by explicitl
18760 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d  y declared colum
18770 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74  ns. ^If.** the t
18780 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d  able has a colum
18790 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 47  n of type [INTEG
187a0 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20  ER PRIMARY KEY] 
187b0 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e  then that column
187c0 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61  .** is another a
187d0 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77  lias for the row
187e0 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  id..**.** ^The s
187f0 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
18800 72 74 5f 72 6f 77 69 64 28 44 29 20 69 6e 74 65  rt_rowid(D) inte
18810 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
18820 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65  e [rowid] of the
18830 20 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74   .** most recent
18840 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53   successful [INS
18850 45 52 54 5d 20 69 6e 74 6f 20 61 20 72 6f 77 69  ERT] into a rowi
18860 64 20 74 61 62 6c 65 20 6f 72 20 5b 76 69 72 74  d table or [virt
18870 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e  ual table].** on
18880 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
18890 74 69 6f 6e 20 44 2e 0a 2a 2a 20 5e 49 6e 73 65  tion D..** ^Inse
188a0 72 74 73 20 69 6e 74 6f 20 5b 57 49 54 48 4f 55  rts into [WITHOU
188b0 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 20  T ROWID] tables 
188c0 61 72 65 20 6e 6f 74 20 72 65 63 6f 72 64 65 64  are not recorded
188d0 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73 75 63 63  ..** ^If no succ
188e0 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73  essful [INSERT]s
188f0 20 69 6e 74 6f 20 72 6f 77 69 64 20 74 61 62 6c   into rowid tabl
18900 65 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 20  es.** have ever 
18910 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68 65 20  occurred on the 
18920 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
18930 69 6f 6e 20 44 2c 20 0a 2a 2a 20 74 68 65 6e 20  ion D, .** then 
18940 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
18950 65 72 74 5f 72 6f 77 69 64 28 44 29 20 72 65 74  ert_rowid(D) ret
18960 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a  urns zero..**.**
18970 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54   ^(If an [INSERT
18980 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20  ] occurs within 
18990 61 20 74 72 69 67 67 65 72 20 6f 72 20 77 69 74  a trigger or wit
189a0 68 69 6e 20 61 20 5b 76 69 72 74 75 61 6c 20 74  hin a [virtual t
189b0 61 62 6c 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c  able].** method,
189c0 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69   then this routi
189d0 6e 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 74  ne will return t
189e0 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68  he [rowid] of th
189f0 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f  e inserted.** ro
18a00 77 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  w as long as the
18a10 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74   trigger or virt
18a20 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64  ual table method
18a30 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20   is running..** 
18a40 42 75 74 20 6f 6e 63 65 20 74 68 65 20 74 72 69  But once the tri
18a50 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20  gger or virtual 
18a60 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 65 6e 64  table method end
18a70 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  s, the value ret
18a80 75 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68 69  urned .** by thi
18a90 73 20 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74  s routine revert
18aa0 73 20 74 6f 20 77 68 61 74 20 69 74 20 77 61 73  s to what it was
18ab0 20 62 65 66 6f 72 65 20 74 68 65 20 74 72 69 67   before the trig
18ac0 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 0a 2a  ger or virtual.*
18ad0 2a 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 62  * table method b
18ae0 65 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41  egan.)^.**.** ^A
18af0 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 20  n [INSERT] that 
18b00 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63  fails due to a c
18b10 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74  onstraint violat
18b20 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20  ion is not a.** 
18b30 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45  successful [INSE
18b40 52 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74  RT] and does not
18b50 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75   change the valu
18b60 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  e returned by th
18b70 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20  is.** routine.  
18b80 5e 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20  ^Thus INSERT OR 
18b90 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20  FAIL, INSERT OR 
18ba0 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f  IGNORE, INSERT O
18bb0 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61  R ROLLBACK,.** a
18bc0 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f  nd INSERT OR ABO
18bd0 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67  RT make no chang
18be0 65 73 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e  es to the return
18bf0 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a   value of this.*
18c00 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74  * routine when t
18c10 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66  heir insertion f
18c20 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e  ails.  ^(When IN
18c30 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 0a  SERT OR REPLACE.
18c40 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20  ** encounters a 
18c50 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
18c60 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f  tion, it does no
18c70 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20  t fail.  The.** 
18c80 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73  INSERT continues
18c90 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61   to completion a
18ca0 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f  fter deleting ro
18cb0 77 73 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a  ws that caused.*
18cc0 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74  * the constraint
18cd0 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45   problem so INSE
18ce0 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69  RT OR REPLACE wi
18cf0 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65  ll always change
18d00 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76  .** the return v
18d10 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74  alue of this int
18d20 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  erface.)^.**.** 
18d30 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65  ^For the purpose
18d40 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e  s of this routin
18d50 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69  e, an [INSERT] i
18d60 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a  s considered to.
18d70 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66 75 6c  ** be successful
18d80 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 73   even if it is s
18d90 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c  ubsequently roll
18da0 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54  ed back..**.** T
18db0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  his function is 
18dc0 61 63 63 65 73 73 69 62 6c 65 20 74 6f 20 53 51  accessible to SQ
18dd0 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 76 69 61  L statements via
18de0 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e   the.** [last_in
18df0 73 65 72 74 5f 72 6f 77 69 64 28 29 20 53 51 4c  sert_rowid() SQL
18e00 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a   function]..**.*
18e10 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  * If a separate 
18e20 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20  thread performs 
18e30 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f  a new [INSERT] o
18e40 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61  n the same.** da
18e50 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
18e60 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c  n while the [sql
18e70 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
18e80 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e  _rowid()].** fun
18e90 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
18ea0 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65   and thus change
18eb0 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72  s the last inser
18ec0 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68  t [rowid],.** th
18ed0 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  en the value ret
18ee0 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
18ef0 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
18f00 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70  wid()] is.** unp
18f10 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d  redictable and m
18f20 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65  ight not equal e
18f30 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72  ither the old or
18f40 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74   the new.** last
18f50 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e   insert [rowid].
18f60 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  .*/.sqlite3_int6
18f70 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69  4 sqlite3_last_i
18f80 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69  nsert_rowid(sqli
18f90 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
18fa0 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68  PI3REF: Count Th
18fb0 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73  e Number Of Rows
18fc0 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54   Modified.** MET
18fd0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
18fe0 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
18ff0 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
19000 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64  mber of rows mod
19010 69 66 69 65 64 2c 20 69 6e 73 65 72 74 65 64 20  ified, inserted 
19020 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79  or.** deleted by
19030 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
19040 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53  ly completed INS
19050 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44  ERT, UPDATE or D
19060 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65  ELETE.** stateme
19070 6e 74 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61  nt on the databa
19080 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 70  se connection sp
19090 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 6f  ecified by the o
190a0 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  nly parameter..*
190b0 2a 20 5e 45 78 65 63 75 74 69 6e 67 20 61 6e 79  * ^Executing any
190c0 20 6f 74 68 65 72 20 74 79 70 65 20 6f 66 20 53   other type of S
190d0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65  QL statement doe
190e0 73 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65  s not modify the
190f0 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e   value.** return
19100 65 64 20 62 79 20 74 68 69 73 20 66 75 6e 63 74  ed by this funct
19110 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79  ion..**.** ^Only
19120 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 64 69   changes made di
19130 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 49 4e  rectly by the IN
19140 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20  SERT, UPDATE or 
19150 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74  DELETE statement
19160 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72   are.** consider
19170 65 64 20 2d 20 61 75 78 69 6c 69 61 72 79 20 63  ed - auxiliary c
19180 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79  hanges caused by
19190 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52   [CREATE TRIGGER
191a0 20 7c 20 74 72 69 67 67 65 72 73 5d 2c 20 0a 2a   | triggers], .*
191b0 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61  * [foreign key a
191c0 63 74 69 6f 6e 73 5d 20 6f 72 20 5b 52 45 50 4c  ctions] or [REPL
191d0 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20  ACE] constraint 
191e0 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65 20 6e  resolution are n
191f0 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a  ot counted..** .
19200 2a 2a 20 43 68 61 6e 67 65 73 20 74 6f 20 61 20  ** Changes to a 
19210 76 69 65 77 20 74 68 61 74 20 61 72 65 20 69 6e  view that are in
19220 74 65 72 63 65 70 74 65 64 20 62 79 20 0a 2a 2a  tercepted by .**
19230 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69   [INSTEAD OF tri
19240 67 67 65 72 20 7c 20 49 4e 53 54 45 41 44 20 4f  gger | INSTEAD O
19250 46 20 74 72 69 67 67 65 72 73 5d 20 61 72 65 20  F triggers] are 
19260 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 5e 54 68  not counted. ^Th
19270 65 20 76 61 6c 75 65 20 0a 2a 2a 20 72 65 74 75  e value .** retu
19280 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
19290 63 68 61 6e 67 65 73 28 29 20 69 6d 6d 65 64 69  changes() immedi
192a0 61 74 65 6c 79 20 61 66 74 65 72 20 61 6e 20 49  ately after an I
192b0 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72  NSERT, UPDATE or
192c0 20 0a 2a 2a 20 44 45 4c 45 54 45 20 73 74 61 74   .** DELETE stat
192d0 65 6d 65 6e 74 20 72 75 6e 20 6f 6e 20 61 20 76  ement run on a v
192e0 69 65 77 20 69 73 20 61 6c 77 61 79 73 20 7a 65  iew is always ze
192f0 72 6f 2e 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73  ro. Only changes
19300 20 6d 61 64 65 20 74 6f 20 72 65 61 6c 20 0a 2a   made to real .*
19310 2a 20 74 61 62 6c 65 73 20 61 72 65 20 63 6f 75  * tables are cou
19320 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e  nted..**.** Thin
19330 67 73 20 61 72 65 20 6d 6f 72 65 20 63 6f 6d 70  gs are more comp
19340 6c 69 63 61 74 65 64 20 69 66 20 74 68 65 20 73  licated if the s
19350 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
19360 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20   function is.** 
19370 65 78 65 63 75 74 65 64 20 77 68 69 6c 65 20 61  executed while a
19380 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d   trigger program
19390 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 54 68 69   is running. Thi
193a0 73 20 6d 61 79 20 68 61 70 70 65 6e 20 69 66 20  s may happen if 
193b0 74 68 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75  the.** program u
193c0 73 65 73 20 74 68 65 20 5b 63 68 61 6e 67 65 73  ses the [changes
193d0 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
193e0 2c 20 6f 72 20 69 66 20 73 6f 6d 65 20 6f 74 68  , or if some oth
193f0 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66  er callback.** f
19400 75 6e 63 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20  unction invokes 
19410 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
19420 29 20 64 69 72 65 63 74 6c 79 2e 20 45 73 73 65  ) directly. Esse
19430 6e 74 69 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20  ntially:.** .** 
19440 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e  <ul>.**   <li> ^
19450 28 42 65 66 6f 72 65 20 65 6e 74 65 72 69 6e 67  (Before entering
19460 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72   a trigger progr
19470 61 6d 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  am the value ret
19480 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20 20  urned by.**     
19490 20 20 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67     sqlite3_chang
194a0 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  es() function is
194b0 20 73 61 76 65 64 2e 20 41 66 74 65 72 20 74 68   saved. After th
194c0 65 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61  e trigger progra
194d0 6d 20 0a 2a 2a 20 20 20 20 20 20 20 20 68 61 73  m .**        has
194e0 20 66 69 6e 69 73 68 65 64 2c 20 74 68 65 20 6f   finished, the o
194f0 72 69 67 69 6e 61 6c 20 76 61 6c 75 65 20 69 73  riginal value is
19500 20 72 65 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20   restored.)^.** 
19510 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 57 69 74  .**   <li> ^(Wit
19520 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 70 72  hin a trigger pr
19530 6f 67 72 61 6d 20 65 61 63 68 20 49 4e 53 45 52  ogram each INSER
19540 54 2c 20 55 50 44 41 54 45 20 61 6e 64 20 44 45  T, UPDATE and DE
19550 4c 45 54 45 20 0a 2a 2a 20 20 20 20 20 20 20 20  LETE .**        
19560 73 74 61 74 65 6d 65 6e 74 20 73 65 74 73 20 74  statement sets t
19570 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
19580 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61  d by sqlite3_cha
19590 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 20  nges() .**      
195a0 20 20 75 70 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f    upon completio
195b0 6e 20 61 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20  n as normal. Of 
195c0 63 6f 75 72 73 65 2c 20 74 68 69 73 20 76 61 6c  course, this val
195d0 75 65 20 77 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c  ue will not incl
195e0 75 64 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 61  ude .**        a
195f0 6e 79 20 63 68 61 6e 67 65 73 20 70 65 72 66 6f  ny changes perfo
19600 72 6d 65 64 20 62 79 20 73 75 62 2d 74 72 69 67  rmed by sub-trig
19610 67 65 72 73 2c 20 61 73 20 74 68 65 20 73 71 6c  gers, as the sql
19620 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 0a  ite3_changes() .
19630 2a 2a 20 20 20 20 20 20 20 20 76 61 6c 75 65 20  **        value 
19640 77 69 6c 6c 20 62 65 20 73 61 76 65 64 20 61 6e  will be saved an
19650 64 20 72 65 73 74 6f 72 65 64 20 61 66 74 65 72  d restored after
19660 20 65 61 63 68 20 73 75 62 2d 74 72 69 67 67 65   each sub-trigge
19670 72 20 68 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20  r has run.)^.** 
19680 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68  </ul>.** .** ^Th
19690 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 69 66  is means that if
196a0 20 74 68 65 20 63 68 61 6e 67 65 73 28 29 20 53   the changes() S
196b0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 28 6f 72 20  QL function (or 
196c0 73 69 6d 69 6c 61 72 29 20 69 73 20 75 73 65 64  similar) is used
196d0 0a 2a 2a 20 62 79 20 74 68 65 20 66 69 72 73 74  .** by the first
196e0 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20   INSERT, UPDATE 
196f0 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  or DELETE statem
19700 65 6e 74 20 77 69 74 68 69 6e 20 61 20 74 72 69  ent within a tri
19710 67 67 65 72 2c 20 69 74 20 0a 2a 2a 20 72 65 74  gger, it .** ret
19720 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 61  urns the value a
19730 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 63  s set when the c
19740 61 6c 6c 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  alling statement
19750 20 62 65 67 61 6e 20 65 78 65 63 75 74 69 6e 67   began executing
19760 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 75  ..** ^If it is u
19770 73 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e  sed by the secon
19780 64 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20  d or subsequent 
19790 73 75 63 68 20 73 74 61 74 65 6d 65 6e 74 20 77  such statement w
197a0 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20  ithin a trigger 
197b0 0a 2a 2a 20 70 72 6f 67 72 61 6d 2c 20 74 68 65  .** program, the
197c0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
197d0 72 65 66 6c 65 63 74 73 20 74 68 65 20 6e 75 6d  reflects the num
197e0 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69  ber of rows modi
197f0 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20  fied by the .** 
19800 70 72 65 76 69 6f 75 73 20 49 4e 53 45 52 54 2c  previous INSERT,
19810 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54   UPDATE or DELET
19820 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  E statement with
19830 69 6e 20 74 68 65 20 73 61 6d 65 20 74 72 69 67  in the same trig
19840 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ger..**.** See a
19850 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33  lso the [sqlite3
19860 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
19870 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  ] interface, the
19880 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67  .** [count_chang
19890 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20  es pragma], and 
198a0 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53  the [changes() S
198b0 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
198c0 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
198d0 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63  e thread makes c
198e0 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61  hanges on the sa
198f0 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
19900 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20  ection.** while 
19910 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73  [sqlite3_changes
19920 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  ()] is running t
19930 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65  hen the value re
19940 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70  turned.** is unp
19950 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e  redictable and n
19960 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a  ot meaningful..*
19970 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68  /.int sqlite3_ch
19980 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b  anges(sqlite3*);
19990 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
199a0 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f  : Total Number O
199b0 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a  f Rows Modified.
199c0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
199d0 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  e3.**.** ^This f
199e0 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
199f0 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72  the total number
19a00 20 6f 66 20 72 6f 77 73 20 69 6e 73 65 72 74 65   of rows inserte
19a10 64 2c 20 6d 6f 64 69 66 69 65 64 20 6f 72 0a 2a  d, modified or.*
19a20 2a 20 64 65 6c 65 74 65 64 20 62 79 20 61 6c 6c  * deleted by all
19a30 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41   [INSERT], [UPDA
19a40 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20  TE] or [DELETE] 
19a50 73 74 61 74 65 6d 65 6e 74 73 20 63 6f 6d 70 6c  statements compl
19a60 65 74 65 64 0a 2a 2a 20 73 69 6e 63 65 20 74 68  eted.** since th
19a70 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
19a80 63 74 69 6f 6e 20 77 61 73 20 6f 70 65 6e 65 64  ction was opened
19a90 2c 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 6f 73  , including thos
19aa0 65 20 65 78 65 63 75 74 65 64 20 61 73 0a 2a 2a  e executed as.**
19ab0 20 70 61 72 74 20 6f 66 20 74 72 69 67 67 65 72   part of trigger
19ac0 20 70 72 6f 67 72 61 6d 73 2e 20 5e 45 78 65 63   programs. ^Exec
19ad0 75 74 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  uting any other 
19ae0 74 79 70 65 20 6f 66 20 53 51 4c 20 73 74 61 74  type of SQL stat
19af0 65 6d 65 6e 74 0a 2a 2a 20 64 6f 65 73 20 6e 6f  ement.** does no
19b00 74 20 61 66 66 65 63 74 20 74 68 65 20 76 61 6c  t affect the val
19b10 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ue returned by s
19b20 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
19b30 6e 67 65 73 28 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e  nges()..** .** ^
19b40 43 68 61 6e 67 65 73 20 6d 61 64 65 20 61 73 20  Changes made as 
19b50 70 61 72 74 20 6f 66 20 5b 66 6f 72 65 69 67 6e  part of [foreign
19b60 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 72   key actions] ar
19b70 65 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68  e included in th
19b80 65 0a 2a 2a 20 63 6f 75 6e 74 2c 20 62 75 74 20  e.** count, but 
19b90 74 68 6f 73 65 20 6d 61 64 65 20 61 73 20 70 61  those made as pa
19ba0 72 74 20 6f 66 20 52 45 50 4c 41 43 45 20 63 6f  rt of REPLACE co
19bb0 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74  nstraint resolut
19bc0 69 6f 6e 20 61 72 65 0a 2a 2a 20 6e 6f 74 2e 20  ion are.** not. 
19bd0 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69  ^Changes to a vi
19be0 65 77 20 74 68 61 74 20 61 72 65 20 69 6e 74 65  ew that are inte
19bf0 72 63 65 70 74 65 64 20 62 79 20 49 4e 53 54 45  rcepted by INSTE
19c00 41 44 20 4f 46 20 74 72 69 67 67 65 72 73 20 0a  AD OF triggers .
19c10 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74  ** are not count
19c20 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 53 65 65 20 61  ed..** .** See a
19c30 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33  lso the [sqlite3
19c40 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65  _changes()] inte
19c50 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63  rface, the.** [c
19c60 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61  ount_changes pra
19c70 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74  gma], and the [t
19c80 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 53  otal_changes() S
19c90 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
19ca0 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
19cb0 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63  e thread makes c
19cc0 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61  hanges on the sa
19cd0 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
19ce0 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20  ection.** while 
19cf0 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
19d00 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e  hanges()] is run
19d10 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61  ning then the va
19d20 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lue.** returned 
19d30 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  is unpredictable
19d40 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67   and not meaning
19d50 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ful..*/.int sqli
19d60 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
19d70 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  s(sqlite3*);../*
19d80 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
19d90 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52  terrupt A Long-R
19da0 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 20  unning Query.** 
19db0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
19dc0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
19dd0 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20  tion causes any 
19de0 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65  pending database
19df0 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62   operation to ab
19e00 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72  ort and.** retur
19e10 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69 65 73  n at its earlies
19e20 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54  t opportunity. T
19e30 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74  his routine is t
19e40 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c  ypically.** call
19e50 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74  ed in response t
19e60 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20  o a user action 
19e70 73 75 63 68 20 61 73 20 70 72 65 73 73 69 6e 67  such as pressing
19e80 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20   "Cancel".** or 
19e90 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65  Ctrl-C where the
19ea0 20 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f   user wants a lo
19eb0 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61 74 69  ng query operati
19ec0 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d  on to halt.** im
19ed0 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a  mediately..**.**
19ee0 20 5e 49 74 20 69 73 20 73 61 66 65 20 74 6f 20   ^It is safe to 
19ef0 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e  call this routin
19f00 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20  e from a thread 
19f10 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74  different from t
19f20 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61  he.** thread tha
19f30 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72  t is currently r
19f40 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62  unning the datab
19f50 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20  ase operation.  
19f60 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74  But it.** is not
19f70 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68   safe to call th
19f80 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20  is routine with 
19f90 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
19fa0 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20  ection] that.** 
19fb0 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67  is closed or mig
19fc0 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20  ht close before 
19fd0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
19fe0 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  t() returns..**.
19ff0 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70  ** ^If an SQL op
1a000 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20  eration is very 
1a010 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20  nearly finished 
1a020 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e  at the time when
1a030 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  .** sqlite3_inte
1a040 72 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65  rrupt() is calle
1a050 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74  d, then it might
1a060 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70   not have an opp
1a070 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62  ortunity.** to b
1a080 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e  e interrupted an
1a090 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65  d might continue
1a0a0 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a   to completion..
1a0b0 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70  **.** ^An SQL op
1a0c0 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20  eration that is 
1a0d0 69 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c  interrupted will
1a0e0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
1a0f0 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e  INTERRUPT]..** ^
1a100 49 66 20 74 68 65 20 69 6e 74 65 72 72 75 70 74  If the interrupt
1a110 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e  ed SQL operation
1a120 20 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55   is an INSERT, U
1a130 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45  PDATE, or DELETE
1a140 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69  .** that is insi
1a150 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74  de an explicit t
1a160 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e  ransaction, then
1a170 20 74 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e   the entire tran
1a180 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20  saction.** will 
1a190 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61  be rolled back a
1a1a0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a  utomatically..**
1a1b0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1a1c0 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 63 61  _interrupt(D) ca
1a1d0 6c 6c 20 69 73 20 69 6e 20 65 66 66 65 63 74 20  ll is in effect 
1a1e0 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e  until all curren
1a1f0 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53  tly running.** S
1a200 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e  QL statements on
1a210 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1a220 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74  ction] D complet
1a230 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c  e.  ^Any new SQL
1a240 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
1a250 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
1a260 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65  after the sqlite
1a270 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
1a280 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68  ll and before th
1a290 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74  e .** running st
1a2a0 61 74 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73  atements reaches
1a2b0 20 7a 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72   zero are interr
1a2c0 75 70 74 65 64 20 61 73 20 69 66 20 74 68 65 79  upted as if they
1a2d0 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e   had been.** run
1a2e0 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68  ning prior to th
1a2f0 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
1a300 75 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65  upt() call.  ^Ne
1a310 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  w SQL statements
1a320 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61  .** that are sta
1a330 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 72  rted after the r
1a340 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  unning statement
1a350 20 63 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a   count reaches z
1a360 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65  ero are.** not e
1a370 66 66 65 63 74 65 64 20 62 79 20 74 68 65 20 73  ffected by the s
1a380 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1a390 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74  ()..** ^A call t
1a3a0 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  o sqlite3_interr
1a3b0 75 70 74 28 44 29 20 74 68 61 74 20 6f 63 63 75  upt(D) that occu
1a3c0 72 73 20 77 68 65 6e 20 74 68 65 72 65 20 61 72  rs when there ar
1a3d0 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20  e no running.** 
1a3e0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69  SQL statements i
1a3f0 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61  s a no-op and ha
1a400 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53  s no effect on S
1a410 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
1a420 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65   that are starte
1a430 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69  d after the sqli
1a440 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
1a450 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  call returns..**
1a460 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61 62  .** If the datab
1a470 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63  ase connection c
1a480 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c  loses while [sql
1a490 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
1a4a0 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20  ].** is running 
1a4b0 74 68 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20  then bad things 
1a4c0 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70  will likely happ
1a4d0 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  en..*/.void sqli
1a4e0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71  te3_interrupt(sq
1a4f0 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
1a500 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d  CAPI3REF: Determ
1a510 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74  ine If An SQL St
1a520 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c  atement Is Compl
1a530 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ete.**.** These 
1a540 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
1a550 66 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61  ful during comma
1a560 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f  nd-line input to
1a570 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68   determine if th
1a580 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65  e.** currently e
1a590 6e 74 65 72 65 64 20 74 65 78 74 20 73 65 65 6d  ntered text seem
1a5a0 73 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70  s to form a comp
1a5b0 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65  lete SQL stateme
1a5c0 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69  nt or.** if addi
1a5d0 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20  tional input is 
1a5e0 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 65  needed before se
1a5f0 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74 20 69  nding the text i
1a600 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f  nto.** SQLite fo
1a610 72 20 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65  r parsing.  ^The
1a620 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
1a630 72 6e 20 31 20 69 66 20 74 68 65 20 69 6e 70 75  rn 1 if the inpu
1a640 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65  t string.** appe
1a650 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70  ars to be a comp
1a660 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65  lete SQL stateme
1a670 6e 74 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e  nt.  ^A statemen
1a680 74 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62  t is judged to b
1a690 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66  e.** complete if
1a6a0 20 69 74 20 65 6e 64 73 20 77 69 74 68 20 61 20   it ends with a 
1a6b0 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20  semicolon token 
1a6c0 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65  and is not a pre
1a6d0 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c  fix of a.** well
1a6e0 2d 66 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54  -formed CREATE T
1a6f0 52 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74  RIGGER statement
1a700 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74  .  ^Semicolons t
1a710 68 61 74 20 61 72 65 20 65 6d 62 65 64 64 65 64  hat are embedded
1a720 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e   within.** strin
1a730 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75  g literals or qu
1a740 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65 72 20  oted identifier 
1a750 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74  names or comment
1a760 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64  s are not.** ind
1a770 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20  ependent tokens 
1a780 28 74 68 65 79 20 61 72 65 20 70 61 72 74 20 6f  (they are part o
1a790 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77  f the token in w
1a7a0 68 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a  hich they are.**
1a7b0 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74   embedded) and t
1a7c0 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74  hus do not count
1a7d0 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20   as a statement 
1a7e0 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68  terminator.  ^Wh
1a7f0 69 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20  itespace.** and 
1a800 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f  comments that fo
1a810 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73  llow the final s
1a820 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e  emicolon are ign
1a830 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ored..**.** ^The
1a840 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
1a850 72 6e 20 30 20 69 66 20 74 68 65 20 73 74 61 74  rn 0 if the stat
1a860 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c  ement is incompl
1a870 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d  ete.  ^If a.** m
1a880 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1a890 20 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c   fails, then SQL
1a8a0 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74  ITE_NOMEM is ret
1a8b0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  urned..**.** ^Th
1a8c0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20  ese routines do 
1a8d0 6e 6f 74 20 70 61 72 73 65 20 74 68 65 20 53 51  not parse the SQ
1a8e0 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75  L statements thu
1a8f0 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65  s.** will not de
1a900 74 65 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c  tect syntactical
1a910 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c  ly incorrect SQL
1a920 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c  ..**.** ^(If SQL
1a930 69 74 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e  ite has not been
1a940 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69   initialized usi
1a950 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74  ng [sqlite3_init
1a960 69 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20  ialize()] prior 
1a970 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20  .** to invoking 
1a980 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
1a990 31 36 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65  16() then sqlite
1a9a0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
1a9b0 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74  s invoked.** aut
1a9c0 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71  omatically by sq
1a9d0 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
1a9e0 28 29 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69  ().  If that ini
1a9f0 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c  tialization fail
1aa00 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72  s,.** then the r
1aa10 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d  eturn value from
1aa20 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
1aa30 65 31 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f  e16() will be no
1aa40 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64  n-zero.** regard
1aa50 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
1aa60 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74  or not the input
1aa70 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65   SQL is complete
1aa80 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  .)^.**.** The in
1aa90 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
1aaa0 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74  complete()] must
1aab0 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   be a zero-termi
1aac0 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73  nated.** UTF-8 s
1aad0 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tring..**.** The
1aae0 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
1aaf0 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d  e3_complete16()]
1ab00 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d   must be a zero-
1ab10 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54  terminated.** UT
1ab20 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e  F-16 string in n
1ab30 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
1ab40 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1ab50 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20  _complete(const 
1ab60 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20  char *sql);.int 
1ab70 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
1ab80 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  16(const void *s
1ab90 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ql);../*.** CAPI
1aba0 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41  3REF: Register A
1abb0 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e   Callback To Han
1abc0 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20  dle SQLITE_BUSY 
1abd0 45 72 72 6f 72 73 0a 2a 2a 20 4b 45 59 57 4f 52  Errors.** KEYWOR
1abe0 44 53 3a 20 7b 62 75 73 79 2d 68 61 6e 64 6c 65  DS: {busy-handle
1abf0 72 20 63 61 6c 6c 62 61 63 6b 7d 20 7b 62 75 73  r callback} {bus
1ac00 79 20 68 61 6e 64 6c 65 72 7d 0a 2a 2a 20 4d 45  y handler}.** ME
1ac10 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
1ac20 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1ac30 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 44 2c  _busy_handler(D,
1ac40 58 2c 50 29 20 72 6f 75 74 69 6e 65 20 73 65 74  X,P) routine set
1ac50 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  s a callback fun
1ac60 63 74 69 6f 6e 20 58 0a 2a 2a 20 74 68 61 74 20  ction X.** that 
1ac70 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64  might be invoked
1ac80 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 50   with argument P
1ac90 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20   whenever.** an 
1aca0 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20  attempt is made 
1acb0 74 6f 20 61 63 63 65 73 73 20 61 20 64 61 74 61  to access a data
1acc0 62 61 73 65 20 74 61 62 6c 65 20 61 73 73 6f 63  base table assoc
1acd0 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 5b 64  iated with.** [d
1ace0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1acf0 6f 6e 5d 20 44 20 77 68 65 6e 20 61 6e 6f 74 68  on] D when anoth
1ad00 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20  er thread.** or 
1ad10 70 72 6f 63 65 73 73 20 68 61 73 20 74 68 65 20  process has the 
1ad20 74 61 62 6c 65 20 6c 6f 63 6b 65 64 2e 0a 2a 2a  table locked..**
1ad30 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62 75 73   The sqlite3_bus
1ad40 79 5f 68 61 6e 64 6c 65 72 28 29 20 69 6e 74 65  y_handler() inte
1ad50 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f  rface is used to
1ad60 20 69 6d 70 6c 65 6d 65 6e 74 0a 2a 2a 20 5b 73   implement.** [s
1ad70 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
1ad80 6f 75 74 28 29 5d 20 61 6e 64 20 5b 50 52 41 47  out()] and [PRAG
1ad90 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d  MA busy_timeout]
1ada0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
1adb0 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73  busy callback is
1adc0 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c   NULL, then [SQL
1add0 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 69 73 20  ITE_BUSY].** is 
1ade0 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61  returned immedia
1adf0 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e  tely upon encoun
1ae00 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e  tering the lock.
1ae10 20 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63    ^If the busy c
1ae20 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f  allback.** is no
1ae30 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65  t NULL, then the
1ae40 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20   callback might 
1ae50 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  be invoked with 
1ae60 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a  two arguments..*
1ae70 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
1ae80 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
1ae90 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20  busy handler is 
1aea0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f  a copy of the vo
1aeb0 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63  id* pointer whic
1aec0 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72  h.** is the thir
1aed0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  d argument to sq
1aee0 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
1aef0 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63 6f  er().  ^The seco
1af00 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  nd argument to.*
1af10 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  * the busy handl
1af20 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74  er callback is t
1af30 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d  he number of tim
1af40 65 73 20 74 68 61 74 20 74 68 65 20 62 75 73 79  es that the busy
1af50 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20   handler has.** 
1af60 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 70 72 65  been invoked pre
1af70 76 69 6f 75 73 6c 79 20 66 6f 72 20 74 68 65 20  viously for the 
1af80 73 61 6d 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65  same locking eve
1af90 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  nt.  ^If the.** 
1afa0 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65  busy callback re
1afb0 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f  turns 0, then no
1afc0 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65   additional atte
1afd0 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f  mpts are made to
1afe0 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20 64  .** access the d
1aff0 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c  atabase and [SQL
1b000 49 54 45 5f 42 55 53 59 5d 20 69 73 20 72 65 74  ITE_BUSY] is ret
1b010 75 72 6e 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20  urned.** to the 
1b020 61 70 70 6c 69 63 61 74 69 6f 6e 2e 0a 2a 2a 20  application..** 
1b030 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ^If the callback
1b040 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
1b050 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20  o, then another 
1b060 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61  attempt.** is ma
1b070 64 65 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  de to access the
1b080 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 74 68   database and th
1b090 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e  e cycle repeats.
1b0a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65  .**.** The prese
1b0b0 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61  nce of a busy ha
1b0c0 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67  ndler does not g
1b0d0 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 69 74  uarantee that it
1b0e0 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64   will be invoked
1b0f0 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69  .** when there i
1b100 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f  s lock contentio
1b110 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65  n. ^If SQLite de
1b120 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e  termines that in
1b130 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a  voking the busy.
1b140 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64  ** handler could
1b150 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61   result in a dea
1b160 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67  dlock, it will g
1b170 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 75  o ahead and retu
1b180 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  rn [SQLITE_BUSY]
1b190 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 70 6c 69  .** to the appli
1b1a0 63 61 74 69 6f 6e 20 69 6e 73 74 65 61 64 20 6f  cation instead o
1b1b0 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 0a  f invoking the .
1b1c0 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  ** busy handler.
1b1d0 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73  .** Consider a s
1b1e0 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e  cenario where on
1b1f0 65 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c  e process is hol
1b200 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b  ding a read lock
1b210 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74   that.** it is t
1b220 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65  rying to promote
1b230 20 74 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c   to a reserved l
1b240 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63  ock and.** a sec
1b250 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20 68  ond process is h
1b260 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76 65  olding a reserve
1b270 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69  d lock that it i
1b280 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70  s trying.** to p
1b290 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63  romote to an exc
1b2a0 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68  lusive lock.  Th
1b2b0 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20  e first process 
1b2c0 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a  cannot proceed.*
1b2d0 2a 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20  * because it is 
1b2e0 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73  blocked by the s
1b2f0 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65  econd and the se
1b300 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e  cond process can
1b310 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62  not.** proceed b
1b320 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f  ecause it is blo
1b330 63 6b 65 64 20 62 79 20 74 68 65 20 66 69 72 73  cked by the firs
1b340 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63  t.  If both proc
1b350 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20  esses.** invoke 
1b360 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
1b370 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20  s, neither will 
1b380 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73  make any progres
1b390 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a  s.  Therefore,.*
1b3a0 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73  * SQLite returns
1b3b0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66   [SQLITE_BUSY] f
1b3c0 6f 72 20 74 68 65 20 66 69 72 73 74 20 70 72 6f  or the first pro
1b3d0 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61  cess, hoping tha
1b3e0 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69  t this.** will i
1b3f0 6e 64 75 63 65 20 74 68 65 20 66 69 72 73 74 20  nduce the first 
1b400 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61  process to relea
1b410 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b  se its read lock
1b420 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68   and allow.** th
1b430 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73  e second process
1b440 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a   to proceed..**.
1b450 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
1b460 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73  busy callback is
1b470 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54   NULL..**.** ^(T
1b480 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65  here can only be
1b490 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68   a single busy h
1b4a0 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66  andler defined f
1b4b0 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61  or each.** [data
1b4c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1b4d0 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77  .  Setting a new
1b4e0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c   busy handler cl
1b4f0 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76  ears any.** prev
1b500 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c  iously set handl
1b510 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61  er.)^  ^Note tha
1b520 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  t calling [sqlit
1b530 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
1b540 29 5d 0a 2a 2a 20 6f 72 20 65 76 61 6c 75 61 74  )].** or evaluat
1b550 69 6e 67 20 5b 50 52 41 47 4d 41 20 62 75 73 79  ing [PRAGMA busy
1b560 5f 74 69 6d 65 6f 75 74 3d 4e 5d 20 77 69 6c 6c  _timeout=N] will
1b570 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 62   change the.** b
1b580 75 73 79 20 68 61 6e 64 6c 65 72 20 61 6e 64 20  usy handler and 
1b590 74 68 75 73 20 63 6c 65 61 72 20 61 6e 79 20 70  thus clear any p
1b5a0 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 62 75  reviously set bu
1b5b0 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a  sy handler..**.*
1b5c0 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62  * The busy callb
1b5d0 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74  ack should not t
1b5e0 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20  ake any actions 
1b5f0 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65  which modify the
1b600 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
1b610 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
1b620 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61  oked the busy ha
1b630 6e 64 6c 65 72 2e 20 20 49 6e 20 6f 74 68 65 72  ndler.  In other
1b640 20 77 6f 72 64 73 2c 0a 2a 2a 20 74 68 65 20 62   words,.** the b
1b650 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 6e  usy handler is n
1b660 6f 74 20 72 65 65 6e 74 72 61 6e 74 2e 20 20 41  ot reentrant.  A
1b670 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a  ny such actions.
1b680 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64  ** result in und
1b690 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e  efined behavior.
1b6a0 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20 68  .** .** A busy h
1b6b0 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20  andler must not 
1b6c0 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61  close the databa
1b6d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
1b6e0 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73 74   or [prepared st
1b6f0 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e  atement] that in
1b700 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68  voked the busy h
1b710 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73  andler..*/.int s
1b720 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
1b730 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 69 6e 74  ler(sqlite3*,int
1b740 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 76  (*)(void*,int),v
1b750 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
1b760 50 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 75  PI3REF: Set A Bu
1b770 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 20 4d 45  sy Timeout.** ME
1b780 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
1b790 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
1b7a0 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65  e sets a [sqlite
1b7b0 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c  3_busy_handler |
1b7c0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74   busy handler] t
1b7d0 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f  hat sleeps.** fo
1b7e0 72 20 61 20 73 70 65 63 69 66 69 65 64 20 61 6d  r a specified am
1b7f0 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65  ount of time whe
1b800 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63  n a table is loc
1b810 6b 65 64 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c  ked.  ^The handl
1b820 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70  er.** will sleep
1b830 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20   multiple times 
1b840 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22  until at least "
1b850 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73  ms" milliseconds
1b860 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20   of sleeping.** 
1b870 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64  have accumulated
1b880 2e 20 20 5e 41 66 74 65 72 20 61 74 20 6c 65 61  .  ^After at lea
1b890 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63  st "ms" millisec
1b8a0 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67  onds of sleeping
1b8b0 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72  ,.** the handler
1b8c0 20 72 65 74 75 72 6e 73 20 30 20 77 68 69 63 68   returns 0 which
1b8d0 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33   causes [sqlite3
1b8e0 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75  _step()] to retu
1b8f0 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55  rn.** [SQLITE_BU
1b900 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c  SY]..**.** ^Call
1b910 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ing this routine
1b920 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e   with an argumen
1b930 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65  t less than or e
1b940 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20  qual to zero.** 
1b950 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75  turns off all bu
1b960 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a  sy handlers..**.
1b970 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f  ** ^(There can o
1b980 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20  nly be a single 
1b990 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72  busy handler for
1b9a0 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a   a particular.**
1b9b0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1b9c0 63 74 69 6f 6e 5d 20 61 74 20 61 6e 79 20 67 69  ction] at any gi
1b9d0 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20  ven moment.  If 
1b9e0 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e  another busy han
1b9f0 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69  dler.** was defi
1ba00 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c  ned  (using [sql
1ba10 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
1ba20 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63  r()]) prior to c
1ba30 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72  alling.** this r
1ba40 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68  outine, that oth
1ba50 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  er busy handler 
1ba60 69 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2a  is cleared.)^.**
1ba70 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b  .** See also:  [
1ba80 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65  PRAGMA busy_time
1ba90 6f 75 74 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  out].*/.int sqli
1baa0 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
1bab0 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d  (sqlite3*, int m
1bac0 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  s);../*.** CAPI3
1bad0 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65  REF: Convenience
1bae0 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75   Routines For Ru
1baf0 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a  nning Queries.**
1bb00 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
1bb10 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61  .**.** This is a
1bb20 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
1bb30 65 20 74 68 61 74 20 69 73 20 70 72 65 73 65 72  e that is preser
1bb40 76 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64  ved for backward
1bb50 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  s compatibility.
1bb60 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20  .** Use of this 
1bb70 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74  interface is not
1bb80 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a   recommended..**
1bb90 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20  .** Definition: 
1bba0 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c  A <b>result tabl
1bbb0 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20  e</b> is memory 
1bbc0 64 61 74 61 20 73 74 72 75 63 74 75 72 65 20 63  data structure c
1bbd0 72 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a  reated by the.**
1bbe0 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
1bbf0 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ble()] interface
1bc00 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  .  A result tabl
1bc10 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a  e records the.**
1bc20 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20   complete query 
1bc30 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65  results from one
1bc40 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73   or more queries
1bc50 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c  ..**.** The tabl
1bc60 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68  e conceptually h
1bc70 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72  as a number of r
1bc80 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e  ows and columns.
1bc90 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e    But.** these n
1bca0 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70  umbers are not p
1bcb0 61 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c  art of the resul
1bcc0 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20  t table itself. 
1bcd0 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72   These.** number
1bce0 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73  s are obtained s
1bcf0 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20  eparately.  Let 
1bd00 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20  N be the number 
1bd10 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d  of rows.** and M
1bd20 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   be the number o
1bd30 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a  f columns..**.**
1bd40 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
1bd50 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
1bd60 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d  ointers to zero-
1bd70 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
1bd80 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65   strings..** The
1bd90 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65  re are (N+1)*M e
1bda0 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61  lements in the a
1bdb0 72 72 61 79 2e 20 20 54 68 65 20 66 69 72 73 74  rray.  The first
1bdc0 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e   M pointers poin
1bdd0 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72  t.** to zero-ter
1bde0 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20  minated strings 
1bdf0 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68  that  contain th
1be00 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63  e names of the c
1be10 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72  olumns..** The r
1be20 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73  emaining entries
1be30 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75   all point to qu
1be40 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55  ery results.  NU
1be50 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74  LL values result
1be60 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e  .** in NULL poin
1be70 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72  ters.  All other
1be80 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74   values are in t
1be90 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d  heir UTF-8 zero-
1bea0 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74  terminated.** st
1beb0 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74  ring representat
1bec0 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20  ion as returned 
1bed0 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  by [sqlite3_colu
1bee0 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a  mn_text()]..**.*
1bef0 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65  * A result table
1bf00 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f   might consist o
1bf10 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65  f one or more me
1bf20 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
1bf30 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73  ..** It is not s
1bf40 61 66 65 20 74 6f 20 70 61 73 73 20 61 20 72 65  afe to pass a re
1bf50 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63  sult table direc
1bf60 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  tly to [sqlite3_
1bf70 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65  free()]..** A re
1bf80 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c  sult table shoul
1bf90 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  d be deallocated
1bfa0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1bfb0 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a  free_table()]..*
1bfc0 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61  *.** ^(As an exa
1bfd0 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75  mple of the resu
1bfe0 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c  lt table format,
1bff0 20 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 79   suppose a query
1c000 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73   result.** is as
1c010 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
1c020 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1c030 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65  >.**        Name
1c040 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a          | Age.**
1c050 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d          --------
1c060 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a  ---------------.
1c070 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20  **        Alice 
1c080 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20        | 43.**   
1c090 20 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20       Bob        
1c0a0 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20   | 28.**        
1c0b0 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31  Cindy       | 21
1c0c0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1c0d0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
1c0e0 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75  ere are two colu
1c0f0 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68  mn (M==2) and th
1c100 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e  ree rows (N==3).
1c110 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65    Thus the.** re
1c120 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38  sult table has 8
1c130 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f   entries.  Suppo
1c140 73 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  se the result ta
1c150 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a  ble is stored.**
1c160 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d   in an array nam
1c170 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68  es azResult.  Th
1c180 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64  en azResult hold
1c190 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a  s this content:.
1c1a0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1c1b0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20  e><pre>.**      
1c1c0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30    azResult&#91;0
1c1d0 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20  ] = "Name";.**  
1c1e0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1c1f0 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a  91;1] = "Age";.*
1c200 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1c210 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63  t&#91;2] = "Alic
1c220 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
1c230 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20  Result&#91;3] = 
1c240 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  "43";.**        
1c250 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20  azResult&#91;4] 
1c260 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20  = "Bob";.**     
1c270 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1c280 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20  5] = "28";.**   
1c290 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1c2a0 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a  1;6] = "Cindy";.
1c2b0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1c2c0 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22  lt&#91;7] = "21"
1c2d0 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
1c2e0 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a  ckquote>)^.**.**
1c2f0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65   ^The sqlite3_ge
1c300 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69  t_table() functi
1c310 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65  on evaluates one
1c320 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69   or more.** semi
1c330 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20  colon-separated 
1c340 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69  SQL statements i
1c350 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69  n the zero-termi
1c360 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73  nated UTF-8.** s
1c370 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64  tring of its 2nd
1c380 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72   parameter and r
1c390 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20  eturns a result 
1c3a0 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20  table to the.** 
1c3b0 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e  pointer given in
1c3c0 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74   its 3rd paramet
1c3d0 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20  er..**.** After 
1c3e0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
1c3f0 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
1c400 68 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f  h the result fro
1c410 6d 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  m sqlite3_get_ta
1c420 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73  ble(),.** it mus
1c430 74 20 70 61 73 73 20 74 68 65 20 72 65 73 75 6c  t pass the resul
1c440 74 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20  t table pointer 
1c450 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  to sqlite3_free_
1c460 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72  table() in order
1c470 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74   to.** release t
1c480 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77  he memory that w
1c490 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65  as malloced.  Be
1c4a0 63 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79  cause of the way
1c4b0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
1c4c0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65  _malloc()] happe
1c4d0 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65  ns within sqlite
1c4e0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74  3_get_table(), t
1c4f0 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75  he calling.** fu
1c500 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  nction must not 
1c510 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c  try to call [sql
1c520 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72  ite3_free()] dir
1c530 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20  ectly.  Only.** 
1c540 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61  [sqlite3_free_ta
1c550 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74  ble()] is able t
1c560 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65  o release the me
1c570 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e  mory properly an
1c580 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  d safely..**.** 
1c590 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
1c5a0 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63  table() interfac
1c5b0 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64  e is implemented
1c5c0 20 61 73 20 61 20 77 72 61 70 70 65 72 20 61 72   as a wrapper ar
1c5d0 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ound.** [sqlite3
1c5e0 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73  _exec()].  The s
1c5f0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1c600 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20  () routine does 
1c610 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 0a  not have access.
1c620 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e  ** to any intern
1c630 61 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 72  al data structur
1c640 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49  es of SQLite.  I
1c650 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20  t uses only the 
1c660 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66  public.** interf
1c670 61 63 65 20 64 65 66 69 6e 65 64 20 68 65 72 65  ace defined here
1c680 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65  .  As a conseque
1c690 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74  nce, errors that
1c6a0 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a   occur in the.**
1c6b0 20 77 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f   wrapper layer o
1c6c0 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e  utside of the in
1c6d0 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f  ternal [sqlite3_
1c6e0 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65  exec()] call are
1c6f0 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65   not.** reflecte
1c700 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20  d in subsequent 
1c710 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
1c720 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a  3_errcode()] or.
1c730 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ** [sqlite3_errm
1c740 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  sg()]..*/.int sq
1c750 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1c760 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
1c770 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f           /* An o
1c780 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  pen database */.
1c790 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
1c7a0 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74  ql,     /* SQL t
1c7b0 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a  o be evaluated *
1c7c0 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52  /.  char ***pazR
1c7d0 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73  esult,    /* Res
1c7e0 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65 72  ults of the quer
1c7f0 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f  y */.  int *pnRo
1c800 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  w,           /* 
1c810 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74  Number of result
1c820 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65   rows written he
1c830 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43  re */.  int *pnC
1c840 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a  olumn,        /*
1c850 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c   Number of resul
1c860 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65  t columns writte
1c870 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72  n here */.  char
1c880 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20   **pzErrmsg     
1c890 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77    /* Error msg w
1c8a0 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29  ritten here */.)
1c8b0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66  ;.void sqlite3_f
1c8c0 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a  ree_table(char *
1c8d0 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a  *result);../*.**
1c8e0 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61   CAPI3REF: Forma
1c8f0 74 74 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e  tted String Prin
1c900 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  ting Functions.*
1c910 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
1c920 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69  nes are work-ali
1c930 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e  kes of the "prin
1c940 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20  tf()" family of 
1c950 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f  functions.** fro
1c960 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  m the standard C
1c970 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 54 68 65   library..** The
1c980 73 65 20 72 6f 75 74 69 6e 65 73 20 75 6e 64 65  se routines unde
1c990 72 73 74 61 6e 64 20 6d 6f 73 74 20 6f 66 20 74  rstand most of t
1c9a0 68 65 20 63 6f 6d 6d 6f 6e 20 4b 26 52 20 66 6f  he common K&R fo
1c9b0 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73  rmatting options
1c9c0 2c 0a 2a 2a 20 70 6c 75 73 20 73 6f 6d 65 20 61  ,.** plus some a
1c9d0 64 64 69 74 69 6f 6e 61 6c 20 6e 6f 6e 2d 73 74  dditional non-st
1c9e0 61 6e 64 61 72 64 20 66 6f 72 6d 61 74 73 2c 20  andard formats, 
1c9f0 64 65 74 61 69 6c 65 64 20 62 65 6c 6f 77 2e 0a  detailed below..
1ca00 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 73 6f 6d  ** Note that som
1ca10 65 20 6f 66 20 74 68 65 20 6d 6f 72 65 20 6f 62  e of the more ob
1ca20 73 63 75 72 65 20 66 6f 72 6d 61 74 74 69 6e 67  scure formatting
1ca30 20 6f 70 74 69 6f 6e 73 20 66 72 6f 6d 20 72 65   options from re
1ca40 63 65 6e 74 0a 2a 2a 20 43 2d 6c 69 62 72 61 72  cent.** C-librar
1ca50 79 20 73 74 61 6e 64 61 72 64 73 20 61 72 65 20  y standards are 
1ca60 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 69  omitted from thi
1ca70 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  s implementation
1ca80 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1ca90 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61  ite3_mprintf() a
1caa0 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69  nd sqlite3_vmpri
1cab0 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77  ntf() routines w
1cac0 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65  rite their.** re
1cad0 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72  sults into memor
1cae0 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
1caf0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1cb00 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e  )]..** The strin
1cb10 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  gs returned by t
1cb20 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65  hese two routine
1cb30 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72  s should be.** r
1cb40 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69  eleased by [sqli
1cb50 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42  te3_free()].  ^B
1cb60 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74  oth routines ret
1cb70 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f  urn a.** NULL po
1cb80 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65  inter if [sqlite
1cb90 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75  3_malloc()] is u
1cba0 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
1cbb0 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f  e enough.** memo
1cbc0 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72  ry to hold the r
1cbd0 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e  esulting string.
1cbe0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c  .**.** ^(The sql
1cbf0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20  ite3_snprintf() 
1cc00 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c  routine is simil
1cc10 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28  ar to "snprintf(
1cc20 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73  )" from.** the s
1cc30 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
1cc40 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 69  y.  The result i
1cc50 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74  s written into t
1cc60 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70  he.** buffer sup
1cc70 70 6c 69 65 64 20 61 73 20 74 68 65 20 73 65 63  plied as the sec
1cc80 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77 68  ond parameter wh
1cc90 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69 76 65  ose size is give
1cca0 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73  n by.** the firs
1ccb0 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74  t parameter. Not
1ccc0 65 20 74 68 61 74 20 74 68 65 20 6f 72 64 65 72  e that the order
1ccd0 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74   of the.** first
1cce0 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20   two parameters 
1ccf0 69 73 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d  is reversed from
1cd00 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20   snprintf().)^  
1cd10 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69  This is an.** hi
1cd20 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e  storical acciden
1cd30 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65  t that cannot be
1cd40 20 66 69 78 65 64 20 77 69 74 68 6f 75 74 20 62   fixed without b
1cd50 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77  reaking.** backw
1cd60 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
1cd70 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f  ty.  ^(Note also
1cd80 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e   that sqlite3_sn
1cd90 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75  printf().** retu
1cda0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
1cdb0 20 69 74 73 20 62 75 66 66 65 72 20 69 6e 73 74   its buffer inst
1cdc0 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65  ead of the numbe
1cdd0 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65  r of.** characte
1cde0 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74  rs actually writ
1cdf0 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66  ten into the buf
1ce00 66 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74  fer.)^  We admit
1ce10 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d   that.** the num
1ce20 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
1ce30 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20  s written would 
1ce40 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c  be a more useful
1ce50 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65   return.** value
1ce60 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63   but we cannot c
1ce70 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d  hange the implem
1ce80 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69  entation of sqli
1ce90 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
1cea0 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72  * now without br
1ceb0 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69  eaking compatibi
1cec0 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20  lity..**.** ^As 
1ced0 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66 66  long as the buff
1cee0 65 72 20 73 69 7a 65 20 69 73 20 67 72 65 61 74  er size is great
1cef0 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71  er than zero, sq
1cf00 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
1cf10 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74  .** guarantees t
1cf20 68 61 74 20 74 68 65 20 62 75 66 66 65 72 20 69  hat the buffer i
1cf30 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65  s always zero-te
1cf40 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20  rminated.  ^The 
1cf50 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74  first.** paramet
1cf60 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f  er "n" is the to
1cf70 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20  tal size of the 
1cf80 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e  buffer, includin
1cf90 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74  g space for.** t
1cfa0 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
1cfb0 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67  or.  So the long
1cfc0 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 20  est string that 
1cfd0 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c  can be completel
1cfe0 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c  y.** written wil
1cff0 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74  l be n-1 charact
1d000 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ers..**.** ^The 
1d010 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74  sqlite3_vsnprint
1d020 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61  f() routine is a
1d030 20 76 61 72 61 72 67 73 20 76 65 72 73 69 6f 6e   varargs version
1d040 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72   of sqlite3_snpr
1d050 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  intf()..**.** Th
1d060 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c  ese routines all
1d070 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20   implement some 
1d080 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61  additional forma
1d090 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73  tting.** options
1d0a0 20 74 68 61 74 20 61 72 65 20 75 73 65 66 75 6c   that are useful
1d0b0 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e   for constructin
1d0c0 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  g SQL statements
1d0d0 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20  ..** All of the 
1d0e0 75 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66  usual printf() f
1d0f0 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e  ormatting option
1d100 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64  s apply.  In add
1d110 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20  ition, there.** 
1d120 69 73 20 61 72 65 20 22 25 71 22 2c 20 22 25 51  is are "%q", "%Q
1d130 22 2c 20 22 25 77 22 20 61 6e 64 20 22 25 7a 22  ", "%w" and "%z"
1d140 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20   options..**.** 
1d150 5e 28 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20  ^(The %q option 
1d160 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e  works like %s in
1d170 20 74 68 61 74 20 69 74 20 73 75 62 73 74 69 74   that it substit
1d180 75 74 65 73 20 61 20 6e 75 6c 2d 74 65 72 6d 69  utes a nul-termi
1d190 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20  nated.** string 
1d1a0 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e  from the argumen
1d1b0 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20  t list.  But %q 
1d1c0 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65  also doubles eve
1d1d0 72 79 20 27 5c 27 27 20 63 68 61 72 61 63 74 65  ry '\'' characte
1d1e0 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69  r..** %q is desi
1d1f0 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73  gned for use ins
1d200 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74  ide a string lit
1d210 65 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62  eral.)^  By doub
1d220 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a  ling each '\''.*
1d230 2a 20 63 68 61 72 61 63 74 65 72 20 69 74 20 65  * character it e
1d240 73 63 61 70 65 73 20 74 68 61 74 20 63 68 61 72  scapes that char
1d250 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73  acter and allows
1d260 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74   it to be insert
1d270 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73  ed into.** the s
1d280 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72  tring..**.** For
1d290 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65   example, assume
1d2a0 20 74 68 65 20 73 74 72 69 6e 67 20 76 61 72 69   the string vari
1d2b0 61 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61  able zText conta
1d2c0 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c  ins text as foll
1d2d0 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
1d2e0 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1d2f0 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22   char *zText = "
1d300 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79  It's a happy day
1d310 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  !";.** </pre></b
1d320 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1d330 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69   One can use thi
1d340 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c  s text in an SQL
1d350 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f   statement as fo
1d360 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
1d370 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1d380 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20  *  char *zSQL = 
1d390 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
1d3a0 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62  "INSERT INTO tab
1d3b0 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27 29 22  le VALUES('%q')"
1d3c0 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71  , zText);.**  sq
1d3d0 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a  lite3_exec(db, z
1d3e0 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a  SQL, 0, 0, 0);.*
1d3f0 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  *  sqlite3_free(
1d400 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  zSQL);.** </pre>
1d410 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1d420 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 20  .** Because the 
1d430 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67  %q format string
1d440 20 69 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c   is used, the '\
1d450 27 27 20 63 68 61 72 61 63 74 65 72 20 69 6e 20  '' character in 
1d460 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61  zText.** is esca
1d470 70 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20  ped and the SQL 
1d480 67 65 6e 65 72 61 74 65 64 20 69 73 20 61 73 20  generated is as 
1d490 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
1d4a0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1d4b0 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f  .**  INSERT INTO
1d4c0 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27   table1 VALUES('
1d4d0 49 74 27 27 73 20 61 20 68 61 70 70 79 20 64 61  It''s a happy da
1d4e0 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  y!').** </pre></
1d4f0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
1d500 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72 65 63  * This is correc
1d510 74 2e 20 20 48 61 64 20 77 65 20 75 73 65 64 20  t.  Had we used 
1d520 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71  %s instead of %q
1d530 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65 64 20  , the generated 
1d540 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76  SQL.** would hav
1d550 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68  e looked like th
1d560 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  is:.**.** <block
1d570 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1d580 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
1d590 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 73 20  e1 VALUES('It's 
1d5a0 61 20 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a  a happy day!');.
1d5b0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1d5c0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  quote>.**.** Thi
1d5d0 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65  s second example
1d5e0 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61   is an SQL synta
1d5f0 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67  x error.  As a g
1d600 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20  eneral rule you 
1d610 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73  should.** always
1d620 20 75 73 65 20 25 71 20 69 6e 73 74 65 61 64 20   use %q instead 
1d630 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72  of %s when inser
1d640 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61  ting text into a
1d650 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e   string literal.
1d660 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20  .**.** ^(The %Q 
1d670 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b  option works lik
1d680 65 20 25 71 20 65 78 63 65 70 74 20 69 74 20 61  e %q except it a
1d690 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20  lso adds single 
1d6a0 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a  quotes around.**
1d6b0 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20   the outside of 
1d6c0 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67  the total string
1d6d0 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c  .  Additionally,
1d6e0 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
1d6f0 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75  r in the.** argu
1d700 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e  ment list is a N
1d710 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20  ULL pointer, %Q 
1d720 73 75 62 73 74 69 74 75 74 65 73 20 74 68 65 20  substitutes the 
1d730 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74  text "NULL" (wit
1d740 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71  hout.** single q
1d750 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66  uotes).)^  So, f
1d760 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20  or example, one 
1d770 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a  could say:.**.**
1d780 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1d790 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51  e>.**  char *zSQ
1d7a0 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  L = sqlite3_mpri
1d7b0 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f  ntf("INSERT INTO
1d7c0 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51   table VALUES(%Q
1d7d0 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20  )", zText);.**  
1d7e0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c  sqlite3_exec(db,
1d7f0 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b   zSQL, 0, 0, 0);
1d800 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65  .**  sqlite3_fre
1d810 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72  e(zSQL);.** </pr
1d820 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
1d830 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61  **.** The code a
1d840 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72  bove will render
1d850 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73   a correct SQL s
1d860 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20  tatement in the 
1d870 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65  zSQL.** variable
1d880 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65   even if the zTe
1d890 78 74 20 76 61 72 69 61 62 6c 65 20 69 73 20 61  xt variable is a
1d8a0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
1d8b0 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 77 22 20  *.** ^(The "%w" 
1d8c0 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f  formatting optio
1d8d0 6e 20 69 73 20 6c 69 6b 65 20 22 25 71 22 20 65  n is like "%q" e
1d8e0 78 63 65 70 74 20 74 68 61 74 20 69 74 20 65 78  xcept that it ex
1d8f0 70 65 63 74 73 20 74 6f 0a 2a 2a 20 62 65 20 63  pects to.** be c
1d900 6f 6e 74 61 69 6e 65 64 20 77 69 74 68 69 6e 20  ontained within 
1d910 64 6f 75 62 6c 65 2d 71 75 6f 74 65 73 20 69 6e  double-quotes in
1d920 73 74 65 61 64 20 6f 66 20 73 69 6e 67 6c 65 20  stead of single 
1d930 71 75 6f 74 65 73 2c 20 61 6e 64 20 69 74 0a 2a  quotes, and it.*
1d940 2a 20 65 73 63 61 70 65 73 20 74 68 65 20 64 6f  * escapes the do
1d950 75 62 6c 65 2d 71 75 6f 74 65 20 63 68 61 72 61  uble-quote chara
1d960 63 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20  cter instead of 
1d970 74 68 65 20 73 69 6e 67 6c 65 2d 71 75 6f 74 65  the single-quote
1d980 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 2e 29 5e  .** character.)^
1d990 20 20 54 68 65 20 22 25 77 22 20 66 6f 72 6d 61    The "%w" forma
1d9a0 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20  tting option is 
1d9b0 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 73 61 66  intended for saf
1d9c0 65 6c 79 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a  ely inserting.**
1d9d0 20 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d   table and colum
1d9e0 6e 20 6e 61 6d 65 73 20 69 6e 74 6f 20 61 20 63  n names into a c
1d9f0 6f 6e 73 74 72 75 63 74 65 64 20 53 51 4c 20 73  onstructed SQL s
1da00 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  tatement..**.** 
1da10 5e 28 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61  ^(The "%z" forma
1da20 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72  tting option wor
1da30 6b 73 20 6c 69 6b 65 20 22 25 73 22 20 62 75 74  ks like "%s" but
1da40 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64   with the.** add
1da50 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72  ition that after
1da60 20 74 68 65 20 73 74 72 69 6e 67 20 68 61 73 20   the string has 
1da70 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f  been read and co
1da80 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65  pied into.** the
1da90 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65   result, [sqlite
1daa0 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c  3_free()] is cal
1dab0 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74  led on the input
1dac0 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68   string.)^.*/.ch
1dad0 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69  ar *sqlite3_mpri
1dae0 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ntf(const char*,
1daf0 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69  ...);.char *sqli
1db00 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e  te3_vmprintf(con
1db10 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73  st char*, va_lis
1db20 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  t);.char *sqlite
1db30 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63  3_snprintf(int,c
1db40 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
1db50 2c 20 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71  , ...);.char *sq
1db60 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28  lite3_vsnprintf(
1db70 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20  int,char*,const 
1db80 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b  char*, va_list);
1db90 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1dba0 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
1dbb0 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a  ion Subsystem.**
1dbc0 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63  .** The SQLite c
1dbd0 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 20 74  ore uses these t
1dbe0 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f  hree routines fo
1dbf0 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e  r all of its own
1dc00 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d  .** internal mem
1dc10 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
1dc20 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20  eeds. "Core" in 
1dc30 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e  the previous sen
1dc40 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f  tence.** does no
1dc50 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74  t include operat
1dc60 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69  ing-system speci
1dc70 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  fic VFS implemen
1dc80 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20  tation.  The.** 
1dc90 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73  Windows VFS uses
1dca0 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29   native malloc()
1dcb0 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20   and free() for 
1dcc0 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e  some operations.
1dcd0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1dce0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75  te3_malloc() rou
1dcf0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70  tine returns a p
1dd00 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63  ointer to a bloc
1dd10 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61  k.** of memory a
1dd20 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20  t least N bytes 
1dd30 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65  in length, where
1dd40 20 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65   N is the parame
1dd50 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  ter..** ^If sqli
1dd60 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20  te3_malloc() is 
1dd70 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e  unable to obtain
1dd80 20 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65   sufficient free
1dd90 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72  .** memory, it r
1dda0 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
1ddb0 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20  inter.  ^If the 
1ddc0 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a  parameter N to.*
1ddd0 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
1dde0 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65  () is zero or ne
1ddf0 67 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69  gative then sqli
1de00 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74  te3_malloc() ret
1de10 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70  urns.** a NULL p
1de20 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ointer..**.** ^T
1de30 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  he sqlite3_mallo
1de40 63 36 34 28 4e 29 20 72 6f 75 74 69 6e 65 20 77  c64(N) routine w
1de50 6f 72 6b 73 20 6a 75 73 74 20 6c 69 6b 65 0a 2a  orks just like.*
1de60 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
1de70 28 4e 29 20 65 78 63 65 70 74 20 74 68 61 74 20  (N) except that 
1de80 4e 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64  N is an unsigned
1de90 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20   64-bit integer 
1dea0 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20  instead.** of a 
1deb0 73 69 67 6e 65 64 20 33 32 2d 62 69 74 20 69 6e  signed 32-bit in
1dec0 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61  teger..**.** ^Ca
1ded0 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72  lling sqlite3_fr
1dee0 65 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e  ee() with a poin
1def0 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72  ter previously r
1df00 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71  eturned.** by sq
1df10 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f  lite3_malloc() o
1df20 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  r sqlite3_reallo
1df30 63 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 61  c() releases tha
1df40 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74  t memory so.** t
1df50 68 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 20  hat it might be 
1df60 72 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71  reused.  ^The sq
1df70 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75  lite3_free() rou
1df80 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d  tine is.** a no-
1df90 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20  op if is called 
1dfa0 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  with a NULL poin
1dfb0 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20  ter.  Passing a 
1dfc0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
1dfd0 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  to sqlite3_free(
1dfe0 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20  ) is harmless.  
1dff0 41 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 65  After being free
1e000 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f  d, memory.** sho
1e010 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 72  uld neither be r
1e020 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e  ead nor written.
1e030 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70    Even reading p
1e040 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a  reviously freed.
1e050 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20  ** memory might 
1e060 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d  result in a segm
1e070 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f  entation fault o
1e080 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65  r other severe e
1e090 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20  rror..** Memory 
1e0a0 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65  corruption, a se
1e0b0 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74  gmentation fault
1e0c0 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72  , or other sever
1e0d0 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74  e error.** might
1e0e0 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74   result if sqlit
1e0f0 65 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c  e3_free() is cal
1e100 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e  led with a non-N
1e110 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74  ULL pointer that
1e120 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61  .** was not obta
1e130 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65  ined from sqlite
1e140 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71  3_malloc() or sq
1e150 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e  lite3_realloc().
1e160 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1e170 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
1e180 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
1e190 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a  pts to resize a.
1e1a0 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20  ** prior memory 
1e1b0 61 6c 6c 6f 63 61 74 69 6f 6e 20 58 20 74 6f 20  allocation X to 
1e1c0 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  be at least N by
1e1d0 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  tes..** ^If the 
1e1e0 58 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  X parameter to s
1e1f0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58  qlite3_realloc(X
1e200 2c 4e 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c  ,N).** is a NULL
1e210 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74   pointer then it
1e220 73 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64  s behavior is id
1e230 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69  entical to calli
1e240 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  ng.** sqlite3_ma
1e250 6c 6c 6f 63 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20  lloc(N)..** ^If 
1e260 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20  the N parameter 
1e270 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
1e280 6f 63 28 58 2c 4e 29 20 69 73 20 7a 65 72 6f 20  oc(X,N) is zero 
1e290 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74  or.** negative t
1e2a0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
1e2b0 20 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20   is exactly the 
1e2c0 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a  same as calling.
1e2d0 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  ** sqlite3_free(
1e2e0 58 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f  X)..** ^sqlite3_
1e2f0 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74  realloc(X,N) ret
1e300 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
1e310 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  o a memory alloc
1e320 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c  ation.** of at l
1e330 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20  east N bytes in 
1e340 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20  size or NULL if 
1e350 69 6e 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d  insufficient mem
1e360 6f 72 79 20 69 73 20 61 76 61 69 6c 61 62 6c 65  ory is available
1e370 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68  ..** ^If M is th
1e380 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72  e size of the pr
1e390 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20  ior allocation, 
1e3a0 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79  then min(N,M) by
1e3b0 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72  tes.** of the pr
1e3c0 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61  ior allocation a
1e3d0 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74  re copied into t
1e3e0 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
1e3f0 62 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a  buffer returned.
1e400 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65  ** by sqlite3_re
1e410 61 6c 6c 6f 63 28 58 2c 4e 29 20 61 6e 64 20 74  alloc(X,N) and t
1e420 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
1e430 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a  ion is freed..**
1e440 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61   ^If sqlite3_rea
1e450 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e  lloc(X,N) return
1e460 73 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20  s NULL and N is 
1e470 70 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20 74  positive, then t
1e480 68 65 0a 2a 2a 20 70 72 69 6f 72 20 61 6c 6c 6f  he.** prior allo
1e490 63 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 66 72  cation is not fr
1e4a0 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  eed..**.** ^The 
1e4b0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36  sqlite3_realloc6
1e4c0 34 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65  4(X,N) interface
1e4d0 73 20 77 6f 72 6b 73 20 74 68 65 20 73 61 6d 65  s works the same
1e4e0 20 61 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72   as.** sqlite3_r
1e4f0 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 65 78 63 65  ealloc(X,N) exce
1e500 70 74 20 74 68 61 74 20 4e 20 69 73 20 61 20 36  pt that N is a 6
1e510 34 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69  4-bit unsigned i
1e520 6e 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a  nteger instead.*
1e530 2a 20 6f 66 20 61 20 33 32 2d 62 69 74 20 73 69  * of a 32-bit si
1e540 67 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a  gned integer..**
1e550 0a 2a 2a 20 5e 49 66 20 58 20 69 73 20 61 20 6d  .** ^If X is a m
1e560 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1e570 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61   previously obta
1e580 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65  ined from sqlite
1e590 33 5f 6d 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73  3_malloc(),.** s
1e5a0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28  qlite3_malloc64(
1e5b0 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  ), sqlite3_reall
1e5c0 6f 63 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33  oc(), or sqlite3
1e5d0 5f 72 65 61 6c 6c 6f 63 36 34 28 29 2c 20 74 68  _realloc64(), th
1e5e0 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73  en.** sqlite3_ms
1e5f0 69 7a 65 28 58 29 20 72 65 74 75 72 6e 73 20 74  ize(X) returns t
1e600 68 65 20 73 69 7a 65 20 6f 66 20 74 68 61 74 20  he size of that 
1e610 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1e620 6e 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e  n in bytes..** ^
1e630 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  The value return
1e640 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 73  ed by sqlite3_ms
1e650 69 7a 65 28 58 29 20 6d 69 67 68 74 20 62 65 20  ize(X) might be 
1e660 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20  larger than the 
1e670 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74  number.** of byt
1e680 65 73 20 72 65 71 75 65 73 74 65 64 20 77 68 65  es requested whe
1e690 6e 20 58 20 77 61 73 20 61 6c 6c 6f 63 61 74 65  n X was allocate
1e6a0 64 2e 20 20 5e 49 66 20 58 20 69 73 20 61 20 4e  d.  ^If X is a N
1e6b0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
1e6c0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a  .** sqlite3_msiz
1e6d0 65 28 58 29 20 72 65 74 75 72 6e 73 20 7a 65 72  e(X) returns zer
1e6e0 6f 2e 20 20 49 66 20 58 20 70 6f 69 6e 74 73 20  o.  If X points 
1e6f0 74 6f 20 73 6f 6d 65 74 68 69 6e 67 20 74 68 61  to something tha
1e700 74 20 69 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20  t is not.** the 
1e710 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d  beginning of mem
1e720 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20  ory allocation, 
1e730 6f 72 20 69 66 20 69 74 20 70 6f 69 6e 74 73 20  or if it points 
1e740 74 6f 20 61 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a  to a formerly.**
1e750 20 76 61 6c 69 64 20 6d 65 6d 6f 72 79 20 61 6c   valid memory al
1e760 6c 6f 63 61 74 69 6f 6e 20 74 68 61 74 20 68 61  location that ha
1e770 73 20 6e 6f 77 20 62 65 65 6e 20 66 72 65 65 64  s now been freed
1e780 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
1e790 69 6f 72 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65  ior.** of sqlite
1e7a0 33 5f 6d 73 69 7a 65 28 58 29 20 69 73 20 75 6e  3_msize(X) is un
1e7b0 64 65 66 69 6e 65 64 20 61 6e 64 20 70 6f 73 73  defined and poss
1e7c0 69 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a  ibly harmful..**
1e7d0 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20  .** ^The memory 
1e7e0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
1e7f0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c 20 73 71  te3_malloc(), sq
1e800 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c  lite3_realloc(),
1e810 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
1e820 6f 63 36 34 28 29 2c 20 61 6e 64 20 73 71 6c 69  oc64(), and sqli
1e830 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29 0a  te3_realloc64().
1e840 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69  ** is always ali
1e850 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74  gned to at least
1e860 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64   an 8 byte bound
1e870 61 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20  ary, or to a.** 
1e880 34 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20  4 byte boundary 
1e890 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34  if the [SQLITE_4
1e8a0 5f 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41  _BYTE_ALIGNED_MA
1e8b0 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  LLOC] compile-ti
1e8c0 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20  me.** option is 
1e8d0 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53  used..**.** In S
1e8e0 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
1e8f0 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69  5.0 and 3.5.1, i
1e900 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74  t was possible t
1e910 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20  o define.** the 
1e920 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f  SQLITE_OMIT_MEMO
1e930 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68  RY_ALLOCATION wh
1e940 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20  ich would cause 
1e950 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20  the built-in.** 
1e960 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
1e970 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
1e980 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20   to be omitted. 
1e990 20 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79   That capability
1e9a0 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72  .** is no longer
1e9b0 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79   provided.  Only
1e9c0 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79   built-in memory
1e9d0 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20   allocators can 
1e9e0 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50  be used..**.** P
1e9f0 72 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76  rior to SQLite v
1ea00 65 72 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74  ersion 3.7.10, t
1ea10 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e  he Windows OS in
1ea20 74 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61  terface layer ca
1ea30 6c 6c 65 64 0a 2a 2a 20 74 68 65 20 73 79 73 74  lled.** the syst
1ea40 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  em malloc() and 
1ea50 66 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20  free() directly 
1ea60 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a  when converting.
1ea70 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74  ** filenames bet
1ea80 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65  ween the UTF-8 e
1ea90 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20  ncoding used by 
1eaa0 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68  SQLite.** and wh
1eab0 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20  atever filename 
1eac0 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64  encoding is used
1ead0 20 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c   by the particul
1eae0 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e  ar Windows.** in
1eaf0 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d  stallation.  Mem
1eb00 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
1eb10 72 72 6f 72 73 20 77 65 72 65 20 64 65 74 65 63  rrors were detec
1eb20 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79  ted, but.** they
1eb30 20 77 65 72 65 20 72 65 70 6f 72 74 65 64 20 62   were reported b
1eb40 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43  ack as [SQLITE_C
1eb50 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b  ANTOPEN] or.** [
1eb60 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61  SQLITE_IOERR] ra
1eb70 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
1eb80 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20  E_NOMEM]..**.** 
1eb90 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75  The pointer argu
1eba0 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65  ments to [sqlite
1ebb0 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73  3_free()] and [s
1ebc0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1ebd0 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74  ].** must be eit
1ebe0 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65  her NULL or else
1ebf0 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e   pointers obtain
1ec00 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a  ed from a prior.
1ec10 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  ** invocation of
1ec20 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1ec30 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
1ec40 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20  realloc()] that 
1ec50 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20  have.** not yet 
1ec60 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a  been released..*
1ec70 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  *.** The applica
1ec80 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65  tion must not re
1ec90 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20  ad or write any 
1eca0 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f  part of.** a blo
1ecb0 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74  ck of memory aft
1ecc0 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72  er it has been r
1ecd0 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a  eleased using.**
1ece0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1ecf0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
1ed00 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69  alloc()]..*/.voi
1ed10 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  d *sqlite3_mallo
1ed20 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71  c(int);.void *sq
1ed30 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 73  lite3_malloc64(s
1ed40 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a  qlite3_uint64);.
1ed50 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65  void *sqlite3_re
1ed60 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74  alloc(void*, int
1ed70 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  );.void *sqlite3
1ed80 5f 72 65 61 6c 6c 6f 63 36 34 28 76 6f 69 64 2a  _realloc64(void*
1ed90 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  , sqlite3_uint64
1eda0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
1edb0 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 73 71 6c  free(void*);.sql
1edc0 69 74 65 33 5f 75 69 6e 74 36 34 20 73 71 6c 69  ite3_uint64 sqli
1edd0 74 65 33 5f 6d 73 69 7a 65 28 76 6f 69 64 2a 29  te3_msize(void*)
1ede0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1edf0 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61  F: Memory Alloca
1ee00 74 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a  tor Statistics.*
1ee10 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76  *.** SQLite prov
1ee20 69 64 65 73 20 74 68 65 73 65 20 74 77 6f 20 69  ides these two i
1ee30 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20 72 65  nterfaces for re
1ee40 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73  porting on the s
1ee50 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20  tatus.** of the 
1ee60 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1ee70 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  )], [sqlite3_fre
1ee80 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  e()], and [sqlit
1ee90 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a  e3_realloc()].**
1eea0 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68   routines, which
1eeb0 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d   form the built-
1eec0 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
1eed0 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a  tion subsystem..
1eee0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  **.** ^The [sqli
1eef0 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
1ef00 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  )] routine retur
1ef10 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
1ef20 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d   bytes.** of mem
1ef30 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75  ory currently ou
1ef40 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f  tstanding (mallo
1ef50 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65  ced but not free
1ef60 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  d)..** ^The [sql
1ef70 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
1ef80 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65  water()] routine
1ef90 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78   returns the max
1efa0 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66  imum.** value of
1efb0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1efc0 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74  _used()] since t
1efd0 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61  he high-water ma
1efe0 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72  rk.** was last r
1eff0 65 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75  eset.  ^The valu
1f000 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  es returned by [
1f010 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
1f020 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73  sed()] and.** [s
1f030 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
1f040 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75  ghwater()] inclu
1f050 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a  de any overhead.
1f060 2a 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c 69  ** added by SQLi
1f070 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d  te in its implem
1f080 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  entation of [sql
1f090 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a  ite3_malloc()],.
1f0a0 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68  ** but not overh
1f0b0 65 61 64 20 61 64 64 65 64 20 62 79 20 74 68 65  ead added by the
1f0c0 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20   any underlying 
1f0d0 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a  system library.*
1f0e0 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  * routines that 
1f0f0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1f100 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a  )] may call..**.
1f110 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68  ** ^The memory h
1f120 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69  igh-water mark i
1f130 73 20 72 65 73 65 74 20 74 6f 20 74 68 65 20 63  s reset to the c
1f140 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a  urrent value of.
1f150 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  ** [sqlite3_memo
1f160 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e  ry_used()] if an
1f170 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61  d only if the pa
1f180 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73  rameter to.** [s
1f190 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
1f1a0 67 68 77 61 74 65 72 28 29 5d 20 69 73 20 74 72  ghwater()] is tr
1f1b0 75 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20  ue.  ^The value 
1f1c0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b  returned.** by [
1f1d0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
1f1e0 69 67 68 77 61 74 65 72 28 31 29 5d 20 69 73 20  ighwater(1)] is 
1f1f0 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d  the high-water m
1f200 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  ark.** prior to 
1f210 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71  the reset..*/.sq
1f220 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
1f230 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
1f240 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69  void);.sqlite3_i
1f250 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d  nt64 sqlite3_mem
1f260 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e  ory_highwater(in
1f270 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f  t resetFlag);../
1f280 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50  *.** CAPI3REF: P
1f290 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d  seudo-Random Num
1f2a0 62 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a  ber Generator.**
1f2b0 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61  .** SQLite conta
1f2c0 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69  ins a high-quali
1f2d0 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d  ty pseudo-random
1f2e0 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f   number generato
1f2f0 72 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f  r (PRNG) used to
1f300 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f  .** select rando
1f310 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44  m [ROWID | ROWID
1f320 73 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e  s] when insertin
1f330 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e  g new records in
1f340 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a  to a table that.
1f350 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73 20  ** already uses 
1f360 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73  the largest poss
1f370 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54  ible [ROWID].  T
1f380 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20  he PRNG is also 
1f390 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20  used for.** the 
1f3a0 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28  build-in random(
1f3b0 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62  ) and randomblob
1f3c0 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  () SQL functions
1f3d0 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  .  This interfac
1f3e0 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c  e allows.** appl
1f3f0 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65  ications to acce
1f400 73 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47  ss the same PRNG
1f410 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f   for other purpo
1f420 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61  ses..**.** ^A ca
1f430 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69  ll to this routi
1f440 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65  ne stores N byte
1f450 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20  s of randomness 
1f460 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a  into buffer P..*
1f470 2a 20 5e 54 68 65 20 50 20 70 61 72 61 6d 65 74  * ^The P paramet
1f480 65 72 20 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c  er can be a NULL
1f490 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
1f4a0 5e 49 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ^If this routine
1f4b0 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 70 72   has not been pr
1f4c0 65 76 69 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20  eviously called 
1f4d0 6f 72 20 69 66 20 74 68 65 20 70 72 65 76 69 6f  or if the previo
1f4e0 75 73 0a 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e  us.** call had N
1f4f0 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 6f   less than one o
1f500 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  r a NULL pointer
1f510 20 66 6f 72 20 50 2c 20 74 68 65 6e 20 74 68 65   for P, then the
1f520 20 50 52 4e 47 20 69 73 0a 2a 2a 20 73 65 65 64   PRNG is.** seed
1f530 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e  ed using randomn
1f540 65 73 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ess obtained fro
1f550 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  m the xRandomnes
1f560 73 20 6d 65 74 68 6f 64 20 6f 66 0a 2a 2a 20 74  s method of.** t
1f570 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
1f580 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
1f590 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 65 76  .** ^If the prev
1f5a0 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69  ious call to thi
1f5b0 73 20 72 6f 75 74 69 6e 65 20 68 61 64 20 61 6e  s routine had an
1f5c0 20 4e 20 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20   N of 1 or more 
1f5d0 61 6e 64 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c  and a.** non-NUL
1f5e0 4c 20 50 20 74 68 65 6e 20 74 68 65 20 70 73 65  L P then the pse
1f5f0 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69  udo-randomness i
1f600 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69  s generated.** i
1f610 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69  nternally and wi
1f620 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74  thout recourse t
1f630 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  o the [sqlite3_v
1f640 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a  fs] xRandomness.
1f650 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f  ** method..*/.vo
1f660 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f  id sqlite3_rando
1f670 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69  mness(int N, voi
1f680 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  d *P);../*.** CA
1f690 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d  PI3REF: Compile-
1f6a0 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69  Time Authorizati
1f6b0 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20  on Callbacks.** 
1f6c0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
1f6d0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
1f6e0 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 6e  ine registers an
1f6f0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1f700 62 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74  back with a part
1f710 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62  icular.** [datab
1f720 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c  ase connection],
1f730 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65   supplied in the
1f740 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
1f750 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69  .** ^The authori
1f760 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
1f770 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73  invoked as SQL s
1f780 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65  tatements are be
1f790 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20  ing compiled.** 
1f7a0 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  by [sqlite3_prep
1f7b0 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61  are()] or its va
1f7c0 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f  riants [sqlite3_
1f7d0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a  prepare_v2()],.*
1f7e0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
1f7f0 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c  re16()] and [sql
1f800 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
1f810 32 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f  2()].  ^At vario
1f820 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72  us.** points dur
1f830 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74  ing the compilat
1f840 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20  ion process, as 
1f850 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 63  logic is being c
1f860 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72  reated.** to per
1f870 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74  form various act
1f880 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72  ions, the author
1f890 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
1f8a0 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73   invoked to.** s
1f8b0 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 69  ee if those acti
1f8c0 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e  ons are allowed.
1f8d0 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65    ^The authorize
1f8e0 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c  r callback shoul
1f8f0 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  d.** return [SQL
1f900 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77  ITE_OK] to allow
1f910 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51   the action, [SQ
1f920 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20  LITE_IGNORE] to 
1f930 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20  disallow the.** 
1f940 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20  specific action 
1f950 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51  but allow the SQ
1f960 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63  L statement to c
1f970 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a  ontinue to be.**
1f980 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53   compiled, or [S
1f990 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63  QLITE_DENY] to c
1f9a0 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20  ause the entire 
1f9b0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  SQL statement to
1f9c0 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20   be.** rejected 
1f9d0 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20  with an error.  
1f9e0 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ^If the authoriz
1f9f0 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  er callback retu
1fa00 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65  rns.** any value
1fa10 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
1fa20 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51  ITE_IGNORE], [SQ
1fa30 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51  LITE_OK], or [SQ
1fa40 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68  LITE_DENY].** th
1fa50 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  en the [sqlite3_
1fa60 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
1fa70 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c   equivalent call
1fa80 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a   that triggered.
1fa90 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ** the authorize
1faa0 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68  r will fail with
1fab0 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
1fac0 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  e..**.** When th
1fad0 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
1fae0 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ns [SQLITE_OK], 
1faf0 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f  that means the o
1fb00 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75  peration.** requ
1fb10 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57  ested is ok.  ^W
1fb20 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
1fb30 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
1fb40 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b  _DENY], the.** [
1fb50 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1fb60 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c  v2()] or equival
1fb70 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72  ent call that tr
1fb80 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61  iggered the.** a
1fb90 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66  uthorizer will f
1fba0 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ail with an erro
1fbb0 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69  r message explai
1fbc0 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63  ning that.** acc
1fbd0 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a  ess is denied. .
1fbe0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
1fbf0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1fc00 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1fc10 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20  lback is a copy 
1fc20 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  of the third.** 
1fc30 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1fc40 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
1fc50 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66  horizer() interf
1fc60 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64  ace. ^The second
1fc70 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f   parameter.** to
1fc80 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
1fc90 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c   an integer [SQL
1fca0 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f  ITE_COPY | actio
1fcb0 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65  n code] that spe
1fcc0 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61  cifies.** the pa
1fcd0 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20  rticular action 
1fce0 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
1fcf0 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74 68 72  . ^The third thr
1fd00 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d  ough sixth param
1fd10 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20  eters.** to the 
1fd20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72  callback are zer
1fd30 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
1fd40 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69  ings that contai
1fd50 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  n additional.** 
1fd60 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68  details about th
1fd70 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  e action to be a
1fd80 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a  uthorized..**.**
1fd90 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20   ^If the action 
1fda0 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  code is [SQLITE_
1fdb0 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65  READ].** and the
1fdc0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1fdd0 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  s [SQLITE_IGNORE
1fde0 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70  ] then the.** [p
1fdf0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1fe00 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  t] statement is 
1fe10 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73  constructed to s
1fe20 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e  ubstitute.** a N
1fe30 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61  ULL value in pla
1fe40 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20  ce of the table 
1fe50 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c  column that woul
1fe60 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72  d have.** been r
1fe70 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f  ead if [SQLITE_O
1fe80 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75  K] had been retu
1fe90 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49  rned.  The [SQLI
1fea0 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65  TE_IGNORE].** re
1feb0 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64  turn can be used
1fec0 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72   to deny an untr
1fed0 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73  usted user acces
1fee0 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a  s to individual.
1fef0 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20  ** columns of a 
1ff00 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68  table..** ^If th
1ff10 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73  e action code is
1ff20 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d   [SQLITE_DELETE]
1ff30 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63   and the callbac
1ff40 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51  k returns.** [SQ
1ff50 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65  LITE_IGNORE] the
1ff60 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f  n the [DELETE] o
1ff70 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64  peration proceed
1ff80 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72  s but the.** [tr
1ff90 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74  uncate optimizat
1ffa0 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64  ion] is disabled
1ffb0 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72   and all rows ar
1ffc0 65 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69  e deleted indivi
1ffd0 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e  dually..**.** An
1ffe0 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75   authorizer is u
1fff0 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  sed when [sqlite
20000 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70  3_prepare | prep
20010 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74  aring].** SQL st
20020 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e  atements from an
20030 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63   untrusted sourc
20040 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61  e, to ensure tha
20050 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
20060 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74  ents.** do not t
20070 72 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74  ry to access dat
20080 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61  a they are not a
20090 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f  llowed to see, o
200a0 72 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e  r that they do n
200b0 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65  ot.** try to exe
200c0 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73  cute malicious s
200d0 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64  tatements that d
200e0 61 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61  amage the databa
200f0 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d  se.  For.** exam
20100 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74  ple, an applicat
20110 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20  ion may allow a 
20120 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72  user to enter ar
20130 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71  bitrary.** SQL q
20140 75 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75  ueries for evalu
20150 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62  ation by a datab
20160 61 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70  ase.  But the ap
20170 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a  plication does.*
20180 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75  * not want the u
20190 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74  ser to be able t
201a0 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79  o make arbitrary
201b0 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a   changes to the.
201c0 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e  ** database.  An
201d0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c   authorizer coul
201e0 64 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e  d then be put in
201f0 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65   place while the
20200 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64  .** user-entered
20210 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73   SQL is being [s
20220 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c  qlite3_prepare |
20230 20 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a   prepared] that.
20240 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65  ** disallows eve
20250 72 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b  rything except [
20260 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
20270 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63  ts..**.** Applic
20280 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64  ations that need
20290 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20   to process SQL 
202a0 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73  from untrusted s
202b0 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20  ources.** might 
202c0 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f  also consider lo
202d0 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20  wering resource 
202e0 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71  limits using [sq
202f0 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a  lite3_limit()].*
20300 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64  * and limiting d
20310 61 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 69  atabase size usi
20320 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65  ng the [max_page
20330 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d  _count] [PRAGMA]
20340 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20  .** in addition 
20350 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68  to using an auth
20360 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28  orizer..**.** ^(
20370 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75  Only a single au
20380 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20  thorizer can be 
20390 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61  in place on a da
203a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
203b0 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20  n.** at a time. 
203c0 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71   Each call to sq
203d0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
203e0 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74  izer overrides t
203f0 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63  he.** previous c
20400 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65  all.)^  ^Disable
20410 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
20420 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20  by installing a 
20430 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  NULL callback..*
20440 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * The authorizer
20450 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20   is disabled by 
20460 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54  default..**.** T
20470 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
20480 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20  llback must not 
20490 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
204a0 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
204b0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
204c0 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
204d0 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72 69  oked the authori
204e0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  zer callback..**
204f0 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
20500 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
20510 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
20520 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
20530 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
20540 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
20550 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
20560 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
20570 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
20580 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c  **.** ^When [sql
20590 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
205a0 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70 72  )] is used to pr
205b0 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e  epare a statemen
205c0 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d  t, the.** statem
205d0 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d  ent might be re-
205e0 70 72 65 70 61 72 65 64 20 64 75 72 69 6e 67 20  prepared during 
205f0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
20600 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63   due to a .** sc
20610 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65  hema change.  He
20620 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61  nce, the applica
20630 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75  tion should ensu
20640 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63  re that the.** c
20650 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65  orrect authorize
20660 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69  r callback remai
20670 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69  ns in place duri
20680 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ng the [sqlite3_
20690 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  step()]..**.** ^
206a0 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75  Note that the au
206b0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
206c0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c  k is invoked onl
206d0 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c  y during.** [sql
206e0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
206f0 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e  or its variants.
20700 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20    Authorization 
20710 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72  is not.** perfor
20720 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65  med during state
20730 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20  ment evaluation 
20740 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  in [sqlite3_step
20750 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61  ()], unless.** a
20760 73 20 73 74 61 74 65 64 20 69 6e 20 74 68 65 20  s stated in the 
20770 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61  previous paragra
20780 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70  ph, sqlite3_step
20790 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71  () invokes.** sq
207a0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
207b0 28 29 20 74 6f 20 72 65 70 72 65 70 61 72 65 20  () to reprepare 
207c0 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65  a statement afte
207d0 72 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67  r a schema chang
207e0 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
207f0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
20800 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20  (.  sqlite3*,.  
20810 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69  int (*xAuth)(voi
20820 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61  d*,int,const cha
20830 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  r*,const char*,c
20840 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
20850 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20   char*),.  void 
20860 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f  *pUserData.);../
20870 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
20880 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e  uthorizer Return
20890 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65   Codes.**.** The
208a0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
208b0 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f  thorizer | autho
208c0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66  rizer callback f
208d0 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a  unction] must.**
208e0 20 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b   return either [
208f0 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e  SQLITE_OK] or on
20900 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63  e of these two c
20910 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65  onstants in orde
20920 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53  r.** to signal S
20930 51 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f 72  QLite whether or
20940 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20   not the action 
20950 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53  is permitted.  S
20960 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ee the.** [sqlit
20970 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
20980 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64  r | authorizer d
20990 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f  ocumentation] fo
209a0 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
209b0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
209c0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c  ** Note that SQL
209d0 49 54 45 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c  ITE_IGNORE is al
209e0 73 6f 20 75 73 65 64 20 61 73 20 61 20 5b 63 6f  so used as a [co
209f0 6e 66 6c 69 63 74 20 72 65 73 6f 6c 75 74 69 6f  nflict resolutio
20a00 6e 20 6d 6f 64 65 5d 0a 2a 2a 20 72 65 74 75 72  n mode].** retur
20a10 6e 65 64 20 66 72 6f 6d 20 74 68 65 20 5b 73 71  ned from the [sq
20a20 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f  lite3_vtab_on_co
20a30 6e 66 6c 69 63 74 28 29 5d 20 69 6e 74 65 72 66  nflict()] interf
20a40 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ace..*/.#define 
20a50 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20  SQLITE_DENY   1 
20a60 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53    /* Abort the S
20a70 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  QL statement wit
20a80 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64  h an error */.#d
20a90 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e  efine SQLITE_IGN
20aa0 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74  ORE 2   /* Don't
20ab0 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62   allow access, b
20ac0 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74  ut don't generat
20ad0 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f  e an error */../
20ae0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
20af0 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e  uthorizer Action
20b00 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65   Codes.**.** The
20b10 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
20b20 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65  thorizer()] inte
20b30 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20  rface registers 
20b40 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
20b50 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69  ion.** that is i
20b60 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72  nvoked to author
20b70 69 7a 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20  ize certain SQL 
20b80 73 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e  statement action
20b90 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e  s.  The.** secon
20ba0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
20bb0 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  he callback is a
20bc0 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74  n integer code t
20bd0 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  hat specifies.**
20be0 20 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20   what action is 
20bf0 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64  being authorized
20c00 2e 20 20 54 68 65 73 65 20 61 72 65 20 74 68 65  .  These are the
20c10 20 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20   integer action 
20c20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68  codes that.** th
20c30 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
20c40 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73  lback may be pas
20c50 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  sed..**.** These
20c60 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c   action code val
20c70 75 65 73 20 73 69 67 6e 69 66 79 20 77 68 61 74  ues signify what
20c80 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69   kind of operati
20c90 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61  on is to be.** a
20ca0 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20  uthorized.  The 
20cb0 33 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 61  3rd and 4th para
20cc0 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20 61 75  meters to the au
20cd0 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63  thorization.** c
20ce0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
20cf0 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74   will be paramet
20d00 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65  ers or NULL depe
20d10 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f  nding on which o
20d20 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73  f these.** codes
20d30 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20   is used as the 
20d40 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
20d50 2e 20 20 5e 28 54 68 65 20 35 74 68 20 70 61 72  .  ^(The 5th par
20d60 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ameter to the.**
20d70 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
20d80 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65  back is the name
20d90 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
20da0 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22   ("main", "temp"
20db0 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70  ,.** etc.) if ap
20dc0 70 6c 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68  plicable.)^  ^Th
20dd0 65 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 6th parameter 
20de0 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  to the authorize
20df0 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73  r callback.** is
20e00 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
20e10 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67   inner-most trig
20e20 67 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 74  ger or view that
20e30 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
20e40 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73  for.** the acces
20e50 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c  s attempt or NUL
20e60 4c 20 69 66 20 74 68 69 73 20 61 63 63 65 73 73  L if this access
20e70 20 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 65   attempt is dire
20e80 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70  ctly from.** top
20e90 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e  -level SQL code.
20ea0 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  .*/./***********
20eb0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
20ec0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
20ed0 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   3rd ***********
20ee0 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  * 4th **********
20ef0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
20f00 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20  E_CREATE_INDEX  
20f10 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49          1   /* I
20f20 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
20f30 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
20f40 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
20f50 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20  _CREATE_TABLE   
20f60 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61         2   /* Ta
20f70 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
20f80 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
20f90 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
20fa0 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45  CREATE_TEMP_INDE
20fb0 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64  X     3   /* Ind
20fc0 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
20fd0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
20fe0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
20ff0 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45  REATE_TEMP_TABLE
21000 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c       4   /* Tabl
21010 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
21020 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
21030 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
21040 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45  EATE_TEMP_TRIGGE
21050 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67  R   5   /* Trigg
21060 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
21070 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
21080 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
21090 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20  ATE_TEMP_VIEW   
210a0 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e     6   /* View N
210b0 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
210c0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
210d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
210e0 54 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20  TE_TRIGGER      
210f0 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72    7   /* Trigger
21100 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
21110 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
21120 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
21130 45 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20  E_VIEW          
21140 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d   8   /* View Nam
21150 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
21160 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
21170 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45  ne SQLITE_DELETE
21180 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
21190 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  9   /* Table Nam
211a0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
211b0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
211c0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e  e SQLITE_DROP_IN
211d0 44 45 58 20 20 20 20 20 20 20 20 20 20 20 31 30  DEX           10
211e0 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
211f0 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
21200 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
21210 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42   SQLITE_DROP_TAB
21220 4c 45 20 20 20 20 20 20 20 20 20 20 20 31 31 20  LE           11 
21230 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
21240 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
21250 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
21260 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
21270 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32 20 20  _INDEX      12  
21280 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
21290 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
212a0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
212b0 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
212c0 54 41 42 4c 45 20 20 20 20 20 20 31 33 20 20 20  TABLE      13   
212d0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
212e0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
212f0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
21300 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54  LITE_DROP_TEMP_T
21310 52 49 47 47 45 52 20 20 20 20 31 34 20 20 20 2f  RIGGER    14   /
21320 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
21330 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
21340 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
21350 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49  ITE_DROP_TEMP_VI
21360 45 57 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a  EW       15   /*
21370 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
21380 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
21390 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
213a0 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20  TE_DROP_TRIGGER 
213b0 20 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20          16   /* 
213c0 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
213d0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
213e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
213f0 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20  E_DROP_VIEW     
21400 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56         17   /* V
21410 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
21420 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
21430 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
21440 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20 20 20  _INSERT         
21450 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61        18   /* Ta
21460 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
21470 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
21480 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
21490 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20  PRAGMA          
214a0 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61       19   /* Pra
214b0 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74  gma Name     1st
214c0 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a   arg or NULL */.
214d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
214e0 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20  EAD             
214f0 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c      20   /* Tabl
21500 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75  e Name      Colu
21510 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  mn Name     */.#
21520 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45  define SQLITE_SE
21530 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20 20  LECT            
21540 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20     21   /* NULL 
21550 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20             NULL 
21560 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
21570 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41  efine SQLITE_TRA
21580 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20  NSACTION        
21590 20 20 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 74    22   /* Operat
215a0 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ion       NULL  
215b0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
215c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41  fine SQLITE_UPDA
215d0 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
215e0 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   23   /* Table N
215f0 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20  ame      Column 
21600 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
21610 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43  ine SQLITE_ATTAC
21620 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
21630 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65  24   /* Filename
21640 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
21650 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
21660 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48  ne SQLITE_DETACH
21670 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
21680 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  5   /* Database 
21690 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20  Name   NULL     
216a0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
216b0 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54  e SQLITE_ALTER_T
216c0 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 36  ABLE          26
216d0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e     /* Database N
216e0 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  ame   Table Name
216f0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
21700 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20   SQLITE_REINDEX 
21710 20 20 20 20 20 20 20 20 20 20 20 20 20 32 37 20               27 
21720 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
21730 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
21740 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
21750 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20  SQLITE_ANALYZE  
21760 20 20 20 20 20 20 20 20 20 20 20 20 32 38 20 20              28  
21770 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
21780 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
21790 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
217a0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41  QLITE_CREATE_VTA
217b0 42 4c 45 20 20 20 20 20 20 20 20 32 39 20 20 20  BLE        29   
217c0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
217d0 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20     Module Name  
217e0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
217f0 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45  LITE_DROP_VTABLE
21800 20 20 20 20 20 20 20 20 20 20 33 30 20 20 20 2f            30   /
21810 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
21820 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20    Module Name   
21830 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
21840 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20  ITE_FUNCTION    
21850 20 20 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a           31   /*
21860 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
21870 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20   Function Name  
21880 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
21890 54 45 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 20  TE_SAVEPOINT    
218a0 20 20 20 20 20 20 20 20 33 32 20 20 20 2f 2a 20          32   /* 
218b0 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20  Operation       
218c0 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20  Savepoint Name  
218d0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
218e0 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20 20  E_COPY          
218f0 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e          0   /* N
21900 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f  o longer used */
21910 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
21920 52 45 43 55 52 53 49 56 45 20 20 20 20 20 20 20  RECURSIVE       
21930 20 20 20 20 20 33 33 20 20 20 2f 2a 20 4e 55 4c       33   /* NUL
21940 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c  L            NUL
21950 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
21960 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
21970 20 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f   Tracing And Pro
21980 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73  filing Functions
21990 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
219a0 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  te3.**.** These 
219b0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65 70  routines are dep
219c0 72 65 63 61 74 65 64 2e 20 55 73 65 20 74 68 65  recated. Use the
219d0 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f   [sqlite3_trace_
219e0 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a  v2()] interface.
219f0 2a 2a 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68  ** instead of th
21a00 65 20 72 6f 75 74 69 6e 65 73 20 64 65 73 63 72  e routines descr
21a10 69 62 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a  ibed here..**.**
21a20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
21a30 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63  register callbac
21a40 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74  k functions that
21a50 20 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72   can be used for
21a60 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20  .** tracing and 
21a70 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78  profiling the ex
21a80 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73  ecution of SQL s
21a90 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
21aa0 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66   ^The callback f
21ab0 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72  unction register
21ac0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72  ed by sqlite3_tr
21ad0 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ace() is invoked
21ae0 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74   at.** various t
21af0 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c  imes when an SQL
21b00 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65   statement is be
21b10 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69  ing run by [sqli
21b20 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20  te3_step()]..** 
21b30 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61  ^The sqlite3_tra
21b40 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73  ce() callback is
21b50 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20   invoked with a 
21b60 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20  UTF-8 rendering 
21b70 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74  of the.** SQL st
21b80 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20  atement text as 
21b90 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69  the statement fi
21ba0 72 73 74 20 62 65 67 69 6e 73 20 65 78 65 63 75  rst begins execu
21bb0 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74  ting..** ^(Addit
21bc0 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72  ional sqlite3_tr
21bd0 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20  ace() callbacks 
21be0 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61  might occur.** a
21bf0 73 20 65 61 63 68 20 74 72 69 67 67 65 72 65 64  s each triggered
21c00 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65   subprogram is e
21c10 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c  ntered.  The cal
21c20 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67  lbacks for trigg
21c30 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61  ers.** contain a
21c40 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65   UTF-8 SQL comme
21c50 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69 66 69  nt that identifi
21c60 65 73 20 74 68 65 20 74 72 69 67 67 65 72 2e 29  es the trigger.)
21c70 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ^.**.** The [SQL
21c80 49 54 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c  ITE_TRACE_SIZE_L
21c90 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  IMIT] compile-ti
21ca0 6d 65 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65  me option can be
21cb0 20 75 73 65 64 20 74 6f 20 6c 69 6d 69 74 0a 2a   used to limit.*
21cc0 2a 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20  * the length of 
21cd0 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72  [bound parameter
21ce0 5d 20 65 78 70 61 6e 73 69 6f 6e 20 69 6e 20 74  ] expansion in t
21cf0 68 65 20 6f 75 74 70 75 74 20 6f 66 20 73 71 6c  he output of sql
21d00 69 74 65 33 5f 74 72 61 63 65 28 29 2e 0a 2a 2a  ite3_trace()..**
21d10 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63  .** ^The callbac
21d20 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73  k function regis
21d30 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33  tered by sqlite3
21d40 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e  _profile() is in
21d50 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68  voked.** as each
21d60 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66   SQL statement f
21d70 69 6e 69 73 68 65 73 2e 20 20 5e 54 68 65 20 70  inishes.  ^The p
21d80 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20  rofile callback 
21d90 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20  contains.** the 
21da0 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65  original stateme
21db0 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65  nt text and an e
21dc0 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d  stimate of wall-
21dd0 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66  clock time.** of
21de0 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73   how long that s
21df0 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f  tatement took to
21e00 20 72 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66   run.  ^The prof
21e10 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  ile callback.** 
21e20 74 69 6d 65 20 69 73 20 69 6e 20 75 6e 69 74 73  time is in units
21e30 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c   of nanoseconds,
21e40 20 68 6f 77 65 76 65 72 20 74 68 65 20 63 75 72   however the cur
21e50 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74  rent implementat
21e60 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63  ion.** is only c
21e70 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73  apable of millis
21e80 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e  econd resolution
21e90 20 73 6f 20 74 68 65 20 73 69 78 20 6c 65 61 73   so the six leas
21ea0 74 20 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a  t significant.**
21eb0 20 64 69 67 69 74 73 20 69 6e 20 74 68 65 20 74   digits in the t
21ec0 69 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c  ime are meaningl
21ed0 65 73 73 2e 20 20 46 75 74 75 72 65 20 76 65 72  ess.  Future ver
21ee0 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a  sions of SQLite.
21ef0 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76 69 64 65  ** might provide
21f00 20 67 72 65 61 74 65 72 20 72 65 73 6f 6c 75 74   greater resolut
21f10 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66 69  ion on the profi
21f20 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54  ler callback.  T
21f30 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72  he.** sqlite3_pr
21f40 6f 66 69 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e  ofile() function
21f50 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 65   is considered e
21f60 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20  xperimental and 
21f70 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f  is.** subject to
21f80 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72   change in futur
21f90 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
21fa0 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  Lite..*/.SQLITE_
21fb0 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20  DEPRECATED void 
21fc0 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73  *sqlite3_trace(s
21fd0 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64  qlite3*,.   void
21fe0 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c  (*xTrace)(void*,
21ff0 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f  const char*), vo
22000 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  id*);.SQLITE_DEP
22010 52 45 43 41 54 45 44 20 76 6f 69 64 20 2a 73 71  RECATED void *sq
22020 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71  lite3_profile(sq
22030 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28  lite3*,.   void(
22040 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a  *xProfile)(void*
22050 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c  ,const char*,sql
22060 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f  ite3_uint64), vo
22070 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
22080 49 33 52 45 46 3a 20 53 51 4c 20 54 72 61 63 65  I3REF: SQL Trace
22090 20 45 76 65 6e 74 20 43 6f 64 65 73 0a 2a 2a 20   Event Codes.** 
220a0 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45  KEYWORDS: SQLITE
220b0 5f 54 52 41 43 45 0a 2a 2a 0a 2a 2a 20 54 68 65  _TRACE.**.** The
220c0 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 69 64 65  se constants ide
220d0 6e 74 69 66 79 20 63 6c 61 73 73 65 73 20 6f 66  ntify classes of
220e0 20 65 76 65 6e 74 73 20 74 68 61 74 20 63 61 6e   events that can
220f0 20 62 65 20 6d 6f 6e 69 74 6f 72 65 64 0a 2a 2a   be monitored.**
22100 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71 6c 69   using the [sqli
22110 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 5d 20  te3_trace_v2()] 
22120 74 72 61 63 69 6e 67 20 6c 6f 67 69 63 2e 20 20  tracing logic.  
22130 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
22140 6e 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65  nt.** to [sqlite
22150 33 5f 74 72 61 63 65 5f 76 32 28 29 5d 20 69 73  3_trace_v2()] is
22160 20 61 6e 20 4f 52 2d 65 64 20 63 6f 6d 62 69 6e   an OR-ed combin
22170 61 74 69 6f 6e 20 6f 66 20 6f 6e 65 20 6f 72 20  ation of one or 
22180 6d 6f 72 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66  more of.** the f
22190 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e 73 74 61 6e  ollowing constan
221a0 74 73 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20  ts.  ^The first 
221b0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
221c0 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  trace callback.*
221d0 2a 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20  * is one of the 
221e0 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e 73 74 61  following consta
221f0 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 74  nts..**.** New t
22200 72 61 63 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73  racing constants
22210 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
22220 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
22230 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 74 72 61 63 65  ..**.** ^A trace
22240 20 63 61 6c 6c 62 61 63 6b 20 68 61 73 20 66 6f   callback has fo
22250 75 72 20 61 72 67 75 6d 65 6e 74 73 3a 20 78 43  ur arguments: xC
22260 61 6c 6c 62 61 63 6b 28 54 2c 43 2c 50 2c 58 29  allback(T,C,P,X)
22270 2e 0a 2a 2a 20 5e 54 68 65 20 54 20 61 72 67 75  ..** ^The T argu
22280 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 74  ment is one of t
22290 68 65 20 69 6e 74 65 67 65 72 20 74 79 70 65 20  he integer type 
222a0 63 6f 64 65 73 20 61 62 6f 76 65 2e 0a 2a 2a 20  codes above..** 
222b0 5e 54 68 65 20 43 20 61 72 67 75 6d 65 6e 74 20  ^The C argument 
222c0 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
222d0 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72   context pointer
222e0 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68   passed in as th
222f0 65 0a 2a 2a 20 66 6f 75 72 74 68 20 61 72 67 75  e.** fourth argu
22300 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
22310 5f 74 72 61 63 65 5f 76 32 28 29 5d 2e 0a 2a 2a  _trace_v2()]..**
22320 20 54 68 65 20 50 20 61 6e 64 20 58 20 61 72 67   The P and X arg
22330 75 6d 65 6e 74 73 20 61 72 65 20 70 6f 69 6e 74  uments are point
22340 65 72 73 20 77 68 6f 73 65 20 6d 65 61 6e 69 6e  ers whose meanin
22350 67 73 20 64 65 70 65 6e 64 20 6f 6e 20 54 2e 0a  gs depend on T..
22360 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b  **.** <dl>.** [[
22370 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d  SQLITE_TRACE_STM
22380 54 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54  T]] <dt>SQLITE_T
22390 52 41 43 45 5f 53 54 4d 54 3c 2f 64 74 3e 0a 2a  RACE_STMT</dt>.*
223a0 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45  * <dd>^An SQLITE
223b0 5f 54 52 41 43 45 5f 53 54 4d 54 20 63 61 6c 6c  _TRACE_STMT call
223c0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
223d0 77 68 65 6e 20 61 20 70 72 65 70 61 72 65 64 20  when a prepared 
223e0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 66 69 72  statement.** fir
223f0 73 74 20 62 65 67 69 6e 73 20 72 75 6e 6e 69 6e  st begins runnin
22400 67 20 61 6e 64 20 70 6f 73 73 69 62 6c 79 20 61  g and possibly a
22410 74 20 6f 74 68 65 72 20 74 69 6d 65 73 20 64 75  t other times du
22420 72 69 6e 67 20 74 68 65 0a 2a 2a 20 65 78 65 63  ring the.** exec
22430 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 70 72 65  ution of the pre
22440 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 2c  pared statement,
22450 20 73 75 63 68 20 61 73 20 61 74 20 74 68 65 20   such as at the 
22460 73 74 61 72 74 20 6f 66 20 65 61 63 68 0a 2a 2a  start of each.**
22470 20 74 72 69 67 67 65 72 20 73 75 62 70 72 6f 67   trigger subprog
22480 72 61 6d 2e 20 5e 54 68 65 20 50 20 61 72 67 75  ram. ^The P argu
22490 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
224a0 72 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 70 72 65  r to the.** [pre
224b0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
224c0 2e 20 5e 54 68 65 20 58 20 61 72 67 75 6d 65 6e  . ^The X argumen
224d0 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
224e0 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68  o a string which
224f0 0a 2a 2a 20 69 73 20 74 68 65 20 75 6e 65 78 70  .** is the unexp
22500 61 6e 64 65 64 20 53 51 4c 20 74 65 78 74 20 6f  anded SQL text o
22510 66 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  f the prepared s
22520 74 61 74 65 6d 65 6e 74 20 6f 72 20 61 6e 20 53  tatement or an S
22530 51 4c 20 63 6f 6d 6d 65 6e 74 20 0a 2a 2a 20 74  QL comment .** t
22540 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 74 68  hat indicates th
22550 65 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  e invocation of 
22560 61 20 74 72 69 67 67 65 72 2e 20 20 5e 54 68 65  a trigger.  ^The
22570 20 63 61 6c 6c 62 61 63 6b 20 63 61 6e 20 63 6f   callback can co
22580 6d 70 75 74 65 0a 2a 2a 20 74 68 65 20 73 61 6d  mpute.** the sam
22590 65 20 74 65 78 74 20 74 68 61 74 20 77 6f 75 6c  e text that woul
225a0 64 20 68 61 76 65 20 62 65 65 6e 20 72 65 74 75  d have been retu
225b0 72 6e 65 64 20 62 79 20 74 68 65 20 6c 65 67 61  rned by the lega
225c0 63 79 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63  cy [sqlite3_trac
225d0 65 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  e()].** interfac
225e0 65 20 62 79 20 75 73 69 6e 67 20 74 68 65 20 58  e by using the X
225f0 20 61 72 67 75 6d 65 6e 74 20 77 68 65 6e 20 58   argument when X
22600 20 62 65 67 69 6e 73 20 77 69 74 68 20 22 2d 2d   begins with "--
22610 22 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 0a 2a  " and invoking.*
22620 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 70 61 6e  * [sqlite3_expan
22630 64 65 64 5f 73 71 6c 28 50 29 5d 20 6f 74 68 65  ded_sql(P)] othe
22640 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  rwise..**.** [[S
22650 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46  QLITE_TRACE_PROF
22660 49 4c 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  ILE]] <dt>SQLITE
22670 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 3c 2f  _TRACE_PROFILE</
22680 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53  dt>.** <dd>^An S
22690 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46  QLITE_TRACE_PROF
226a0 49 4c 45 20 63 61 6c 6c 62 61 63 6b 20 70 72 6f  ILE callback pro
226b0 76 69 64 65 73 20 61 70 70 72 6f 78 69 6d 61 74  vides approximat
226c0 65 6c 79 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  ely the same.** 
226d0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 69  information as i
226e0 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68  s provided by th
226f0 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  e [sqlite3_profi
22700 6c 65 28 29 5d 20 63 61 6c 6c 62 61 63 6b 2e 0a  le()] callback..
22710 2a 2a 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65  ** ^The P argume
22720 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  nt is a pointer 
22730 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  to the [prepared
22740 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20   statement] and 
22750 74 68 65 0a 2a 2a 20 58 20 61 72 67 75 6d 65 6e  the.** X argumen
22760 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 36 34  t points to a 64
22770 2d 62 69 74 20 69 6e 74 65 67 65 72 20 77 68 69  -bit integer whi
22780 63 68 20 69 73 20 74 68 65 20 65 73 74 69 6d 61  ch is the estima
22790 74 65 64 20 6f 66 0a 2a 2a 20 74 68 65 20 6e 75  ted of.** the nu
227a0 6d 62 65 72 20 6f 66 20 6e 61 6e 6f 73 65 63 6f  mber of nanoseco
227b0 6e 64 20 74 68 61 74 20 74 68 65 20 70 72 65 70  nd that the prep
227c0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 74  ared statement t
227d0 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a 2a 20 5e  ook to run..** ^
227e0 54 68 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45  The SQLITE_TRACE
227f0 5f 50 52 4f 46 49 4c 45 20 63 61 6c 6c 62 61 63  _PROFILE callbac
22800 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65  k is invoked whe
22810 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  n the statement 
22820 66 69 6e 69 73 68 65 73 2e 0a 2a 2a 0a 2a 2a 20  finishes..**.** 
22830 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52  [[SQLITE_TRACE_R
22840 4f 57 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  OW]] <dt>SQLITE_
22850 54 52 41 43 45 5f 52 4f 57 3c 2f 64 74 3e 0a 2a  TRACE_ROW</dt>.*
22860 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45  * <dd>^An SQLITE
22870 5f 54 52 41 43 45 5f 52 4f 57 20 63 61 6c 6c 62  _TRACE_ROW callb
22880 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  ack is invoked w
22890 68 65 6e 65 76 65 72 20 61 20 70 72 65 70 61 72  henever a prepar
228a0 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  ed.** statement 
228b0 67 65 6e 65 72 61 74 65 73 20 61 20 73 69 6e 67  generates a sing
228c0 6c 65 20 72 6f 77 20 6f 66 20 72 65 73 75 6c 74  le row of result
228d0 2e 20 20 0a 2a 2a 20 5e 54 68 65 20 50 20 61 72  .  .** ^The P ar
228e0 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
228f0 74 65 72 20 74 6f 20 74 68 65 20 5b 70 72 65 70  ter to the [prep
22900 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
22910 61 6e 64 20 74 68 65 0a 2a 2a 20 58 20 61 72 67  and the.** X arg
22920 75 6d 65 6e 74 20 69 73 20 75 6e 75 73 65 64 2e  ument is unused.
22930 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
22940 54 52 41 43 45 5f 43 4c 4f 53 45 5d 5d 20 3c 64  TRACE_CLOSE]] <d
22950 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43  t>SQLITE_TRACE_C
22960 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LOSE</dt>.** <dd
22970 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43  >^An SQLITE_TRAC
22980 45 5f 43 4c 4f 53 45 20 63 61 6c 6c 62 61 63 6b  E_CLOSE callback
22990 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   is invoked when
229a0 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63   a database.** c
229b0 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73  onnection closes
229c0 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 61 72 67 75  ..** ^The P argu
229d0 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
229e0 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61  r to the [databa
229f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f  se connection] o
22a00 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 74 68 65  bject.** and the
22a10 20 58 20 61 72 67 75 6d 65 6e 74 20 69 73 20 75   X argument is u
22a20 6e 75 73 65 64 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  nused..** </dl>.
22a30 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22a40 45 5f 54 52 41 43 45 5f 53 54 4d 54 20 20 20 20  E_TRACE_STMT    
22a50 20 20 20 30 78 30 31 0a 23 64 65 66 69 6e 65 20     0x01.#define 
22a60 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f  SQLITE_TRACE_PRO
22a70 46 49 4c 45 20 20 20 20 30 78 30 32 0a 23 64 65  FILE    0x02.#de
22a80 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43  fine SQLITE_TRAC
22a90 45 5f 52 4f 57 20 20 20 20 20 20 20 20 30 78 30  E_ROW        0x0
22aa0 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
22ab0 5f 54 52 41 43 45 5f 43 4c 4f 53 45 20 20 20 20  _TRACE_CLOSE    
22ac0 20 20 30 78 30 38 0a 0a 2f 2a 0a 2a 2a 20 43 41    0x08../*.** CA
22ad0 50 49 33 52 45 46 3a 20 53 51 4c 20 54 72 61 63  PI3REF: SQL Trac
22ae0 65 20 48 6f 6f 6b 0a 2a 2a 20 4d 45 54 48 4f 44  e Hook.** METHOD
22af0 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
22b00 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61  ^The sqlite3_tra
22b10 63 65 5f 76 32 28 44 2c 4d 2c 58 2c 50 29 20 69  ce_v2(D,M,X,P) i
22b20 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
22b30 72 73 20 61 20 74 72 61 63 65 20 63 61 6c 6c 62  rs a trace callb
22b40 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ack.** function 
22b50 58 20 61 67 61 69 6e 73 74 20 5b 64 61 74 61 62  X against [datab
22b60 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
22b70 44 2c 20 75 73 69 6e 67 20 70 72 6f 70 65 72 74  D, using propert
22b80 79 20 6d 61 73 6b 20 4d 0a 2a 2a 20 61 6e 64 20  y mask M.** and 
22b90 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 20  context pointer 
22ba0 50 2e 20 20 5e 49 66 20 74 68 65 20 58 20 63 61  P.  ^If the X ca
22bb0 6c 6c 62 61 63 6b 20 69 73 0a 2a 2a 20 4e 55 4c  llback is.** NUL
22bc0 4c 20 6f 72 20 69 66 20 74 68 65 20 4d 20 6d 61  L or if the M ma
22bd0 73 6b 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e  sk is zero, then
22be0 20 74 72 61 63 69 6e 67 20 69 73 20 64 69 73 61   tracing is disa
22bf0 62 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 4d 20  bled.  The.** M 
22c00 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
22c10 62 65 20 74 68 65 20 62 69 74 77 69 73 65 20 4f  be the bitwise O
22c20 52 2d 65 64 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  R-ed combination
22c30 20 6f 66 0a 2a 2a 20 7a 65 72 6f 20 6f 72 20 6d   of.** zero or m
22c40 6f 72 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43  ore [SQLITE_TRAC
22c50 45 5d 20 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a  E] constants..**
22c60 0a 2a 2a 20 5e 45 61 63 68 20 63 61 6c 6c 20 74  .** ^Each call t
22c70 6f 20 65 69 74 68 65 72 20 73 71 6c 69 74 65 33  o either sqlite3
22c80 5f 74 72 61 63 65 28 29 20 6f 72 20 73 71 6c 69  _trace() or sqli
22c90 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 20 6f  te3_trace_v2() o
22ca0 76 65 72 72 69 64 65 73 20 0a 2a 2a 20 28 63 61  verrides .** (ca
22cb0 6e 63 65 6c 73 29 20 61 6e 79 20 70 72 69 6f 72  ncels) any prior
22cc0 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
22cd0 33 5f 74 72 61 63 65 28 29 20 6f 72 20 73 71 6c  3_trace() or sql
22ce0 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 2e  ite3_trace_v2().
22cf0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 58 20 63 61  .**.** ^The X ca
22d00 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
22d10 64 20 77 68 65 6e 65 76 65 72 20 61 6e 79 20 6f  d whenever any o
22d20 66 20 74 68 65 20 65 76 65 6e 74 73 20 69 64 65  f the events ide
22d30 6e 74 69 66 69 65 64 20 62 79 20 0a 2a 2a 20 6d  ntified by .** m
22d40 61 73 6b 20 4d 20 6f 63 63 75 72 2e 20 20 5e 54  ask M occur.  ^T
22d50 68 65 20 69 6e 74 65 67 65 72 20 72 65 74 75 72  he integer retur
22d60 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 74 68 65  n value from the
22d70 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 63 75 72   callback is cur
22d80 72 65 6e 74 6c 79 0a 2a 2a 20 69 67 6e 6f 72 65  rently.** ignore
22d90 64 2c 20 74 68 6f 75 67 68 20 74 68 69 73 20 6d  d, though this m
22da0 61 79 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74  ay change in fut
22db0 75 72 65 20 72 65 6c 65 61 73 65 73 2e 20 20 43  ure releases.  C
22dc0 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 6d 70 6c 65  allback.** imple
22dd0 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c  mentations shoul
22de0 64 20 72 65 74 75 72 6e 20 7a 65 72 6f 20 74 6f  d return zero to
22df0 20 65 6e 73 75 72 65 20 66 75 74 75 72 65 20 63   ensure future c
22e00 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a  ompatibility..**
22e10 0a 2a 2a 20 5e 41 20 74 72 61 63 65 20 63 61 6c  .** ^A trace cal
22e20 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
22e30 20 77 69 74 68 20 66 6f 75 72 20 61 72 67 75 6d   with four argum
22e40 65 6e 74 73 3a 20 63 61 6c 6c 62 61 63 6b 28 54  ents: callback(T
22e50 2c 43 2c 50 2c 58 29 2e 0a 2a 2a 20 5e 54 68 65  ,C,P,X)..** ^The
22e60 20 54 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f   T argument is o
22e70 6e 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54  ne of the [SQLIT
22e80 45 5f 54 52 41 43 45 5d 0a 2a 2a 20 63 6f 6e 73  E_TRACE].** cons
22e90 74 61 6e 74 73 20 74 6f 20 69 6e 64 69 63 61 74  tants to indicat
22ea0 65 20 77 68 79 20 74 68 65 20 63 61 6c 6c 62 61  e why the callba
22eb0 63 6b 20 77 61 73 20 69 6e 76 6f 6b 65 64 2e 0a  ck was invoked..
22ec0 2a 2a 20 5e 54 68 65 20 43 20 61 72 67 75 6d 65  ** ^The C argume
22ed0 6e 74 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  nt is a copy of 
22ee0 74 68 65 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e  the context poin
22ef0 74 65 72 2e 0a 2a 2a 20 54 68 65 20 50 20 61 6e  ter..** The P an
22f00 64 20 58 20 61 72 67 75 6d 65 6e 74 73 20 61 72  d X arguments ar
22f10 65 20 70 6f 69 6e 74 65 72 73 20 77 68 6f 73 65  e pointers whose
22f20 20 6d 65 61 6e 69 6e 67 73 20 64 65 70 65 6e 64   meanings depend
22f30 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   on T..**.** The
22f40 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76   sqlite3_trace_v
22f50 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  2() interface is
22f60 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 72 65 70   intended to rep
22f70 6c 61 63 65 20 74 68 65 20 6c 65 67 61 63 79 0a  lace the legacy.
22f80 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73  ** interfaces [s
22f90 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d 20  qlite3_trace()] 
22fa0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f  and [sqlite3_pro
22fb0 66 69 6c 65 28 29 5d 2c 20 62 6f 74 68 20 6f 66  file()], both of
22fc0 20 77 68 69 63 68 0a 2a 2a 20 61 72 65 20 64 65   which.** are de
22fd0 70 72 65 63 61 74 65 64 2e 0a 2a 2f 0a 69 6e 74  precated..*/.int
22fe0 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76   sqlite3_trace_v
22ff0 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20  2(.  sqlite3*,. 
23000 20 75 6e 73 69 67 6e 65 64 20 75 4d 61 73 6b 2c   unsigned uMask,
23010 0a 20 20 69 6e 74 28 2a 78 43 61 6c 6c 62 61 63  .  int(*xCallbac
23020 6b 29 28 75 6e 73 69 67 6e 65 64 2c 76 6f 69 64  k)(unsigned,void
23030 2a 2c 76 6f 69 64 2a 2c 76 6f 69 64 2a 29 2c 0a  *,void*,void*),.
23040 20 20 76 6f 69 64 20 2a 70 43 74 78 0a 29 3b 0a    void *pCtx.);.
23050 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
23060 20 51 75 65 72 79 20 50 72 6f 67 72 65 73 73 20   Query Progress 
23070 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54  Callbacks.** MET
23080 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
23090 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
230a0 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72  progress_handler
230b0 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66  (D,N,X,P) interf
230c0 61 63 65 20 63 61 75 73 65 73 20 74 68 65 20 63  ace causes the c
230d0 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74  allback.** funct
230e0 69 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e 76 6f  ion X to be invo
230f0 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79  ked periodically
23100 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e   during long run
23110 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  ning calls to.**
23120 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
23130 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ], [sqlite3_step
23140 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
23150 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f  _get_table()] fo
23160 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  r.** database co
23170 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20  nnection D.  An 
23180 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20  example use for 
23190 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63  this.** interfac
231a0 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47  e is to keep a G
231b0 55 49 20 75 70 64 61 74 65 64 20 64 75 72 69 6e  UI updated durin
231c0 67 20 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e  g a large query.
231d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61  .**.** ^The para
231e0 6d 65 74 65 72 20 50 20 69 73 20 70 61 73 73 65  meter P is passe
231f0 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65  d through as the
23200 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20   only parameter 
23210 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62  to the .** callb
23220 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20  ack function X. 
23230 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20   ^The parameter 
23240 4e 20 69 73 20 74 68 65 20 61 70 70 72 6f 78 69  N is the approxi
23250 6d 61 74 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a  mate number of .
23260 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61 63 68  ** [virtual mach
23270 69 6e 65 20 69 6e 73 74 72 75 63 74 69 6f 6e 73  ine instructions
23280 5d 20 74 68 61 74 20 61 72 65 20 65 76 61 6c 75  ] that are evalu
23290 61 74 65 64 20 62 65 74 77 65 65 6e 20 73 75 63  ated between suc
232a0 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63  cessive.** invoc
232b0 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 63 61  ations of the ca
232c0 6c 6c 62 61 63 6b 20 58 2e 20 20 5e 49 66 20 4e  llback X.  ^If N
232d0 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e   is less than on
232e0 65 20 74 68 65 6e 20 74 68 65 20 70 72 6f 67 72  e then the progr
232f0 65 73 73 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 69  ess.** handler i
23300 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  s disabled..**.*
23310 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65  * ^Only a single
23320 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
23330 72 20 6d 61 79 20 62 65 20 64 65 66 69 6e 65 64  r may be defined
23340 20 61 74 20 6f 6e 65 20 74 69 6d 65 20 70 65 72   at one time per
23350 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
23360 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69  nnection]; setti
23370 6e 67 20 61 20 6e 65 77 20 70 72 6f 67 72 65 73  ng a new progres
23380 73 20 68 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c  s handler cancel
23390 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65  s the.** old one
233a0 2e 20 20 5e 53 65 74 74 69 6e 67 20 70 61 72 61  .  ^Setting para
233b0 6d 65 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20  meter X to NULL 
233c0 64 69 73 61 62 6c 65 73 20 74 68 65 20 70 72 6f  disables the pro
233d0 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a  gress handler..*
233e0 2a 20 5e 54 68 65 20 70 72 6f 67 72 65 73 73 20  * ^The progress 
233f0 68 61 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f 20  handler is also 
23400 64 69 73 61 62 6c 65 64 20 62 79 20 73 65 74 74  disabled by sett
23410 69 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c 75 65  ing N to a value
23420 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e   less.** than 1.
23430 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70  .**.** ^If the p
23440 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b  rogress callback
23450 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
23460 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  o, the operation
23470 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74   is.** interrupt
23480 65 64 2e 20 20 54 68 69 73 20 66 65 61 74 75 72  ed.  This featur
23490 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
234a0 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20   implement a.** 
234b0 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20  "Cancel" button 
234c0 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65 73  on a GUI progres
234d0 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a  s dialog box..**
234e0 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73  .** The progress
234f0 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63   handler callbac
23500 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  k must not do an
23510 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
23520 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
23530 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
23540 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
23550 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  the progress han
23560 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  dler..** Note th
23570 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  at [sqlite3_prep
23580 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
23590 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62  qlite3_step()] b
235a0 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72  oth modify their
235b0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
235c0 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  nections for the
235d0 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64   meaning of "mod
235e0 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72  ify" in this par
235f0 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f  agraph..**.*/.vo
23600 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  id sqlite3_progr
23610 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69  ess_handler(sqli
23620 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a  te3*, int, int(*
23630 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29  )(void*), void*)
23640 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
23650 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77  F: Opening A New
23660 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
23670 74 69 6f 6e 0a 2a 2a 20 43 4f 4e 53 54 52 55 43  tion.** CONSTRUC
23680 54 4f 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  TOR: sqlite3.**.
23690 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
236a0 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74  es open an SQLit
236b0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
236c0 61 73 20 73 70 65 63 69 66 69 65 64 20 62 79 20  as specified by 
236d0 74 68 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65  the .** filename
236e0 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20   argument. ^The 
236f0 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
23700 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  t is interpreted
23710 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a   as UTF-8 for.**
23720 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
23730 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  and sqlite3_open
23740 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55 54 46  _v2() and as UTF
23750 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76  -16 in the nativ
23760 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20  e byte.** order 
23770 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
23780 31 36 28 29 2e 20 5e 28 41 20 5b 64 61 74 61 62  16(). ^(A [datab
23790 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
237a0 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c  handle is usuall
237b0 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e  y.** returned in
237c0 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20   *ppDb, even if 
237d0 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e  an error occurs.
237e0 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70    The only excep
237f0 74 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20  tion is that.** 
23800 69 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61  if SQLite is una
23810 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
23820 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  memory to hold t
23830 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  he [sqlite3] obj
23840 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77  ect,.** a NULL w
23850 69 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69  ill be written i
23860 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61  nto *ppDb instea
23870 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74  d of a pointer t
23880 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a  o the [sqlite3].
23890 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49  ** object.)^ ^(I
238a0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  f the database i
238b0 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72  s opened (and/or
238c0 20 63 72 65 61 74 65 64 29 20 73 75 63 63 65 73   created) succes
238d0 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20  sfully, then.** 
238e0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72  [SQLITE_OK] is r
238f0 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77  eturned.  Otherw
23900 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  ise an [error co
23910 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
23920 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69  )^ ^The.** [sqli
23930 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72  te3_errmsg()] or
23940 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
23950 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63  16()] routines c
23960 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62  an be used to ob
23970 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69  tain.** an Engli
23980 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63  sh language desc
23990 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65  ription of the e
239a0 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  rror following a
239b0 20 66 61 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a   failure of any.
239c0 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ** of the sqlite
239d0 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e 65  3_open() routine
239e0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65  s..**.** ^The de
239f0 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 77  fault encoding w
23a00 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 66 6f 72  ill be UTF-8 for
23a10 20 64 61 74 61 62 61 73 65 73 20 63 72 65 61 74   databases creat
23a20 65 64 20 75 73 69 6e 67 0a 2a 2a 20 73 71 6c 69  ed using.** sqli
23a30 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71  te3_open() or sq
23a40 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
23a50 20 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65    ^The default e
23a60 6e 63 6f 64 69 6e 67 20 66 6f 72 20 64 61 74 61  ncoding for data
23a70 62 61 73 65 73 0a 2a 2a 20 63 72 65 61 74 65 64  bases.** created
23a80 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f   using sqlite3_o
23a90 70 65 6e 31 36 28 29 20 77 69 6c 6c 20 62 65 20  pen16() will be 
23aa0 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61  UTF-16 in the na
23ab0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
23ac0 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f  .**.** Whether o
23ad0 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f  r not an error o
23ae0 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 73  ccurs when it is
23af0 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63   opened, resourc
23b00 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  es.** associated
23b10 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62   with the [datab
23b20 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
23b30 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65  handle should be
23b40 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20   released by.** 
23b50 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73  passing it to [s
23b60 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20  qlite3_close()] 
23b70 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f  when it is no lo
23b80 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a  nger required..*
23b90 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
23ba0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72  _open_v2() inter
23bb0 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20  face works like 
23bc0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a  sqlite3_open().*
23bd0 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74  * except that it
23be0 20 61 63 63 65 70 74 73 20 74 77 6f 20 61 64 64   accepts two add
23bf0 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65  itional paramete
23c00 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  rs for additiona
23c10 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65  l control.** ove
23c20 72 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61  r the new databa
23c30 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  se connection.  
23c40 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61 72 61  ^(The flags para
23c50 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69  meter to.** sqli
23c60 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61  te3_open_v2() ca
23c70 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a  n take one of.**
23c80 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74   the following t
23c90 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74  hree values, opt
23ca0 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64  ionally combined
23cb0 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53   with the .** [S
23cc0 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
23cd0 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  EX], [SQLITE_OPE
23ce0 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53  N_FULLMUTEX], [S
23cf0 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
23d00 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c  DCACHE],.** [SQL
23d10 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
23d20 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b  CACHE], and/or [
23d30 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d  SQLITE_OPEN_URI]
23d40 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20   flags:)^.**.** 
23d50 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53  <dl>.** ^(<dt>[S
23d60 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
23d70 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NLY]</dt>.** <dd
23d80 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
23d90 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d   opened in read-
23da0 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74  only mode.  If t
23db0 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73  he database does
23dc0 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20   not.** already 
23dd0 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20  exist, an error 
23de0 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64  is returned.</dd
23df0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
23e00 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
23e10 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20  DWRITE]</dt>.** 
23e20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65  <dd>The database
23e30 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
23e40 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69  eading and writi
23e50 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20  ng if possible, 
23e60 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e  or reading.** on
23e70 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65 20 69  ly if the file i
23e80 73 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65  s write protecte
23e90 64 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 69  d by the operati
23ea0 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65  ng system.  In e
23eb0 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68  ither.** case th
23ec0 65 20 64 61 74 61 62 61 73 65 20 6d 75 73 74 20  e database must 
23ed0 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f  already exist, o
23ee0 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f  therwise an erro
23ef0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f  r is returned.</
23f00 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
23f10 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  t>[SQLITE_OPEN_R
23f20 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c  EADWRITE] | [SQL
23f30 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
23f40 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
23f50 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
23f60 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ned for reading 
23f70 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64  and writing, and
23f80 20 69 73 20 63 72 65 61 74 65 64 20 69 66 0a 2a   is created if.*
23f90 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c  * it does not al
23fa0 72 65 61 64 79 20 65 78 69 73 74 2e 20 54 68 69  ready exist. Thi
23fb0 73 20 69 73 20 74 68 65 20 62 65 68 61 76 69 6f  s is the behavio
23fc0 72 20 74 68 61 74 20 69 73 20 61 6c 77 61 79 73  r that is always
23fd0 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c   used for.** sql
23fe0 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20  ite3_open() and 
23ff0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
24000 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c  .</dd>)^.** </dl
24010 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33  >.**.** If the 3
24020 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
24030 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
24040 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20  ) is not one of 
24050 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69  the.** combinati
24060 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20  ons shown above 
24070 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69  optionally combi
24080 6e 65 64 20 77 69 74 68 20 6f 74 68 65 72 0a 2a  ned with other.*
24090 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  * [SQLITE_OPEN_R
240a0 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45  EADONLY | SQLITE
240b0 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a  _OPEN_* bits].**
240c0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
240d0 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
240e0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b  .**.** ^If the [
240f0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
24100 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74  TEX] flag is set
24110 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
24120 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
24130 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d  * opens in the m
24140 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72  ulti-thread [thr
24150 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20  eading mode] as 
24160 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67  long as the sing
24170 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64  le-thread.** mod
24180 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73  e has not been s
24190 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  et at compile-ti
241a0 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65  me or start-time
241b0 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53  .  ^If the.** [S
241c0 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
241d0 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65  UTEX] flag is se
241e0 74 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  t then the datab
241f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
24200 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73  pens.** in the s
24210 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61  erialized [threa
24220 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73  ding mode] unles
24230 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20  s single-thread 
24240 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  was.** previousl
24250 79 20 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f  y selected at co
24260 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74  mpile-time or st
24270 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68  art-time..** ^Th
24280 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  e [SQLITE_OPEN_S
24290 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67  HAREDCACHE] flag
242a0 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61   causes the data
242b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
242c0 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c  to be.** eligibl
242d0 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64  e to use [shared
242e0 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65   cache mode], re
242f0 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
24300 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65  her or not share
24310 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e  d.** cache is en
24320 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  abled using [sql
24330 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72  ite3_enable_shar
24340 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54  ed_cache()].  ^T
24350 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  he.** [SQLITE_OP
24360 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d  EN_PRIVATECACHE]
24370 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65   flag causes the
24380 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
24390 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70  tion to not.** p
243a0 61 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73  articipate in [s
243b0 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65  hared cache mode
243c0 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20  ] even if it is 
243d0 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  enabled..**.** ^
243e0 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
243f0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
24400 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65  open_v2() is the
24410 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20   name of the.** 
24420 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
24430 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65  ject that define
24440 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  s the operating 
24450 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65  system interface
24460 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77   that.** the new
24470 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
24480 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e  tion should use.
24490 20 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68    ^If the fourth
244a0 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a   parameter is.**
244b0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
244c0 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74  then the default
244d0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
244e0 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a  bject is used..*
244f0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c  *.** ^If the fil
24500 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72  ename is ":memor
24510 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76  y:", then a priv
24520 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69  ate, temporary i
24530 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
24540 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20  e.** is created 
24550 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69  for the connecti
24560 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65  on.  ^This in-me
24570 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 69  mory database wi
24580 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a  ll vanish when.*
24590 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
245a0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
245b0 73 65 64 2e 20 20 46 75 74 75 72 65 20 76 65 72  sed.  Future ver
245c0 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
245d0 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73  might.** make us
245e0 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20  e of additional 
245f0 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65  special filename
24600 73 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 74  s that begin wit
24610 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 63  h the ":" charac
24620 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65  ter..** It is re
24630 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77  commended that w
24640 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 66  hen a database f
24650 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79  ilename actually
24660 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68   does begin with
24670 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63  .** a ":" charac
24680 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70  ter you should p
24690 72 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61  refix the filena
246a0 6d 65 20 77 69 74 68 20 61 20 70 61 74 68 6e 61  me with a pathna
246b0 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e  me such as.** ".
246c0 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69  /" to avoid ambi
246d0 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  guity..**.** ^If
246e0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
246f0 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
24700 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65  , then a private
24710 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f  , temporary.** o
24720 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20  n-disk database 
24730 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e  will be created.
24740 20 20 5e 54 68 69 73 20 70 72 69 76 61 74 65 20    ^This private 
24750 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
24760 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
24770 79 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f  y deleted as soo
24780 6e 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73  n as the databas
24790 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
247a0 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  closed..**.** [[
247b0 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e  URI filenames in
247c0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d   sqlite3_open()]
247d0 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e 61  ] <h3>URI Filena
247e0 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e  mes</h3>.**.** ^
247f0 49 66 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65  If [URI filename
24800 5d 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e  ] interpretation
24810 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64   is enabled, and
24820 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72   the filename ar
24830 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73  gument.** begins
24840 20 77 69 74 68 20 22 66 69 6c 65 3a 22 2c 20 74   with "file:", t
24850 68 65 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  hen the filename
24860 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
24870 61 73 20 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a  as a URI. ^URI.*
24880 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72  * filename inter
24890 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61  pretation is ena
248a0 62 6c 65 64 20 69 66 20 74 68 65 20 5b 53 51 4c  bled if the [SQL
248b0 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c  ITE_OPEN_URI] fl
248c0 61 67 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20  ag is.** set in 
248d0 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  the fourth argum
248e0 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ent to sqlite3_o
248f0 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66 20  pen_v2(), or if 
24900 69 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65  it has.** been e
24910 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20  nabled globally 
24920 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54  using the [SQLIT
24930 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70  E_CONFIG_URI] op
24940 74 69 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a  tion with the.**
24950 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
24960 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62 79  ()] method or by
24970 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45   the [SQLITE_USE
24980 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  _URI] compile-ti
24990 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73  me option..** As
249a0 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 69   of SQLite versi
249b0 6f 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20 66 69  on 3.7.7, URI fi
249c0 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74  lename interpret
249d0 61 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20  ation is turned 
249e0 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c  off.** by defaul
249f0 74 2c 20 62 75 74 20 66 75 74 75 72 65 20 72 65  t, but future re
24a00 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
24a10 20 6d 69 67 68 74 20 65 6e 61 62 6c 65 20 55 52   might enable UR
24a20 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e  I filename.** in
24a30 74 65 72 70 72 65 74 61 74 69 6f 6e 20 62 79 20  terpretation by 
24a40 64 65 66 61 75 6c 74 2e 20 20 53 65 65 20 22 5b  default.  See "[
24a50 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20  URI filenames]" 
24a60 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  for additional.*
24a70 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  * information..*
24a80 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d  *.** URI filenam
24a90 65 73 20 61 72 65 20 70 61 72 73 65 64 20 61 63  es are parsed ac
24aa0 63 6f 72 64 69 6e 67 20 74 6f 20 52 46 43 20 33  cording to RFC 3
24ab0 39 38 36 2e 20 5e 49 66 20 74 68 65 20 55 52 49  986. ^If the URI
24ac0 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20   contains an.** 
24ad0 61 75 74 68 6f 72 69 74 79 2c 20 74 68 65 6e 20  authority, then 
24ae0 69 74 20 6d 75 73 74 20 62 65 20 65 69 74 68 65  it must be eithe
24af0 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  r an empty strin
24b00 67 20 6f 72 20 74 68 65 20 73 74 72 69 6e 67 20  g or the string 
24b10 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e  .** "localhost".
24b20 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69   ^If the authori
24b30 74 79 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70  ty is not an emp
24b40 74 79 20 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f  ty string or "lo
24b50 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a  calhost", an .**
24b60 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
24b70 65 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72  ed to the caller
24b80 2e 20 5e 54 68 65 20 66 72 61 67 6d 65 6e 74 20  . ^The fragment 
24b90 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55  component of a U
24ba0 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73 65  RI, if .** prese
24bb0 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a  nt, is ignored..
24bc0 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73  **.** ^SQLite us
24bd0 65 73 20 74 68 65 20 70 61 74 68 20 63 6f 6d 70  es the path comp
24be0 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20 55 52 49  onent of the URI
24bf0 20 61 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   as the name of 
24c00 74 68 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a  the disk file.**
24c10 20 77 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 20   which contains 
24c20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 5e 49  the database. ^I
24c30 66 20 74 68 65 20 70 61 74 68 20 62 65 67 69 6e  f the path begin
24c40 73 20 77 69 74 68 20 61 20 27 2f 27 20 63 68 61  s with a '/' cha
24c50 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e  racter, .** then
24c60 20 69 74 20 69 73 20 69 6e 74 65 72 70 72 65 74   it is interpret
24c70 65 64 20 61 73 20 61 6e 20 61 62 73 6f 6c 75 74  ed as an absolut
24c80 65 20 70 61 74 68 2e 20 5e 49 66 20 74 68 65 20  e path. ^If the 
24c90 70 61 74 68 20 64 6f 65 73 20 6e 6f 74 20 62 65  path does not be
24ca0 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20 27  gin .** with a '
24cb0 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74 68 61 74  /' (meaning that
24cc0 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 73   the authority s
24cd0 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65  ection is omitte
24ce0 64 20 66 72 6f 6d 20 74 68 65 20 55 52 49 29 0a  d from the URI).
24cf0 2a 2a 20 74 68 65 6e 20 74 68 65 20 70 61 74 68  ** then the path
24d00 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
24d10 61 73 20 61 20 72 65 6c 61 74 69 76 65 20 70 61  as a relative pa
24d20 74 68 2e 20 0a 2a 2a 20 5e 28 4f 6e 20 77 69 6e  th. .** ^(On win
24d30 64 6f 77 73 2c 20 74 68 65 20 66 69 72 73 74 20  dows, the first 
24d40 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20  component of an 
24d50 61 62 73 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a  absolute path .*
24d60 2a 20 69 73 20 61 20 64 72 69 76 65 20 73 70 65  * is a drive spe
24d70 63 69 66 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e  cification (e.g.
24d80 20 22 43 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20   "C:").)^.**.** 
24d90 5b 5b 63 6f 72 65 20 55 52 49 20 71 75 65 72 79  [[core URI query
24da0 20 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a   parameters]].**
24db0 20 54 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f   The query compo
24dc0 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 6d 61  nent of a URI ma
24dd0 79 20 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65  y contain parame
24de0 74 65 72 73 20 74 68 61 74 20 61 72 65 20 69 6e  ters that are in
24df0 74 65 72 70 72 65 74 65 64 0a 2a 2a 20 65 69 74  terpreted.** eit
24e00 68 65 72 20 62 79 20 53 51 4c 69 74 65 20 69 74  her by SQLite it
24e10 73 65 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b 56  self, or by a [V
24e20 46 53 20 7c 20 63 75 73 74 6f 6d 20 56 46 53 20  FS | custom VFS 
24e30 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e  implementation].
24e40 0a 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64 20 69  .** SQLite and i
24e50 74 73 20 62 75 69 6c 74 2d 69 6e 20 5b 56 46 53  ts built-in [VFS
24e60 65 73 5d 20 69 6e 74 65 72 70 72 65 74 20 74 68  es] interpret th
24e70 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 71  e.** following q
24e80 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 3a  uery parameters:
24e90 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20  .**.** <ul>.**  
24ea0 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e   <li> <b>vfs</b>
24eb0 3a 20 5e 54 68 65 20 22 76 66 73 22 20 70 61 72  : ^The "vfs" par
24ec0 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 75 73  ameter may be us
24ed0 65 64 20 74 6f 20 73 70 65 63 69 66 79 20 74 68  ed to specify th
24ee0 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20  e name of.**    
24ef0 20 61 20 56 46 53 20 6f 62 6a 65 63 74 20 74 68   a VFS object th
24f00 61 74 20 70 72 6f 76 69 64 65 73 20 74 68 65 20  at provides the 
24f10 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
24f20 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
24f30 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65  should.**     be
24f40 20 75 73 65 64 20 74 6f 20 61 63 63 65 73 73 20   used to access 
24f50 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
24f60 65 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74  e on disk. ^If t
24f70 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 73 65  his option is se
24f80 74 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65  t to.**     an e
24f90 6d 70 74 79 20 73 74 72 69 6e 67 20 74 68 65 20  mpty string the 
24fa0 64 65 66 61 75 6c 74 20 56 46 53 20 6f 62 6a 65  default VFS obje
24fb0 63 74 20 69 73 20 75 73 65 64 2e 20 5e 53 70 65  ct is used. ^Spe
24fc0 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f  cifying an unkno
24fd0 77 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20 69 73  wn.**     VFS is
24fe0 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20 73   an error. ^If s
24ff0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
25000 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65   is used and the
25010 20 76 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a   vfs option is.*
25020 2a 20 20 20 20 20 70 72 65 73 65 6e 74 2c 20 74  *     present, t
25030 68 65 6e 20 74 68 65 20 56 46 53 20 73 70 65 63  hen the VFS spec
25040 69 66 69 65 64 20 62 79 20 74 68 65 20 6f 70 74  ified by the opt
25050 69 6f 6e 20 74 61 6b 65 73 20 70 72 65 63 65 64  ion takes preced
25060 65 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20  ence over.**    
25070 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 65   the value passe
25080 64 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 20  d as the fourth 
25090 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
250a0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a  ite3_open_v2()..
250b0 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e  **.**   <li> <b>
250c0 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20  mode</b>: ^(The 
250d0 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 6d  mode parameter m
250e0 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74  ay be set to eit
250f0 68 65 72 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a  her "ro", "rw",.
25100 2a 2a 20 20 20 20 20 22 72 77 63 22 2c 20 6f 72  **     "rwc", or
25110 20 22 6d 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d   "memory". Attem
25120 70 74 69 6e 67 20 74 6f 20 73 65 74 20 69 74 20  pting to set it 
25130 74 6f 20 61 6e 79 20 6f 74 68 65 72 20 76 61 6c  to any other val
25140 75 65 20 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20  ue is.**     an 
25150 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20  error)^. .**    
25160 20 5e 49 66 20 22 72 6f 22 20 69 73 20 73 70 65   ^If "ro" is spe
25170 63 69 66 69 65 64 2c 20 74 68 65 6e 20 74 68 65  cified, then the
25180 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
25190 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c  ned for read-onl
251a0 79 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73  y .**     access
251b0 2c 20 6a 75 73 74 20 61 73 20 69 66 20 74 68 65  , just as if the
251c0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
251d0 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64  ADONLY] flag had
251e0 20 62 65 65 6e 20 73 65 74 20 69 6e 20 74 68 65   been set in the
251f0 20 0a 2a 2a 20 20 20 20 20 74 68 69 72 64 20 61   .**     third a
25200 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
25210 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 49  e3_open_v2(). ^I
25220 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f  f the mode optio
25230 6e 20 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20  n is set to .** 
25240 20 20 20 20 22 72 77 22 2c 20 74 68 65 6e 20 74      "rw", then t
25250 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
25260 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 77  pened for read-w
25270 72 69 74 65 20 28 62 75 74 20 6e 6f 74 20 63 72  rite (but not cr
25280 65 61 74 65 29 20 0a 2a 2a 20 20 20 20 20 61 63  eate) .**     ac
25290 63 65 73 73 2c 20 61 73 20 69 66 20 53 51 4c 49  cess, as if SQLI
252a0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
252b0 45 20 28 62 75 74 20 6e 6f 74 20 53 51 4c 49 54  E (but not SQLIT
252c0 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29 20 68  E_OPEN_CREATE) h
252d0 61 64 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20  ad .**     been 
252e0 73 65 74 2e 20 5e 56 61 6c 75 65 20 22 72 77 63  set. ^Value "rwc
252f0 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20  " is equivalent 
25300 74 6f 20 73 65 74 74 69 6e 67 20 62 6f 74 68 20  to setting both 
25310 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f  .**     SQLITE_O
25320 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 61 6e  PEN_READWRITE an
25330 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  d SQLITE_OPEN_CR
25340 45 41 54 45 2e 20 20 5e 49 66 20 74 68 65 20 6d  EATE.  ^If the m
25350 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a  ode option is.**
25360 20 20 20 20 20 73 65 74 20 74 6f 20 22 6d 65 6d       set to "mem
25370 6f 72 79 22 20 74 68 65 6e 20 61 20 70 75 72 65  ory" then a pure
25380 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61   [in-memory data
25390 62 61 73 65 5d 20 74 68 61 74 20 6e 65 76 65 72  base] that never
253a0 20 72 65 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72   reads.**     or
253b0 20 77 72 69 74 65 73 20 66 72 6f 6d 20 64 69 73   writes from dis
253c0 6b 20 69 73 20 75 73 65 64 2e 20 5e 49 74 20 69  k is used. ^It i
253d0 73 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70  s an error to sp
253e0 65 63 69 66 79 20 61 20 76 61 6c 75 65 20 66 6f  ecify a value fo
253f0 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 6d 6f 64  r.**     the mod
25400 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74  e parameter that
25410 20 69 73 20 6c 65 73 73 20 72 65 73 74 72 69 63   is less restric
25420 74 69 76 65 20 74 68 61 6e 20 74 68 61 74 20 73  tive than that s
25430 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20  pecified by.**  
25440 20 20 20 74 68 65 20 66 6c 61 67 73 20 70 61 73     the flags pas
25450 73 65 64 20 69 6e 20 74 68 65 20 74 68 69 72 64  sed in the third
25460 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
25470 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
25480 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62  .**.**   <li> <b
25490 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65  >cache</b>: ^The
254a0 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72   cache parameter
254b0 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65   may be set to e
254c0 69 74 68 65 72 20 22 73 68 61 72 65 64 22 20 6f  ither "shared" o
254d0 72 0a 2a 2a 20 20 20 20 20 22 70 72 69 76 61 74  r.**     "privat
254e0 65 22 2e 20 5e 53 65 74 74 69 6e 67 20 69 74 20  e". ^Setting it 
254f0 74 6f 20 22 73 68 61 72 65 64 22 20 69 73 20 65  to "shared" is e
25500 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74  quivalent to set
25510 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20  ting the.**     
25520 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
25530 45 44 43 41 43 48 45 20 62 69 74 20 69 6e 20 74  EDCACHE bit in t
25540 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
25550 74 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20  t passed to.**  
25560 20 20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f     sqlite3_open_
25570 76 32 28 29 2e 20 5e 53 65 74 74 69 6e 67 20 74  v2(). ^Setting t
25580 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74  he cache paramet
25590 65 72 20 74 6f 20 22 70 72 69 76 61 74 65 22 20  er to "private" 
255a0 69 73 20 0a 2a 2a 20 20 20 20 20 65 71 75 69 76  is .**     equiv
255b0 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67  alent to setting
255c0 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e   the SQLITE_OPEN
255d0 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 62 69  _PRIVATECACHE bi
255e0 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73 71  t..**     ^If sq
255f0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
25600 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20  is used and the 
25610 22 63 61 63 68 65 22 20 70 61 72 61 6d 65 74 65  "cache" paramete
25620 72 20 69 73 20 70 72 65 73 65 6e 74 20 69 6e 0a  r is present in.
25630 2a 2a 20 20 20 20 20 61 20 55 52 49 20 66 69 6c  **     a URI fil
25640 65 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c 75 65  ename, its value
25650 20 6f 76 65 72 72 69 64 65 73 20 61 6e 79 20 62   overrides any b
25660 65 68 61 76 69 6f 72 20 72 65 71 75 65 73 74 65  ehavior requeste
25670 64 20 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20  d by setting.** 
25680 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f      SQLITE_OPEN_
25690 50 52 49 56 41 54 45 43 41 43 48 45 20 6f 72 20  PRIVATECACHE or 
256a0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
256b0 45 44 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a  EDCACHE flag..**
256c0 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 70 73 6f  .**  <li> <b>pso
256d0 77 3c 2f 62 3e 3a 20 5e 54 68 65 20 70 73 6f 77  w</b>: ^The psow
256e0 20 70 61 72 61 6d 65 74 65 72 20 69 6e 64 69 63   parameter indic
256f0 61 74 65 73 20 77 68 65 74 68 65 72 20 6f 72 20  ates whether or 
25700 6e 6f 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 5b  not the.**     [
25710 70 6f 77 65 72 73 61 66 65 20 6f 76 65 72 77 72  powersafe overwr
25720 69 74 65 5d 20 70 72 6f 70 65 72 74 79 20 64 6f  ite] property do
25730 65 73 20 6f 72 20 64 6f 65 73 20 6e 6f 74 20 61  es or does not a
25740 70 70 6c 79 20 74 6f 20 74 68 65 0a 2a 2a 20 20  pply to the.**  
25750 20 20 20 73 74 6f 72 61 67 65 20 6d 65 64 69 61     storage media
25760 20 6f 6e 20 77 68 69 63 68 20 74 68 65 20 64 61   on which the da
25770 74 61 62 61 73 65 20 66 69 6c 65 20 72 65 73 69  tabase file resi
25780 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e  des..**.**  <li>
25790 20 3c 62 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20   <b>nolock</b>: 
257a0 5e 54 68 65 20 6e 6f 6c 6f 63 6b 20 70 61 72 61  ^The nolock para
257b0 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65  meter is a boole
257c0 61 6e 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  an query paramet
257d0 65 72 0a 2a 2a 20 20 20 20 20 77 68 69 63 68 20  er.**     which 
257e0 69 66 20 73 65 74 20 64 69 73 61 62 6c 65 73 20  if set disables 
257f0 66 69 6c 65 20 6c 6f 63 6b 69 6e 67 20 69 6e 20  file locking in 
25800 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c  rollback journal
25810 20 6d 6f 64 65 73 2e 20 20 54 68 69 73 0a 2a 2a   modes.  This.**
25820 20 20 20 20 20 69 73 20 75 73 65 66 75 6c 20 66       is useful f
25830 6f 72 20 61 63 63 65 73 73 69 6e 67 20 61 20 64  or accessing a d
25840 61 74 61 62 61 73 65 20 6f 6e 20 61 20 66 69 6c  atabase on a fil
25850 65 73 79 73 74 65 6d 20 74 68 61 74 20 64 6f 65  esystem that doe
25860 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 73 75 70  s not.**     sup
25870 70 6f 72 74 20 6c 6f 63 6b 69 6e 67 2e 20 20 43  port locking.  C
25880 61 75 74 69 6f 6e 3a 20 20 44 61 74 61 62 61 73  aution:  Databas
25890 65 20 63 6f 72 72 75 70 74 69 6f 6e 20 6d 69 67  e corruption mig
258a0 68 74 20 72 65 73 75 6c 74 20 69 66 20 74 77 6f  ht result if two
258b0 0a 2a 2a 20 20 20 20 20 6f 72 20 6d 6f 72 65 20  .**     or more 
258c0 70 72 6f 63 65 73 73 65 73 20 77 72 69 74 65 20  processes write 
258d0 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  to the same data
258e0 62 61 73 65 20 61 6e 64 20 61 6e 79 20 6f 6e 65  base and any one
258f0 20 6f 66 20 74 68 6f 73 65 0a 2a 2a 20 20 20 20   of those.**    
25900 20 70 72 6f 63 65 73 73 65 73 20 75 73 65 73 20   processes uses 
25910 6e 6f 6c 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20  nolock=1..**.** 
25920 20 3c 6c 69 3e 20 3c 62 3e 69 6d 6d 75 74 61 62   <li> <b>immutab
25930 6c 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 69 6d 6d  le</b>: ^The imm
25940 75 74 61 62 6c 65 20 70 61 72 61 6d 65 74 65 72  utable parameter
25950 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75   is a boolean qu
25960 65 72 79 0a 2a 2a 20 20 20 20 20 70 61 72 61 6d  ery.**     param
25970 65 74 65 72 20 74 68 61 74 20 69 6e 64 69 63 61  eter that indica
25980 74 65 73 20 74 68 61 74 20 74 68 65 20 64 61 74  tes that the dat
25990 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 73 74  abase file is st
259a0 6f 72 65 64 20 6f 6e 0a 2a 2a 20 20 20 20 20 72  ored on.**     r
259b0 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 2e 20  ead-only media. 
259c0 20 5e 57 68 65 6e 20 69 6d 6d 75 74 61 62 6c 65   ^When immutable
259d0 20 69 73 20 73 65 74 2c 20 53 51 4c 69 74 65 20   is set, SQLite 
259e0 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
259f0 0a 2a 2a 20 20 20 20 20 64 61 74 61 62 61 73 65  .**     database
25a00 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20   file cannot be 
25a10 63 68 61 6e 67 65 64 2c 20 65 76 65 6e 20 62 79  changed, even by
25a20 20 61 20 70 72 6f 63 65 73 73 20 77 69 74 68 20   a process with 
25a30 68 69 67 68 65 72 0a 2a 2a 20 20 20 20 20 70 72  higher.**     pr
25a40 69 76 69 6c 65 67 65 2c 20 61 6e 64 20 73 6f 20  ivilege, and so 
25a50 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
25a60 6f 70 65 6e 65 64 20 72 65 61 64 2d 6f 6e 6c 79  opened read-only
25a70 20 61 6e 64 20 61 6c 6c 20 6c 6f 63 6b 69 6e 67   and all locking
25a80 0a 2a 2a 20 20 20 20 20 61 6e 64 20 63 68 61 6e  .**     and chan
25a90 67 65 20 64 65 74 65 63 74 69 6f 6e 20 69 73 20  ge detection is 
25aa0 64 69 73 61 62 6c 65 64 2e 20 20 43 61 75 74 69  disabled.  Cauti
25ab0 6f 6e 3a 20 53 65 74 74 69 6e 67 20 74 68 65 20  on: Setting the 
25ac0 69 6d 6d 75 74 61 62 6c 65 0a 2a 2a 20 20 20 20  immutable.**    
25ad0 20 70 72 6f 70 65 72 74 79 20 6f 6e 20 61 20 64   property on a d
25ae0 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 61  atabase file tha
25af0 74 20 64 6f 65 73 20 69 6e 20 66 61 63 74 20 63  t does in fact c
25b00 68 61 6e 67 65 20 63 61 6e 20 72 65 73 75 6c 74  hange can result
25b10 0a 2a 2a 20 20 20 20 20 69 6e 20 69 6e 63 6f 72  .**     in incor
25b20 72 65 63 74 20 71 75 65 72 79 20 72 65 73 75 6c  rect query resul
25b30 74 73 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54  ts and/or [SQLIT
25b40 45 5f 43 4f 52 52 55 50 54 5d 20 65 72 72 6f 72  E_CORRUPT] error
25b50 73 2e 0a 2a 2a 20 20 20 20 20 53 65 65 20 61 6c  s..**     See al
25b60 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  so: [SQLITE_IOCA
25b70 50 5f 49 4d 4d 55 54 41 42 4c 45 5d 2e 0a 2a 2a  P_IMMUTABLE]..**
25b80 20 20 20 20 20 20 20 0a 2a 2a 20 3c 2f 75 6c 3e         .** </ul>
25b90 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69  .**.** ^Specifyi
25ba0 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61  ng an unknown pa
25bb0 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20 71  rameter in the q
25bc0 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  uery component o
25bd0 66 20 61 20 55 52 49 20 69 73 20 6e 6f 74 20 61  f a URI is not a
25be0 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75 74  n.** error.  Fut
25bf0 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
25c00 53 51 4c 69 74 65 20 6d 69 67 68 74 20 75 6e 64  SQLite might und
25c10 65 72 73 74 61 6e 64 20 61 64 64 69 74 69 6f 6e  erstand addition
25c20 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61  al query.** para
25c30 6d 65 74 65 72 73 2e 20 20 53 65 65 20 22 5b 71  meters.  See "[q
25c40 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 20  uery parameters 
25c50 77 69 74 68 20 73 70 65 63 69 61 6c 20 6d 65 61  with special mea
25c60 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d 22  ning to SQLite]"
25c70 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e   for.** addition
25c80 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
25c90 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65  **.** [[URI file
25ca0 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20  name examples]] 
25cb0 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65  <h3>URI filename
25cc0 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a   examples</h3>.*
25cd0 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64  *.** <table bord
25ce0 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e  er="1" align=cen
25cf0 74 65 72 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d  ter cellpadding=
25d00 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55  5>.** <tr><th> U
25d10 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68  RI filenames <th
25d20 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72  > Results.** <tr
25d30 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e  ><td> file:data.
25d40 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  db <td> .**     
25d50 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 66 69       Open the fi
25d60 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20  le "data.db" in 
25d70 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65  the current dire
25d80 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  ctory..** <tr><t
25d90 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72  d> file:/home/fr
25da0 65 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a  ed/data.db<br>.*
25db0 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a  *          file:
25dc0 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  ///home/fred/dat
25dd0 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20  a.db <br> .**   
25de0 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f         file://lo
25df0 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65  calhost/home/fre
25e00 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c  d/data.db <br> <
25e10 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
25e20 20 4f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61   Open the databa
25e30 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66  se file "/home/f
25e40 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a  red/data.db"..**
25e50 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f   <tr><td> file:/
25e60 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66  /darkstar/home/f
25e70 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e  red/data.db <td>
25e80 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e   .**          An
25e90 20 65 72 72 6f 72 2e 20 22 64 61 72 6b 73 74 61   error. "darksta
25ea0 72 22 20 69 73 20 6e 6f 74 20 61 20 72 65 63 6f  r" is not a reco
25eb0 67 6e 69 7a 65 64 20 61 75 74 68 6f 72 69 74 79  gnized authority
25ec0 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79  ..** <tr><td sty
25ed0 6c 65 3d 22 77 68 69 74 65 2d 73 70 61 63 65 3a  le="white-space:
25ee0 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20  nowrap"> .**    
25ef0 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a        file:///C:
25f00 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e 64  /Documents%20and
25f10 25 32 30 53 65 74 74 69 6e 67 73 2f 66 72 65 64  %20Settings/fred
25f20 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62  /Desktop/data.db
25f30 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57 69 6e  .**     <td> Win
25f40 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20  dows only: Open 
25f50 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64  the file "data.d
25f60 62 22 20 6f 6e 20 66 72 65 64 27 73 20 64 65 73  b" on fred's des
25f70 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a  ktop on drive.**
25f80 20 20 20 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f            C:. No
25f90 74 65 20 74 68 61 74 20 74 68 65 20 25 32 30 20  te that the %20 
25fa0 65 73 63 61 70 69 6e 67 20 69 6e 20 74 68 69 73  escaping in this
25fb0 20 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20   example is not 
25fc0 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20  strictly .**    
25fd0 20 20 20 20 20 20 6e 65 63 65 73 73 61 72 79 20        necessary 
25fe0 2d 20 73 70 61 63 65 20 63 68 61 72 61 63 74 65  - space characte
25ff0 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 6c  rs can be used l
26000 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20  iterally.**     
26010 20 20 20 20 20 69 6e 20 55 52 49 20 66 69 6c 65       in URI file
26020 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  names..** <tr><t
26030 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f  d> file:data.db?
26040 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d 70 72  mode=ro&cache=pr
26050 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20  ivate <td> .**  
26060 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c          Open fil
26070 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74  e "data.db" in t
26080 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63  he current direc
26090 74 6f 72 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e  tory for read-on
260a0 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20  ly access..**   
260b0 20 20 20 20 20 20 20 52 65 67 61 72 64 6c 65 73         Regardles
260c0 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
260d0 6e 6f 74 20 73 68 61 72 65 64 2d 63 61 63 68 65  not shared-cache
260e0 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64   mode is enabled
260f0 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   by.**          
26100 64 65 66 61 75 6c 74 2c 20 75 73 65 20 61 20 70  default, use a p
26110 72 69 76 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a  rivate cache..**
26120 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f   <tr><td> file:/
26130 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
26140 62 3f 76 66 73 3d 75 6e 69 78 2d 64 6f 74 66 69  b?vfs=unix-dotfi
26150 6c 65 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20  le <td>.**      
26160 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f      Open file "/
26170 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
26180 62 22 2e 20 55 73 65 20 74 68 65 20 73 70 65 63  b". Use the spec
26190 69 61 6c 20 56 46 53 20 22 75 6e 69 78 2d 64 6f  ial VFS "unix-do
261a0 74 66 69 6c 65 22 0a 2a 2a 20 20 20 20 20 20 20  tfile".**       
261b0 20 20 20 74 68 61 74 20 75 73 65 73 20 64 6f 74     that uses dot
261c0 2d 66 69 6c 65 73 20 69 6e 20 70 6c 61 63 65 20  -files in place 
261d0 6f 66 20 70 6f 73 69 78 20 61 64 76 69 73 6f 72  of posix advisor
261e0 79 20 6c 6f 63 6b 69 6e 67 2e 0a 2a 2a 20 3c 74  y locking..** <t
261f0 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61  r><td> file:data
26200 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c  .db?mode=readonl
26210 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  y <td> .**      
26220 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 72      An error. "r
26230 65 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20  eadonly" is not 
26240 61 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66  a valid option f
26250 6f 72 20 74 68 65 20 22 6d 6f 64 65 22 20 70 61  or the "mode" pa
26260 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61  rameter..** </ta
26270 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20  ble>.**.** ^URI 
26280 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61  hexadecimal esca
26290 70 65 20 73 65 71 75 65 6e 63 65 73 20 28 25 48  pe sequences (%H
262a0 48 29 20 61 72 65 20 73 75 70 70 6f 72 74 65 64  H) are supported
262b0 20 77 69 74 68 69 6e 20 74 68 65 20 70 61 74 68   within the path
262c0 20 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f   and.** query co
262d0 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55 52  mponents of a UR
262e0 49 2e 20 41 20 68 65 78 61 64 65 63 69 6d 61 6c  I. A hexadecimal
262f0 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65   escape sequence
26300 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a   consists of a.*
26310 2a 20 70 65 72 63 65 6e 74 20 73 69 67 6e 20 2d  * percent sign -
26320 20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20   "%" - followed 
26330 62 79 20 65 78 61 63 74 6c 79 20 74 77 6f 20 68  by exactly two h
26340 65 78 61 64 65 63 69 6d 61 6c 20 64 69 67 69 74  exadecimal digit
26350 73 20 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e 67  s .** specifying
26360 20 61 6e 20 6f 63 74 65 74 20 76 61 6c 75 65 2e   an octet value.
26370 20 5e 42 65 66 6f 72 65 20 74 68 65 20 70 61 74   ^Before the pat
26380 68 20 6f 72 20 71 75 65 72 79 20 63 6f 6d 70 6f  h or query compo
26390 6e 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52  nents of a.** UR
263a0 49 20 66 69 6c 65 6e 61 6d 65 20 61 72 65 20 69  I filename are i
263b0 6e 74 65 72 70 72 65 74 65 64 2c 20 74 68 65 79  nterpreted, they
263c0 20 61 72 65 20 65 6e 63 6f 64 65 64 20 75 73 69   are encoded usi
263d0 6e 67 20 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c  ng UTF-8 and all
263e0 20 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d 61 6c   .** hexadecimal
263f0 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65   escape sequence
26400 73 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20  s replaced by a 
26410 73 69 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e 74  single byte cont
26420 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f  aining the.** co
26430 72 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65  rresponding octe
26440 74 2e 20 49 66 20 74 68 69 73 20 70 72 6f 63 65  t. If this proce
26450 73 73 20 67 65 6e 65 72 61 74 65 73 20 61 6e 20  ss generates an 
26460 69 6e 76 61 6c 69 64 20 55 54 46 2d 38 20 65 6e  invalid UTF-8 en
26470 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72  coding,.** the r
26480 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
26490 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e  ined..**.** <b>N
264a0 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75  ote to Windows u
264b0 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65  sers:</b>  The e
264c0 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72  ncoding used for
264d0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72   the filename ar
264e0 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c  gument.** of sql
264f0 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20  ite3_open() and 
26500 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
26510 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c  ) must be UTF-8,
26520 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a   not whatever.**
26530 20 63 6f 64 65 70 61 67 65 20 69 73 20 63 75 72   codepage is cur
26540 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20  rently defined. 
26550 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61   Filenames conta
26560 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f  ining internatio
26570 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72  nal.** character
26580 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  s must be conver
26590 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69  ted to UTF-8 pri
265a0 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68  or to passing th
265b0 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74  em into.** sqlit
265c0 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c  e3_open() or sql
265d0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a  ite3_open_v2()..
265e0 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f  **.** <b>Note to
265f0 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65   Windows Runtime
26600 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65   users:</b>  The
26610 20 74 65 6d 70 6f 72 61 72 79 20 64 69 72 65 63   temporary direc
26620 74 6f 72 79 20 6d 75 73 74 20 62 65 20 73 65 74  tory must be set
26630 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c  .** prior to cal
26640 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65  ling sqlite3_ope
26650 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  n() or sqlite3_o
26660 70 65 6e 5f 76 32 28 29 2e 20 20 4f 74 68 65 72  pen_v2().  Other
26670 77 69 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a  wise, various.**
26680 20 66 65 61 74 75 72 65 73 20 74 68 61 74 20 72   features that r
26690 65 71 75 69 72 65 20 74 68 65 20 75 73 65 20 6f  equire the use o
266a0 66 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  f temporary file
266b0 73 20 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a  s may fail..**.*
266c0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
266d0 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74  ite3_temp_direct
266e0 6f 72 79 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ory].*/.int sqli
266f0 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73  te3_open(.  cons
26700 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65  t char *filename
26710 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
26720 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29  filename (UTF-8)
26730 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
26740 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a  ppDb          /*
26750 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
26760 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74  handle */.);.int
26770 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
26780 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66  .  const void *f
26790 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
267a0 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
267b0 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71  (UTF-16) */.  sq
267c0 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20  lite3 **ppDb    
267d0 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
267e0 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
267f0 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
26800 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73  _open_v2(.  cons
26810 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65  t char *filename
26820 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
26830 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29  filename (UTF-8)
26840 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
26850 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a  ppDb,         /*
26860 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
26870 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20  handle */.  int 
26880 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20  flags,          
26890 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a      /* Flags */.
268a0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56    const char *zV
268b0 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  fs        /* Nam
268c0 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20  e of VFS module 
268d0 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a  to use */.);../*
268e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62  .** CAPI3REF: Ob
268f0 74 61 69 6e 20 56 61 6c 75 65 73 20 46 6f 72 20  tain Values For 
26900 55 52 49 20 50 61 72 61 6d 65 74 65 72 73 0a 2a  URI Parameters.*
26910 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 75  *.** These are u
26920 74 69 6c 69 74 79 20 72 6f 75 74 69 6e 65 73 2c  tility routines,
26930 20 75 73 65 66 75 6c 20 74 6f 20 56 46 53 20 69   useful to VFS i
26940 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20  mplementations, 
26950 74 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f  that check.** to
26960 20 73 65 65 20 69 66 20 61 20 64 61 74 61 62 61   see if a databa
26970 73 65 20 66 69 6c 65 20 77 61 73 20 61 20 55 52  se file was a UR
26980 49 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 65 64  I that contained
26990 20 61 20 73 70 65 63 69 66 69 63 20 71 75 65 72   a specific quer
269a0 79 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c  y .** parameter,
269b0 20 61 6e 64 20 69 66 20 73 6f 20 6f 62 74 61 69   and if so obtai
269c0 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ns the value of 
269d0 74 68 61 74 20 71 75 65 72 79 20 70 61 72 61 6d  that query param
269e0 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46  eter..**.** If F
269f0 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65   is the database
26a00 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65   filename pointe
26a10 72 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68  r passed into th
26a20 65 20 78 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64  e xOpen() method
26a30 20 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d   of .** a VFS im
26a40 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65  plementation whe
26a50 6e 20 74 68 65 20 66 6c 61 67 73 20 70 61 72 61  n the flags para
26a60 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 28 29  meter to xOpen()
26a70 20 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20   has one or .** 
26a80 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b 53 51 4c  more of the [SQL
26a90 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72  ITE_OPEN_URI] or
26aa0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
26ab0 49 4e 5f 44 42 5d 20 62 69 74 73 20 73 65 74 20  IN_DB] bits set 
26ac0 61 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68 65 20  and.** P is the 
26ad0 6e 61 6d 65 20 6f 66 20 74 68 65 20 71 75 65 72  name of the quer
26ae0 79 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65  y parameter, the
26af0 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69  n.** sqlite3_uri
26b00 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20  _parameter(F,P) 
26b10 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75  returns the valu
26b20 65 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20 70 61  e of the P.** pa
26b30 72 61 6d 65 74 65 72 20 69 66 20 69 74 20 65 78  rameter if it ex
26b40 69 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70  ists or a NULL p
26b50 6f 69 6e 74 65 72 20 69 66 20 50 20 64 6f 65 73  ointer if P does
26b60 20 6e 6f 74 20 61 70 70 65 61 72 20 61 73 20 61   not appear as a
26b70 20 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d   .** query param
26b80 65 74 65 72 20 6f 6e 20 46 2e 20 20 49 66 20 50  eter on F.  If P
26b90 20 69 73 20 61 20 71 75 65 72 79 20 70 61 72 61   is a query para
26ba0 6d 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61  meter of F.** ha
26bb0 73 20 6e 6f 20 65 78 70 6c 69 63 69 74 20 76 61  s no explicit va
26bc0 6c 75 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  lue, then sqlite
26bd0 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28  3_uri_parameter(
26be0 46 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20  F,P) returns.** 
26bf0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
26c00 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a  empty string..**
26c10 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
26c20 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
26c30 42 29 20 72 6f 75 74 69 6e 65 20 61 73 73 75 6d  B) routine assum
26c40 65 73 20 74 68 61 74 20 50 20 69 73 20 61 20 62  es that P is a b
26c50 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65  oolean.** parame
26c60 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ter and returns 
26c70 74 72 75 65 20 28 31 29 20 6f 72 20 66 61 6c 73  true (1) or fals
26c80 65 20 28 30 29 20 61 63 63 6f 72 64 69 6e 67 20  e (0) according 
26c90 74 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20  to the value.** 
26ca0 6f 66 20 50 2e 20 20 54 68 65 20 73 71 6c 69 74  of P.  The sqlit
26cb0 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
26cc0 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 72 65  ,P,B) routine re
26cd0 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 69  turns true (1) i
26ce0 66 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f  f the.** value o
26cf0 66 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  f query paramete
26d00 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 79  r P is one of "y
26d10 65 73 22 2c 20 22 74 72 75 65 22 2c 20 6f 72 20  es", "true", or 
26d20 22 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63  "on" in any.** c
26d30 61 73 65 20 6f 72 20 69 66 20 74 68 65 20 76 61  ase or if the va
26d40 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20  lue begins with 
26d50 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65  a non-zero numbe
26d60 72 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69  r.  The .** sqli
26d70 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
26d80 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 73 20  F,P,B) routines 
26d90 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 28 30  returns false (0
26da0 29 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f  ) if the value o
26db0 66 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d  f.** query param
26dc0 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66  eter P is one of
26dd0 20 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20   "no", "false", 
26de0 6f 72 20 22 6f 66 66 22 20 69 6e 20 61 6e 79 20  or "off" in any 
26df0 63 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68  case or.** if th
26e00 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77  e value begins w
26e10 69 74 68 20 61 20 6e 75 6d 65 72 69 63 20 7a 65  ith a numeric ze
26e20 72 6f 2e 20 20 49 66 20 50 20 69 73 20 6e 6f 74  ro.  If P is not
26e30 20 61 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61   a query.** para
26e40 6d 65 74 65 72 20 6f 6e 20 46 20 6f 72 20 69 66  meter on F or if
26e50 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20   the value of P 
26e60 69 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63  is does not matc
26e70 68 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20  h any of the.** 
26e80 61 62 6f 76 65 2c 20 74 68 65 6e 20 73 71 6c 69  above, then sqli
26e90 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
26ea0 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 28  F,P,B) returns (
26eb0 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  B!=0)..**.** The
26ec0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74   sqlite3_uri_int
26ed0 36 34 28 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e  64(F,P,D) routin
26ee0 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 20 76  e converts the v
26ef0 61 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f 20 61  alue of P into a
26f00 0a 2a 2a 20 36 34 2d 62 69 74 20 73 69 67 6e 65  .** 64-bit signe
26f10 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 72 65  d integer and re
26f20 74 75 72 6e 73 20 74 68 61 74 20 69 6e 74 65 67  turns that integ
26f30 65 72 2c 20 6f 72 20 44 20 69 66 20 50 20 64 6f  er, or D if P do
26f40 65 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e  es not.** exist.
26f50 20 20 49 66 20 74 68 65 20 76 61 6c 75 65 20 6f    If the value o
26f60 66 20 50 20 69 73 20 73 6f 6d 65 74 68 69 6e 67  f P is something
26f70 20 6f 74 68 65 72 20 74 68 61 6e 20 61 6e 20 69   other than an i
26f80 6e 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20  nteger, then.** 
26f90 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64  zero is returned
26fa0 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73  ..** .** If F is
26fb0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
26fc0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72   then sqlite3_ur
26fd0 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29  i_parameter(F,P)
26fe0 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e   returns NULL an
26ff0 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69  d.** sqlite3_uri
27000 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20  _boolean(F,P,B) 
27010 72 65 74 75 72 6e 73 20 42 2e 20 20 49 66 20 46  returns B.  If F
27020 20 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70   is not a NULL p
27030 6f 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73  ointer and.** is
27040 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20   not a database 
27050 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 70 6f  file pathname po
27060 69 6e 74 65 72 20 74 68 61 74 20 53 51 4c 69 74  inter that SQLit
27070 65 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68  e passed into th
27080 65 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d  e xOpen.** VFS m
27090 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 65 20  ethod, then the 
270a0 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69 73  behavior of this
270b0 20 72 6f 75 74 69 6e 65 20 69 73 20 75 6e 64 65   routine is unde
270c0 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
270d0 6c 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c  ly.** undesirabl
270e0 65 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  e..*/.const char
270f0 20 2a 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61   *sqlite3_uri_pa
27100 72 61 6d 65 74 65 72 28 63 6f 6e 73 74 20 63 68  rameter(const ch
27110 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 63  ar *zFilename, c
27120 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61  onst char *zPara
27130 6d 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  m);.int sqlite3_
27140 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73  uri_boolean(cons
27150 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63  t char *zFile, c
27160 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61  onst char *zPara
27170 6d 2c 20 69 6e 74 20 62 44 65 66 61 75 6c 74 29  m, int bDefault)
27180 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  ;.sqlite3_int64 
27190 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36  sqlite3_uri_int6
271a0 34 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63  4(const char*, c
271b0 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69  onst char*, sqli
271c0 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a  te3_int64);.../*
271d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72  .** CAPI3REF: Er
271e0 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65  ror Codes And Me
271f0 73 73 61 67 65 73 0a 2a 2a 20 4d 45 54 48 4f 44  ssages.** METHOD
27200 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
27210 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
27220 65 6e 74 20 73 71 6c 69 74 65 33 5f 2a 20 41 50  ent sqlite3_* AP
27230 49 20 63 61 6c 6c 20 61 73 73 6f 63 69 61 74 65  I call associate
27240 64 20 77 69 74 68 20 0a 2a 2a 20 5b 64 61 74 61  d with .** [data
27250 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
27260 20 44 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 20   D failed, then 
27270 74 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63  the sqlite3_errc
27280 6f 64 65 28 44 29 20 69 6e 74 65 72 66 61 63 65  ode(D) interface
27290 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20  .** returns the 
272a0 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20  numeric [result 
272b0 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64  code] or [extend
272c0 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  ed result code] 
272d0 66 6f 72 20 74 68 61 74 0a 2a 2a 20 41 50 49 20  for that.** API 
272e0 63 61 6c 6c 2e 0a 2a 2a 20 49 66 20 74 68 65 20  call..** If the 
272f0 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49 20  most recent API 
27300 63 61 6c 6c 20 77 61 73 20 73 75 63 63 65 73 73  call was success
27310 66 75 6c 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ful,.** then the
27320 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72   return value fr
27330 6f 6d 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  om sqlite3_errco
27340 64 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65  de() is undefine
27350 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  d..** ^The sqlit
27360 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63  e3_extended_errc
27370 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  ode().** interfa
27380 63 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 65  ce is the same e
27390 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 6c  xcept that it al
273a0 77 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 65  ways returns the
273b0 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72   .** [extended r
273c0 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e  esult code] even
273d0 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72   when extended r
273e0 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a  esult codes are.
273f0 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a  ** disabled..**.
27400 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
27410 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c  errmsg() and sql
27420 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20  ite3_errmsg16() 
27430 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c  return English-l
27440 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20  anguage.** text 
27450 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74  that describes t
27460 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74  he error, as eit
27470 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46  her UTF-8 or UTF
27480 2d 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79  -16 respectively
27490 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f  ..** ^(Memory to
274a0 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20   hold the error 
274b0 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69  message string i
274c0 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e  s managed intern
274d0 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70  ally..** The app
274e0 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f  lication does no
274f0 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20  t need to worry 
27500 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68  about freeing th
27510 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77  e result..** How
27520 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20  ever, the error 
27530 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20  string might be 
27540 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64  overwritten or d
27550 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a  eallocated by.**
27560 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
27570 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74  s to other SQLit
27580 65 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63  e interface func
27590 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  tions.)^.**.** ^
275a0 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 73  The sqlite3_errs
275b0 74 72 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  tr() interface r
275c0 65 74 75 72 6e 73 20 74 68 65 20 45 6e 67 6c 69  eturns the Engli
275d0 73 68 2d 6c 61 6e 67 75 61 67 65 20 74 65 78 74  sh-language text
275e0 0a 2a 2a 20 74 68 61 74 20 64 65 73 63 72 69 62  .** that describ
275f0 65 73 20 74 68 65 20 5b 72 65 73 75 6c 74 20 63  es the [result c
27600 6f 64 65 5d 2c 20 61 73 20 55 54 46 2d 38 2e 0a  ode], as UTF-8..
27610 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68  ** ^(Memory to h
27620 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65  old the error me
27630 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
27640 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c  managed internal
27650 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75 73 74 20 6e  ly.** and must n
27660 6f 74 20 62 65 20 66 72 65 65 64 20 62 79 20 74  ot be freed by t
27670 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 5e  he application)^
27680 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
27690 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72   serialized [thr
276a0 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20  eading mode] is 
276b0 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68 74  in use, it might
276c0 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 20   be the.** case 
276d0 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65 72  that a second er
276e0 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 20  ror occurs on a 
276f0 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
27700 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68  in between.** th
27710 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66 69  e time of the fi
27720 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74 68  rst error and th
27730 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 20  e call to these 
27740 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57  interfaces..** W
27750 68 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e 73  hen that happens
27760 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72 72  , the second err
27770 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f 72  or will be repor
27780 74 65 64 20 73 69 6e 63 65 20 74 68 65 73 65 0a  ted since these.
27790 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 6c  ** interfaces al
277a0 77 61 79 73 20 72 65 70 6f 72 74 20 74 68 65 20  ways report the 
277b0 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73 75  most recent resu
277c0 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a  lt.  To avoid.**
277d0 20 74 68 69 73 2c 20 65 61 63 68 20 74 68 72 65   this, each thre
277e0 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 78  ad can obtain ex
277f0 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20 74  clusive use of t
27800 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
27810 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79  nection] D.** by
27820 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74   invoking [sqlit
27830 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28  e3_mutex_enter](
27840 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65  [sqlite3_db_mute
27850 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62 65  x](D)) before be
27860 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73  ginning.** to us
27870 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67  e D and invoking
27880 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
27890 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f  leave]([sqlite3_
278a0 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 66  db_mutex](D)) af
278b0 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73  ter.** all calls
278c0 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61 63   to the interfac
278d0 65 73 20 6c 69 73 74 65 64 20 68 65 72 65 20 61  es listed here a
278e0 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a  re completed..**
278f0 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66  .** If an interf
27900 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20 53  ace fails with S
27910 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68  QLITE_MISUSE, th
27920 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74  at means the int
27930 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e  erface.** was in
27940 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c  voked incorrectl
27950 79 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  y by the applica
27960 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63  tion.  In that c
27970 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f  ase, the.** erro
27980 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61  r code and messa
27990 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f  ge may or may no
279a0 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74  t be set..*/.int
279b0 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65   sqlite3_errcode
279c0 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 69  (sqlite3 *db);.i
279d0 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  nt sqlite3_exten
279e0 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69  ded_errcode(sqli
279f0 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20  te3 *db);.const 
27a00 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72  char *sqlite3_er
27a10 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a  rmsg(sqlite3*);.
27a20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
27a30 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c  te3_errmsg16(sql
27a40 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 63 68  ite3*);.const ch
27a50 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 73  ar *sqlite3_errs
27a60 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  tr(int);../*.** 
27a70 43 41 50 49 33 52 45 46 3a 20 50 72 65 70 61 72  CAPI3REF: Prepar
27a80 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  ed Statement Obj
27a90 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ect.** KEYWORDS:
27aa0 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
27ab0 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20  ment} {prepared 
27ac0 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a  statements}.**.*
27ad0 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
27ae0 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70   this object rep
27af0 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65  resents a single
27b00 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
27b10 68 61 74 0a 2a 2a 20 68 61 73 20 62 65 65 6e 20  hat.** has been 
27b20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 62 69  compiled into bi
27b30 6e 61 72 79 20 66 6f 72 6d 20 61 6e 64 20 69 73  nary form and is
27b40 20 72 65 61 64 79 20 74 6f 20 62 65 20 65 76 61   ready to be eva
27b50 6c 75 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  luated..**.** Th
27b60 69 6e 6b 20 6f 66 20 65 61 63 68 20 53 51 4c 20  ink of each SQL 
27b70 73 74 61 74 65 6d 65 6e 74 20 61 73 20 61 20 73  statement as a s
27b80 65 70 61 72 61 74 65 20 63 6f 6d 70 75 74 65 72  eparate computer
27b90 20 70 72 6f 67 72 61 6d 2e 20 20 54 68 65 0a 2a   program.  The.*
27ba0 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74  * original SQL t
27bb0 65 78 74 20 69 73 20 73 6f 75 72 63 65 20 63 6f  ext is source co
27bc0 64 65 2e 20 20 41 20 70 72 65 70 61 72 65 64 20  de.  A prepared 
27bd0 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74  statement object
27be0 20 0a 2a 2a 20 69 73 20 74 68 65 20 63 6f 6d 70   .** is the comp
27bf0 69 6c 65 64 20 6f 62 6a 65 63 74 20 63 6f 64 65  iled object code
27c00 2e 20 20 41 6c 6c 20 53 51 4c 20 6d 75 73 74 20  .  All SQL must 
27c10 62 65 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74  be converted int
27c20 6f 20 61 0a 2a 2a 20 70 72 65 70 61 72 65 64 20  o a.** prepared 
27c30 73 74 61 74 65 6d 65 6e 74 20 62 65 66 6f 72 65  statement before
27c40 20 69 74 20 63 61 6e 20 62 65 20 72 75 6e 2e 0a   it can be run..
27c50 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 2d 63  **.** The life-c
27c60 79 63 6c 65 20 6f 66 20 61 20 70 72 65 70 61 72  ycle of a prepar
27c70 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a  ed statement obj
27c80 65 63 74 20 75 73 75 61 6c 6c 79 20 67 6f 65 73  ect usually goes
27c90 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a   like this:.**.*
27ca0 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43  * <ol>.** <li> C
27cb0 72 65 61 74 65 20 74 68 65 20 70 72 65 70 61 72  reate the prepar
27cc0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a  ed statement obj
27cd0 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ect using [sqlit
27ce0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
27cf0 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76  ..** <li> Bind v
27d00 61 6c 75 65 73 20 74 6f 20 5b 70 61 72 61 6d 65  alues to [parame
27d10 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20  ters] using the 
27d20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
27d30 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61  .**      interfa
27d40 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e  ces..** <li> Run
27d50 20 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c   the SQL by call
27d60 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ing [sqlite3_ste
27d70 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  p()] one or more
27d80 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20   times..** <li> 
27d90 52 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72  Reset the prepar
27da0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69  ed statement usi
27db0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
27dc0 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63  t()] then go bac
27dd0 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65  k.**      to ste
27de0 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65  p 2.  Do this ze
27df0 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ro or more times
27e00 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f  ..** <li> Destro
27e10 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69  y the object usi
27e20 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
27e30 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c  lize()]..** </ol
27e40 3e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  >.*/.typedef str
27e50 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  uct sqlite3_stmt
27e60 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a   sqlite3_stmt;..
27e70 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
27e80 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a  Run-time Limits.
27e90 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
27ea0 65 33 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20  e3.**.** ^(This 
27eb0 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73  interface allows
27ec0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72   the size of var
27ed0 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20  ious constructs 
27ee0 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a  to be limited.**
27ef0 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e   on a connection
27f00 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62   by connection b
27f10 61 73 69 73 2e 20 20 54 68 65 20 66 69 72 73 74  asis.  The first
27f20 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
27f30 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
27f40 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65  onnection] whose
27f50 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20   limit is to be 
27f60 73 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20  set or queried. 
27f70 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   The.** second p
27f80 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20  arameter is one 
27f90 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61  of the [limit ca
27fa0 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64  tegories] that d
27fb0 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73  efine a.** class
27fc0 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74   of constructs t
27fd0 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65  o be size limite
27fe0 64 2e 20 20 54 68 65 20 74 68 69 72 64 20 70 61  d.  The third pa
27ff0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
28000 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20  * new limit for 
28010 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 29  that construct.)
28020 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ^.**.** ^If the 
28030 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e  new limit is a n
28040 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20  egative number, 
28050 74 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63  the limit is unc
28060 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72  hanged..** ^(For
28070 20 65 61 63 68 20 6c 69 6d 69 74 20 63 61 74 65   each limit cate
28080 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49  gory SQLITE_LIMI
28090 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68  T_<i>NAME</i> th
280a0 65 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69  ere is a .** [li
280b0 6d 69 74 73 20 7c 20 68 61 72 64 20 75 70 70 65  mits | hard uppe
280c0 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20  r bound].** set 
280d0 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
280e0 62 79 20 61 20 43 20 70 72 65 70 72 6f 63 65 73  by a C preproces
280f0 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64  sor macro called
28100 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51  .** [limits | SQ
28110 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45  LITE_MAX_<i>NAME
28120 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22  </i>]..** (The "
28130 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20  _LIMIT_" in the 
28140 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20  name is changed 
28150 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a  to "_MAX_".))^.*
28160 2a 20 5e 41 74 74 65 6d 70 74 73 20 74 6f 20 69  * ^Attempts to i
28170 6e 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20  ncrease a limit 
28180 61 62 6f 76 65 20 69 74 73 20 68 61 72 64 20 75  above its hard u
28190 70 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a  pper bound are.*
281a0 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63  * silently trunc
281b0 61 74 65 64 20 74 6f 20 74 68 65 20 68 61 72 64  ated to the hard
281c0 20 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a   upper bound..**
281d0 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20  .** ^Regardless 
281e0 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
281f0 74 20 74 68 65 20 6c 69 6d 69 74 20 77 61 73 20  t the limit was 
28200 63 68 61 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a  changed, the .**
28210 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
28220 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
28230 75 72 6e 73 20 74 68 65 20 70 72 69 6f 72 20 76  urns the prior v
28240 61 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69  alue of the limi
28250 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f  t..** ^Hence, to
28260 20 66 69 6e 64 20 74 68 65 20 63 75 72 72 65 6e   find the curren
28270 74 20 76 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d  t value of a lim
28280 69 74 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67  it without chang
28290 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c  ing it,.** simpl
282a0 79 20 69 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e  y invoke this in
282b0 74 65 72 66 61 63 65 20 77 69 74 68 20 74 68 65  terface with the
282c0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
282d0 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a   set to -1..**.*
282e0 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74  * Run-time limit
282f0 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66  s are intended f
28300 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63  or use in applic
28310 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61  ations that mana
28320 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72  ge.** both their
28330 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61   own internal da
28340 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20  tabase and also 
28350 64 61 74 61 62 61 73 65 73 20 74 68 61 74 20 61  databases that a
28360 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a  re controlled.**
28370 20 62 79 20 75 6e 74 72 75 73 74 65 64 20 65 78   by untrusted ex
28380 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20  ternal sources. 
28390 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c   An example appl
283a0 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65  ication might be
283b0 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65   a.** web browse
283c0 72 20 74 68 61 74 20 68 61 73 20 69 74 73 20 6f  r that has its o
283d0 77 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f 72  wn databases for
283e0 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79   storing history
283f0 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65   and.** separate
28400 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72   databases contr
28410 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72  olled by JavaScr
28420 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  ipt applications
28430 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f   downloaded.** o
28440 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e  ff the Internet.
28450 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64    The internal d
28460 61 74 61 62 61 73 65 73 20 63 61 6e 20 62 65 20  atabases can be 
28470 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72  given the.** lar
28480 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69  ge, default limi
28490 74 73 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d  ts.  Databases m
284a0 61 6e 61 67 65 64 20 62 79 20 65 78 74 65 72 6e  anaged by extern
284b0 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a  al sources can.*
284c0 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20  * be given much 
284d0 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64  smaller limits d
284e0 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65  esigned to preve
284f0 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73  nt a denial of s
28500 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b  ervice.** attack
28510 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69  .  Developers mi
28520 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f  ght also want to
28530 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65   use the [sqlite
28540 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
28550 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
28560 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74   to further cont
28570 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51  rol untrusted SQ
28580 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20  L.  The size of 
28590 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
285a0 63 72 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e  created by an un
285b0 74 72 75 73 74 65 64 20 73 63 72 69 70 74 20 63  trusted script c
285c0 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20  an be contained 
285d0 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61  using the.** [ma
285e0 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50  x_page_count] [P
285f0 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65  RAGMA]..**.** Ne
28600 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74  w run-time limit
28610 20 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20   categories may 
28620 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
28630 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a  re releases..*/.
28640 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69  int sqlite3_limi
28650 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  t(sqlite3*, int 
28660 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b  id, int newVal);
28670 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
28680 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74  : Run-Time Limit
28690 20 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b   Categories.** K
286a0 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20  EYWORDS: {limit 
286b0 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69  category} {*limi
286c0 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a  t categories}.**
286d0 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
286e0 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f  nts define vario
286f0 75 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c  us performance l
28700 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61  imits.** that ca
28710 6e 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20  n be lowered at 
28720 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b  run-time using [
28730 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
28740 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69  ..** The synopsi
28750 73 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67  s of the meaning
28760 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73  s of the various
28770 20 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e   limits is shown
28780 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74   below..** Addit
28790 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
287a0 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61  n is available a
287b0 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69  t [limits | Limi
287c0 74 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a  ts in SQLite]..*
287d0 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53  *.** <dl>.** [[S
287e0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
287f0 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  TH]] ^(<dt>SQLIT
28800 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f  E_LIMIT_LENGTH</
28810 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
28820 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61  aximum size of a
28830 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f  ny string or BLO
28840 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c 20  B or table row, 
28850 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a  in bytes.<dd>)^.
28860 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
28870 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d  IMIT_SQL_LENGTH]
28880 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
28890 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c  IMIT_SQL_LENGTH<
288a0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
288b0 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  maximum length o
288c0 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  f an SQL stateme
288d0 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64  nt, in bytes.</d
288e0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
288f0 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e  ITE_LIMIT_COLUMN
28900 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
28910 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74  LIMIT_COLUMN</dt
28920 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
28930 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63  imum number of c
28940 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c  olumns in a tabl
28950 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20  e definition or 
28960 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  in the.** result
28970 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43   set of a [SELEC
28980 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75  T] or the maximu
28990 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  m number of colu
289a0 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a  mns in an index.
289b0 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45  ** or in an ORDE
289c0 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59  R BY or GROUP BY
289d0 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a   clause.</dd>)^.
289e0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
289f0 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 5d  IMIT_EXPR_DEPTH]
28a00 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
28a10 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c  IMIT_EXPR_DEPTH<
28a20 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
28a30 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66  maximum depth of
28a40 20 74 68 65 20 70 61 72 73 65 20 74 72 65 65 20   the parse tree 
28a50 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f  on any expressio
28a60 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  n.</dd>)^.**.** 
28a70 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  [[SQLITE_LIMIT_C
28a80 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d  OMPOUND_SELECT]]
28a90 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
28aa0 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c  MIT_COMPOUND_SEL
28ab0 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ECT</dt>.** <dd>
28ac0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
28ad0 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61  er of terms in a
28ae0 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54   compound SELECT
28af0 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e   statement.</dd>
28b00 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
28b10 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d  E_LIMIT_VDBE_OP]
28b20 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
28b30 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74  IMIT_VDBE_OP</dt
28b40 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
28b50 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69  imum number of i
28b60 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61  nstructions in a
28b70 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65   virtual machine
28b80 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64   program.** used
28b90 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e   to implement an
28ba0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20   SQL statement. 
28bb0 20 54 68 69 73 20 6c 69 6d 69 74 20 69 73 20 6e   This limit is n
28bc0 6f 74 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20  ot currently.** 
28bd0 65 6e 66 6f 72 63 65 64 2c 20 74 68 6f 75 67 68  enforced, though
28be0 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 61   that might be a
28bf0 64 64 65 64 20 69 6e 20 73 6f 6d 65 20 66 75 74  dded in some fut
28c00 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a  ure release of.*
28c10 2a 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e  * SQLite.</dd>)^
28c20 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
28c30 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41  LIMIT_FUNCTION_A
28c40 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  RG]] ^(<dt>SQLIT
28c50 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e  E_LIMIT_FUNCTION
28c60 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  _ARG</dt>.** <dd
28c70 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
28c80 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
28c90 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c   on a function.<
28ca0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
28cb0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41  QLITE_LIMIT_ATTA
28cc0 43 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  CHED]] ^(<dt>SQL
28cd0 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48  ITE_LIMIT_ATTACH
28ce0 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  ED</dt>.** <dd>T
28cf0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
28d00 72 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61  r of [ATTACH | a
28d10 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
28d20 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  s].)^</dd>.**.**
28d30 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
28d40 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e  LIKE_PATTERN_LEN
28d50 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53  GTH]].** ^(<dt>S
28d60 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45  QLITE_LIMIT_LIKE
28d70 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c  _PATTERN_LENGTH<
28d80 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
28d90 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  maximum length o
28da0 66 20 74 68 65 20 70 61 74 74 65 72 6e 20 61 72  f the pattern ar
28db0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c  gument to the [L
28dc0 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42  IKE] or.** [GLOB
28dd0 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64  ] operators.</dd
28de0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
28df0 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
28e00 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28  E_NUMBER]].** ^(
28e10 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
28e20 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
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 69 6e 64 65 78 20 6e   maximum index n
28e50 75 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b 70 61  umber of any [pa
28e60 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20 53  rameter] in an S
28e70 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a  QL statement.)^.
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 54 52 49 47 47 45 52 5f 44 45 50  IMIT_TRIGGER_DEP
28ea0 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  TH]] ^(<dt>SQLIT
28eb0 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f  E_LIMIT_TRIGGER_
28ec0 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  DEPTH</dt>.** <d
28ed0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65  d>The maximum de
28ee0 70 74 68 20 6f 66 20 72 65 63 75 72 73 69 6f 6e  pth of recursion
28ef0 20 66 6f 72 20 74 72 69 67 67 65 72 73 2e 3c 2f   for triggers.</
28f00 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
28f10 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45  LITE_LIMIT_WORKE
28f20 52 5f 54 48 52 45 41 44 53 5d 5d 20 5e 28 3c 64  R_THREADS]] ^(<d
28f30 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57  t>SQLITE_LIMIT_W
28f40 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 3c 2f 64  ORKER_THREADS</d
28f50 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
28f60 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
28f70 61 75 78 69 6c 69 61 72 79 20 77 6f 72 6b 65 72  auxiliary worker
28f80 20 74 68 72 65 61 64 73 20 74 68 61 74 20 61 20   threads that a 
28f90 73 69 6e 67 6c 65 0a 2a 2a 20 5b 70 72 65 70 61  single.** [prepa
28fa0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6d  red statement] m
28fb0 61 79 20 73 74 61 72 74 2e 3c 2f 64 64 3e 29 5e  ay start.</dd>)^
28fc0 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
28fd0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
28fe0 54 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20  T_LENGTH        
28ff0 20 20 20 20 20 20 20 20 20 20 20 20 30 0a 23 64              0.#d
29000 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
29010 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20  IT_SQL_LENGTH   
29020 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23               1.#
29030 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
29040 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20  MIT_COLUMN      
29050 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a                2.
29060 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
29070 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20  IMIT_EXPR_DEPTH 
29080 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 33                 3
29090 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
290a0 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53  LIMIT_COMPOUND_S
290b0 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20  ELECT           
290c0 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
290d0 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20  _LIMIT_VDBE_OP  
290e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
290f0 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   5.#define SQLIT
29100 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e  E_LIMIT_FUNCTION
29110 5f 41 52 47 20 20 20 20 20 20 20 20 20 20 20 20  _ARG            
29120 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    6.#define SQLI
29130 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45  TE_LIMIT_ATTACHE
29140 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  D               
29150 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c     7.#define SQL
29160 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50  ITE_LIMIT_LIKE_P
29170 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20  ATTERN_LENGTH   
29180 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51      8.#define SQ
29190 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
291a0 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20  BLE_NUMBER      
291b0 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53       9.#define S
291c0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47  QLITE_LIMIT_TRIG
291d0 47 45 52 5f 44 45 50 54 48 20 20 20 20 20 20 20  GER_DEPTH       
291e0 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20       10.#define 
291f0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52  SQLITE_LIMIT_WOR
29200 4b 45 52 5f 54 48 52 45 41 44 53 20 20 20 20 20  KER_THREADS     
29210 20 20 20 20 20 20 31 31 0a 0a 2f 2a 0a 2a 2a 20        11../*.** 
29220 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c  CAPI3REF: Compil
29230 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65  ing An SQL State
29240 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ment.** KEYWORDS
29250 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  : {SQL statement
29260 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 20 4d 45   compiler}.** ME
29270 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
29280 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a 20 73 71   CONSTRUCTOR: sq
29290 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
292a0 20 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53   To execute an S
292b0 51 4c 20 71 75 65 72 79 2c 20 69 74 20 6d 75 73  QL query, it mus
292c0 74 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69  t first be compi
292d0 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d  led into a byte-
292e0 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20  code.** program 
292f0 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65  using one of the
29300 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  se routines..**.
29310 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
29320 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69 73 20  ument, "db", is 
29330 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
29340 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64  ection] obtained
29350 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72   from a.** prior
29360 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
29370 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
29380 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
29390 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20  pen_v2()] or.** 
293a0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
293b0 29 5d 2e 20 20 54 68 65 20 64 61 74 61 62 61 73  )].  The databas
293c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73  e connection mus
293d0 74 20 6e 6f 74 20 68 61 76 65 20 62 65 65 6e 20  t not have been 
293e0 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  closed..**.** Th
293f0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
29400 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20 74 68  t, "zSql", is th
29410 65 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62  e statement to b
29420 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f  e compiled, enco
29430 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72  ded.** as either
29440 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36   UTF-8 or UTF-16
29450 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70  .  The sqlite3_p
29460 72 65 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c  repare() and sql
29470 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
29480 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  ).** interfaces 
29490 75 73 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 73  use UTF-8, and s
294a0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
294b0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  () and sqlite3_p
294c0 72 65 70 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a  repare16_v2().**
294d0 20 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a   use UTF-16..**.
294e0 2a 2a 20 5e 49 66 20 74 68 65 20 6e 42 79 74 65  ** ^If the nByte
294f0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6e 65 67   argument is neg
29500 61 74 69 76 65 2c 20 74 68 65 6e 20 7a 53 71 6c  ative, then zSql
29510 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74   is read up to t
29520 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f  he.** first zero
29530 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66   terminator. ^If
29540 20 6e 42 79 74 65 20 69 73 20 70 6f 73 69 74 69   nByte is positi
29550 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74  ve, then it is t
29560 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
29570 62 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20  bytes read from 
29580 7a 53 71 6c 2e 20 20 5e 49 66 20 6e 42 79 74 65  zSql.  ^If nByte
29590 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 6e   is zero, then n
295a0 6f 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  o prepared.** st
295b0 61 74 65 6d 65 6e 74 20 69 73 20 67 65 6e 65 72  atement is gener
295c0 61 74 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20  ated..** If the 
295d0 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 20 74 68 61  caller knows tha
295e0 74 20 74 68 65 20 73 75 70 70 6c 69 65 64 20 73  t the supplied s
295f0 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72  tring is nul-ter
29600 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 0a 2a 2a  minated, then.**
29610 20 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c   there is a smal
29620 6c 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64  l performance ad
29630 76 61 6e 74 61 67 65 20 74 6f 20 70 61 73 73 69  vantage to passi
29640 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61  ng an nByte para
29650 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73  meter that.** is
29660 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
29670 79 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75  ytes in the inpu
29680 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c  t string <i>incl
29690 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65  uding</i>.** the
296a0 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 2e   nul-terminator.
296b0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69  .**.** ^If pzTai
296c0 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68  l is not NULL th
296d0 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61  en *pzTail is ma
296e0 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74  de to point to t
296f0 68 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a 2a  he first byte.**
29700 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66   past the end of
29710 20 74 68 65 20 66 69 72 73 74 20 53 51 4c 20 73   the first SQL s
29720 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c  tatement in zSql
29730 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  .  These routine
29740 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c  s only.** compil
29750 65 20 74 68 65 20 66 69 72 73 74 20 73 74 61 74  e the first stat
29760 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73  ement in zSql, s
29770 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66  o *pzTail is lef
29780 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a  t pointing to.**
29790 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e   what remains un
297a0 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  compiled..**.** 
297b0 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74  ^*ppStmt is left
297c0 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63   pointing to a c
297d0 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65  ompiled [prepare
297e0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
297f0 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63  t can be.** exec
29800 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  uted using [sqli
29810 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49  te3_step()].  ^I
29820 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 72  f there is an er
29830 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20  ror, *ppStmt is 
29840 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20  set.** to NULL. 
29850 20 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20 74   ^If the input t
29860 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20  ext contains no 
29870 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75  SQL (if the inpu
29880 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a  t is an empty.**
29890 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d   string or a com
298a0 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74  ment) then *ppSt
298b0 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c  mt is set to NUL
298c0 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e  L..** The callin
298d0 67 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 72  g procedure is r
298e0 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64  esponsible for d
298f0 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70  eleting the comp
29900 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74  iled.** SQL stat
29910 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c  ement using [sql
29920 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
29930 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69   after it has fi
29940 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a  nished with it..
29950 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f  ** ppStmt may no
29960 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  t be NULL..**.**
29970 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74 68   ^On success, th
29980 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
29990 65 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f  e() family of ro
299a0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53  utines return [S
299b0 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74  QLITE_OK];.** ot
299c0 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f  herwise an [erro
299d0 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
299e0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ned..**.** The s
299f0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
29a00 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  2() and sqlite3_
29a10 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 20 69  prepare16_v2() i
29a20 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a  nterfaces are.**
29a30 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72   recommended for
29a40 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d   all new program
29a50 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72  s. The two older
29a60 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
29a70 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20  retained.** for 
29a80 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
29a90 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65  ibility, but the
29aa0 69 72 20 75 73 65 20 69 73 20 64 69 73 63 6f 75  ir use is discou
29ab0 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68  raged..** ^In th
29ac0 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
29ad0 73 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 20  s, the prepared 
29ae0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61  statement.** tha
29af0 74 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 74  t is returned (t
29b00 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
29b10 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69  ] object) contai
29b20 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  ns a copy of the
29b30 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c  .** original SQL
29b40 20 74 65 78 74 2e 20 54 68 69 73 20 63 61 75 73   text. This caus
29b50 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  es the [sqlite3_
29b60 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63  step()] interfac
29b70 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64  e to.** behave d
29b80 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 68  ifferently in th
29b90 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20  ree ways:.**.** 
29ba0 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20  <ol>.** <li>.** 
29bb0 5e 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65  ^If the database
29bc0 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c   schema changes,
29bd0 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75   instead of retu
29be0 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43  rning [SQLITE_SC
29bf0 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61  HEMA] as it.** a
29c00 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f  lways used to do
29c10 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
29c20 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69  )] will automati
29c30 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20  cally recompile 
29c40 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65  the SQL.** state
29c50 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20  ment and try to 
29c60 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 20 41 73  run it again. As
29c70 20 6d 61 6e 79 20 61 73 20 5b 53 51 4c 49 54 45   many as [SQLITE
29c80 5f 4d 41 58 5f 53 43 48 45 4d 41 5f 52 45 54 52  _MAX_SCHEMA_RETR
29c90 59 5d 0a 2a 2a 20 72 65 74 72 69 65 73 20 77 69  Y].** retries wi
29ca0 6c 6c 20 6f 63 63 75 72 20 62 65 66 6f 72 65 20  ll occur before 
29cb0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 67  sqlite3_step() g
29cc0 69 76 65 73 20 75 70 20 61 6e 64 20 72 65 74 75  ives up and retu
29cd0 72 6e 73 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a  rns an error..**
29ce0 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   </li>.**.** <li
29cf0 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72  >.** ^When an er
29d00 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c  ror occurs, [sql
29d10 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c  ite3_step()] wil
29d20 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20  l return one of 
29d30 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20  the detailed.** 
29d40 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72  [error codes] or
29d50 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   [extended error
29d60 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c   codes].  ^The l
29d70 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 20 77  egacy behavior w
29d80 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69  as that.** [sqli
29d90 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c  te3_step()] woul
29da0 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20  d only return a 
29db0 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 5f  generic [SQLITE_
29dc0 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f  ERROR] result co
29dd0 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61 70  de.** and the ap
29de0 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20  plication would 
29df0 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73  have to make a s
29e00 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73  econd call to [s
29e10 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a  qlite3_reset()].
29e20 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66  ** in order to f
29e30 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69  ind the underlyi
29e40 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68 65 20  ng cause of the 
29e50 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68  problem. With th
29e60 65 20 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a  e "v2" prepare.*
29e70 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68  * interfaces, th
29e80 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61  e underlying rea
29e90 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f  son for the erro
29ea0 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d  r is returned im
29eb0 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f  mediately..** </
29ec0 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a  li>.**.** <li>.*
29ed0 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 66  * ^If the specif
29ee0 69 63 20 76 61 6c 75 65 20 62 6f 75 6e 64 20 74  ic value bound t
29ef0 6f 20 5b 70 61 72 61 6d 65 74 65 72 20 7c 20 68  o [parameter | h
29f00 6f 73 74 20 70 61 72 61 6d 65 74 65 72 5d 20 69  ost parameter] i
29f10 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45 52 45 20  n the .** WHERE 
29f20 63 6c 61 75 73 65 20 6d 69 67 68 74 20 69 6e 66  clause might inf
29f30 6c 75 65 6e 63 65 20 74 68 65 20 63 68 6f 69 63  luence the choic
29f40 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20  e of query plan 
29f50 66 6f 72 20 61 20 73 74 61 74 65 6d 65 6e 74 2c  for a statement,
29f60 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 73 74 61  .** then the sta
29f70 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 61  tement will be a
29f80 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63  utomatically rec
29f90 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69 66 20 74  ompiled, as if t
29fa0 68 65 72 65 20 68 61 64 20 62 65 65 6e 20 0a 2a  here had been .*
29fb0 2a 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67  * a schema chang
29fc0 65 2c 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20  e, on the first 
29fd0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
29fe0 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67  ] call following
29ff0 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74   any change.** t
2a000 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  o the [sqlite3_b
2a010 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e 64 69  ind_text | bindi
2a020 6e 67 73 5d 20 6f 66 20 74 68 61 74 20 5b 70 61  ngs] of that [pa
2a030 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54  rameter]. .** ^T
2a040 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75  he specific valu
2a050 65 20 6f 66 20 57 48 45 52 45 2d 63 6c 61 75 73  e of WHERE-claus
2a060 65 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d 69  e [parameter] mi
2a070 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68  ght influence th
2a080 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20  e .** choice of 
2a090 71 75 65 72 79 20 70 6c 61 6e 20 69 66 20 74 68  query plan if th
2a0a0 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  e parameter is t
2a0b0 68 65 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64  he left-hand sid
2a0c0 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a  e of a [LIKE].**
2a0d0 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61   or [GLOB] opera
2a0e0 74 6f 72 20 6f 72 20 69 66 20 74 68 65 20 70 61  tor or if the pa
2a0f0 72 61 6d 65 74 65 72 20 69 73 20 63 6f 6d 70 61  rameter is compa
2a100 72 65 64 20 74 6f 20 61 6e 20 69 6e 64 65 78 65  red to an indexe
2a110 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20  d column.** and 
2a120 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  the [SQLITE_ENAB
2a130 4c 45 5f 53 54 41 54 33 5d 20 63 6f 6d 70 69 6c  LE_STAT3] compil
2a140 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73  e-time option is
2a150 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c   enabled..** </l
2a160 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69  i>.** </ol>.*/.i
2a170 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
2a180 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  re(.  sqlite3 *d
2a190 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
2a1a0 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
2a1b0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
2a1c0 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
2a1d0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
2a1e0 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f  UTF-8 encoded */
2a1f0 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
2a200 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
2a210 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
2a220 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
2a230 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
2a240 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
2a250 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
2a260 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2a270 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20  char **pzTail   
2a280 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
2a290 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
2a2a0 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
2a2b0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  ;.int sqlite3_pr
2a2c0 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69  epare_v2(.  sqli
2a2d0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
2a2e0 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
2a2f0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
2a300 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
2a310 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
2a320 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f  ment, UTF-8 enco
2a330 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
2a340 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
2a350 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
2a360 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
2a370 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
2a380 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
2a390 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
2a3a0 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
2a3b0 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54  const char **pzT
2a3c0 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
2a3d0 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
2a3e0 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
2a3f0 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  l */.);.int sqli
2a400 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20  te3_prepare16(. 
2a410 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
2a420 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
2a430 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
2a440 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71   const void *zSq
2a450 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
2a460 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31  statement, UTF-1
2a470 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  6 encoded */.  i
2a480 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
2a490 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
2a4a0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
2a4b0 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
2a4c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
2a4d0 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
2a4e0 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
2a4f0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
2a500 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
2a510 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
2a520 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
2a530 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e  of zSql */.);.in
2a540 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
2a550 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  e16_v2(.  sqlite
2a560 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
2a570 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
2a580 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2a590 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20  void *zSql,     
2a5a0 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
2a5b0 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  nt, UTF-16 encod
2a5c0 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
2a5d0 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
2a5e0 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
2a5f0 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
2a600 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
2a610 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
2a620 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
2a630 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
2a640 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61  onst void **pzTa
2a650 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
2a660 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
2a670 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
2a680 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
2a690 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 76 69  PI3REF: Retrievi
2a6a0 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c  ng Statement SQL
2a6b0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2a6c0 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
2a6d0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 71 6c 28  The sqlite3_sql(
2a6e0 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  P) interface ret
2a6f0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
2a700 6f 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  o a copy of the 
2a710 55 54 46 2d 38 0a 2a 2a 20 53 51 4c 20 74 65 78  UTF-8.** SQL tex
2a720 74 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 65  t used to create
2a730 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2a740 6d 65 6e 74 5d 20 50 20 69 66 20 50 20 77 61 73  ment] P if P was
2a750 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 65  .** created by e
2a760 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70  ither [sqlite3_p
2a770 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
2a780 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2a790 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 20 5e 54 68  16_v2()]..** ^Th
2a7a0 65 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64  e sqlite3_expand
2a7b0 65 64 5f 73 71 6c 28 50 29 20 69 6e 74 65 72 66  ed_sql(P) interf
2a7c0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
2a7d0 69 6e 74 65 72 20 74 6f 20 61 20 55 54 46 2d 38  inter to a UTF-8
2a7e0 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61  .** string conta
2a7f0 69 6e 69 6e 67 20 74 68 65 20 53 51 4c 20 74 65  ining the SQL te
2a800 78 74 20 6f 66 20 70 72 65 70 61 72 65 64 20 73  xt of prepared s
2a810 74 61 74 65 6d 65 6e 74 20 50 20 77 69 74 68 0a  tatement P with.
2a820 2a 2a 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65  ** [bound parame
2a830 74 65 72 73 5d 20 65 78 70 61 6e 64 65 64 2e 0a  ters] expanded..
2a840 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d  **.** ^(For exam
2a850 70 6c 65 2c 20 69 66 20 61 20 70 72 65 70 61 72  ple, if a prepar
2a860 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  ed statement is 
2a870 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 74 68  created using th
2a880 65 20 53 51 4c 0a 2a 2a 20 74 65 78 74 20 22 53  e SQL.** text "S
2a890 45 4c 45 43 54 20 24 61 62 63 2c 3a 78 79 7a 22  ELECT $abc,:xyz"
2a8a0 20 61 6e 64 20 69 66 20 70 61 72 61 6d 65 74 65   and if paramete
2a8b0 72 20 24 61 62 63 20 69 73 20 62 6f 75 6e 64 20  r $abc is bound 
2a8c0 74 6f 20 69 6e 74 65 67 65 72 20 32 33 34 35 0a  to integer 2345.
2a8d0 2a 2a 20 61 6e 64 20 70 61 72 61 6d 65 74 65 72  ** and parameter
2a8e0 20 3a 78 79 7a 20 69 73 20 75 6e 62 6f 75 6e 64   :xyz is unbound
2a8f0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 73  , then sqlite3_s
2a900 71 6c 28 29 20 77 69 6c 6c 20 72 65 74 75 72 6e  ql() will return
2a910 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  .** the original
2a920 20 73 74 72 69 6e 67 2c 20 22 53 45 4c 45 43 54   string, "SELECT
2a930 20 24 61 62 63 2c 3a 78 79 7a 22 20 62 75 74 20   $abc,:xyz" but 
2a940 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64  sqlite3_expanded
2a950 5f 73 71 6c 28 29 0a 2a 2a 20 77 69 6c 6c 20 72  _sql().** will r
2a960 65 74 75 72 6e 20 22 53 45 4c 45 43 54 20 32 33  eturn "SELECT 23
2a970 34 35 2c 4e 55 4c 4c 22 2e 29 5e 0a 2a 2a 0a 2a  45,NULL".)^.**.*
2a980 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
2a990 78 70 61 6e 64 65 64 5f 73 71 6c 28 29 20 69 6e  xpanded_sql() in
2a9a0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2a9b0 4e 55 4c 4c 20 69 66 20 69 6e 73 75 66 66 69 63  NULL if insuffic
2a9c0 69 65 6e 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 69  ient memory.** i
2a9d0 73 20 61 76 61 69 6c 61 62 6c 65 20 74 6f 20 68  s available to h
2a9e0 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74 2c 20  old the result, 
2a9f0 6f 72 20 69 66 20 74 68 65 20 72 65 73 75 6c 74  or if the result
2aa00 20 77 6f 75 6c 64 20 65 78 63 65 65 64 20 74 68   would exceed th
2aa10 65 0a 2a 2a 20 74 68 65 20 6d 61 78 69 6d 75 6d  e.** the maximum
2aa20 20 73 74 72 69 6e 67 20 6c 65 6e 67 74 68 20 64   string length d
2aa30 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65  etermined by the
2aa40 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c   [SQLITE_LIMIT_L
2aa50 45 4e 47 54 48 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ENGTH]..**.** ^T
2aa60 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45  he [SQLITE_TRACE
2aa70 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d  _SIZE_LIMIT] com
2aa80 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
2aa90 20 6c 69 6d 69 74 73 20 74 68 65 20 73 69 7a 65   limits the size
2aaa0 20 6f 66 0a 2a 2a 20 62 6f 75 6e 64 20 70 61 72   of.** bound par
2aab0 61 6d 65 74 65 72 20 65 78 70 61 6e 73 69 6f 6e  ameter expansion
2aac0 73 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  s.  ^The [SQLITE
2aad0 5f 4f 4d 49 54 5f 54 52 41 43 45 5d 20 63 6f 6d  _OMIT_TRACE] com
2aae0 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74  pile-time.** opt
2aaf0 69 6f 6e 20 63 61 75 73 65 73 20 73 71 6c 69 74  ion causes sqlit
2ab00 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28  e3_expanded_sql(
2ab10 29 20 74 6f 20 61 6c 77 61 79 73 20 72 65 74 75  ) to always retu
2ab20 72 6e 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  rn NULL..**.** ^
2ab30 54 68 65 20 73 74 72 69 6e 67 20 72 65 74 75 72  The string retur
2ab40 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73  ned by sqlite3_s
2ab50 71 6c 28 50 29 20 69 73 20 6d 61 6e 61 67 65 64  ql(P) is managed
2ab60 20 62 79 20 53 51 4c 69 74 65 20 61 6e 64 20 69   by SQLite and i
2ab70 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  s.** automatical
2ab80 6c 79 20 66 72 65 65 64 20 77 68 65 6e 20 74 68  ly freed when th
2ab90 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
2aba0 6d 65 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65  ment is finalize
2abb0 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 74 72 69 6e  d..** ^The strin
2abc0 67 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  g returned by sq
2abd0 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73  lite3_expanded_s
2abe0 71 6c 28 50 29 2c 20 6f 6e 20 74 68 65 20 6f 74  ql(P), on the ot
2abf0 68 65 72 20 68 61 6e 64 2c 0a 2a 2a 20 69 73 20  her hand,.** is 
2ac00 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
2ac10 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
2ac20 20 61 6e 64 20 6d 75 73 74 20 62 65 20 66 72 65   and must be fre
2ac30 65 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  e by the applica
2ac40 74 69 6f 6e 0a 2a 2a 20 62 79 20 70 61 73 73 69  tion.** by passi
2ac50 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65  ng it to [sqlite
2ac60 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2f 0a 63 6f  3_free()]..*/.co
2ac70 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
2ac80 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74  3_sql(sqlite3_st
2ac90 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 63 68 61 72  mt *pStmt);.char
2aca0 20 2a 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64   *sqlite3_expand
2acb0 65 64 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73  ed_sql(sqlite3_s
2acc0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
2acd0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
2ace0 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51  termine If An SQ
2acf0 4c 20 53 74 61 74 65 6d 65 6e 74 20 57 72 69 74  L Statement Writ
2ad00 65 73 20 54 68 65 20 44 61 74 61 62 61 73 65 0a  es The Database.
2ad10 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2ad20 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
2ad30 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  he sqlite3_stmt_
2ad40 72 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65  readonly(X) inte
2ad50 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72  rface returns tr
2ad60 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66  ue (non-zero) if
2ad70 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20  .** and only if 
2ad80 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2ad90 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73  atement] X makes
2ada0 20 6e 6f 20 64 69 72 65 63 74 20 63 68 61 6e 67   no direct chang
2adb0 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e  es to.** the con
2adc0 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61  tent of the data
2add0 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a  base file..**.**
2ade0 20 4e 6f 74 65 20 74 68 61 74 20 5b 61 70 70 6c   Note that [appl
2adf0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2ae00 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f  SQL functions] o
2ae10 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61  r.** [virtual ta
2ae20 62 6c 65 73 5d 20 6d 69 67 68 74 20 63 68 61 6e  bles] might chan
2ae30 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ge the database 
2ae40 69 6e 64 69 72 65 63 74 6c 79 20 61 73 20 61 20  indirectly as a 
2ae50 73 69 64 65 20 65 66 66 65 63 74 2e 20 20 0a 2a  side effect.  .*
2ae60 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c  * ^(For example,
2ae70 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69   if an applicati
2ae80 6f 6e 20 64 65 66 69 6e 65 73 20 61 20 66 75 6e  on defines a fun
2ae90 63 74 69 6f 6e 20 22 65 76 61 6c 28 29 22 20 74  ction "eval()" t
2aea0 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73  hat .** calls [s
2aeb0 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20  qlite3_exec()], 
2aec0 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69  then the followi
2aed0 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ng SQL statement
2aee0 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65   would.** change
2aef0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
2af00 6c 65 20 74 68 72 6f 75 67 68 20 73 69 64 65 2d  le through side-
2af10 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c  effects:.**.** <
2af20 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
2af30 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54 20 65 76  .**    SELECT ev
2af40 61 6c 28 27 44 45 4c 45 54 45 20 46 52 4f 4d 20  al('DELETE FROM 
2af50 74 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a  t1') FROM t2;.**
2af60 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
2af70 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62  ote>.**.** But b
2af80 65 63 61 75 73 65 20 74 68 65 20 5b 53 45 4c 45  ecause the [SELE
2af90 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 64 6f  CT] statement do
2afa0 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  es not change th
2afb0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a  e database file.
2afc0 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20 73 71 6c  ** directly, sql
2afd0 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
2afe0 6c 79 28 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c  ly() would still
2aff0 20 72 65 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a   return true.)^.
2b000 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69  **.** ^Transacti
2b010 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65  on control state
2b020 6d 65 6e 74 73 20 73 75 63 68 20 61 73 20 5b 42  ments such as [B
2b030 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c  EGIN], [COMMIT],
2b040 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20   [ROLLBACK],.** 
2b050 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64  [SAVEPOINT], and
2b060 20 5b 52 45 4c 45 41 53 45 5d 20 63 61 75 73 65   [RELEASE] cause
2b070 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
2b080 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75  adonly() to retu
2b090 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63  rn true,.** sinc
2b0a0 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 73  e the statements
2b0b0 20 74 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e   themselves do n
2b0c0 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69  ot actually modi
2b0d0 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20  fy the database 
2b0e0 62 75 74 0a 2a 2a 20 72 61 74 68 65 72 20 74 68  but.** rather th
2b0f0 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74  ey control the t
2b100 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74  iming of when ot
2b110 68 65 72 20 73 74 61 74 65 6d 65 6e 74 73 20 6d  her statements m
2b120 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a 20 64 61  odify the .** da
2b130 74 61 62 61 73 65 2e 20 20 5e 54 68 65 20 5b 41  tabase.  ^The [A
2b140 54 54 41 43 48 5d 20 61 6e 64 20 5b 44 45 54 41  TTACH] and [DETA
2b150 43 48 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 61  CH] statements a
2b160 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c  lso cause.** sql
2b170 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
2b180 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74  ly() to return t
2b190 72 75 65 20 73 69 6e 63 65 2c 20 77 68 69 6c 65  rue since, while
2b1a0 20 74 68 6f 73 65 20 73 74 61 74 65 6d 65 6e 74   those statement
2b1b0 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20  s.** change the 
2b1c0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 66  configuration of
2b1d0 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
2b1e0 65 63 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20  ection, they do 
2b1f0 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61  not make .** cha
2b200 6e 67 65 73 20 74 6f 20 74 68 65 20 63 6f 6e 74  nges to the cont
2b210 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62  ent of the datab
2b220 61 73 65 20 66 69 6c 65 73 20 6f 6e 20 64 69 73  ase files on dis
2b230 6b 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  k..*/.int sqlite
2b240 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
2b250 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
2b260 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
2b270 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
2b280 20 49 66 20 41 20 50 72 65 70 61 72 65 64 20 53   If A Prepared S
2b290 74 61 74 65 6d 65 6e 74 20 48 61 73 20 42 65 65  tatement Has Bee
2b2a0 6e 20 52 65 73 65 74 0a 2a 2a 20 4d 45 54 48 4f  n Reset.** METHO
2b2b0 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
2b2c0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2b2d0 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 20  e3_stmt_busy(S) 
2b2e0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2b2f0 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f  s true (non-zero
2b300 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65  ) if the.** [pre
2b310 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2b320 20 53 20 68 61 73 20 62 65 65 6e 20 73 74 65 70   S has been step
2b330 70 65 64 20 61 74 20 6c 65 61 73 74 20 6f 6e 63  ped at least onc
2b340 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c  e using .** [sql
2b350 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 62 75  ite3_step(S)] bu
2b360 74 20 68 61 73 20 6e 65 69 74 68 65 72 20 72 75  t has neither ru
2b370 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  n to completion 
2b380 28 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51  (returned.** [SQ
2b390 4c 49 54 45 5f 44 4f 4e 45 5d 20 66 72 6f 6d 20  LITE_DONE] from 
2b3a0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
2b3b0 5d 29 20 6e 6f 72 0a 2a 2a 20 62 65 65 6e 20 72  ]) nor.** been r
2b3c0 65 73 65 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  eset using [sqli
2b3d0 74 65 33 5f 72 65 73 65 74 28 53 29 5d 2e 20 20  te3_reset(S)].  
2b3e0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d  ^The sqlite3_stm
2b3f0 74 5f 62 75 73 79 28 53 29 0a 2a 2a 20 69 6e 74  t_busy(S).** int
2b400 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 66  erface returns f
2b410 61 6c 73 65 20 69 66 20 53 20 69 73 20 61 20 4e  alse if S is a N
2b420 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49 66  ULL pointer.  If
2b430 20 53 20 69 73 20 6e 6f 74 20 61 20 0a 2a 2a 20   S is not a .** 
2b440 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64  NULL pointer and
2b450 20 69 73 20 6e 6f 74 20 61 20 70 6f 69 6e 74 65   is not a pointe
2b460 72 20 74 6f 20 61 20 76 61 6c 69 64 20 5b 70 72  r to a valid [pr
2b470 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2b480 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20 74 68 65  ].** object, the
2b490 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
2b4a0 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20  s undefined and 
2b4b0 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72  probably undesir
2b4c0 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  able..**.** This
2b4d0 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62   interface can b
2b4e0 65 20 75 73 65 64 20 69 6e 20 63 6f 6d 62 69 6e  e used in combin
2b4f0 61 74 69 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 6e  ation [sqlite3_n
2b500 65 78 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20 74  ext_stmt()].** t
2b510 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 20 70 72 65  o locate all pre
2b520 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
2b530 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
2b540 20 61 20 64 61 74 61 62 61 73 65 20 0a 2a 2a 20   a database .** 
2b550 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
2b560 61 72 65 20 69 6e 20 6e 65 65 64 20 6f 66 20 62  are in need of b
2b570 65 69 6e 67 20 72 65 73 65 74 2e 20 20 54 68 69  eing reset.  Thi
2b580 73 20 63 61 6e 20 62 65 20 75 73 65 64 2c 0a 2a  s can be used,.*
2b590 2a 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69  * for example, i
2b5a0 6e 20 64 69 61 67 6e 6f 73 74 69 63 20 72 6f 75  n diagnostic rou
2b5b0 74 69 6e 65 73 20 74 6f 20 73 65 61 72 63 68 20  tines to search 
2b5c0 66 6f 72 20 70 72 65 70 61 72 65 64 20 0a 2a 2a  for prepared .**
2b5d0 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74   statements that
2b5e0 20 61 72 65 20 68 6f 6c 64 69 6e 67 20 61 20 74   are holding a t
2b5f0 72 61 6e 73 61 63 74 69 6f 6e 20 6f 70 65 6e 2e  ransaction open.
2b600 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2b610 73 74 6d 74 5f 62 75 73 79 28 73 71 6c 69 74 65  stmt_busy(sqlite
2b620 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
2b630 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d   CAPI3REF: Dynam
2b640 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c  ically Typed Val
2b650 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59  ue Object.** KEY
2b660 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65  WORDS: {protecte
2b670 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d  d sqlite3_value}
2b680 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   {unprotected sq
2b690 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a  lite3_value}.**.
2b6a0 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 74  ** SQLite uses t
2b6b0 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
2b6c0 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65   object to repre
2b6d0 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a  sent all values.
2b6e0 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 73  ** that can be s
2b6f0 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61 62  tored in a datab
2b700 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74  ase table. SQLit
2b710 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74  e uses dynamic t
2b720 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65  yping.** for the
2b730 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65   values it store
2b740 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 74 6f 72  s.  ^Values stor
2b750 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61  ed in sqlite3_va
2b760 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63  lue objects.** c
2b770 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20  an be integers, 
2b780 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
2b790 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20  alues, strings, 
2b7a0 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a  BLOBs, or NULL..
2b7b0 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33  **.** An sqlite3
2b7c0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61  _value object ma
2b7d0 79 20 62 65 20 65 69 74 68 65 72 20 22 70 72 6f  y be either "pro
2b7e0 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72  tected" or "unpr
2b7f0 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d  otected"..** Som
2b800 65 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71  e interfaces req
2b810 75 69 72 65 20 61 20 70 72 6f 74 65 63 74 65 64  uire a protected
2b820 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20   sqlite3_value. 
2b830 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65   Other interface
2b840 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74  s.** will accept
2b850 20 65 69 74 68 65 72 20 61 20 70 72 6f 74 65 63   either a protec
2b860 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74  ted or an unprot
2b870 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2b880 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e  lue..** Every in
2b890 74 65 72 66 61 63 65 20 74 68 61 74 20 61 63 63  terface that acc
2b8a0 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c  epts sqlite3_val
2b8b0 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65  ue arguments spe
2b8c0 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65  cifies.** whethe
2b8d0 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75  r or not it requ
2b8e0 69 72 65 73 20 61 20 70 72 6f 74 65 63 74 65 64  ires a protected
2b8f0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20   sqlite3_value. 
2b900 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   The.** [sqlite3
2b910 5f 76 61 6c 75 65 5f 64 75 70 28 29 5d 20 69 6e  _value_dup()] in
2b920 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
2b930 73 65 64 20 74 6f 20 63 6f 6e 73 74 72 75 63 74  sed to construct
2b940 20 61 20 6e 65 77 20 0a 2a 2a 20 70 72 6f 74 65   a new .** prote
2b950 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2b960 75 65 20 66 72 6f 6d 20 61 6e 20 75 6e 70 72 6f  ue from an unpro
2b970 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2b980 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  alue..**.** The 
2b990 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64  terms "protected
2b9a0 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74  " and "unprotect
2b9b0 65 64 22 20 72 65 66 65 72 20 74 6f 20 77 68 65  ed" refer to whe
2b9c0 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61  ther or not.** a
2b9d0 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20   mutex is held. 
2b9e0 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74   An internal mut
2b9f0 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61  ex is held for a
2ba00 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71   protected.** sq
2ba10 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2ba20 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20  ct but no mutex 
2ba30 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75  is held for an u
2ba40 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71  nprotected.** sq
2ba50 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2ba60 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69  ct.  If SQLite i
2ba70 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65  s compiled to be
2ba80 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64   single-threaded
2ba90 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54  .** (with [SQLIT
2baa0 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
2bab0 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65  and with [sqlite
2bac0 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20  3_threadsafe()] 
2bad0 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20  returning 0).** 
2bae0 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  or if SQLite is 
2baf0 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65  run in one of re
2bb00 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65  duced mutex mode
2bb10 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  s .** [SQLITE_CO
2bb20 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
2bb30 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f  D] or [SQLITE_CO
2bb40 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
2bb50 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20  ].** then there 
2bb60 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f  is no distinctio
2bb70 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63  n between protec
2bb80 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63  ted and unprotec
2bb90 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
2bba0 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64  alue objects and
2bbb0 20 74 68 65 79 20 63 61 6e 20 62 65 20 75 73 65   they can be use
2bbc0 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c  d interchangeabl
2bbd0 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20  y.  However,.** 
2bbe0 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65  for maximum code
2bbf0 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20   portability it 
2bc00 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
2bc10 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  hat applications
2bc20 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74  .** still make t
2bc30 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62  he distinction b
2bc40 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64  etween protected
2bc50 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64   and unprotected
2bc60 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
2bc70 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77  e objects even w
2bc80 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79  hen not strictly
2bc90 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
2bca0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61   ^The sqlite3_va
2bcb0 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74  lue objects that
2bcc0 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20 70   are passed as p
2bcd0 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74  arameters into t
2bce0 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  he.** implementa
2bcf0 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61  tion of [applica
2bd00 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
2bd10 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20   functions] are 
2bd20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54  protected..** ^T
2bd30 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
2bd40 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
2bd50 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
2bd60 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20  column_value()] 
2bd70 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a  is unprotected..
2bd80 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73  ** Unprotected s
2bd90 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2bda0 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65  ects may only be
2bdb0 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73   used with.** [s
2bdc0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
2bdd0 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  lue()] and [sqli
2bde0 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29  te3_bind_value()
2bdf0 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  ]..** The [sqlit
2be00 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20  e3_value_blob | 
2be10 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79  sqlite3_value_ty
2be20 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a  pe()] family of.
2be30 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72 65  ** interfaces re
2be40 71 75 69 72 65 20 70 72 6f 74 65 63 74 65 64 20  quire protected 
2be50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2be60 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65  jects..*/.typede
2be70 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c  f struct Mem sql
2be80 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a  ite3_value;../*.
2be90 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c  ** CAPI3REF: SQL
2bea0 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78   Function Contex
2beb0 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54  t Object.**.** T
2bec0 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68  he context in wh
2bed0 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74  ich an SQL funct
2bee0 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 20  ion executes is 
2bef0 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20  stored in an.** 
2bf00 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
2bf10 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e  object.  ^A poin
2bf20 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65  ter to an sqlite
2bf30 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74  3_context object
2bf40 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69  .** is always fi
2bf50 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
2bf60 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
2bf70 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
2bf80 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70  ons]..** The app
2bf90 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2bfa0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d   SQL function im
2bfb0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c  plementation wil
2bfc0 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70  l pass this.** p
2bfd0 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69  ointer through i
2bfe0 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  nto calls to [sq
2bff0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
2c000 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c   | sqlite3_resul
2c010 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  t()],.** [sqlite
2c020 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
2c030 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ext()], [sqlite3
2c040 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a  _user_data()],.*
2c050 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  * [sqlite3_conte
2c060 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c  xt_db_handle()],
2c070 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75   [sqlite3_get_au
2c080 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64  xdata()],.** and
2c090 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  /or [sqlite3_set
2c0a0 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a  _auxdata()]..*/.
2c0b0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
2c0c0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73  qlite3_context s
2c0d0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a  qlite3_context;.
2c0e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2c0f0 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20   Binding Values 
2c100 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 74  To Prepared Stat
2c110 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52  ements.** KEYWOR
2c120 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  DS: {host parame
2c130 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d  ter} {host param
2c140 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72  eters} {host par
2c150 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20  ameter name}.** 
2c160 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70  KEYWORDS: {SQL p
2c170 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70  arameter} {SQL p
2c180 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61  arameters} {para
2c190 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a  meter binding}.*
2c1a0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2c1b0 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 49  3_stmt.**.** ^(I
2c1c0 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  n the SQL statem
2c1d0 65 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20 74  ent text input t
2c1e0 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  o [sqlite3_prepa
2c1f0 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73  re_v2()] and its
2c200 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69   variants,.** li
2c210 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65  terals may be re
2c220 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61 72  placed by a [par
2c230 61 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61 74  ameter] that mat
2c240 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c  ches one of foll
2c250 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74  owing.** templat
2c260 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  es:.**.** <ul>.*
2c270 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69  * <li>  ?.** <li
2c280 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20  >  ?NNN.** <li> 
2c290 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40   :VVV.** <li>  @
2c2a0 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56  VVV.** <li>  $VV
2c2b0 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  V.** </ul>.**.**
2c2c0 20 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74 65   In the template
2c2d0 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70  s above, NNN rep
2c2e0 72 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65 67  resents an integ
2c2f0 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61  er literal,.** a
2c300 6e 64 20 56 56 56 20 72 65 70 72 65 73 65 6e 74  nd VVV represent
2c310 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69  s an alphanumeri
2c320 63 20 69 64 65 6e 74 69 66 69 65 72 2e 29 5e 20  c identifier.)^ 
2c330 20 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20   ^The values of 
2c340 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74  these.** paramet
2c350 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64  ers (also called
2c360 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   "host parameter
2c370 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20   names" or "SQL 
2c380 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20  parameters").** 
2c390 63 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67  can be set using
2c3a0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
2c3b0 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64  d_*() routines d
2c3c0 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a  efined here..**.
2c3d0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
2c3e0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71  gument to the sq
2c3f0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
2c400 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79  outines is alway
2c410 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74  s.** a pointer t
2c420 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  o the [sqlite3_s
2c430 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75  tmt] object retu
2c440 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71  rned from.** [sq
2c450 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2c460 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
2c470 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
2c480 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
2c490 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  is the index of 
2c4a0 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65  the SQL paramete
2c4b0 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20  r to be set..** 
2c4c0 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51  ^The leftmost SQ
2c4d0 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20  L parameter has 
2c4e0 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20  an index of 1.  
2c4f0 5e 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e  ^When the same n
2c500 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61  amed.** SQL para
2c510 6d 65 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f  meter is used mo
2c520 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65  re than once, se
2c530 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75  cond and subsequ
2c540 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63  ent.** occurrenc
2c550 65 73 20 68 61 76 65 20 74 68 65 20 73 61 6d 65  es have the same
2c560 20 69 6e 64 65 78 20 61 73 20 74 68 65 20 66 69   index as the fi
2c570 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a  rst occurrence..
2c580 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66 6f  ** ^The index fo
2c590 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65  r named paramete
2c5a0 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64  rs can be looked
2c5b0 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a   up using the.**
2c5c0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2c5d0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
2c5e0 5d 20 41 50 49 20 69 66 20 64 65 73 69 72 65 64  ] API if desired
2c5f0 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a  .  ^The index.**
2c600 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61   for "?NNN" para
2c610 6d 65 74 65 72 73 20 69 73 20 74 68 65 20 76 61  meters is the va
2c620 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e  lue of NNN..** ^
2c630 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75  The NNN value mu
2c640 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 20  st be between 1 
2c650 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33  and the [sqlite3
2c660 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72  _limit()].** par
2c670 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c  ameter [SQLITE_L
2c680 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
2c690 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76  MBER] (default v
2c6a0 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a  alue: 999)..**.*
2c6b0 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67  * ^The third arg
2c6c0 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c  ument is the val
2c6d0 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68  ue to bind to th
2c6e0 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  e parameter..** 
2c6f0 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61  ^If the third pa
2c700 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
2c710 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f  e3_bind_text() o
2c720 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  r sqlite3_bind_t
2c730 65 78 74 31 36 28 29 0a 2a 2a 20 6f 72 20 73 71  ext16().** or sq
2c740 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
2c750 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ) is a NULL poin
2c760 74 65 72 20 74 68 65 6e 20 74 68 65 20 66 6f 75  ter then the fou
2c770 72 74 68 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  rth parameter.**
2c780 20 69 73 20 69 67 6e 6f 72 65 64 20 61 6e 64 20   is ignored and 
2c790 74 68 65 20 65 6e 64 20 72 65 73 75 6c 74 20 69  the end result i
2c7a0 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 73 71  s the same as sq
2c7b0 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28  lite3_bind_null(
2c7c0 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68  )..**.** ^(In th
2c7d0 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61  ose routines tha
2c7e0 74 20 68 61 76 65 20 61 20 66 6f 75 72 74 68 20  t have a fourth 
2c7f0 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61  argument, its va
2c800 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75  lue is the.** nu
2c810 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
2c820 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20   the parameter. 
2c830 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68   To be clear: th
2c840 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a  e value is the.*
2c850 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62  * number of <u>b
2c860 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20  ytes</u> in the 
2c870 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e  value, not the n
2c880 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
2c890 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68  ers.)^.** ^If th
2c8a0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
2c8b0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  er to sqlite3_bi
2c8c0 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c  nd_text() or sql
2c8d0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
2c8e0 28 29 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76  ().** is negativ
2c8f0 65 2c 20 74 68 65 6e 20 74 68 65 20 6c 65 6e 67  e, then the leng
2c900 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67  th of the string
2c910 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65   is.** the numbe
2c920 72 20 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f  r of bytes up to
2c930 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
2c940 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49  terminator..** I
2c950 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
2c960 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
2c970 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73  3_bind_blob() is
2c980 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 0a   negative, then.
2c990 2a 2a 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  ** the behavior 
2c9a0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
2c9b0 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69   If a non-negati
2c9c0 76 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  ve fourth parame
2c9d0 74 65 72 20 69 73 20 70 72 6f 76 69 64 65 64 20  ter is provided 
2c9e0 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
2c9f0 74 65 78 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  text().** or sql
2ca00 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
2ca10 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  () or sqlite3_bi
2ca20 6e 64 5f 74 65 78 74 36 34 28 29 20 74 68 65 6e  nd_text64() then
2ca30 0a 2a 2a 20 74 68 61 74 20 70 61 72 61 6d 65 74  .** that paramet
2ca40 65 72 20 6d 75 73 74 20 62 65 20 74 68 65 20 62  er must be the b
2ca50 79 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68  yte offset.** wh
2ca60 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d  ere the NUL term
2ca70 69 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63  inator would occ
2ca80 75 72 20 61 73 73 75 6d 69 6e 67 20 74 68 65 20  ur assuming the 
2ca90 73 74 72 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a  string were NUL.
2caa0 2a 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  ** terminated.  
2cab0 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61  If any NUL chara
2cac0 63 74 65 72 73 20 6f 63 63 75 72 20 61 74 20 62  cters occur at b
2cad0 79 74 65 20 6f 66 66 73 65 74 73 20 6c 65 73 73  yte offsets less
2cae0 20 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61   than .** the va
2caf0 6c 75 65 20 6f 66 20 74 68 65 20 66 6f 75 72 74  lue of the fourt
2cb00 68 20 70 61 72 61 6d 65 74 65 72 20 74 68 65 6e  h parameter then
2cb10 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73   the resulting s
2cb20 74 72 69 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c  tring value will
2cb30 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65  .** contain embe
2cb40 64 64 65 64 20 4e 55 4c 73 2e 20 20 54 68 65 20  dded NULs.  The 
2cb50 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73  result of expres
2cb60 73 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20  sions involving 
2cb70 73 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20  strings.** with 
2cb80 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73  embedded NULs is
2cb90 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
2cba0 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67  * ^The fifth arg
2cbb0 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 42 4c 4f  ument to the BLO
2cbc0 42 20 61 6e 64 20 73 74 72 69 6e 67 20 62 69 6e  B and string bin
2cbd0 64 69 6e 67 20 69 6e 74 65 72 66 61 63 65 73 0a  ding interfaces.
2cbe0 2a 2a 20 69 73 20 61 20 64 65 73 74 72 75 63 74  ** is a destruct
2cbf0 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f  or used to dispo
2cc00 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f  se of the BLOB o
2cc10 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65  r.** string afte
2cc20 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e  r SQLite has fin
2cc30 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 20  ished with it.  
2cc40 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20  ^The destructor 
2cc50 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20  is called.** to 
2cc60 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42  dispose of the B
2cc70 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 65 76  LOB or string ev
2cc80 65 6e 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74  en if the call t
2cc90 6f 20 62 69 6e 64 20 41 50 49 20 66 61 69 6c 73  o bind API fails
2cca0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66  ..** ^If the fif
2ccb0 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a  th argument is.*
2ccc0 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 76 61  * the special va
2ccd0 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54  lue [SQLITE_STAT
2cce0 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  IC], then SQLite
2ccf0 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68   assumes that th
2cd00 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  e.** information
2cd10 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75   is in static, u
2cd20 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 61  nmanaged space a
2cd30 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  nd does not need
2cd40 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a   to be freed..**
2cd50 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61   ^If the fifth a
2cd60 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20  rgument has the 
2cd70 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52  value [SQLITE_TR
2cd80 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a  ANSIENT], then.*
2cd90 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69  * SQLite makes i
2cda0 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63  ts own private c
2cdb0 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 20  opy of the data 
2cdc0 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66  immediately, bef
2cdd0 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74  ore.** the sqlit
2cde0 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
2cdf0 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  ine returns..**.
2ce00 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 20 61 72  ** ^The sixth ar
2ce10 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
2ce20 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20  3_bind_text64() 
2ce30 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 0a 2a  must be one of.*
2ce40 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c  * [SQLITE_UTF8],
2ce50 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c   [SQLITE_UTF16],
2ce60 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45   [SQLITE_UTF16BE
2ce70 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54  ], or [SQLITE_UT
2ce80 46 31 36 4c 45 5d 0a 2a 2a 20 74 6f 20 73 70 65  F16LE].** to spe
2ce90 63 69 66 79 20 74 68 65 20 65 6e 63 6f 64 69 6e  cify the encodin
2cea0 67 20 6f 66 20 74 68 65 20 74 65 78 74 20 69 6e  g of the text in
2ceb0 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
2cec0 65 74 65 72 2e 20 20 49 66 0a 2a 2a 20 74 68 65  eter.  If.** the
2ced0 20 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20   sixth argument 
2cee0 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
2cef0 74 65 78 74 36 34 28 29 20 69 73 20 6e 6f 74 20  text64() is not 
2cf00 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 61 6c  one of the.** al
2cf10 6c 6f 77 65 64 20 76 61 6c 75 65 73 20 73 68 6f  lowed values sho
2cf20 77 6e 20 61 62 6f 76 65 2c 20 6f 72 20 69 66 20  wn above, or if 
2cf30 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  the text encodin
2cf40 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 0a 2a  g is different.*
2cf50 2a 20 66 72 6f 6d 20 74 68 65 20 65 6e 63 6f 64  * from the encod
2cf60 69 6e 67 20 73 70 65 63 69 66 69 65 64 20 62 79  ing specified by
2cf70 20 74 68 65 20 73 69 78 74 68 20 70 61 72 61 6d   the sixth param
2cf80 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 62  eter, then the b
2cf90 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75 6e  ehavior.** is un
2cfa0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
2cfb0 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  The sqlite3_bind
2cfc0 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74  _zeroblob() rout
2cfd0 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42  ine binds a BLOB
2cfe0 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61   of length N tha
2cff0 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77  t.** is filled w
2d000 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20  ith zeroes.  ^A 
2d010 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20  zeroblob uses a 
2d020 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20  fixed amount of 
2d030 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20  memory.** (just 
2d040 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f  an integer to ho
2d050 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77 68 69  ld its size) whi
2d060 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67 20 70  le it is being p
2d070 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72  rocessed..** Zer
2d080 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e  oblobs are inten
2d090 64 65 64 20 74 6f 20 73 65 72 76 65 20 61 73 20  ded to serve as 
2d0a0 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72  placeholders for
2d0b0 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20   BLOBs whose.** 
2d0c0 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72  content is later
2d0d0 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a   written using.*
2d0e0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  * [sqlite3_blob_
2d0f0 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74  open | increment
2d100 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75  al BLOB I/O] rou
2d110 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67  tines..** ^A neg
2d120 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20  ative value for 
2d130 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73  the zeroblob res
2d140 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c  ults in a zero-l
2d150 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a  ength BLOB..**.*
2d160 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20 74 68 65  * ^If any of the
2d170 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
2d180 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  ) routines are c
2d190 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c  alled with a NUL
2d1a0 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72  L pointer.** for
2d1b0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2d1c0 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74  tatement] or wit
2d1d0 68 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61  h a prepared sta
2d1e0 74 65 6d 65 6e 74 20 66 6f 72 20 77 68 69 63 68  tement for which
2d1f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
2d200 70 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61  p()] has been ca
2d210 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63 65 6e 74  lled more recent
2d220 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69 74 65 33  ly than [sqlite3
2d230 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68  _reset()],.** th
2d240 65 6e 20 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c  en the call will
2d250 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
2d260 4d 49 53 55 53 45 5d 2e 20 20 49 66 20 61 6e 79  MISUSE].  If any
2d270 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29   sqlite3_bind_()
2d280 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73 20 70  .** routine is p
2d290 61 73 73 65 64 20 61 20 5b 70 72 65 70 61 72 65  assed a [prepare
2d2a0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
2d2b0 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c  t has been final
2d2c0 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73  ized, the.** res
2d2d0 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ult is undefined
2d2e0 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 68 61   and probably ha
2d2f0 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69  rmful..**.** ^Bi
2d300 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63  ndings are not c
2d310 6c 65 61 72 65 64 20 62 79 20 74 68 65 20 5b 73  leared by the [s
2d320 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2d330 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62  routine..** ^Unb
2d340 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20  ound parameters 
2d350 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20  are interpreted 
2d360 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  as NULL..**.** ^
2d370 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  The sqlite3_bind
2d380 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  _* routines retu
2d390 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  rn [SQLITE_OK] o
2d3a0 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e 0a  n success or an.
2d3b0 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ** [error code] 
2d3c0 69 66 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73  if anything goes
2d3d0 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c   wrong..** ^[SQL
2d3e0 49 54 45 5f 54 4f 4f 42 49 47 5d 20 6d 69 67 68  ITE_TOOBIG] migh
2d3f0 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 69 66  t be returned if
2d400 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 20 73   the size of a s
2d410 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 0a 2a 2a  tring or BLOB.**
2d420 20 65 78 63 65 65 64 73 20 6c 69 6d 69 74 73 20   exceeds limits 
2d430 69 6d 70 6f 73 65 64 20 62 79 20 5b 73 71 6c 69  imposed by [sqli
2d440 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49  te3_limit]([SQLI
2d450 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d  TE_LIMIT_LENGTH]
2d460 29 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ) or.** [SQLITE_
2d470 4d 41 58 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 20  MAX_LENGTH]..** 
2d480 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20  ^[SQLITE_RANGE] 
2d490 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74  is returned if t
2d4a0 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  he parameter.** 
2d4b0 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20  index is out of 
2d4c0 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45  range.  ^[SQLITE
2d4d0 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72  _NOMEM] is retur
2d4e0 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20  ned if malloc() 
2d4f0 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  fails..**.** See
2d500 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
2d510 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
2d520 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  ount()],.** [sql
2d530 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2d540 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64  ter_name()], and
2d550 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2d560 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
2d570 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
2d580 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69  3_bind_blob(sqli
2d590 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
2d5a0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
2d5b0 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   n, void(*)(void
2d5c0 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  *));.int sqlite3
2d5d0 5f 62 69 6e 64 5f 62 6c 6f 62 36 34 28 73 71 6c  _bind_blob64(sql
2d5e0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
2d5f0 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 73 71   const void*, sq
2d600 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20  lite3_uint64,.  
2d610 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2d620 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28 76 6f        void(*)(vo
2d630 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74  id*));.int sqlit
2d640 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73  e3_bind_double(s
2d650 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2d660 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20  t, double);.int 
2d670 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74  sqlite3_bind_int
2d680 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2d690 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73  int, int);.int s
2d6a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36  qlite3_bind_int6
2d6b0 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
2d6c0 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e   int, sqlite3_in
2d6d0 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  t64);.int sqlite
2d6e0 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69  3_bind_null(sqli
2d6f0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b  te3_stmt*, int);
2d700 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
2d710 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73  d_text(sqlite3_s
2d720 74 6d 74 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63  tmt*,int,const c
2d730 68 61 72 2a 2c 69 6e 74 2c 76 6f 69 64 28 2a 29  har*,int,void(*)
2d740 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
2d750 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
2d760 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2d770 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
2d780 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
2d790 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c  void*));.int sql
2d7a0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34  ite3_bind_text64
2d7b0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2d7c0 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  int, const char*
2d7d0 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  , sqlite3_uint64
2d7e0 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
2d7f0 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 28             void(
2d800 2a 29 28 76 6f 69 64 2a 29 2c 20 75 6e 73 69 67  *)(void*), unsig
2d810 6e 65 64 20 63 68 61 72 20 65 6e 63 6f 64 69 6e  ned char encodin
2d820 67 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  g);.int sqlite3_
2d830 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74  bind_value(sqlit
2d840 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
2d850 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  onst sqlite3_val
2d860 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
2d870 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28  3_bind_zeroblob(
2d880 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2d890 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 69 6e 74 20  nt, int n);.int 
2d8a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
2d8b0 6f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 5f  oblob64(sqlite3_
2d8c0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69  stmt*, int, sqli
2d8d0 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 0a 2f 2a  te3_uint64);../*
2d8e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
2d8f0 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61  mber Of SQL Para
2d900 6d 65 74 65 72 73 0a 2a 2a 20 4d 45 54 48 4f 44  meters.** METHOD
2d910 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2d920 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
2d930 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ne can be used t
2d940 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65  o find the numbe
2d950 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65  r of [SQL parame
2d960 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70  ters].** in a [p
2d970 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2d980 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74  t].  SQL paramet
2d990 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f  ers are tokens o
2d9a0 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f  f the.** form "?
2d9b0 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41  ", "?NNN", ":AAA
2d9c0 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40  ", "$AAA", or "@
2d9d0 41 41 41 22 20 74 68 61 74 20 73 65 72 76 65 20  AAA" that serve 
2d9e0 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65  as.** placeholde
2d9f0 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68  rs for values th
2da00 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f  at are [sqlite3_
2da10 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e  bind_blob | boun
2da20 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72  d].** to the par
2da30 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61 74  ameters at a lat
2da40 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e  er time..**.** ^
2da50 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63  (This routine ac
2da60 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74  tually returns t
2da70 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
2da80 6c 61 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f  largest (rightmo
2da90 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  st).** parameter
2daa0 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20  . For all forms 
2dab0 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69  except ?NNN, thi
2dac0 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e  s will correspon
2dad0 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  d to the.** numb
2dae0 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72  er of unique par
2daf0 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61 72  ameters.  If par
2db00 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f  ameters of the ?
2db10 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75 73 65  NNN form are use
2db20 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20  d,.** there may 
2db30 62 65 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c  be gaps in the l
2db40 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65  ist.)^.**.** See
2db50 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
2db60 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
2db70 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
2db80 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2db90 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61  meter_name()], a
2dba0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
2dbb0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
2dbc0 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  dex()]..*/.int s
2dbd0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2dbe0 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69  meter_count(sqli
2dbf0 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
2dc00 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d  ** CAPI3REF: Nam
2dc10 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61  e Of A Host Para
2dc20 6d 65 74 65 72 0a 2a 2a 20 4d 45 54 48 4f 44 3a  meter.** METHOD:
2dc30 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2dc40 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2dc50 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2dc60 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66  name(P,N) interf
2dc70 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  ace returns.** t
2dc80 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e  he name of the N
2dc90 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74  -th [SQL paramet
2dca0 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70  er] in the [prep
2dcb0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2dcc0 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61  P..** ^(SQL para
2dcd0 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f  meters of the fo
2dce0 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41  rm "?NNN" or ":A
2dcf0 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72  AA" or "@AAA" or
2dd00 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20   "$AAA".** have 
2dd10 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20  a name which is 
2dd20 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e  the string "?NNN
2dd30 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22  " or ":AAA" or "
2dd40 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a  @AAA" or "$AAA".
2dd50 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  ** respectively.
2dd60 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  .** In other wor
2dd70 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20  ds, the initial 
2dd80 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40  ":" or "$" or "@
2dd90 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69  " or "?".** is i
2dda0 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 74 20  ncluded as part 
2ddb0 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a  of the name.)^.*
2ddc0 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66  * ^Parameters of
2ddd0 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69   the form "?" wi
2dde0 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e  thout a followin
2ddf0 67 20 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e  g integer have n
2de00 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72  o name.** and ar
2de10 65 20 72 65 66 65 72 72 65 64 20 74 6f 20 61 73  e referred to as
2de20 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22   "nameless" or "
2de30 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65  anonymous parame
2de40 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ters"..**.** ^Th
2de50 65 20 66 69 72 73 74 20 68 6f 73 74 20 70 61 72  e first host par
2de60 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e  ameter has an in
2de70 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e  dex of 1, not 0.
2de80 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76  .**.** ^If the v
2de90 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66  alue N is out of
2dea0 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65   range or if the
2deb0 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20   N-th parameter 
2dec0 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20  is.** nameless, 
2ded0 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74  then NULL is ret
2dee0 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74  urned.  ^The ret
2def0 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a  urned string is.
2df00 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46  ** always in UTF
2df10 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e  -8 encoding even
2df20 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61   if the named pa
2df30 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f  rameter was.** o
2df40 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66  riginally specif
2df50 69 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  ied as UTF-16 in
2df60 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2df70 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  e16()] or.** [sq
2df80 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2df90 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  v2()]..**.** See
2dfa0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
2dfb0 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
2dfc0 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
2dfd0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2dfe0 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20  meter_count()], 
2dff0 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
2e000 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
2e010 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73  ndex()]..*/.cons
2e020 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
2e030 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
2e040 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
2e050 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *, int);../*.** 
2e060 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20  CAPI3REF: Index 
2e070 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57  Of A Parameter W
2e080 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65  ith A Given Name
2e090 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2e0a0 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
2e0b0 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78  Return the index
2e0c0 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d   of an SQL param
2e0d0 65 74 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e  eter given its n
2e0e0 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e  ame.  ^The.** in
2e0f0 64 65 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e  dex value return
2e100 65 64 20 69 73 20 73 75 69 74 61 62 6c 65 20 66  ed is suitable f
2e110 6f 72 20 75 73 65 20 61 73 20 74 68 65 20 73 65  or use as the se
2e120 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65  cond.** paramete
2e130 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69  r to [sqlite3_bi
2e140 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
2e150 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72  bind()].  ^A zer
2e160 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  o.** is returned
2e170 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20   if no matching 
2e180 70 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75  parameter is fou
2e190 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65  nd.  ^The parame
2e1a0 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74  ter.** name must
2e1b0 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46   be given in UTF
2e1c0 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f  -8 even if the o
2e1d0 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e  riginal statemen
2e1e0 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65  t.** was prepare
2e1f0 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65  d from UTF-16 te
2e200 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  xt using [sqlite
2e210 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
2e220 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  ]..**.** See als
2e230 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
2e240 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
2e250 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
2e260 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2e270 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a  r_count()], and.
2e280 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
2e290 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
2e2a0 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
2e2b0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2e2c0 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f  r_index(sqlite3_
2e2d0 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  stmt*, const cha
2e2e0 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a  r *zName);../*.*
2e2f0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65  * CAPI3REF: Rese
2e300 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f  t All Bindings O
2e310 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  n A Prepared Sta
2e320 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44  tement.** METHOD
2e330 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2e340 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74  *.** ^Contrary t
2e350 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20  o the intuition 
2e360 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65  of many, [sqlite
2e370 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20  3_reset()] does 
2e380 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65  not reset.** the
2e390 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2e3a0 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20  lob | bindings] 
2e3b0 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  on a [prepared s
2e3c0 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55  tatement]..** ^U
2e3d0 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  se this routine 
2e3e0 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73  to reset all hos
2e3f0 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  t parameters to 
2e400 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  NULL..*/.int sql
2e410 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69  ite3_clear_bindi
2e420 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ngs(sqlite3_stmt
2e430 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
2e440 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43  REF: Number Of C
2e450 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75  olumns In A Resu
2e460 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44  lt Set.** METHOD
2e470 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2e480 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65  *.** ^Return the
2e490 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
2e4a0 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
2e4b0 20 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79   set returned by
2e4c0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
2e4d0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54  d statement]. ^T
2e4e0 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
2e4f0 72 6e 73 20 30 20 69 66 20 70 53 74 6d 74 20 69  rns 0 if pStmt i
2e500 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74  s an SQL.** stat
2e510 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20  ement that does 
2e520 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61 20  not return data 
2e530 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20  (for example an 
2e540 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a  [UPDATE])..**.**
2e550 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
2e560 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29  te3_data_count()
2e570 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
2e580 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71  _column_count(sq
2e590 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
2e5a0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2e5b0 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65  REF: Column Name
2e5c0 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65  s In A Result Se
2e5d0 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
2e5e0 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
2e5f0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
2e600 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20  return the name 
2e610 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61  assigned to a pa
2e620 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a  rticular column.
2e630 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ** in the result
2e640 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43   set of a [SELEC
2e650 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e  T] statement.  ^
2e660 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  The sqlite3_colu
2e670 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74  mn_name().** int
2e680 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
2e690 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65   pointer to a ze
2e6a0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
2e6b0 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e  F-8 string.** an
2e6c0 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
2e6d0 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e  _name16() return
2e6e0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
2e6f0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
2e700 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e  .** UTF-16 strin
2e710 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 70  g.  ^The first p
2e720 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
2e730 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2e740 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70  ent].** that imp
2e750 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c  lements the [SEL
2e760 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20  ECT] statement. 
2e770 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
2e780 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
2e790 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20  column number.  
2e7a0 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f  ^The leftmost co
2e7b0 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30  lumn is number 0
2e7c0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74  ..**.** ^The ret
2e7d0 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69  urned string poi
2e7e0 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e  nter is valid un
2e7f0 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b  til either the [
2e800 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2e810 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f  nt].** is destro
2e820 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  yed by [sqlite3_
2e830 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75  finalize()] or u
2e840 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65  ntil the stateme
2e850 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61  nt is automatica
2e860 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65  lly.** reprepare
2e870 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63  d by the first c
2e880 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2e890 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61  step()] for a pa
2e8a0 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20  rticular run.** 
2e8b0 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78  or until the nex
2e8c0 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c  t call to.** sql
2e8d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
2e8e0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  () or sqlite3_co
2e8f0 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e  lumn_name16() on
2e900 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e   the same column
2e910 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  ..**.** ^If sqli
2e920 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69  te3_malloc() fai
2e930 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 72  ls during the pr
2e940 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68  ocessing of eith
2e950 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66  er routine.** (f
2e960 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e  or example durin
2e970 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66  g a conversion f
2e980 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46  rom UTF-8 to UTF
2e990 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e  -16) then a.** N
2e9a0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72  ULL pointer is r
2e9b0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
2e9c0 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65  The name of a re
2e9d0 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74  sult column is t
2e9e0 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
2e9f0 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a  "AS" clause for.
2ea00 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20  ** that column, 
2ea10 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 41  if there is an A
2ea20 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68  S clause.  If th
2ea30 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61  ere is no AS cla
2ea40 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  use.** then the 
2ea50 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75  name of the colu
2ea60 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 65  mn is unspecifie
2ea70 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65  d and may change
2ea80 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c   from.** one rel
2ea90 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74  ease of SQLite t
2eaa0 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63  o the next..*/.c
2eab0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
2eac0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73  e3_column_name(s
2ead0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2eae0 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  t N);.const void
2eaf0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2eb00 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
2eb10 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a  stmt*, int N);..
2eb20 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2eb30 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49  Source Of Data I
2eb40 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74  n A Query Result
2eb50 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2eb60 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
2eb70 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70  These routines p
2eb80 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74  rovide a means t
2eb90 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  o determine the 
2eba0 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
2ebb0 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f   and.** table co
2ebc0 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68 65  lumn that is the
2ebd0 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61 72   origin of a par
2ebe0 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20 63  ticular result c
2ebf0 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c  olumn in.** [SEL
2ec00 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a  ECT] statement..
2ec10 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  ** ^The name of 
2ec20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 20  the database or 
2ec30 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20  table or column 
2ec40 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20  can be returned 
2ec50 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55  as.** either a U
2ec60 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73  TF-8 or UTF-16 s
2ec70 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61  tring.  ^The _da
2ec80 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73  tabase_ routines
2ec90 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64   return.** the d
2eca0 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68  atabase name, th
2ecb0 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e  e _table_ routin
2ecc0 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 61  es return the ta
2ecd0 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a  ble name, and.**
2ece0 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75   the origin_ rou
2ecf0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
2ed00 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a   column name..**
2ed10 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
2ed20 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75  tring is valid u
2ed30 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72  ntil the [prepar
2ed40 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73  ed statement] is
2ed50 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73   destroyed.** us
2ed60 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
2ed70 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69  alize()] or unti
2ed80 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  l the statement 
2ed90 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  is automatically
2eda0 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62  .** reprepared b
2edb0 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c  y the first call
2edc0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
2edd0 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69  p()] for a parti
2ede0 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20  cular run.** or 
2edf0 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69  until the same i
2ee00 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65  nformation is re
2ee10 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e  quested.** again
2ee20 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20   in a different 
2ee30 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  encoding..**.** 
2ee40 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72  ^The names retur
2ee50 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67  ned are the orig
2ee60 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20  inal un-aliased 
2ee70 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20  names of the.** 
2ee80 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
2ee90 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a   and column..**.
2eea0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
2eeb0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 20  gument to these 
2eec0 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 61 20  interfaces is a 
2eed0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2eee0 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20  ent]..** ^These 
2eef0 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
2ef00 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
2ef10 75 74 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c  ut the Nth resul
2ef20 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65  t column returne
2ef30 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74  d by.** the stat
2ef40 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69  ement, where N i
2ef50 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e  s the second fun
2ef60 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a  ction argument..
2ef70 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73  ** ^The left-mos
2ef80 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75  t column is colu
2ef90 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65 20 72  mn 0 for these r
2efa0 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  outines..**.** ^
2efb0 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  If the Nth colum
2efc0 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  n returned by th
2efd0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
2efe0 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a  n expression or.
2eff0 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64 20  ** subquery and 
2f000 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20  is not a column 
2f010 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20  value, then all 
2f020 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  of these functio
2f030 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c  ns return.** NUL
2f040 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69  L.  ^These routi
2f050 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65  ne might also re
2f060 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d  turn NULL if a m
2f070 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
2f080 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73   error.** occurs
2f090 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 74  .  ^Otherwise, t
2f0a0 68 65 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e  hey return the n
2f0b0 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 63  ame of the attac
2f0c0 68 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 61  hed database, ta
2f0d0 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d  ble,.** or colum
2f0e0 6e 20 74 68 61 74 20 71 75 65 72 79 20 72 65 73  n that query res
2f0f0 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65  ult column was e
2f100 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a  xtracted from..*
2f110 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 6c  *.** ^As with al
2f120 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41  l other SQLite A
2f130 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 65  PIs, those whose
2f140 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68 20   names end with 
2f150 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55  "16" return.** U
2f160 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74  TF-16 encoded st
2f170 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f 74  rings and the ot
2f180 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  her functions re
2f190 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a  turn UTF-8..**.*
2f1a0 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20 61 72  * ^These APIs ar
2f1b0 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  e only available
2f1c0 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20   if the library 
2f1d0 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  was compiled wit
2f1e0 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  h the.** [SQLITE
2f1f0 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d  _ENABLE_COLUMN_M
2f200 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72  ETADATA] C-prepr
2f210 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a  ocessor symbol..
2f220 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20  **.** If two or 
2f230 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c  more threads cal
2f240 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66  l one or more of
2f250 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
2f260 61 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65  against the same
2f270 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61  .** prepared sta
2f280 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d  tement and colum
2f290 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  n at the same ti
2f2a0 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  me then the resu
2f2b0 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66  lts are.** undef
2f2c0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  ined..**.** If t
2f2d0 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61  wo or more threa
2f2e0 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d  ds call one or m
2f2f0 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ore.** [sqlite3_
2f300 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
2f310 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65  name | column me
2f320 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 65  tadata interface
2f330 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61  s].** for the sa
2f340 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  me [prepared sta
2f350 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75  tement] and resu
2f360 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20  lt column.** at 
2f370 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68  the same time th
2f380 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
2f390 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f  re undefined..*/
2f3a0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
2f3b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
2f3c0 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65  base_name(sqlite
2f3d0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
2f3e0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2f3f0 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
2f400 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  e_name16(sqlite3
2f410 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
2f420 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
2f430 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61  _column_table_na
2f440 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
2f450 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
2f460 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
2f470 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73  n_table_name16(s
2f480 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2f490 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
2f4a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72  qlite3_column_or
2f4b0 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65  igin_name(sqlite
2f4c0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
2f4d0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2f4e0 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f  3_column_origin_
2f4f0 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
2f500 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  tmt*,int);../*.*
2f510 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c  * CAPI3REF: Decl
2f520 61 72 65 64 20 44 61 74 61 74 79 70 65 20 4f 66  ared Datatype Of
2f530 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a   A Query Result.
2f540 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2f550 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28  e3_stmt.**.** ^(
2f560 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
2f570 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 72  ter is a [prepar
2f580 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
2f590 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65 6d  * If this statem
2f5a0 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54  ent is a [SELECT
2f5b0 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  ] statement and 
2f5c0 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
2f5d0 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65  f the.** returne
2f5e0 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  d result set of 
2f5f0 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73  that [SELECT] is
2f600 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20   a table column 
2f610 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65  (not an.** expre
2f620 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72  ssion or subquer
2f630 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c  y) then the decl
2f640 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65  ared type of the
2f650 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e   table.** column
2f660 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20   is returned.)^ 
2f670 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c   ^If the Nth col
2f680 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c  umn of the resul
2f690 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65  t set is an.** e
2f6a0 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
2f6b0 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55  query, then a NU
2f6c0 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  LL pointer is re
2f6d0 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  turned..** ^The 
2f6e0 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
2f6f0 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20  is always UTF-8 
2f700 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  encoded..**.** ^
2f710 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69  (For example, gi
2f720 76 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  ven the database
2f730 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43   schema:.**.** C
2f740 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 63  REATE TABLE t1(c
2f750 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a  1 VARIANT);.**.*
2f760 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77  * and the follow
2f770 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  ing statement to
2f780 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a   be compiled:.**
2f790 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20  .** SELECT c1 + 
2f7a0 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a  1, c1 FROM t1;.*
2f7b0 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e  *.** this routin
2f7c0 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74  e would return t
2f7d0 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 41  he string "VARIA
2f7e0 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f  NT" for the seco
2f7f0 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c  nd result.** col
2f800 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20  umn (i==1), and 
2f810 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66  a NULL pointer f
2f820 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65 73  or the first res
2f830 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30  ult column (i==0
2f840 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  ).)^.**.** ^SQLi
2f850 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20  te uses dynamic 
2f860 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e  run-time typing.
2f870 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75    ^So just becau
2f880 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  se a column.** i
2f890 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f  s declared to co
2f8a0 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c  ntain a particul
2f8b0 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74  ar type does not
2f8c0 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a   mean that the.*
2f8d0 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e  * data stored in
2f8e0 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20   that column is 
2f8f0 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20  of the declared 
2f900 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73  type.  SQLite is
2f910 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70  .** strongly typ
2f920 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69  ed, but the typi
2f930 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f  ng is dynamic no
2f940 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65  t static.  ^Type
2f950 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65  .** is associate
2f960 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61  d with individua
2f970 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69  l values, not wi
2f980 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72  th the container
2f990 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c  s.** used to hol
2f9a0 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a  d those values..
2f9b0 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
2f9c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
2f9d0 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73  cltype(sqlite3_s
2f9e0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
2f9f0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
2fa00 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36  olumn_decltype16
2fa10 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2fa20 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
2fa30 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41  3REF: Evaluate A
2fa40 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a  n SQL Statement.
2fa50 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2fa60 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 41 66  e3_stmt.**.** Af
2fa70 74 65 72 20 61 20 5b 70 72 65 70 61 72 65 64 20  ter a [prepared 
2fa80 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62  statement] has b
2fa90 65 65 6e 20 70 72 65 70 61 72 65 64 20 75 73 69  een prepared usi
2faa0 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71  ng either.** [sq
2fab0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2fac0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2fad0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
2fae0 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65  or one of the le
2faf0 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
2fb00 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  es [sqlite3_prep
2fb10 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  are()] or [sqlit
2fb20 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c  e3_prepare16()],
2fb30 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a   this function.*
2fb40 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  * must be called
2fb50 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d   one or more tim
2fb60 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74  es to evaluate t
2fb70 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  he statement..**
2fb80 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20  .** The details 
2fb90 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  of the behavior 
2fba0 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  of the sqlite3_s
2fbb0 74 65 70 28 29 20 69 6e 74 65 72 66 61 63 65 20  tep() interface 
2fbc0 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65  depend.** on whe
2fbd0 74 68 65 72 20 74 68 65 20 73 74 61 74 65 6d 65  ther the stateme
2fbe0 6e 74 20 77 61 73 20 70 72 65 70 61 72 65 64 20  nt was prepared 
2fbf0 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20  using the newer 
2fc00 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a  "v2" interface.*
2fc10 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
2fc20 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
2fc30 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2fc40 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64  v2()] or the old
2fc50 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  er legacy.** int
2fc60 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f  erface [sqlite3_
2fc70 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b  prepare()] and [
2fc80 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2fc90 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f  6()].  The use o
2fca0 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32  f the.** new "v2
2fcb0 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72  " interface is r
2fcc0 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e  ecommended for n
2fcd0 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ew applications 
2fce0 62 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a  but the legacy.*
2fcf0 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  * interface will
2fd00 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20   continue to be 
2fd10 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a  supported..**.**
2fd20 20 5e 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20   ^In the legacy 
2fd30 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72  interface, the r
2fd40 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c  eturn value will
2fd50 20 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49   be either [SQLI
2fd60 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51  TE_BUSY],.** [SQ
2fd70 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c  LITE_DONE], [SQL
2fd80 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54  ITE_ROW], [SQLIT
2fd90 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51  E_ERROR], or [SQ
2fda0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a  LITE_MISUSE]..**
2fdb0 20 5e 57 69 74 68 20 74 68 65 20 22 76 32 22 20   ^With the "v2" 
2fdc0 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f  interface, any o
2fdd0 66 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73  f the other [res
2fde0 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a  ult codes] or.**
2fdf0 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
2fe00 74 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62  t codes] might b
2fe10 65 20 72 65 74 75 72 6e 65 64 20 61 73 20 77 65  e returned as we
2fe20 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49  ll..**.** ^[SQLI
2fe30 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74  TE_BUSY] means t
2fe40 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65  hat the database
2fe50 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62   engine was unab
2fe60 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20 74 68  le to acquire th
2fe70 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f  e.** database lo
2fe80 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20  cks it needs to 
2fe90 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66  do its job.  ^If
2fea0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
2feb0 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20  s a [COMMIT].** 
2fec0 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64  or occurs outsid
2fed0 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74  e of an explicit
2fee0 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68   transaction, th
2fef0 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79  en you can retry
2ff00 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   the.** statemen
2ff10 74 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65  t.  If the state
2ff20 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43  ment is not a [C
2ff30 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72  OMMIT] and occur
2ff40 73 20 77 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65  s within an.** e
2ff50 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
2ff60 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f  ion then you sho
2ff70 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65  uld rollback the
2ff80 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66   transaction bef
2ff90 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e  ore.** continuin
2ffa0 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54  g..**.** ^[SQLIT
2ffb0 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68  E_DONE] means th
2ffc0 61 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  at the statement
2ffd0 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78   has finished ex
2ffe0 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65  ecuting.** succe
2fff0 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65  ssfully.  sqlite
30000 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20  3_step() should 
30010 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67  not be called ag
30020 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74  ain on this virt
30030 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77  ual.** machine w
30040 69 74 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c  ithout first cal
30050 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
30060 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20  set()] to reset 
30070 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d  the virtual.** m
30080 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69  achine back to i
30090 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65  ts initial state
300a0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
300b0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65  SQL statement be
300c0 69 6e 67 20 65 78 65 63 75 74 65 64 20 72 65 74  ing executed ret
300d0 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74  urns any data, t
300e0 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  hen [SQLITE_ROW]
300f0 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
30100 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20  each time a new 
30110 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20 72  row of data is r
30120 65 61 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73  eady for process
30130 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61  ing by the.** ca
30140 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73  ller. The values
30150 20 6d 61 79 20 62 65 20 61 63 63 65 73 73 65 64   may be accessed
30160 20 75 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75   using the [colu
30170 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
30180 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33  ons]..** sqlite3
30190 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65  _step() is calle
301a0 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69  d again to retri
301b0 65 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77  eve the next row
301c0 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20   of data..**.** 
301d0 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20  ^[SQLITE_ERROR] 
301e0 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e  means that a run
301f0 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63  -time error (suc
30200 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e  h as a constrain
30210 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20  t.** violation) 
30220 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73  has occurred.  s
30230 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68  qlite3_step() sh
30240 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c  ould not be call
30250 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74  ed again on.** t
30260 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f  he VM. More info
30270 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66  rmation may be f
30280 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20  ound by calling 
30290 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
302a0 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65  )]..** ^With the
302b0 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
302c0 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66  e, a more specif
302d0 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66  ic error code (f
302e0 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b  or example,.** [
302f0 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
30300 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  ], [SQLITE_SCHEM
30310 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52  A], [SQLITE_CORR
30320 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72  UPT], and so for
30330 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62  th).** can be ob
30340 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e  tained by callin
30350 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
30360 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70  ()] on the.** [p
30370 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
30380 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22 76 32  t].  ^In the "v2
30390 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20  " interface,.** 
303a0 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69  the more specifi
303b0 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20  c error code is 
303c0 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c  returned directl
303d0 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65  y by sqlite3_ste
303e0 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49  p()..**.** [SQLI
303f0 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73  TE_MISUSE] means
30400 20 74 68 61 74 20 74 68 65 20 74 68 69 73 20 72   that the this r
30410 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65  outine was calle
30420 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c  d inappropriatel
30430 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74  y..** Perhaps it
30440 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61   was called on a
30450 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
30460 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a  ment] that has.*
30470 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b  * already been [
30480 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
30490 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72   | finalized] or
304a0 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64   on one that had
304b0 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72  .** previously r
304c0 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
304d0 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54  ERROR] or [SQLIT
304e0 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20  E_DONE].  Or it 
304f0 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20  could.** be the 
30500 63 61 73 65 20 74 68 61 74 20 74 68 65 20 73 61  case that the sa
30510 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
30520 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20  ection is being 
30530 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a  used by two or.*
30540 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61  * more threads a
30550 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e  t the same momen
30560 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  t in time..**.**
30570 20 46 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e   For all version
30580 73 20 6f 66 20 53 51 4c 69 74 65 20 75 70 20 74  s of SQLite up t
30590 6f 20 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20  o and including 
305a0 33 2e 36 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c  3.6.23.1, a call
305b0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
305c0 72 65 73 65 74 28 29 5d 20 77 61 73 20 72 65 71  reset()] was req
305d0 75 69 72 65 64 20 61 66 74 65 72 20 73 71 6c 69  uired after sqli
305e0 74 65 33 5f 73 74 65 70 28 29 20 72 65 74 75 72  te3_step() retur
305f0 6e 65 64 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20  ned anything.** 
30600 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
30610 54 45 5f 52 4f 57 5d 20 62 65 66 6f 72 65 20 61  TE_ROW] before a
30620 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e  ny subsequent in
30630 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73  vocation of.** s
30640 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
30650 46 61 69 6c 75 72 65 20 74 6f 20 72 65 73 65 74  Failure to reset
30660 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
30670 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a  atement using .*
30680 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
30690 28 29 5d 20 77 6f 75 6c 64 20 72 65 73 75 6c 74  ()] would result
306a0 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d   in an [SQLITE_M
306b0 49 53 55 53 45 5d 20 72 65 74 75 72 6e 20 66 72  ISUSE] return fr
306c0 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  om.** sqlite3_st
306d0 65 70 28 29 2e 20 20 42 75 74 20 61 66 74 65 72  ep().  But after
306e0 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e   version 3.6.23.
306f0 31 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  1, sqlite3_step(
30700 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69  ) began.** calli
30710 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
30720 74 28 29 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c  t()] automatical
30730 6c 79 20 69 6e 20 74 68 69 73 20 63 69 72 63 75  ly in this circu
30740 6d 73 74 61 6e 63 65 20 72 61 74 68 65 72 0a 2a  mstance rather.*
30750 2a 20 74 68 61 6e 20 72 65 74 75 72 6e 69 6e 67  * than returning
30760 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
30770 2e 20 20 54 68 69 73 20 69 73 20 6e 6f 74 20 63  .  This is not c
30780 6f 6e 73 69 64 65 72 65 64 20 61 20 63 6f 6d 70  onsidered a comp
30790 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65  atibility.** bre
307a0 61 6b 20 62 65 63 61 75 73 65 20 61 6e 79 20 61  ak because any a
307b0 70 70 6c 69 63 61 74 69 6f 6e 20 74 68 61 74 20  pplication that 
307c0 65 76 65 72 20 72 65 63 65 69 76 65 73 20 61 6e  ever receives an
307d0 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 65   SQLITE_MISUSE e
307e0 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65  rror.** is broke
307f0 6e 20 62 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e  n by definition.
30800 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d    The [SQLITE_OM
30810 49 54 5f 41 55 54 4f 52 45 53 45 54 5d 20 63 6f  IT_AUTORESET] co
30820 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
30830 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64  n.** can be used
30840 20 74 6f 20 72 65 73 74 6f 72 65 20 74 68 65 20   to restore the 
30850 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 2e  legacy behavior.
30860 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20  .**.** <b>Goofy 
30870 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a  Interface Alert:
30880 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61  </b> In the lega
30890 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  cy interface, th
308a0 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  e sqlite3_step()
308b0 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72  .** API always r
308c0 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63  eturns a generic
308d0 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51   error code, [SQ
308e0 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c  LITE_ERROR], fol
308f0 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72  lowing any.** er
30900 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  ror other than [
30910 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64  SQLITE_BUSY] and
30920 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
30930 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c  .  You must call
30940 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
30950 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  et()] or [sqlite
30960 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e  3_finalize()] in
30970 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f   order to find o
30980 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65  ne of the.** spe
30990 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64  cific [error cod
309a0 65 73 5d 20 74 68 61 74 20 62 65 74 74 65 72 20  es] that better 
309b0 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72  describes the er
309c0 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74  ror..** We admit
309d0 20 74 68 61 74 20 74 68 69 73 20 69 73 20 61 20   that this is a 
309e0 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54  goofy design.  T
309f0 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62  he problem has b
30a00 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74  een fixed.** wit
30a10 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  h the "v2" inter
30a20 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72  face.  If you pr
30a30 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75  epare all of you
30a40 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  r SQL statements
30a50 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72  .** using either
30a60 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
30a70 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  e_v2()] or [sqli
30a80 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
30a90 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f  ()] instead.** o
30aa0 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71  f the legacy [sq
30ab0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
30ac0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
30ad0 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72  epare16()] inter
30ae0 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74  faces,.** then t
30af0 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63  he more specific
30b00 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61   [error codes] a
30b10 72 65 20 72 65 74 75 72 6e 65 64 20 64 69 72 65  re returned dire
30b20 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74  ctly.** by sqlit
30b30 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20  e3_step().  The 
30b40 75 73 65 20 6f 66 20 74 68 65 20 22 76 32 22 20  use of the "v2" 
30b50 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63  interface is rec
30b60 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74  ommended..*/.int
30b70 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71   sqlite3_step(sq
30b80 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
30b90 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
30ba0 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
30bb0 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74   in a result set
30bc0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
30bd0 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
30be0 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
30bf0 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72 66  _count(P) interf
30c00 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
30c10 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
30c20 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72  s in the.** curr
30c30 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72  ent row of the r
30c40 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72  esult set of [pr
30c50 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
30c60 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70  ] P..** ^If prep
30c70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50  ared statement P
30c80 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 72   does not have r
30c90 65 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f 20  esults ready to 
30ca0 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63  return.** (via c
30cb0 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71 6c  alls to the [sql
30cc0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20  ite3_column_int 
30cd0 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  | sqlite3_column
30ce0 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65  _*()] of.** inte
30cf0 72 66 61 63 65 73 29 20 74 68 65 6e 20 73 71 6c  rfaces) then sql
30d00 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
30d10 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a  P) returns 0..**
30d20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
30d30 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74  ta_count(P) rout
30d40 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e 73  ine also returns
30d50 20 30 20 69 66 20 50 20 69 73 20 61 20 4e 55 4c   0 if P is a NUL
30d60 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54  L pointer..** ^T
30d70 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  he sqlite3_data_
30d80 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65  count(P) routine
30d90 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 74 68   returns 0 if th
30da0 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  e previous call 
30db0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  to.** [sqlite3_s
30dc0 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64  tep](P) returned
30dd0 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20   [SQLITE_DONE]. 
30de0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
30df0 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77  ta_count(P).** w
30e00 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a  ill return non-z
30e10 65 72 6f 20 69 66 20 70 72 65 76 69 6f 75 73 20  ero if previous 
30e20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
30e30 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e  _step](P) return
30e40 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f  ed.** [SQLITE_RO
30e50 57 5d 2c 20 65 78 63 65 70 74 20 69 6e 20 74 68  W], except in th
30e60 65 20 63 61 73 65 20 6f 66 20 74 68 65 20 5b 50  e case of the [P
30e70 52 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61  RAGMA incrementa
30e80 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65  l_vacuum].** whe
30e90 72 65 20 69 74 20 61 6c 77 61 79 73 20 72 65 74  re it always ret
30ea0 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65 20  urns zero since 
30eb0 65 61 63 68 20 73 74 65 70 20 6f 66 20 74 68 61  each step of tha
30ec0 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20  t multi-step.** 
30ed0 70 72 61 67 6d 61 20 72 65 74 75 72 6e 73 20 30  pragma returns 0
30ee0 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61   columns of data
30ef0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
30f00 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  : [sqlite3_colum
30f10 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e  n_count()].*/.in
30f20 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  t sqlite3_data_c
30f30 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  ount(sqlite3_stm
30f40 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
30f50 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64  * CAPI3REF: Fund
30f60 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65  amental Datatype
30f70 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53  s.** KEYWORDS: S
30f80 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a  QLITE_TEXT.**.**
30f90 20 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20 69   ^(Every value i
30fa0 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65  n SQLite has one
30fb0 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65   of five fundame
30fc0 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a  ntal datatypes:.
30fd0 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
30fe0 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  i> 64-bit signed
30ff0 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e   integer.** <li>
31000 20 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f   64-bit IEEE flo
31010 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62  ating point numb
31020 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e  er.** <li> strin
31030 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a  g.** <li> BLOB.*
31040 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c  * <li> NULL.** <
31050 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  /ul>)^.**.** The
31060 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  se constants are
31070 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20   codes for each 
31080 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a  of those types..
31090 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
310a0 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20  the SQLITE_TEXT 
310b0 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73  constant was als
310c0 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65  o used in SQLite
310d0 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f   version 2.** fo
310e0 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64  r a completely d
310f0 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67  ifferent meaning
31100 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74  .  Software that
31110 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62   links against b
31120 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65  oth.** SQLite ve
31130 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69  rsion 2 and SQLi
31140 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f  te version 3 sho
31150 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f  uld use SQLITE3_
31160 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c  TEXT, not.** SQL
31170 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65  ITE_TEXT..*/.#de
31180 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
31190 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53  GER  1.#define S
311a0 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32  QLITE_FLOAT    2
311b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
311c0 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69  BLOB     4.#defi
311d0 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20  ne SQLITE_NULL  
311e0 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49     5.#ifdef SQLI
311f0 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20  TE_TEXT.# undef 
31200 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73  SQLITE_TEXT.#els
31210 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  e.# define SQLIT
31220 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e  E_TEXT     3.#en
31230 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  dif.#define SQLI
31240 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a  TE3_TEXT     3..
31250 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
31260 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72  Result Values Fr
31270 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45  om A Query.** KE
31280 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20  YWORDS: {column 
31290 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73  access functions
312a0 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  }.** METHOD: sql
312b0 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
312c0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
312d0 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69  return informati
312e0 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c  on about a singl
312f0 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  e column of the 
31300 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c  current.** resul
31310 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79  t row of a query
31320 2e 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61 73  .  ^In every cas
31330 65 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  e the first argu
31340 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
31350 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65  r.** to the [pre
31360 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
31370 20 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 65   that is being e
31380 76 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73  valuated (the [s
31390 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a  qlite3_stmt*].**
313a0 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e   that was return
313b0 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
313c0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
313d0 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72  r one of its var
313e0 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68  iants).** and th
313f0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
31400 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f  t is the index o
31410 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72  f the column for
31420 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69   which informati
31430 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20  on.** should be 
31440 72 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c  returned. ^The l
31450 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f  eftmost column o
31460 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
31470 20 68 61 73 20 74 68 65 20 69 6e 64 65 78 20 30   has the index 0
31480 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72  ..** ^The number
31490 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
314a0 68 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62 65  he result can be
314b0 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e   determined usin
314c0 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  g.** [sqlite3_co
314d0 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a  lumn_count()]..*
314e0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20  *.** If the SQL 
314f0 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e  statement does n
31500 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69  ot currently poi
31510 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f  nt to a valid ro
31520 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20  w, or if the.** 
31530 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20  column index is 
31540 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68  out of range, th
31550 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65  e result is unde
31560 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20  fined..** These 
31570 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c  routines may onl
31580 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e  y be called when
31590 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
315a0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
315b0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
315c0 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
315d0 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68  E_ROW] and neith
315e0 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  er.** [sqlite3_r
315f0 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c  eset()] nor [sql
31600 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
31610 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65   have been calle
31620 64 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a  d subsequently..
31630 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65  ** If any of the
31640 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
31650 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71  called after [sq
31660 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
31670 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  r.** [sqlite3_fi
31680 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74  nalize()] or aft
31690 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  er [sqlite3_step
316a0 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64  ()] has returned
316b0 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74  .** something ot
316c0 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
316d0 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c  _ROW], the resul
316e0 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
316f0 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33  ..** If [sqlite3
31700 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c  _step()] or [sql
31710 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
31720 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
31730 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c  ze()].** are cal
31740 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65  led from a diffe
31750 72 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c  rent thread whil
31760 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72  e any of these r
31770 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70  outines.** are p
31780 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65  ending, then the
31790 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
317a0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
317b0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
317c0 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65  n_type() routine
317d0 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20   returns the.** 
317e0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20  [SQLITE_INTEGER 
317f0 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d  | datatype code]
31800 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c   for the initial
31810 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66   data type.** of
31820 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75   the result colu
31830 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e  mn.  ^The return
31840 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20  ed value is one 
31850 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  of [SQLITE_INTEG
31860 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ER],.** [SQLITE_
31870 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  FLOAT], [SQLITE_
31880 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42  TEXT], [SQLITE_B
31890 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  LOB], or [SQLITE
318a0 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c  _NULL].  The val
318b0 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  ue.** returned b
318c0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
318d0 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20  _type() is only 
318e0 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f  meaningful if no
318f0 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73   type.** convers
31900 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72  ions have occurr
31910 65 64 20 61 73 20 64 65 73 63 72 69 62 65 64 20  ed as described 
31920 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20  below.  After a 
31930 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c  type conversion,
31940 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65  .** the value re
31950 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
31960 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
31970 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46  is undefined.  F
31980 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e  uture.** version
31990 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20  s of SQLite may 
319a0 63 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 76  change the behav
319b0 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63  ior of sqlite3_c
319c0 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20  olumn_type().** 
319d0 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65  following a type
319e0 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a   conversion..**.
319f0 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
31a00 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55  t is a BLOB or U
31a10 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e  TF-8 string then
31a20 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   the sqlite3_col
31a30 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72  umn_bytes().** r
31a40 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
31a50 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
31a60 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20  es in that BLOB 
31a70 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  or string..** ^I
31a80 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
31a90 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c  a UTF-16 string,
31aa0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
31ab0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e  lumn_bytes() con
31ac0 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72  verts.** the str
31ad0 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64  ing to UTF-8 and
31ae0 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68   then returns th
31af0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
31b00 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  s..** ^If the re
31b10 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69  sult is a numeri
31b20 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c  c value then sql
31b30 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
31b40 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c  s() uses.** [sql
31b50 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
31b60 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74   to convert that
31b70 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d   value to a UTF-
31b80 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74  8 string and ret
31b90 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  urns.** the numb
31ba0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
31bb0 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e  hat string..** ^
31bc0 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
31bd0 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69   NULL, then sqli
31be0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
31bf0 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e  () returns zero.
31c00 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  .**.** ^If the r
31c10 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20  esult is a BLOB 
31c20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  or UTF-16 string
31c30 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
31c40 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
31c50 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65  ().** routine re
31c60 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
31c70 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
31c80 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  t BLOB or string
31c90 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
31ca0 75 6c 74 20 69 73 20 61 20 55 54 46 2d 38 20 73  ult is a UTF-8 s
31cb0 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69  tring, then sqli
31cc0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
31cd0 31 36 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a  16() converts.**
31ce0 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55   the string to U
31cf0 54 46 2d 31 36 20 61 6e 64 20 74 68 65 6e 20 72  TF-16 and then r
31d00 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
31d10 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e  r of bytes..** ^
31d20 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
31d30 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65   a numeric value
31d40 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
31d50 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 75  lumn_bytes16() u
31d60 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ses.** [sqlite3_
31d70 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63  snprintf()] to c
31d80 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75  onvert that valu
31d90 65 20 74 6f 20 61 20 55 54 46 2d 31 36 20 73 74  e to a UTF-16 st
31da0 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73  ring and returns
31db0 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
31dc0 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
31dd0 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74  string..** ^If t
31de0 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c  he result is NUL
31df0 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  L, then sqlite3_
31e00 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
31e10 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a   returns zero..*
31e20 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 73  *.** ^The values
31e30 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
31e40 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
31e50 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73  es()] and .** [s
31e60 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
31e70 74 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20  tes16()] do not 
31e80 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f  include the zero
31e90 20 74 65 72 6d 69 6e 61 74 6f 72 73 20 61 74 20   terminators at 
31ea0 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68  the end.** of th
31eb0 65 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20  e string.  ^For 
31ec0 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c  clarity: the val
31ed0 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ues returned by.
31ee0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
31ef0 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20  mn_bytes()] and 
31f00 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
31f10 62 79 74 65 73 31 36 28 29 5d 20 61 72 65 20 74  bytes16()] are t
31f20 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
31f30 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72  bytes in the str
31f40 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d  ing, not the num
31f50 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
31f60 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67  s..**.** ^String
31f70 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  s returned by sq
31f80 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
31f90 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
31fa0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c  column_text16(),
31fb0 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73  .** even empty s
31fc0 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61  trings, are alwa
31fd0 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  ys zero-terminat
31fe0 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e  ed.  ^The return
31ff0 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  .** value from s
32000 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
32010 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d  ob() for a zero-
32020 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61  length BLOB is a
32030 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
32040 2a 0a 2a 2a 20 3c 62 3e 57 61 72 6e 69 6e 67 3a  *.** <b>Warning:
32050 3c 2f 62 3e 20 5e 54 68 65 20 6f 62 6a 65 63 74  </b> ^The object
32060 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
32070 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
32080 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b  ue()] is an.** [
32090 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
320a0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
320b0 74 2e 20 20 49 6e 20 61 20 6d 75 6c 74 69 74 68  t.  In a multith
320c0 72 65 61 64 65 64 20 65 6e 76 69 72 6f 6e 6d 65  readed environme
320d0 6e 74 2c 0a 2a 2a 20 61 6e 20 75 6e 70 72 6f 74  nt,.** an unprot
320e0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
320f0 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 6f  lue object may o
32100 6e 6c 79 20 62 65 20 75 73 65 64 20 73 61 66 65  nly be used safe
32110 6c 79 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69  ly with.** [sqli
32120 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29  te3_bind_value()
32130 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  ] and [sqlite3_r
32140 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a  esult_value()]..
32150 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f  ** If the [unpro
32160 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
32170 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74  alue] object ret
32180 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
32190 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
321a0 65 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20  e()] is used in 
321b0 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69  any other way, i
321c0 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a  ncluding calls.*
321d0 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69  * to routines li
321e0 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ke [sqlite3_valu
321f0 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74  e_int()], [sqlit
32200 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d  e3_value_text()]
32210 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ,.** or [sqlite3
32220 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c  _value_bytes()],
32230 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
32240 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e   not threadsafe.
32250 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
32260 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74 6f  tines attempt to
32270 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c   convert the val
32280 75 65 20 77 68 65 72 65 20 61 70 70 72 6f 70 72  ue where appropr
32290 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65  iate.  ^For.** e
322a0 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69  xample, if the i
322b0 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e  nternal represen
322c0 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20  tation is FLOAT 
322d0 61 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 6c  and a text resul
322e0 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65  t.** is requeste
322f0 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  d, [sqlite3_snpr
32300 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64 20  intf()] is used 
32310 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65  internally to pe
32320 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e  rform the.** con
32330 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69  version automati
32340 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f  cally.  ^(The fo
32350 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65  llowing table de
32360 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72  tails the conver
32370 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72  sions.** that ar
32380 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a  e applied:.**.**
32390 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a   <blockquote>.**
323a0 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22   <table border="
323b0 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20  1">.** <tr><th> 
323c0 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65  Internal<br>Type
323d0 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c   <th> Requested<
323e0 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f  br>Type <th>  Co
323f0 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c  nversion.**.** <
32400 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
32410 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
32420 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30  <td> Result is 0
32430 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
32440 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  LL    <td>  FLOA
32450 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  T    <td> Result
32460 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c   is 0.0.** <tr><
32470 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
32480 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
32490 20 52 65 73 75 6c 74 20 69 73 20 61 20 4e 55 4c   Result is a NUL
324a0 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72  L pointer.** <tr
324b0 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
324c0 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
324d0 64 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20 4e  d> Result is a N
324e0 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c  ULL pointer.** <
324f0 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
32500 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
32510 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f  <td> Convert fro
32520 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f  m integer to flo
32530 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49  at.** <tr><td> I
32540 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54  NTEGER  <td>   T
32550 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49  EXT    <td> ASCI
32560 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  I rendering of t
32570 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74  he integer.** <t
32580 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20  r><td> INTEGER  
32590 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
325a0 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45  td> Same as INTE
325b0 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72  GER->TEXT.** <tr
325c0 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
325d0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
325e0 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54  d> [CAST] to INT
325f0 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  EGER.** <tr><td>
32600 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20    FLOAT   <td>  
32610 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53   TEXT    <td> AS
32620 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  CII rendering of
32630 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74   the float.** <t
32640 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20  r><td>  FLOAT   
32650 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
32660 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 42 4c  td> [CAST] to BL
32670 4f 42 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  OB.** <tr><td>  
32680 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54  TEXT    <td> INT
32690 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53  EGER   <td> [CAS
326a0 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a  T] to INTEGER.**
326b0 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
326c0 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
326d0 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f    <td> [CAST] to
326e0 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64   REAL.** <tr><td
326f0 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
32700 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e    BLOB    <td> N
32710 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e  o change.** <tr>
32720 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
32730 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
32740 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45  > [CAST] to INTE
32750 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  GER.** <tr><td> 
32760 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46   BLOB    <td>  F
32770 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 41  LOAT    <td> [CA
32780 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c  ST] to REAL.** <
32790 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
327a0 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
327b0 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20  <td> Add a zero 
327c0 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65  terminator if ne
327d0 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e  eded.** </table>
327e0 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  .** </blockquote
327f0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  >)^.**.** Note t
32800 68 61 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f  hat when type co
32810 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c  nversions occur,
32820 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
32830 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63  ed by prior.** c
32840 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
32850 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73  column_blob(), s
32860 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
32870 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20  xt(), and/or.** 
32880 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
32890 65 78 74 31 36 28 29 20 6d 61 79 20 62 65 20 69  ext16() may be i
328a0 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54  nvalidated..** T
328b0 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20  ype conversions 
328c0 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61  and pointer inva
328d0 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20  lidations might 
328e0 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20  occur.** in the 
328f0 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a  following cases:
32900 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
32910 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20  li> The initial 
32920 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f  content is a BLO
32930 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  B and sqlite3_co
32940 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a  lumn_text() or.*
32950 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63  *      sqlite3_c
32960 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69  olumn_text16() i
32970 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72  s called.  A zer
32980 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67  o-terminator mig
32990 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20  ht.**      need 
329a0 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20 74  to be added to t
329b0 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a  he string.</li>.
329c0 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
329d0 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55  ial content is U
329e0 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71  TF-8 text and sq
329f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
32a00 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20  es16() or.**    
32a10 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
32a20 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c  _text16() is cal
32a30 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e  led.  The conten
32a40 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  t must be conver
32a50 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55  ted.**      to U
32a60 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c  TF-16.</li>.** <
32a70 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20  li> The initial 
32a80 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31  content is UTF-1
32a90 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74  6 text and sqlit
32aa0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
32ab0 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c  ) or.**      sql
32ac0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
32ad0 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54  () is called.  T
32ae0 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20  he content must 
32af0 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20  be converted.** 
32b00 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f       to UTF-8.</
32b10 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  li>.** </ul>.**.
32b20 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20  ** ^Conversions 
32b30 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65  between UTF-16be
32b40 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72   and UTF-16le ar
32b50 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e  e always done in
32b60 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a   place and do.**
32b70 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20   not invalidate 
32b80 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c  a prior pointer,
32b90 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73   though of cours
32ba0 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  e the content of
32bb0 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74   the buffer.** t
32bc0 68 61 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f  hat the prior po
32bd0 69 6e 74 65 72 20 72 65 66 65 72 65 6e 63 65 73  inter references
32be0 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20   will have been 
32bf0 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72  modified.  Other
32c00 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e   kinds.** of con
32c10 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65  version are done
32c20 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69   in place when i
32c30 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62  t is possible, b
32c40 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65  ut sometimes the
32c50 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73  y.** are not pos
32c60 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f  sible and in tho
32c70 73 65 20 63 61 73 65 73 20 70 72 69 6f 72 20 70  se cases prior p
32c80 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61  ointers are inva
32c90 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  lidated..**.** T
32ca0 68 65 20 73 61 66 65 73 74 20 70 6f 6c 69 63 79  he safest policy
32cb0 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68   is to invoke th
32cc0 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  ese routines.** 
32cd0 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  in one of the fo
32ce0 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a  llowing ways:.**
32cf0 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69  .** <ul>.**  <li
32d00 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
32d10 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20  text() followed 
32d20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
32d30 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a  n_bytes()</li>.*
32d40 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
32d50 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c  olumn_blob() fol
32d60 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
32d70 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c  _column_bytes()<
32d80 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  /li>.**  <li>sql
32d90 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
32da0 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  16() followed by
32db0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
32dc0 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a  bytes16()</li>.*
32dd0 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e  * </ul>.**.** In
32de0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f   other words, yo
32df0 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71  u should call sq
32e00 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
32e10 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  t(),.** sqlite3_
32e20 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f  column_blob(), o
32e30 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
32e40 5f 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20  _text16() first 
32e50 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73  to force the res
32e60 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20  ult.** into the 
32e70 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20  desired format, 
32e80 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69  then invoke sqli
32e90 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
32ea0 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  () or.** sqlite3
32eb0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
32ec0 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69  ) to find the si
32ed0 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ze of the result
32ee0 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61  .  Do not mix ca
32ef0 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  lls.** to sqlite
32f00 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
32f10 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
32f20 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61  n_blob() with ca
32f30 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  lls to.** sqlite
32f40 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
32f50 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d  (), and do not m
32f60 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ix calls to sqli
32f70 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
32f80 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c  6().** with call
32f90 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
32fa0 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a  umn_bytes()..**.
32fb0 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73  ** ^The pointers
32fc0 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 61   returned are va
32fd0 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65  lid until a type
32fe0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75   conversion occu
32ff0 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62  rs as.** describ
33000 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74  ed above, or unt
33010 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  il [sqlite3_step
33020 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
33030 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b  reset()] or.** [
33040 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
33050 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  ()] is called.  
33060 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63  ^The memory spac
33070 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73  e used to hold s
33080 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c  trings.** and BL
33090 4f 42 73 20 69 73 20 66 72 65 65 64 20 61 75 74  OBs is freed aut
330a0 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20  omatically.  Do 
330b0 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20 70 61 73  <em>not</em> pas
330c0 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72  s the pointers r
330d0 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  eturned.** from 
330e0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
330f0 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65  blob()], [sqlite
33100 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d  3_column_text()]
33110 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b  , etc. into.** [
33120 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
33130 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65  .**.** ^(If a me
33140 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
33150 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72  error occurs dur
33160 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74 69  ing the evaluati
33170 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20  on of any.** of 
33180 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20  these routines, 
33190 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20  a default value 
331a0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  is returned.  Th
331b0 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a  e default value.
331c0 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74 68 65  ** is either the
331d0 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20   integer 0, the 
331e0 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e  floating point n
331f0 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20  umber 0.0, or a 
33200 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e  NULL.** pointer.
33210 20 20 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c    Subsequent cal
33220 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  ls to [sqlite3_e
33230 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72  rrcode()] will r
33240 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  eturn.** [SQLITE
33250 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f  _NOMEM].)^.*/.co
33260 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
33270 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71  3_column_blob(sq
33280 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
33290 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
332a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
332b0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
332c0 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int 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 73 71 6c 69 74 65 33 5f 73 74  tes16(sqlite3_st
332f0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
33300 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63  double sqlite3_c
33310 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c  olumn_double(sql
33320 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
33330 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
33340 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71  e3_column_int(sq
33350 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
33360 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f   iCol);.sqlite3_
33370 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f  int64 sqlite3_co
33380 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74  lumn_int64(sqlit
33390 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
333a0 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67  ol);.const unsig
333b0 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65  ned char *sqlite
333c0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71  3_column_text(sq
333d0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
333e0 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f   iCol);.const vo
333f0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
33400 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  mn_text16(sqlite
33410 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
33420 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
33430 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69  column_type(sqli
33440 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
33450 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61  Col);.sqlite3_va
33460 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  lue *sqlite3_col
33470 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65  umn_value(sqlite
33480 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
33490 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
334a0 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50  REF: Destroy A P
334b0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
334c0 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 44 45 53 54  t Object.** DEST
334d0 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 5f  RUCTOR: sqlite3_
334e0 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  stmt.**.** ^The 
334f0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
33500 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  () function is c
33510 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20  alled to delete 
33520 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
33530 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74  ement]..** ^If t
33540 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65  he most recent e
33550 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68 65  valuation of the
33560 20 73 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75   statement encou
33570 6e 74 65 72 65 64 20 6e 6f 20 65 72 72 6f 72 73  ntered no errors
33580 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65 20 73 74  .** or if the st
33590 61 74 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 72  atement is never
335a0 20 62 65 65 6e 20 65 76 61 6c 75 61 74 65 64 2c   been evaluated,
335b0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 69   then sqlite3_fi
335c0 6e 61 6c 69 7a 65 28 29 20 72 65 74 75 72 6e 73  nalize() returns
335d0 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20  .** SQLITE_OK.  
335e0 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
335f0 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f  ent evaluation o
33600 66 20 73 74 61 74 65 6d 65 6e 74 20 53 20 66 61  f statement S fa
33610 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71  iled, then.** sq
33620 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53  lite3_finalize(S
33630 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 61 70  ) returns the ap
33640 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72  propriate [error
33650 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78   code] or.** [ex
33660 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64  tended error cod
33670 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  e]..**.** ^The s
33680 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
33690 53 29 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62  S) routine can b
336a0 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20  e called at any 
336b0 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20  point during.** 
336c0 74 68 65 20 6c 69 66 65 20 63 79 63 6c 65 20 6f  the life cycle o
336d0 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  f [prepared stat
336e0 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66  ement] S:.** bef
336f0 6f 72 65 20 73 74 61 74 65 6d 65 6e 74 20 53 20  ore statement S 
33700 69 73 20 65 76 65 72 20 65 76 61 6c 75 61 74 65  is ever evaluate
33710 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20  d, after.** one 
33720 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f  or more calls to
33730 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
33740 29 5d 2c 20 6f 72 20 61 66 74 65 72 20 61 6e 79  )], or after any
33750 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c   call.** to [sql
33760 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 67  ite3_step()] reg
33770 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
33780 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 74  er or not the st
33790 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63  atement has.** c
337a0 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 69  ompleted executi
337b0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b  on..**.** ^Invok
337c0 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  ing sqlite3_fina
337d0 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c  lize() on a NULL
337e0 20 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61   pointer is a ha
337f0 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a  rmless no-op..**
33800 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
33810 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a  ion must finaliz
33820 65 20 65 76 65 72 79 20 5b 70 72 65 70 61 72 65  e every [prepare
33830 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20  d statement] in 
33840 6f 72 64 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a  order to avoid.*
33850 2a 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 73  * resource leaks
33860 2e 20 20 49 74 20 69 73 20 61 20 67 72 69 65 76  .  It is a griev
33870 6f 75 73 20 65 72 72 6f 72 20 66 6f 72 20 74 68  ous error for th
33880 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f  e application to
33890 20 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61   try to use.** a
338a0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
338b0 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73  ent after it has
338c0 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e   been finalized.
338d0 20 20 41 6e 79 20 75 73 65 20 6f 66 20 61 20 70    Any use of a p
338e0 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65  repared.** state
338f0 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61  ment after it ha
33900 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64  s been finalized
33910 20 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 75   can result in u
33920 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20  ndefined and.** 
33930 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 61  undesirable beha
33940 76 69 6f 72 20 73 75 63 68 20 61 73 20 73 65 67  vior such as seg
33950 66 61 75 6c 74 73 20 61 6e 64 20 68 65 61 70 20  faults and heap 
33960 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 69  corruption..*/.i
33970 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  nt sqlite3_final
33980 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ize(sqlite3_stmt
33990 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
339a0 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74   CAPI3REF: Reset
339b0 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
339c0 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20  ement Object.** 
339d0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
339e0 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  stmt.**.** The s
339f0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20 66  qlite3_reset() f
33a00 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65  unction is calle
33a10 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b 70 72  d to reset a [pr
33a20 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
33a30 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b  ].** object back
33a40 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20   to its initial 
33a50 73 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20  state, ready to 
33a60 62 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a  be re-executed..
33a70 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74 61 74  ** ^Any SQL stat
33a80 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20  ement variables 
33a90 74 68 61 74 20 68 61 64 20 76 61 6c 75 65 73 20  that had values 
33aa0 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73  bound to them us
33ab0 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  ing.** the [sqli
33ac0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
33ad0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
33ae0 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65   API] retain the
33af0 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73  ir values..** Us
33b00 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72  e [sqlite3_clear
33b10 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20  _bindings()] to 
33b20 72 65 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e  reset the bindin
33b30 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  gs..**.** ^The [
33b40 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
33b50 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 65  ] interface rese
33b60 74 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  ts the [prepared
33b70 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a   statement] S.**
33b80 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62 65 67   back to the beg
33b90 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 72  inning of its pr
33ba0 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  ogram..**.** ^If
33bb0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
33bc0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
33bd0 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74  3_step(S)] for t
33be0 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
33bf0 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74  statement] S ret
33c00 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f  urned [SQLITE_RO
33c10 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f  W] or [SQLITE_DO
33c20 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b 73  NE],.** or if [s
33c30 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
33c40 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65  has never before
33c50 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20   been called on 
33c60 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69  S,.** then [sqli
33c70 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65  te3_reset(S)] re
33c80 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
33c90 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  ]..**.** ^If the
33ca0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
33cb0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
33cc0 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a  ep(S)] for the.*
33cd0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
33ce0 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63 61 74  ement] S indicat
33cf0 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65  ed an error, the
33d00 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  n.** [sqlite3_re
33d10 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20  set(S)] returns 
33d20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b  an appropriate [
33d30 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a  error code]..**.
33d40 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
33d50 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72  _reset(S)] inter
33d60 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68  face does not ch
33d70 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a  ange the values.
33d80 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74  ** of any [sqlit
33d90 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e  e3_bind_blob|bin
33da0 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70  dings] on the [p
33db0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
33dc0 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  t] S..*/.int sql
33dd0 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74  ite3_reset(sqlit
33de0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
33df0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
33e00 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65 64 65  : Create Or Rede
33e10 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f  fine SQL Functio
33e20 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ns.** KEYWORDS: 
33e30 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69  {function creati
33e40 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20  on routines}.** 
33e50 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69  KEYWORDS: {appli
33e60 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
33e70 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20  QL function}.** 
33e80 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69  KEYWORDS: {appli
33e90 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
33ea0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a  QL functions}.**
33eb0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
33ec0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75  .**.** ^These fu
33ed0 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74  nctions (collect
33ee0 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22  ively known as "
33ef0 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f  function creatio
33f00 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20  n routines").** 
33f10 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20  are used to add 
33f20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  SQL functions or
33f30 20 61 67 67 72 65 67 61 74 65 73 20 6f 72 20 74   aggregates or t
33f40 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65 20 62  o redefine the b
33f50 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78  ehavior.** of ex
33f60 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74  isting SQL funct
33f70 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74  ions or aggregat
33f80 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69  es.  The only di
33f90 66 66 65 72 65 6e 63 65 73 20 62 65 74 77 65 65  fferences betwee
33fa0 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69  n.** these routi
33fb0 6e 65 73 20 61 72 65 20 74 68 65 20 74 65 78 74  nes are the text
33fc0 20 65 6e 63 6f 64 69 6e 67 20 65 78 70 65 63 74   encoding expect
33fd0 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73 65  ed for.** the se
33fe0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28  cond parameter (
33ff0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
34000 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 63  function being c
34010 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74  reated).** and t
34020 68 65 20 70 72 65 73 65 6e 63 65 20 6f 72 20 61  he presence or a
34030 62 73 65 6e 63 65 20 6f 66 20 61 20 64 65 73 74  bsence of a dest
34040 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20  ructor callback 
34050 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69  for.** the appli
34060 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e  cation data poin
34070 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
34080 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
34090 69 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  is the [database
340a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20   connection] to 
340b0 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a  which the SQL.**
340c0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20   function is to 
340d0 62 65 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61  be added.  ^If a
340e0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73  n application us
340f0 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65  es more than one
34100 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
34110 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70  nection then app
34120 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
34130 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d   SQL functions m
34140 75 73 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20  ust be added.** 
34150 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65  to each database
34160 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61   connection sepa
34170 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54  rately..**.** ^T
34180 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
34190 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20  ter is the name 
341a0 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  of the SQL funct
341b0 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65  ion to be create
341c0 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65  d or.** redefine
341d0 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20  d.  ^The length 
341e0 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c  of the name is l
341f0 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 79  imited to 255 by
34200 74 65 73 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a  tes in a UTF-8.*
34210 2a 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  * representation
34220 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74  , exclusive of t
34230 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  he zero-terminat
34240 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20  or.  ^Note that 
34250 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67  the name.** leng
34260 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 55  th limit is in U
34270 54 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74 20  TF-8 bytes, not 
34280 63 68 61 72 61 63 74 65 72 73 20 6e 6f 72 20 55  characters nor U
34290 54 46 2d 31 36 20 62 79 74 65 73 2e 20 20 0a 2a  TF-16 bytes.  .*
342a0 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70 74 20 74  * ^Any attempt t
342b0 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e 63 74  o create a funct
342c0 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65  ion with a longe
342d0 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72  r name.** will r
342e0 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45  esult in [SQLITE
342f0 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e 67 20 72  _MISUSE] being r
34300 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
34310 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
34320 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73  ter (nArg).** is
34330 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61   the number of a
34340 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68  rguments that th
34350 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
34360 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74  r.** aggregate t
34370 61 6b 65 73 2e 20 5e 49 66 20 74 68 69 73 20 70  akes. ^If this p
34380 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20  arameter is -1, 
34390 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e  then the SQL fun
343a0 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
343b0 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61  egate may take a
343c0 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  ny number of arg
343d0 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30  uments between 0
343e0 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a   and the limit.*
343f0 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65  * set by [sqlite
34400 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45  3_limit]([SQLITE
34410 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
34420 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74  ARG]).  If the t
34430 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65  hird.** paramete
34440 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d  r is less than -
34450 31 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61  1 or greater tha
34460 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65 20 62  n 127 then the b
34470 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e  ehavior is.** un
34480 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
34490 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
344a0 65 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20  eter, eTextRep, 
344b0 73 70 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a  specifies what.*
344c0 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c  * [SQLITE_UTF8 |
344d0 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20   text encoding] 
344e0 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f  this SQL functio
344f0 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a  n prefers for.**
34500 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e   its parameters.
34510 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f    The applicatio
34520 6e 20 73 68 6f 75 6c 64 20 73 65 74 20 74 68 69  n should set thi
34530 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  s parameter to.*
34540 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  * [SQLITE_UTF16L
34550 45 5d 20 69 66 20 74 68 65 20 66 75 6e 63 74 69  E] if the functi
34560 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
34570 6e 20 69 6e 76 6f 6b 65 73 20 0a 2a 2a 20 5b 73  n invokes .** [s
34580 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
34590 74 31 36 6c 65 28 29 5d 20 6f 6e 20 61 6e 20 69  t16le()] on an i
345a0 6e 70 75 74 2c 20 6f 72 20 5b 53 51 4c 49 54 45  nput, or [SQLITE
345b0 5f 55 54 46 31 36 42 45 5d 20 69 66 20 74 68 65  _UTF16BE] if the
345c0 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
345d0 6f 6e 20 69 6e 76 6f 6b 65 73 20 5b 73 71 6c 69  on invokes [sqli
345e0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
345f0 62 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70 75  be()] on an inpu
34600 74 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  t, or.** [SQLITE
34610 5f 55 54 46 31 36 5d 20 69 66 20 5b 73 71 6c 69  _UTF16] if [sqli
34620 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
34630 28 29 5d 20 69 73 20 75 73 65 64 2c 20 6f 72 20  ()] is used, or 
34640 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 0a 2a 2a  [SQLITE_UTF8].**
34650 20 6f 74 68 65 72 77 69 73 65 2e 20 20 5e 54 68   otherwise.  ^Th
34660 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74  e same SQL funct
34670 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73  ion may be regis
34680 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 20 74  tered multiple t
34690 69 6d 65 73 20 75 73 69 6e 67 0a 2a 2a 20 64 69  imes using.** di
346a0 66 66 65 72 65 6e 74 20 70 72 65 66 65 72 72 65  fferent preferre
346b0 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73  d text encodings
346c0 2c 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74  , with different
346d0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
346e0 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 65 6e 63   for.** each enc
346f0 6f 64 69 6e 67 2e 0a 2a 2a 20 5e 57 68 65 6e 20  oding..** ^When 
34700 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65  multiple impleme
34710 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ntations of the 
34720 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72  same function ar
34730 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c  e available, SQL
34740 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b  ite.** will pick
34750 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e   the one that in
34760 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74  volves the least
34770 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20   amount of data 
34780 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a  conversion..**.*
34790 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61  * ^The fourth pa
347a0 72 61 6d 65 74 65 72 20 6d 61 79 20 6f 70 74 69  rameter may opti
347b0 6f 6e 61 6c 6c 79 20 62 65 20 4f 52 65 64 20 77  onally be ORed w
347c0 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 54 45  ith [SQLITE_DETE
347d0 52 4d 49 4e 49 53 54 49 43 5d 0a 2a 2a 20 74 6f  RMINISTIC].** to
347e0 20 73 69 67 6e 61 6c 20 74 68 61 74 20 74 68 65   signal that the
347f0 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 61   function will a
34800 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74 68 65  lways return the
34810 20 73 61 6d 65 20 72 65 73 75 6c 74 20 67 69 76   same result giv
34820 65 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 69  en.** the same i
34830 6e 70 75 74 73 20 77 69 74 68 69 6e 20 61 20 73  nputs within a s
34840 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d  ingle SQL statem
34850 65 6e 74 2e 20 20 4d 6f 73 74 20 53 51 4c 20 66  ent.  Most SQL f
34860 75 6e 63 74 69 6f 6e 73 20 61 72 65 0a 2a 2a 20  unctions are.** 
34870 64 65 74 65 72 6d 69 6e 69 73 74 69 63 2e 20 20  deterministic.  
34880 54 68 65 20 62 75 69 6c 74 2d 69 6e 20 5b 72 61  The built-in [ra
34890 6e 64 6f 6d 28 29 5d 20 53 51 4c 20 66 75 6e 63  ndom()] SQL func
348a0 74 69 6f 6e 20 69 73 20 61 6e 20 65 78 61 6d 70  tion is an examp
348b0 6c 65 20 6f 66 20 61 0a 2a 2a 20 66 75 6e 63 74  le of a.** funct
348c0 69 6f 6e 20 74 68 61 74 20 69 73 20 6e 6f 74 20  ion that is not 
348d0 64 65 74 65 72 6d 69 6e 69 73 74 69 63 2e 20 20  deterministic.  
348e0 54 68 65 20 53 51 4c 69 74 65 20 71 75 65 72 79  The SQLite query
348f0 20 70 6c 61 6e 6e 65 72 20 69 73 20 61 62 6c 65   planner is able
34900 20 74 6f 0a 2a 2a 20 70 65 72 66 6f 72 6d 20 61   to.** perform a
34910 64 64 69 74 69 6f 6e 61 6c 20 6f 70 74 69 6d 69  dditional optimi
34920 7a 61 74 69 6f 6e 73 20 6f 6e 20 64 65 74 65 72  zations on deter
34930 6d 69 6e 69 73 74 69 63 20 66 75 6e 63 74 69 6f  ministic functio
34940 6e 73 2c 20 73 6f 20 75 73 65 0a 2a 2a 20 6f 66  ns, so use.** of
34950 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 44 45 54   the [SQLITE_DET
34960 45 52 4d 49 4e 49 53 54 49 43 5d 20 66 6c 61 67  ERMINISTIC] flag
34970 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
34980 77 68 65 72 65 20 70 6f 73 73 69 62 6c 65 2e 0a  where possible..
34990 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66 74  **.** ^(The fift
349a0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  h parameter is a
349b0 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e  n arbitrary poin
349c0 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d  ter.  The implem
349d0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a  entation of the.
349e0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20  ** function can 
349f0 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74  gain access to t
34a00 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e  his pointer usin
34a10 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  g [sqlite3_user_
34a20 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a  data()].)^.**.**
34a30 20 5e 54 68 65 20 73 69 78 74 68 2c 20 73 65 76   ^The sixth, sev
34a40 65 6e 74 68 20 61 6e 64 20 65 69 67 68 74 68 20  enth and eighth 
34a50 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e  parameters, xFun
34a60 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46 69  c, xStep and xFi
34a70 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e  nal, are.** poin
34a80 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61  ters to C-langua
34a90 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61  ge functions tha
34aa0 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20  t implement the 
34ab0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
34ac0 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20 5e 41  ** aggregate. ^A
34ad0 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63   scalar SQL func
34ae0 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e  tion requires an
34af0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
34b00 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20  of the xFunc.** 
34b10 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e  callback only; N
34b20 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75 73  ULL pointers mus
34b30 74 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  t be passed as t
34b40 68 65 20 78 53 74 65 70 20 61 6e 64 20 78 46 69  he xStep and xFi
34b50 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  nal.** parameter
34b60 73 2e 20 5e 41 6e 20 61 67 67 72 65 67 61 74 65  s. ^An aggregate
34b70 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65   SQL function re
34b80 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d  quires an implem
34b90 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65  entation of xSte
34ba0 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20  p.** and xFinal 
34bb0 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  and NULL pointer
34bc0 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20   must be passed 
34bd0 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64  for xFunc. ^To d
34be0 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e  elete an existin
34bf0 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f  g.** SQL functio
34c00 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20  n or aggregate, 
34c10 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  pass NULL pointe
34c20 72 73 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65  rs for all three
34c30 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c   function.** cal
34c40 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  lbacks..**.** ^(
34c50 49 66 20 74 68 65 20 6e 69 6e 74 68 20 70 61 72  If the ninth par
34c60 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
34c70 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
34c80 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 4e 55  n_v2() is not NU
34c90 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69  LL,.** then it i
34ca0 73 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72  s destructor for
34cb0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
34cc0 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a   data pointer. .
34cd0 2a 2a 20 54 68 65 20 64 65 73 74 72 75 63 74 6f  ** The destructo
34ce0 72 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65  r is invoked whe
34cf0 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  n the function i
34d00 73 20 64 65 6c 65 74 65 64 2c 20 65 69 74 68 65  s deleted, eithe
34d10 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76  r by being.** ov
34d20 65 72 6c 6f 61 64 65 64 20 6f 72 20 77 68 65 6e  erloaded or when
34d30 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
34d40 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e  nnection closes.
34d50 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74 72  )^.** ^The destr
34d60 75 63 74 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e  uctor is also in
34d70 76 6f 6b 65 64 20 69 66 20 74 68 65 20 63 61 6c  voked if the cal
34d80 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  l to.** sqlite3_
34d90 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f  create_function_
34da0 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e  v2() fails..** ^
34db0 57 68 65 6e 20 74 68 65 20 64 65 73 74 72 75 63  When the destruc
34dc0 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20  tor callback of 
34dd0 74 68 65 20 74 65 6e 74 68 20 70 61 72 61 6d 65  the tenth parame
34de0 74 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20  ter is invoked, 
34df0 69 74 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20  it.** is passed 
34e00 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
34e10 74 20 77 68 69 63 68 20 69 73 20 61 20 63 6f 70  t which is a cop
34e20 79 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  y of the applica
34e30 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f  tion data .** po
34e40 69 6e 74 65 72 20 77 68 69 63 68 20 77 61 73 20  inter which was 
34e50 74 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65  the fifth parame
34e60 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ter to sqlite3_c
34e70 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76  reate_function_v
34e80 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69  2()..**.** ^It i
34e90 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72  s permitted to r
34ea0 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65  egister multiple
34eb0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
34ec0 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20   of the same.** 
34ed0 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74  functions with t
34ee0 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74  he same name but
34ef0 20 77 69 74 68 20 65 69 74 68 65 72 20 64 69 66   with either dif
34f00 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f  fering numbers o
34f10 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f  f.** arguments o
34f20 72 20 64 69 66 66 65 72 69 6e 67 20 70 72 65 66  r differing pref
34f30 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
34f40 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65 20 77  ings.  ^SQLite w
34f50 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69  ill use.** the i
34f60 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68  mplementation th
34f70 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20  at most closely 
34f80 6d 61 74 63 68 65 73 20 74 68 65 20 77 61 79 20  matches the way 
34f90 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20  in which the.** 
34fa0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
34fb0 75 73 65 64 2e 20 20 5e 41 20 66 75 6e 63 74 69  used.  ^A functi
34fc0 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
34fd0 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67  n with a non-neg
34fe0 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61  ative.** nArg pa
34ff0 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 65 74  rameter is a bet
35000 74 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61  ter match than a
35010 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
35020 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a  entation with.**
35030 20 61 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67   a negative nArg
35040 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77  .  ^A function w
35050 68 65 72 65 20 74 68 65 20 70 72 65 66 65 72 72  here the preferr
35060 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ed text encoding
35070 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20  .** matches the 
35080 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e  database encodin
35090 67 20 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a  g is a better.**
350a0 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75   match than a fu
350b0 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
350c0 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66   encoding is dif
350d0 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20  ferent.  .** ^A 
350e0 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
350f0 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66  he encoding diff
35100 65 72 65 6e 63 65 20 69 73 20 62 65 74 77 65 65  erence is betwee
35110 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54  n UTF16le and UT
35120 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c  F16be.** is a cl
35130 6f 73 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20  oser match than 
35140 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  a function where
35150 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69   the encoding di
35160 66 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62  fference is.** b
35170 65 74 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20  etween UTF8 and 
35180 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75  UTF16..**.** ^Bu
35190 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73  ilt-in functions
351a0 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64   may be overload
351b0 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63  ed by new applic
351c0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
351d0 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  nctions..**.** ^
351e0 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  An application-d
351f0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
35200 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20  is permitted to 
35210 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51  call other.** SQ
35220 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e  Lite interfaces.
35230 20 20 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20    However, such 
35240 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a  calls must not.*
35250 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61  * close the data
35260 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
35270 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20  nor finalize or 
35280 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72  reset the prepar
35290 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  ed.** statement 
352a0 69 6e 20 77 68 69 63 68 20 74 68 65 20 66 75 6e  in which the fun
352b0 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
352c0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
352d0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
352e0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
352f0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
35300 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20  FunctionName,.  
35310 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20  int nArg,.  int 
35320 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64  eTextRep,.  void
35330 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28   *pApp,.  void (
35340 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xFunc)(sqlite3_
35350 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
35360 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
35370 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73   void (*xStep)(s
35380 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
35390 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
353a0 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
353b0 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63  Final)(sqlite3_c
353c0 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20  ontext*).);.int 
353d0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
353e0 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c  unction16(.  sql
353f0 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73  ite3 *db,.  cons
35400 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f  t void *zFunctio
35410 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72  nName,.  int nAr
35420 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  g,.  int eTextRe
35430 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c  p,.  void *pApp,
35440 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29  .  void (*xFunc)
35450 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
35460 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
35470 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
35480 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f  *xStep)(sqlite3_
35490 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
354a0 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
354b0 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28   void (*xFinal)(
354c0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
354d0 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ).);.int sqlite3
354e0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
354f0 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
35500 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  db,.  const char
35510 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c   *zFunctionName,
35520 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69  .  int nArg,.  i
35530 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76  nt eTextRep,.  v
35540 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69  oid *pApp,.  voi
35550 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74  d (*xFunc)(sqlit
35560 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
35570 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
35580 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70  ,.  void (*xStep
35590 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
355a0 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
355b0 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
355c0 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65  (*xFinal)(sqlite
355d0 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76  3_context*),.  v
355e0 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76  oid(*xDestroy)(v
355f0 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  oid*).);../*.** 
35600 43 41 50 49 33 52 45 46 3a 20 54 65 78 74 20 45  CAPI3REF: Text E
35610 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54  ncodings.**.** T
35620 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65  hese constant de
35630 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64  fine integer cod
35640 65 73 20 74 68 61 74 20 72 65 70 72 65 73 65 6e  es that represen
35650 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a  t the various.**
35660 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20   text encodings 
35670 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c  supported by SQL
35680 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ite..*/.#define 
35690 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20  SQLITE_UTF8     
356a0 20 20 20 20 20 20 31 20 20 20 20 2f 2a 20 49 4d        1    /* IM
356b0 50 3a 20 52 2d 33 37 35 31 34 2d 33 35 35 36 36  P: R-37514-35566
356c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
356d0 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20  TE_UTF16LE      
356e0 20 20 32 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52    2    /* IMP: R
356f0 2d 30 33 33 37 31 2d 33 37 36 33 37 20 2a 2f 0a  -03371-37637 */.
35700 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
35710 54 46 31 36 42 45 20 20 20 20 20 20 20 20 33 20  TF16BE        3 
35720 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 35 31 39     /* IMP: R-519
35730 37 31 2d 33 34 31 35 34 20 2a 2f 0a 23 64 65 66  71-34154 */.#def
35740 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
35750 20 20 20 20 20 20 20 20 20 20 34 20 20 20 20 2f            4    /
35760 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62 79 74  * Use native byt
35770 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69  e order */.#defi
35780 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20  ne SQLITE_ANY   
35790 20 20 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a           5    /*
357a0 20 44 65 70 72 65 63 61 74 65 64 20 2a 2f 0a 23   Deprecated */.#
357b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
357c0 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20  F16_ALIGNED  8  
357d0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65    /* sqlite3_cre
357e0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e  ate_collation on
357f0 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ly */../*.** CAP
35800 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20  I3REF: Function 
35810 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  Flags.**.** Thes
35820 65 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61 79 20  e constants may 
35830 62 65 20 4f 52 65 64 20 74 6f 67 65 74 68 65 72  be ORed together
35840 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53   with the .** [S
35850 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 70 72 65  QLITE_UTF8 | pre
35860 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f  ferred text enco
35870 64 69 6e 67 5d 20 61 73 20 74 68 65 20 66 6f 75  ding] as the fou
35880 72 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  rth argument.** 
35890 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  to [sqlite3_crea
358a0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20  te_function()], 
358b0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
358c0 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 2c 20 6f  function16()], o
358d0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72  r.** [sqlite3_cr
358e0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
358f0 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ()]..*/.#define 
35900 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49  SQLITE_DETERMINI
35910 53 54 49 43 20 20 20 20 30 78 38 30 30 0a 0a 2f  STIC    0x800../
35920 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
35930 65 70 72 65 63 61 74 65 64 20 46 75 6e 63 74 69  eprecated Functi
35940 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41 54 45  ons.** DEPRECATE
35950 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75  D.**.** These fu
35960 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b 64 65 70  nctions are [dep
35970 72 65 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72  recated].  In or
35980 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a  der to maintain.
35990 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  ** backwards com
359a0 70 61 74 69 62 69 6c 69 74 79 20 77 69 74 68 20  patibility with 
359b0 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74 68 65 73  older code, thes
359c0 65 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74  e functions cont
359d0 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73  inue .** to be s
359e0 75 70 70 6f 72 74 65 64 2e 20 20 48 6f 77 65 76  upported.  Howev
359f0 65 72 2c 20 6e 65 77 20 61 70 70 6c 69 63 61 74  er, new applicat
35a00 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f 69  ions should avoi
35a10 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20  d.** the use of 
35a20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e  these functions.
35a30 20 20 54 6f 20 65 6e 63 6f 75 72 61 67 65 20 70    To encourage p
35a40 72 6f 67 72 61 6d 6d 65 72 73 20 74 6f 20 61 76  rogrammers to av
35a50 6f 69 64 0a 2a 2a 20 74 68 65 73 65 20 66 75 6e  oid.** these fun
35a60 63 74 69 6f 6e 73 2c 20 77 65 20 77 69 6c 6c 20  ctions, we will 
35a70 6e 6f 74 20 65 78 70 6c 61 69 6e 20 77 68 61 74  not explain what
35a80 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66   they do..*/.#if
35a90 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  ndef SQLITE_OMIT
35aa0 5f 44 45 50 52 45 43 41 54 45 44 0a 53 51 4c 49  _DEPRECATED.SQLI
35ab0 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
35ac0 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  t sqlite3_aggreg
35ad0 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ate_count(sqlite
35ae0 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c  3_context*);.SQL
35af0 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
35b00 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 70 69 72  nt sqlite3_expir
35b10 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ed(sqlite3_stmt*
35b20 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  );.SQLITE_DEPREC
35b30 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
35b40 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e  _transfer_bindin
35b50 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  gs(sqlite3_stmt*
35b60 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  , sqlite3_stmt*)
35b70 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
35b80 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
35b90 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 76  global_recover(v
35ba0 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  oid);.SQLITE_DEP
35bb0 52 45 43 41 54 45 44 20 76 6f 69 64 20 73 71 6c  RECATED void sql
35bc0 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 61  ite3_thread_clea
35bd0 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54  nup(void);.SQLIT
35be0 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
35bf0 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
35c00 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f  alarm(void(*)(vo
35c10 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36  id*,sqlite3_int6
35c20 34 2c 69 6e 74 29 2c 0a 20 20 20 20 20 20 20 20  4,int),.        
35c30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f                vo
35c40 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36  id*,sqlite3_int6
35c50 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  4);.#endif../*.*
35c60 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61  * CAPI3REF: Obta
35c70 69 6e 69 6e 67 20 53 51 4c 20 56 61 6c 75 65 73  ining SQL Values
35c80 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
35c90 74 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20  te3_value.**.** 
35ca0 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69  The C-language i
35cb0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
35cc0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61   SQL functions a
35cd0 6e 64 20 61 67 67 72 65 67 61 74 65 73 20 75 73  nd aggregates us
35ce0 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f  es.** this set o
35cf0 66 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74  f interface rout
35d00 69 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20 74  ines to access t
35d10 68 65 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c  he parameter val
35d20 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75  ues on.** the fu
35d30 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67  nction or aggreg
35d40 61 74 65 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65  ate.  .**.** The
35d50 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61 6c   xFunc (for scal
35d60 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72  ar functions) or
35d70 20 78 53 74 65 70 20 28 66 6f 72 20 61 67 67 72   xStep (for aggr
35d80 65 67 61 74 65 73 29 20 70 61 72 61 6d 65 74 65  egates) paramete
35d90 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65  rs.** to [sqlite
35da0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
35db0 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
35dc0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
35dd0 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65  n16()].** define
35de0 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20   callbacks that 
35df0 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51  implement the SQ
35e00 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20  L functions and 
35e10 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54  aggregates..** T
35e20 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
35e30 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 61   to these callba
35e40 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79 20  cks is an array 
35e50 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a  of pointers to.*
35e60 2a 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  * [protected sql
35e70 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
35e80 63 74 73 2e 20 20 54 68 65 72 65 20 69 73 20 6f  cts.  There is o
35e90 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ne [sqlite3_valu
35ea0 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a  e] object for.**
35eb0 20 65 61 63 68 20 70 61 72 61 6d 65 74 65 72 20   each parameter 
35ec0 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  to the SQL funct
35ed0 69 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 74  ion.  These rout
35ee0 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 74 6f  ines are used to
35ef0 0a 2a 2a 20 65 78 74 72 61 63 74 20 76 61 6c 75  .** extract valu
35f00 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c  es from the [sql
35f10 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
35f20 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  cts..**.** These
35f30 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f   routines work o
35f40 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f 74 65 63  nly with [protec
35f50 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
35f60 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41  e] objects..** A
35f70 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73  ny attempt to us
35f80 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  e these routines
35f90 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63   on an [unprotec
35fa0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
35fb0 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73  e].** object res
35fc0 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65  ults in undefine
35fd0 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a  d behavior..**.*
35fe0 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
35ff0 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65  s work just like
36000 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
36010 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73  ng [column acces
36020 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20  s functions].** 
36030 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65 73  except that thes
36040 65 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20  e routines take 
36050 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63  a single [protec
36060 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
36070 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69  e] object.** poi
36080 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20  nter instead of 
36090 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  a [sqlite3_stmt*
360a0 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e  ] pointer and an
360b0 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20   integer column 
360c0 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  number..**.** ^T
360d0 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
360e0 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65 72 66  _text16() interf
360f0 61 63 65 20 65 78 74 72 61 63 74 73 20 61 20 55  ace extracts a U
36100 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20  TF-16 string.** 
36110 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
36120 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20  te-order of the 
36130 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e  host machine.  ^
36140 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  The.** sqlite3_v
36150 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29 20  alue_text16be() 
36160 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  and sqlite3_valu
36170 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e 74  e_text16le() int
36180 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 61  erfaces.** extra
36190 63 74 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  ct UTF-16 string
361a0 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e 20  s as big-endian 
361b0 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61  and little-endia
361c0 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  n respectively..
361d0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69  **.** ^(The sqli
361e0 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69  te3_value_numeri
361f0 63 5f 74 79 70 65 28 29 20 69 6e 74 65 72 66 61  c_type() interfa
36200 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61  ce attempts to a
36210 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20  pply.** numeric 
36220 61 66 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20  affinity to the 
36230 76 61 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61  value.  This mea
36240 6e 73 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d  ns that an attem
36250 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f  pt is.** made to
36260 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c   convert the val
36270 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  ue to an integer
36280 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69   or floating poi
36290 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20  nt.  If.** such 
362a0 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20  a conversion is 
362b0 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74  possible without
362c0 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61   loss of informa
362d0 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a  tion (in other.*
362e0 2a 20 77 6f 72 64 73 2c 20 69 66 20 74 68 65 20  * words, if the 
362f0 76 61 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e  value is a strin
36300 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b  g that looks lik
36310 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74  e a number).** t
36320 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69  hen the conversi
36330 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e  on is performed.
36340 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63    Otherwise no c
36350 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73  onversion occurs
36360 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ..** The [SQLITE
36370 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74  _INTEGER | datat
36380 79 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65  ype] after conve
36390 72 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65  rsion is returne
363a0 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73  d.)^.**.** Pleas
363b0 65 20 70 61 79 20 70 61 72 74 69 63 75 6c 61 72  e pay particular
363c0 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68   attention to th
363d0 65 20 66 61 63 74 20 74 68 61 74 20 74 68 65 20  e fact that the 
363e0 70 6f 69 6e 74 65 72 20 72 65 74 75 72 6e 65 64  pointer returned
363f0 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
36400 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c  3_value_blob()],
36410 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
36420 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b  text()], or.** [
36430 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
36440 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69  xt16()] can be i
36450 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20 61 20  nvalidated by a 
36460 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20  subsequent call 
36470 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  to.** [sqlite3_v
36480 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b  alue_bytes()], [
36490 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
364a0 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74  tes16()], [sqlit
364b0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d  e3_value_text()]
364c0 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ,.** or [sqlite3
364d0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d  _value_text16()]
364e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
364f0 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63  utines must be c
36500 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
36510 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a  ame thread as.**
36520 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
36530 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65 64 20  n that supplied 
36540 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
36550 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 2e  ue*] parameters.
36560 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  .*/.const void *
36570 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
36580 6f 62 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ob(sqlite3_value
36590 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
365a0 76 61 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69  value_bytes(sqli
365b0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
365c0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62   sqlite3_value_b
365d0 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76  ytes16(sqlite3_v
365e0 61 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73  alue*);.double s
365f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75  qlite3_value_dou
36600 62 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ble(sqlite3_valu
36610 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
36620 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74  _value_int(sqlit
36630 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69  e3_value*);.sqli
36640 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
36650 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71  3_value_int64(sq
36660 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63  lite3_value*);.c
36670 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68  onst unsigned ch
36680 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  ar *sqlite3_valu
36690 65 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76  e_text(sqlite3_v
366a0 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f  alue*);.const vo
366b0 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
366c0 65 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  e_text16(sqlite3
366d0 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20  _value*);.const 
366e0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
366f0 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c  lue_text16le(sql
36700 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f  ite3_value*);.co
36710 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
36720 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65  3_value_text16be
36730 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
36740 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
36750 6c 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33  lue_type(sqlite3
36760 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
36770 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65  lite3_value_nume
36780 72 69 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33  ric_type(sqlite3
36790 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  _value*);../*.**
367a0 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 69   CAPI3REF: Findi
367b0 6e 67 20 54 68 65 20 53 75 62 74 79 70 65 20 4f  ng The Subtype O
367c0 66 20 53 51 4c 20 56 61 6c 75 65 73 0a 2a 2a 20  f SQL Values.** 
367d0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
367e0 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20  value.**.** The 
367f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 73 75  sqlite3_value_su
36800 62 74 79 70 65 28 56 29 20 66 75 6e 63 74 69 6f  btype(V) functio
36810 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 75  n returns the su
36820 62 74 79 70 65 20 66 6f 72 0a 2a 2a 20 61 6e 20  btype for.** an 
36830 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
36840 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
36850 6e 5d 20 61 72 67 75 6d 65 6e 74 20 56 2e 20 20  n] argument V.  
36860 54 68 65 20 73 75 62 74 79 70 65 0a 2a 2a 20 69  The subtype.** i
36870 6e 66 6f 72 6d 61 74 69 6f 6e 20 63 61 6e 20 62  nformation can b
36880 65 20 75 73 65 64 20 74 6f 20 70 61 73 73 20 61  e used to pass a
36890 20 6c 69 6d 69 74 65 64 20 61 6d 6f 75 6e 74 20   limited amount 
368a0 6f 66 20 63 6f 6e 74 65 78 74 20 66 72 6f 6d 0a  of context from.
368b0 2a 2a 20 6f 6e 65 20 53 51 4c 20 66 75 6e 63 74  ** one SQL funct
368c0 69 6f 6e 20 74 6f 20 61 6e 6f 74 68 65 72 2e 20  ion to another. 
368d0 20 55 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65   Use the [sqlite
368e0 33 5f 72 65 73 75 6c 74 5f 73 75 62 74 79 70 65  3_result_subtype
368f0 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74  ()].** routine t
36900 6f 20 73 65 74 20 74 68 65 20 73 75 62 74 79 70  o set the subtyp
36910 65 20 66 6f 72 20 74 68 65 20 72 65 74 75 72 6e  e for the return
36920 20 76 61 6c 75 65 20 6f 66 20 61 6e 20 53 51 4c   value of an SQL
36930 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
36940 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 6e 6f   SQLite makes no
36950 20 75 73 65 20 6f 66 20 73 75 62 74 79 70 65 20   use of subtype 
36960 69 74 73 65 6c 66 2e 20 20 49 74 20 6d 65 72 65  itself.  It mere
36970 6c 79 20 70 61 73 73 65 73 20 74 68 65 20 73 75  ly passes the su
36980 62 74 79 70 65 0a 2a 2a 20 66 72 6f 6d 20 74 68  btype.** from th
36990 65 20 72 65 73 75 6c 74 20 6f 66 20 6f 6e 65 20  e result of one 
369a0 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
369b0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
369c0 6e 5d 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69  n] into the.** i
369d0 6e 70 75 74 20 6f 66 20 61 6e 6f 74 68 65 72 2e  nput of another.
369e0 0a 2a 2f 0a 75 6e 73 69 67 6e 65 64 20 69 6e 74  .*/.unsigned int
369f0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 73   sqlite3_value_s
36a00 75 62 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76  ubtype(sqlite3_v
36a10 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  alue*);../*.** C
36a20 41 50 49 33 52 45 46 3a 20 43 6f 70 79 20 41 6e  API3REF: Copy An
36a30 64 20 46 72 65 65 20 53 51 4c 20 56 61 6c 75 65  d Free SQL Value
36a40 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
36a50 69 74 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a  ite3_value.**.**
36a60 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61   ^The sqlite3_va
36a70 6c 75 65 5f 64 75 70 28 56 29 20 69 6e 74 65 72  lue_dup(V) inter
36a80 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  face makes a cop
36a90 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  y of the [sqlite
36aa0 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65  3_value].** obje
36ab0 63 74 20 44 20 61 6e 64 20 72 65 74 75 72 6e 73  ct D and returns
36ac0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
36ad0 61 74 20 63 6f 70 79 2e 20 20 5e 54 68 65 20 5b  at copy.  ^The [
36ae0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 72  sqlite3_value] r
36af0 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 61 20  eturned.** is a 
36b00 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
36b10 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
36b20 20 65 76 65 6e 20 69 66 20 74 68 65 20 69 6e 70   even if the inp
36b30 75 74 20 69 73 20 6e 6f 74 2e 0a 2a 2a 20 5e 54  ut is not..** ^T
36b40 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
36b50 5f 64 75 70 28 56 29 20 69 6e 74 65 72 66 61 63  _dup(V) interfac
36b60 65 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69  e returns NULL i
36b70 66 20 56 20 69 73 20 4e 55 4c 4c 20 6f 72 20 69  f V is NULL or i
36b80 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  f a.** memory al
36b90 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2e 0a  location fails..
36ba0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
36bb0 65 33 5f 76 61 6c 75 65 5f 66 72 65 65 28 56 29  e3_value_free(V)
36bc0 20 69 6e 74 65 72 66 61 63 65 20 66 72 65 65 73   interface frees
36bd0 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   an [sqlite3_val
36be0 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 72  ue] object.** pr
36bf0 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65  eviously obtaine
36c00 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
36c10 76 61 6c 75 65 5f 64 75 70 28 29 5d 2e 20 20 5e  value_dup()].  ^
36c20 49 66 20 56 20 69 73 20 61 20 4e 55 4c 4c 20 70  If V is a NULL p
36c30 6f 69 6e 74 65 72 0a 2a 2a 20 74 68 65 6e 20 73  ointer.** then s
36c40 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 66 72 65  qlite3_value_fre
36c50 65 28 56 29 20 69 73 20 61 20 68 61 72 6d 6c 65  e(V) is a harmle
36c60 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 73 71 6c  ss no-op..*/.sql
36c70 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69  ite3_value *sqli
36c80 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 63 6f  te3_value_dup(co
36c90 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  nst sqlite3_valu
36ca0 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  e*);.void sqlite
36cb0 33 5f 76 61 6c 75 65 5f 66 72 65 65 28 73 71 6c  3_value_free(sql
36cc0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f  ite3_value*);../
36cd0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
36ce0 62 74 61 69 6e 20 41 67 67 72 65 67 61 74 65 20  btain Aggregate 
36cf0 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74  Function Context
36d00 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
36d10 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a  te3_context.**.*
36d20 2a 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * Implementation
36d30 73 20 6f 66 20 61 67 67 72 65 67 61 74 65 20 53  s of aggregate S
36d40 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65  QL functions use
36d50 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65   this.** routine
36d60 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d   to allocate mem
36d70 6f 72 79 20 66 6f 72 20 73 74 6f 72 69 6e 67 20  ory for storing 
36d80 74 68 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a  their state..**.
36d90 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74 69  ** ^The first ti
36da0 6d 65 20 74 68 65 20 73 71 6c 69 74 65 33 5f 61  me the sqlite3_a
36db0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
36dc0 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 69 73  (C,N) routine is
36dd0 20 63 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20   called .** for 
36de0 61 20 70 61 72 74 69 63 75 6c 61 72 20 61 67 67  a particular agg
36df0 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c  regate function,
36e00 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63   SQLite.** alloc
36e10 61 74 65 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79  ates N of memory
36e20 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 61  , zeroes out tha
36e30 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65  t memory, and re
36e40 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a  turns a pointer.
36e50 2a 2a 20 74 6f 20 74 68 65 20 6e 65 77 20 6d 65  ** to the new me
36e60 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64  mory. ^On second
36e70 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20   and subsequent 
36e80 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69  calls to.** sqli
36e90 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
36ea0 6e 74 65 78 74 28 29 20 66 6f 72 20 74 68 65 20  ntext() for the 
36eb0 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66  same aggregate f
36ec0 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65  unction instance
36ed0 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 75  ,.** the same bu
36ee0 66 66 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  ffer is returned
36ef0 2e 20 20 53 71 6c 69 74 65 33 5f 61 67 67 72 65  .  Sqlite3_aggre
36f00 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 69  gate_context() i
36f10 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61  s normally.** ca
36f20 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61  lled once for ea
36f30 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  ch invocation of
36f40 20 74 68 65 20 78 53 74 65 70 20 63 61 6c 6c 62   the xStep callb
36f50 61 63 6b 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65  ack and then one
36f60 0a 2a 2a 20 6c 61 73 74 20 74 69 6d 65 20 77 68  .** last time wh
36f70 65 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61  en the xFinal ca
36f80 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
36f90 64 2e 20 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f  d.  ^(When no ro
36fa0 77 73 20 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61  ws match.** an a
36fb0 67 67 72 65 67 61 74 65 20 71 75 65 72 79 2c 20  ggregate query, 
36fc0 74 68 65 20 78 53 74 65 70 28 29 20 63 61 6c 6c  the xStep() call
36fd0 62 61 63 6b 20 6f 66 20 74 68 65 20 61 67 67 72  back of the aggr
36fe0 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a  egate function.*
36ff0 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
37000 20 69 73 20 6e 65 76 65 72 20 63 61 6c 6c 65 64   is never called
37010 20 61 6e 64 20 78 46 69 6e 61 6c 28 29 20 69 73   and xFinal() is
37020 20 63 61 6c 6c 65 64 20 65 78 61 63 74 6c 79 20   called exactly 
37030 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73  once..** In thos
37040 65 20 63 61 73 65 73 2c 20 73 71 6c 69 74 65 33  e cases, sqlite3
37050 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
37060 78 74 28 29 20 6d 69 67 68 74 20 62 65 20 63 61  xt() might be ca
37070 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20  lled for the.** 
37080 66 69 72 73 74 20 74 69 6d 65 20 66 72 6f 6d 20  first time from 
37090 77 69 74 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e  within xFinal().
370a0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )^.**.** ^The sq
370b0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
370c0 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75  context(C,N) rou
370d0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 4e  tine returns a N
370e0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 0a 2a 2a 20  ULL pointer .** 
370f0 77 68 65 6e 20 66 69 72 73 74 20 63 61 6c 6c 65  when first calle
37100 64 20 69 66 20 4e 20 69 73 20 6c 65 73 73 20 74  d if N is less t
37110 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20  han or equal to 
37120 7a 65 72 6f 20 6f 72 20 69 66 20 61 20 6d 65 6d  zero or if a mem
37130 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20  ory.** allocate 
37140 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a  error occurs..**
37150 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74  .** ^(The amount
37160 20 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f 63 61   of space alloca
37170 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 61  ted by sqlite3_a
37180 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
37190 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65  (C,N) is.** dete
371a0 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20 4e 20  rmined by the N 
371b0 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 66 69 72  parameter on fir
371c0 73 74 20 73 75 63 63 65 73 73 66 75 6c 20 63 61  st successful ca
371d0 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20 74 68  ll.  Changing th
371e0 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20  e.** value of N 
371f0 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  in subsequent ca
37200 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67  ll to sqlite3_ag
37210 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
37220 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20  ) within.** the 
37230 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66  same aggregate f
37240 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65  unction instance
37250 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65   will not resize
37260 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61   the memory.** a
37270 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 20 20 57 69  llocation.)^  Wi
37280 74 68 69 6e 20 74 68 65 20 78 46 69 6e 61 6c 20  thin the xFinal 
37290 63 61 6c 6c 62 61 63 6b 2c 20 69 74 20 69 73 20  callback, it is 
372a0 63 75 73 74 6f 6d 61 72 79 20 74 6f 20 73 65 74  customary to set
372b0 0a 2a 2a 20 4e 3d 30 20 69 6e 20 63 61 6c 6c 73  .** N=0 in calls
372c0 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72   to sqlite3_aggr
372d0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
372e0 4e 29 20 73 6f 20 74 68 61 74 20 6e 6f 20 0a 2a  N) so that no .*
372f0 2a 20 70 6f 69 6e 74 6c 65 73 73 20 6d 65 6d 6f  * pointless memo
37300 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 6f  ry allocations o
37310 63 63 75 72 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  ccur..**.** ^SQL
37320 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ite automaticall
37330 79 20 66 72 65 65 73 20 74 68 65 20 6d 65 6d 6f  y frees the memo
37340 72 79 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  ry allocated by 
37350 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72  .** sqlite3_aggr
37360 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
37370 77 68 65 6e 20 74 68 65 20 61 67 67 72 65 67 61  when the aggrega
37380 74 65 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64  te query conclud
37390 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  es..**.** The fi
373a0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75  rst parameter mu
373b0 73 74 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20  st be a copy of 
373c0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
373d0 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75  context | SQL fu
373e0 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20  nction context] 
373f0 74 68 61 74 20 69 73 20 74 68 65 20 66 69 72 73  that is the firs
37400 74 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74  t parameter.** t
37410 6f 20 74 68 65 20 78 53 74 65 70 20 6f 72 20 78  o the xStep or x
37420 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72  Final callback r
37430 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c  outine that impl
37440 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67 72 65  ements the aggre
37450 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  gate.** function
37460 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ..**.** This rou
37470 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c  tine must be cal
37480 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
37490 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63  e thread in whic
374a0 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61  h.** the aggrega
374b0 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  te SQL function 
374c0 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76  is running..*/.v
374d0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67  oid *sqlite3_agg
374e0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73  regate_context(s
374f0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
37500 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f   int nBytes);../
37510 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55  *.** CAPI3REF: U
37520 73 65 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e  ser Data For Fun
37530 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44  ctions.** METHOD
37540 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  : sqlite3_contex
37550 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
37560 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29  ite3_user_data()
37570 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
37580 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  ns a copy of.** 
37590 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74  the pointer that
375a0 20 77 61 73 20 74 68 65 20 70 55 73 65 72 44 61   was the pUserDa
375b0 74 61 20 70 61 72 61 6d 65 74 65 72 20 28 74 68  ta parameter (th
375c0 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 29  e 5th parameter)
375d0 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
375e0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
375f0 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ion()].** and [s
37600 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
37610 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74  nction16()] rout
37620 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e  ines that origin
37630 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72  ally.** register
37640 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ed the applicati
37650 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on defined funct
37660 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ion..**.** This 
37670 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20  routine must be 
37680 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
37690 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
376a0 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c  hich.** the appl
376b0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
376c0 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
376d0 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ing..*/.void *sq
376e0 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
376f0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
37700 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
37710 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
37720 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63  nection For Func
37730 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  tions.** METHOD:
37740 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
37750 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
37760 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
37770 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63  andle() interfac
37780 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79  e returns a copy
37790 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74   of.** the point
377a0 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62  er to the [datab
377b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
377c0 28 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74  (the 1st paramet
377d0 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  er).** of the [s
377e0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
377f0 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64  nction()].** and
37800 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
37810 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72  _function16()] r
37820 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69  outines that ori
37830 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73  ginally.** regis
37840 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63  tered the applic
37850 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75  ation defined fu
37860 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c 69 74  nction..*/.sqlit
37870 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74  e3 *sqlite3_cont
37880 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71  ext_db_handle(sq
37890 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
378a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
378b0 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c  : Function Auxil
378c0 69 61 72 79 20 44 61 74 61 0a 2a 2a 20 4d 45 54  iary Data.** MET
378d0 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e  HOD: sqlite3_con
378e0 74 65 78 74 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  text.**.** These
378f0 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62   functions may b
37900 65 20 75 73 65 64 20 62 79 20 28 6e 6f 6e 2d 61  e used by (non-a
37910 67 67 72 65 67 61 74 65 29 20 53 51 4c 20 66 75  ggregate) SQL fu
37920 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73  nctions to.** as
37930 73 6f 63 69 61 74 65 20 6d 65 74 61 64 61 74 61  sociate metadata
37940 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76   with argument v
37950 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73 61  alues. If the sa
37960 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61 73 73  me value is pass
37970 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c  ed to.** multipl
37980 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66  e invocations of
37990 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75   the same SQL fu
379a0 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75  nction during qu
379b0 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75  ery execution, u
379c0 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72  nder.** some cir
379d0 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61  cumstances the a
379e0 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61  ssociated metada
379f0 74 61 20 6d 61 79 20 62 65 20 70 72 65 73 65 72  ta may be preser
37a00 76 65 64 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65  ved.  An example
37a10 0a 2a 2a 20 6f 66 20 77 68 65 72 65 20 74 68 69  .** of where thi
37a20 73 20 6d 69 67 68 74 20 62 65 20 75 73 65 66 75  s might be usefu
37a30 6c 20 69 73 20 69 6e 20 61 20 72 65 67 75 6c 61  l is in a regula
37a40 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74  r-expression mat
37a50 63 68 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f  ching.** functio
37a60 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20  n. The compiled 
37a70 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72  version of the r
37a80 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f  egular expressio
37a90 6e 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20  n can be stored 
37aa0 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20 61  as.** metadata a
37ab0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
37ac0 68 65 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e  he pattern strin
37ad0 67 2e 20 20 0a 2a 2a 20 54 68 65 6e 20 61 73 20  g.  .** Then as 
37ae0 6c 6f 6e 67 20 61 73 20 74 68 65 20 70 61 74 74  long as the patt
37af0 65 72 6e 20 73 74 72 69 6e 67 20 72 65 6d 61 69  ern string remai
37b00 6e 73 20 74 68 65 20 73 61 6d 65 2c 0a 2a 2a 20  ns the same,.** 
37b10 74 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67  the compiled reg
37b20 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20  ular expression 
37b30 63 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e  can be reused on
37b40 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76   multiple.** inv
37b50 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ocations of the 
37b60 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  same function..*
37b70 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
37b80 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_get_auxdata() 
37b90 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
37ba0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
37bb0 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61  he metadata.** a
37bc0 73 73 6f 63 69 61 74 65 64 20 62 79 20 74 68 65  ssociated by the
37bd0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
37be0 64 61 74 61 28 29 20 66 75 6e 63 74 69 6f 6e 20  data() function 
37bf0 77 69 74 68 20 74 68 65 20 4e 74 68 20 61 72 67  with the Nth arg
37c00 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74  ument.** value t
37c10 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
37c20 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
37c30 6f 6e 2e 20 5e 49 66 20 74 68 65 72 65 20 69 73  on. ^If there is
37c40 20 6e 6f 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20   no metadata.** 
37c50 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
37c60 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 67  the function arg
37c70 75 6d 65 6e 74 2c 20 74 68 69 73 20 73 71 6c 69  ument, this sqli
37c80 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
37c90 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72  ) interface.** r
37ca0 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
37cb0 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  inter..**.** ^Th
37cc0 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
37cd0 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 69  xdata(C,N,P,X) i
37ce0 6e 74 65 72 66 61 63 65 20 73 61 76 65 73 20 50  nterface saves P
37cf0 20 61 73 20 6d 65 74 61 64 61 74 61 20 66 6f 72   as metadata for
37d00 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67   the N-th.** arg
37d10 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 70 70  ument of the app
37d20 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
37d30 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 53 75 62   function.  ^Sub
37d40 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73  sequent.** calls
37d50 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 5f   to sqlite3_get_
37d60 61 75 78 64 61 74 61 28 43 2c 4e 29 20 72 65 74  auxdata(C,N) ret
37d70 75 72 6e 20 50 20 66 72 6f 6d 20 74 68 65 20 6d  urn P from the m
37d80 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 71  ost recent.** sq
37d90 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
37da0 61 28 43 2c 4e 2c 50 2c 58 29 20 63 61 6c 6c 20  a(C,N,P,X) call 
37db0 69 66 20 74 68 65 20 6d 65 74 61 64 61 74 61 20  if the metadata 
37dc0 69 73 20 73 74 69 6c 6c 20 76 61 6c 69 64 20 6f  is still valid o
37dd0 72 0a 2a 2a 20 4e 55 4c 4c 20 69 66 20 74 68 65  r.** NULL if the
37de0 20 6d 65 74 61 64 61 74 61 20 68 61 73 20 62 65   metadata has be
37df0 65 6e 20 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a  en discarded..**
37e00 20 5e 41 66 74 65 72 20 65 61 63 68 20 63 61 6c   ^After each cal
37e10 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74  l to sqlite3_set
37e20 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58  _auxdata(C,N,P,X
37e30 29 20 77 68 65 72 65 20 58 20 69 73 20 6e 6f 74  ) where X is not
37e40 20 4e 55 4c 4c 2c 0a 2a 2a 20 53 51 4c 69 74 65   NULL,.** SQLite
37e50 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65   will invoke the
37e60 20 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63   destructor func
37e70 74 69 6f 6e 20 58 20 77 69 74 68 20 70 61 72 61  tion X with para
37e80 6d 65 74 65 72 20 50 20 65 78 61 63 74 6c 79 0a  meter P exactly.
37e90 2a 2a 20 6f 6e 63 65 2c 20 77 68 65 6e 20 74 68  ** once, when th
37ea0 65 20 6d 65 74 61 64 61 74 61 20 69 73 20 64 69  e metadata is di
37eb0 73 63 61 72 64 65 64 2e 0a 2a 2a 20 53 51 4c 69  scarded..** SQLi
37ec0 74 65 20 69 73 20 66 72 65 65 20 74 6f 20 64 69  te is free to di
37ed0 73 63 61 72 64 20 74 68 65 20 6d 65 74 61 64 61  scard the metada
37ee0 74 61 20 61 74 20 61 6e 79 20 74 69 6d 65 2c 20  ta at any time, 
37ef0 69 6e 63 6c 75 64 69 6e 67 3a 20 3c 75 6c 3e 0a  including: <ul>.
37f00 2a 2a 20 3c 6c 69 3e 20 5e 28 77 68 65 6e 20 74  ** <li> ^(when t
37f10 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
37f20 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65   function parame
37f30 74 65 72 20 63 68 61 6e 67 65 73 29 5e 2c 20 6f  ter changes)^, o
37f40 72 0a 2a 2a 20 3c 6c 69 3e 20 5e 28 77 68 65 6e  r.** <li> ^(when
37f50 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
37f60 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
37f70 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61  inalize()] is ca
37f80 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20  lled for the.** 
37f90 20 20 20 20 20 53 51 4c 20 73 74 61 74 65 6d 65       SQL stateme
37fa0 6e 74 29 5e 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e  nt)^, or.** <li>
37fb0 20 5e 28 77 68 65 6e 20 73 71 6c 69 74 65 33 5f   ^(when sqlite3_
37fc0 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 73  set_auxdata() is
37fd0 20 69 6e 76 6f 6b 65 64 20 61 67 61 69 6e 20 6f   invoked again o
37fe0 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20  n the same.**   
37ff0 20 20 20 20 70 61 72 61 6d 65 74 65 72 29 5e 2c      parameter)^,
38000 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5e 28 64 75   or.** <li> ^(du
38010 72 69 6e 67 20 74 68 65 20 6f 72 69 67 69 6e 61  ring the origina
38020 6c 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  l sqlite3_set_au
38030 78 64 61 74 61 28 29 20 63 61 6c 6c 20 77 68 65  xdata() call whe
38040 6e 20 61 20 6d 65 6d 6f 72 79 20 0a 2a 2a 20 20  n a memory .**  
38050 20 20 20 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65      allocation e
38060 72 72 6f 72 20 6f 63 63 75 72 73 2e 29 5e 20 3c  rror occurs.)^ <
38070 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  /ul>.**.** Note 
38080 74 68 65 20 6c 61 73 74 20 62 75 6c 6c 65 74 20  the last bullet 
38090 69 6e 20 70 61 72 74 69 63 75 6c 61 72 2e 20 20  in particular.  
380a0 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 58  The destructor X
380b0 20 69 6e 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   in .** sqlite3_
380c0 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c  set_auxdata(C,N,
380d0 50 2c 58 29 20 6d 69 67 68 74 20 62 65 20 63 61  P,X) might be ca
380e0 6c 6c 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79  lled immediately
380f0 2c 20 62 65 66 6f 72 65 20 74 68 65 0a 2a 2a 20  , before the.** 
38100 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
38110 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20  ata() interface 
38120 65 76 65 6e 20 72 65 74 75 72 6e 73 2e 20 20 48  even returns.  H
38130 65 6e 63 65 20 73 71 6c 69 74 65 33 5f 73 65 74  ence sqlite3_set
38140 5f 61 75 78 64 61 74 61 28 29 0a 2a 2a 20 73 68  _auxdata().** sh
38150 6f 75 6c 64 20 62 65 20 63 61 6c 6c 65 64 20 6e  ould be called n
38160 65 61 72 20 74 68 65 20 65 6e 64 20 6f 66 20 74  ear the end of t
38170 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c  he function impl
38180 65 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 20 74  ementation and t
38190 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69  he.** function i
381a0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68  mplementation sh
381b0 6f 75 6c 64 20 6e 6f 74 20 6d 61 6b 65 20 61 6e  ould not make an
381c0 79 20 75 73 65 20 6f 66 20 50 20 61 66 74 65 72  y use of P after
381d0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  .** sqlite3_set_
381e0 61 75 78 64 61 74 61 28 29 20 68 61 73 20 62 65  auxdata() has be
381f0 65 6e 20 63 61 6c 6c 65 64 2e 0a 2a 2a 0a 2a 2a  en called..**.**
38200 20 5e 28 49 6e 20 70 72 61 63 74 69 63 65 2c 20   ^(In practice, 
38210 6d 65 74 61 64 61 74 61 20 69 73 20 70 72 65 73  metadata is pres
38220 65 72 76 65 64 20 62 65 74 77 65 65 6e 20 66 75  erved between fu
38230 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72  nction calls for
38240 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 72  .** function par
38250 61 6d 65 74 65 72 73 20 74 68 61 74 20 61 72 65  ameters that are
38260 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 63 6f   compile-time co
38270 6e 73 74 61 6e 74 73 2c 20 69 6e 63 6c 75 64 69  nstants, includi
38280 6e 67 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61  ng literal.** va
38290 6c 75 65 73 20 61 6e 64 20 5b 70 61 72 61 6d 65  lues and [parame
382a0 74 65 72 73 5d 20 61 6e 64 20 65 78 70 72 65 73  ters] and expres
382b0 73 69 6f 6e 73 20 63 6f 6d 70 6f 73 65 64 20 66  sions composed f
382c0 72 6f 6d 20 74 68 65 20 73 61 6d 65 2e 29 5e 0a  rom the same.)^.
382d0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
382e0 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c  ines must be cal
382f0 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
38300 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63  e thread in whic
38310 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e  h.** the SQL fun
38320 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
38330 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
38340 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73  e3_get_auxdata(s
38350 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
38360 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 20 73 71   int N);.void sq
38370 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
38380 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  a(sqlite3_contex
38390 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a  t*, int N, void*
383a0 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a  , void (*)(void*
383b0 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ));.../*.** CAPI
383c0 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20  3REF: Constants 
383d0 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61 6c  Defining Special
383e0 20 44 65 73 74 72 75 63 74 6f 72 20 42 65 68 61   Destructor Beha
383f0 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  vior.**.** These
38400 20 61 72 65 20 73 70 65 63 69 61 6c 20 76 61 6c   are special val
38410 75 65 73 20 66 6f 72 20 74 68 65 20 64 65 73 74  ues for the dest
38420 72 75 63 74 6f 72 20 74 68 61 74 20 69 73 20 70  ructor that is p
38430 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a  assed in as the.
38440 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e  ** final argumen
38450 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69  t to routines li
38460 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  ke [sqlite3_resu
38470 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e 49 66  lt_blob()].  ^If
38480 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a   the destructor.
38490 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 53  ** argument is S
384a0 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 69 74  QLITE_STATIC, it
384b0 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
384c0 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72 20  content pointer 
384d0 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61  is constant.** a
384e0 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20 63 68  nd will never ch
384f0 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73 20 6e  ange.  It does n
38500 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 64 65  ot need to be de
38510 73 74 72 6f 79 65 64 2e 20 20 5e 54 68 65 0a 2a  stroyed.  ^The.*
38520 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45  * SQLITE_TRANSIE
38530 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73 20 74  NT value means t
38540 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  hat the content 
38550 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e  will likely chan
38560 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61  ge in.** the nea
38570 72 20 66 75 74 75 72 65 20 61 6e 64 20 74 68 61  r future and tha
38580 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c 64 20  t SQLite should 
38590 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70 72 69  make its own pri
385a0 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  vate copy of.** 
385b0 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f  the content befo
385c0 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a  re returning..**
385d0 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65 66 20  .** The typedef 
385e0 69 73 20 6e 65 63 65 73 73 61 72 79 20 74 6f 20  is necessary to 
385f0 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62  work around prob
38600 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69 6e 0a  lems in certain.
38610 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73  ** C++ compilers
38620 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 69  ..*/.typedef voi
38630 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 74  d (*sqlite3_dest
38640 72 75 63 74 6f 72 5f 74 79 70 65 29 28 76 6f 69  ructor_type)(voi
38650 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c  d*);.#define SQL
38660 49 54 45 5f 53 54 41 54 49 43 20 20 20 20 20 20  ITE_STATIC      
38670 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75  ((sqlite3_destru
38680 63 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 65  ctor_type)0).#de
38690 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e  fine SQLITE_TRAN
386a0 53 49 45 4e 54 20 20 20 28 28 73 71 6c 69 74 65  SIENT   ((sqlite
386b0 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70  3_destructor_typ
386c0 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e)-1)../*.** CAP
386d0 49 33 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54  I3REF: Setting T
386e0 68 65 20 52 65 73 75 6c 74 20 4f 66 20 41 6e 20  he Result Of An 
386f0 53 51 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 20  SQL Function.** 
38700 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
38710 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 54 68  context.**.** Th
38720 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
38730 20 75 73 65 64 20 62 79 20 74 68 65 20 78 46 75   used by the xFu
38740 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c  nc or xFinal cal
38750 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69  lbacks that.** i
38760 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e  mplement SQL fun
38770 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65  ctions and aggre
38780 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b  gates.  See.** [
38790 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
387a0 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  unction()] and [
387b0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
387c0 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20  unction16()].** 
387d0 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
387e0 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
387f0 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
38800 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 68  s work very much
38810 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61 6d   like the [param
38820 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66 61  eter binding] fa
38830 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74  mily of.** funct
38840 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69 6e  ions used to bin