/ Hex Artifact Content
Login

Artifact 8d126e4cfbd1f4bc6f4043aacd77f78b45613e7d630185d49a5d099394247483:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 64 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a  ed to operate..*
04e0: 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66  *.** The name of
04f0: 20 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72   this file under
0500: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d   configuration m
0510: 61 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71  anagement is "sq
0520: 6c 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54  lite.h.in"..** T
0530: 68 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65  he makefile make
0540: 73 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61  s some minor cha
0550: 6e 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c  nges to this fil
0560: 65 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72  e (such as inser
0570: 74 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73  ting.** the vers
0580: 69 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20  ion number) and 
0590: 63 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65  changes its name
05a0: 20 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20   to "sqlite3.h" 
05b0: 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68  as.** part of th
05c0: 65 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e  e build process.
05d0: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  .*/.#ifndef SQLI
05e0: 54 45 33 5f 48 0a 23 64 65 66 69 6e 65 20 53 51  TE3_H.#define SQ
05f0: 4c 49 54 45 33 5f 48 0a 23 69 6e 63 6c 75 64 65  LITE3_H.#include
0600: 20 3c 73 74 64 61 72 67 2e 68 3e 20 20 20 20 20   <stdarg.h>     
0610: 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72 20 74 68  /* Needed for th
0620: 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 66 20  e definition of 
0630: 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a  va_list */../*.*
0640: 2a 20 4d 61 6b 65 20 73 75 72 65 20 77 65 20 63  * Make sure we c
0650: 61 6e 20 63 61 6c 6c 20 74 68 69 73 20 73 74 75  an call this stu
0660: 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a  ff from C++..*/.
0670: 23 69 66 64 65 66 20 5f 5f 63 70 6c 75 73 70 6c  #ifdef __cpluspl
0680: 75 73 0a 65 78 74 65 72 6e 20 22 43 22 20 7b 0a  us.extern "C" {.
0690: 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 50  #endif.../*.** P
06a0: 72 6f 76 69 64 65 20 74 68 65 20 61 62 69 6c 69  rovide the abili
06b0: 74 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 6c  ty to override l
06c0: 69 6e 6b 61 67 65 20 66 65 61 74 75 72 65 73 20  inkage features 
06d0: 6f 66 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  of the interface
06e0: 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c  ..*/.#ifndef SQL
06f0: 49 54 45 5f 45 58 54 45 52 4e 0a 23 20 64 65 66  ITE_EXTERN.# def
0700: 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 54 45 52  ine SQLITE_EXTER
0710: 4e 20 65 78 74 65 72 6e 0a 23 65 6e 64 69 66 0a  N extern.#endif.
0720: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 41  #ifndef SQLITE_A
0730: 50 49 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  PI.# define SQLI
0740: 54 45 5f 41 50 49 0a 23 65 6e 64 69 66 0a 23 69  TE_API.#endif.#i
0750: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 43 44 45  fndef SQLITE_CDE
0760: 43 4c 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  CL.# define SQLI
0770: 54 45 5f 43 44 45 43 4c 0a 23 65 6e 64 69 66 0a  TE_CDECL.#endif.
0780: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 41  #ifndef SQLITE_A
0790: 50 49 43 41 4c 4c 0a 23 20 64 65 66 69 6e 65 20  PICALL.# define 
07a0: 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a 23  SQLITE_APICALL.#
07b0: 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51  endif.#ifndef SQ
07c0: 4c 49 54 45 5f 53 54 44 43 41 4c 4c 0a 23 20 64  LITE_STDCALL.# d
07d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 44  efine SQLITE_STD
07e0: 43 41 4c 4c 20 53 51 4c 49 54 45 5f 41 50 49 43  CALL SQLITE_APIC
07f0: 41 4c 4c 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64  ALL.#endif.#ifnd
0800: 65 66 20 53 51 4c 49 54 45 5f 43 41 4c 4c 42 41  ef SQLITE_CALLBA
0810: 43 4b 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  CK.# define SQLI
0820: 54 45 5f 43 41 4c 4c 42 41 43 4b 0a 23 65 6e 64  TE_CALLBACK.#end
0830: 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  if.#ifndef SQLIT
0840: 45 5f 53 59 53 41 50 49 0a 23 20 64 65 66 69 6e  E_SYSAPI.# defin
0850: 65 20 53 51 4c 49 54 45 5f 53 59 53 41 50 49 0a  e SQLITE_SYSAPI.
0860: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68  #endif../*.** Th
0870: 65 73 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73  ese no-op macros
0880: 20 61 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f   are used in fro
0890: 6e 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73  nt of interfaces
08a0: 20 74 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a   to mark those.*
08b0: 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 73 20  * interfaces as 
08c0: 65 69 74 68 65 72 20 64 65 70 72 65 63 61 74 65  either deprecate
08d0: 64 20 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61  d or experimenta
08e0: 6c 2e 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74  l.  New applicat
08f0: 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e  ions.** should n
0900: 6f 74 20 75 73 65 20 64 65 70 72 65 63 61 74 65  ot use deprecate
0910: 64 20 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74  d interfaces - t
0920: 68 65 79 20 61 72 65 20 73 75 70 70 6f 72 74 65  hey are supporte
0930: 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a  d for backwards.
0940: 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ** compatibility
0950: 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69 63 61 74   only.  Applicat
0960: 69 6f 6e 20 77 72 69 74 65 72 73 20 73 68 6f 75  ion writers shou
0970: 6c 64 20 62 65 20 61 77 61 72 65 20 74 68 61 74  ld be aware that
0980: 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e 74 61 6c  .** experimental
0990: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
09a0: 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
09b0: 65 20 69 6e 20 70 6f 69 6e 74 20 72 65 6c 65 61  e in point relea
09c0: 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ses..**.** These
09d0: 20 6d 61 63 72 6f 73 20 75 73 65 64 20 74 6f 20   macros used to 
09e0: 72 65 73 6f 6c 76 65 20 74 6f 20 76 61 72 69 6f  resolve to vario
09f0: 75 73 20 6b 69 6e 64 73 20 6f 66 20 63 6f 6d 70  us kinds of comp
0a00: 69 6c 65 72 20 6d 61 67 69 63 20 74 68 61 74 0a  iler magic that.
0a10: 2a 2a 20 77 6f 75 6c 64 20 67 65 6e 65 72 61 74  ** would generat
0a20: 65 20 77 61 72 6e 69 6e 67 20 6d 65 73 73 61 67  e warning messag
0a30: 65 73 20 77 68 65 6e 20 74 68 65 79 20 77 65 72  es when they wer
0a40: 65 20 75 73 65 64 2e 20 20 42 75 74 20 74 68 61  e used.  But tha
0a50: 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72 20 6d 61  t.** compiler ma
0a60: 67 69 63 20 65 6e 64 65 64 20 75 70 20 67 65 6e  gic ended up gen
0a70: 65 72 61 74 69 6e 67 20 73 75 63 68 20 61 20 66  erating such a f
0a80: 6c 75 72 72 79 20 6f 66 20 62 75 67 20 72 65 70  lurry of bug rep
0a90: 6f 72 74 73 0a 2a 2a 20 74 68 61 74 20 77 65 20  orts.** that we 
0aa0: 68 61 76 65 20 74 61 6b 65 6e 20 69 74 20 61 6c  have taken it al
0ab0: 6c 20 6f 75 74 20 61 6e 64 20 67 6f 6e 65 20 62  l out and gone b
0ac0: 61 63 6b 20 74 6f 20 75 73 69 6e 67 20 73 69 6d  ack to using sim
0ad0: 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72  ple.** noop macr
0ae0: 6f 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  os..*/.#define S
0af0: 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
0b00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
0b10: 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a  EXPERIMENTAL../*
0b20: 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68 65 73 65  .** Ensure these
0b30: 20 73 79 6d 62 6f 6c 73 20 77 65 72 65 20 6e 6f   symbols were no
0b40: 74 20 64 65 66 69 6e 65 64 20 62 79 20 73 6f 6d  t defined by som
0b50: 65 20 70 72 65 76 69 6f 75 73 20 68 65 61 64 65  e previous heade
0b60: 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65  r file..*/.#ifde
0b70: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0b80: 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f  .# undef SQLITE_
0b90: 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69 66 0a 23  VERSION.#endif.#
0ba0: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52  ifdef SQLITE_VER
0bb0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 20 75 6e  SION_NUMBER.# un
0bc0: 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49  def SQLITE_VERSI
0bd0: 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e 64 69 66  ON_NUMBER.#endif
0be0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
0bf0: 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 4c  : Compile-Time L
0c00: 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e  ibrary Version N
0c10: 75 6d 62 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54  umbers.**.** ^(T
0c20: 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  he [SQLITE_VERSI
0c30: 4f 4e 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  ON] C preprocess
0c40: 6f 72 20 6d 61 63 72 6f 20 69 6e 20 74 68 65 20  or macro in the 
0c50: 73 71 6c 69 74 65 33 2e 68 20 68 65 61 64 65 72  sqlite3.h header
0c60: 0a 2a 2a 20 65 76 61 6c 75 61 74 65 73 20 74 6f  .** evaluates to
0c70: 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
0c80: 6c 20 74 68 61 74 20 69 73 20 74 68 65 20 53 51  l that is the SQ
0c90: 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 69 6e 20  Lite version in 
0ca0: 74 68 65 0a 2a 2a 20 66 6f 72 6d 61 74 20 22 58  the.** format "X
0cb0: 2e 59 2e 5a 22 20 77 68 65 72 65 20 58 20 69 73  .Y.Z" where X is
0cc0: 20 74 68 65 20 6d 61 6a 6f 72 20 76 65 72 73 69   the major versi
0cd0: 6f 6e 20 6e 75 6d 62 65 72 20 28 61 6c 77 61 79  on number (alway
0ce0: 73 20 33 20 66 6f 72 0a 2a 2a 20 53 51 4c 69 74  s 3 for.** SQLit
0cf0: 65 33 29 20 61 6e 64 20 59 20 69 73 20 74 68 65  e3) and Y is the
0d00: 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f 6e 20 6e   minor version n
0d10: 75 6d 62 65 72 20 61 6e 64 20 5a 20 69 73 20 74  umber and Z is t
0d20: 68 65 20 72 65 6c 65 61 73 65 20 6e 75 6d 62 65  he release numbe
0d30: 72 2e 29 5e 0a 2a 2a 20 5e 28 54 68 65 20 5b 53  r.)^.** ^(The [S
0d40: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
0d50: 4d 42 45 52 5d 20 43 20 70 72 65 70 72 6f 63 65  MBER] C preproce
0d60: 73 73 6f 72 20 6d 61 63 72 6f 20 72 65 73 6f 6c  ssor macro resol
0d70: 76 65 73 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ves to an intege
0d80: 72 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 76 61  r.** with the va
0d90: 6c 75 65 20 28 58 2a 31 30 30 30 30 30 30 20 2b  lue (X*1000000 +
0da0: 20 59 2a 31 30 30 30 20 2b 20 5a 29 20 77 68 65   Y*1000 + Z) whe
0db0: 72 65 20 58 2c 20 59 2c 20 61 6e 64 20 5a 20 61  re X, Y, and Z a
0dc0: 72 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 6e  re the same.** n
0dd0: 75 6d 62 65 72 73 20 75 73 65 64 20 69 6e 20 5b  umbers used in [
0de0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2e  SQLITE_VERSION].
0df0: 29 5e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  )^.** The SQLITE
0e00: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20  _VERSION_NUMBER 
0e10: 66 6f 72 20 61 6e 79 20 67 69 76 65 6e 20 72 65  for any given re
0e20: 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20  lease of SQLite 
0e30: 77 69 6c 6c 20 61 6c 73 6f 0a 2a 2a 20 62 65 20  will also.** be 
0e40: 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20  larger than the 
0e50: 72 65 6c 65 61 73 65 20 66 72 6f 6d 20 77 68 69  release from whi
0e60: 63 68 20 69 74 20 69 73 20 64 65 72 69 76 65 64  ch it is derived
0e70: 2e 20 20 45 69 74 68 65 72 20 59 20 77 69 6c 6c  .  Either Y will
0e80: 0a 2a 2a 20 62 65 20 68 65 6c 64 20 63 6f 6e 73  .** be held cons
0e90: 74 61 6e 74 20 61 6e 64 20 5a 20 77 69 6c 6c 20  tant and Z will 
0ea0: 62 65 20 69 6e 63 72 65 6d 65 6e 74 65 64 20 6f  be incremented o
0eb0: 72 20 65 6c 73 65 20 59 20 77 69 6c 6c 20 62 65  r else Y will be
0ec0: 20 69 6e 63 72 65 6d 65 6e 74 65 64 0a 2a 2a 20   incremented.** 
0ed0: 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 72 65  and Z will be re
0ee0: 73 65 74 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a  set to zero..**.
0ef0: 2a 2a 20 53 69 6e 63 65 20 5b 76 65 72 73 69 6f  ** Since [versio
0f00: 6e 20 33 2e 36 2e 31 38 5d 20 28 5b 64 61 74 65  n 3.6.18] ([date
0f10: 6f 66 3a 33 2e 36 2e 31 38 5d 29 2c 20 0a 2a 2a  of:3.6.18]), .**
0f20: 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 63   SQLite source c
0f30: 6f 64 65 20 68 61 73 20 62 65 65 6e 20 73 74 6f  ode has been sto
0f40: 72 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 3c 61  red in the.** <a
0f50: 20 68 72 65 66 3d 22 68 74 74 70 3a 2f 2f 77 77   href="http://ww
0f60: 77 2e 66 6f 73 73 69 6c 2d 73 63 6d 2e 6f 72 67  w.fossil-scm.org
0f70: 2f 22 3e 46 6f 73 73 69 6c 20 63 6f 6e 66 69 67  /">Fossil config
0f80: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65  uration manageme
0f90: 6e 74 0a 2a 2a 20 73 79 73 74 65 6d 3c 2f 61 3e  nt.** system</a>
0fa0: 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 53  .  ^The SQLITE_S
0fb0: 4f 55 52 43 45 5f 49 44 20 6d 61 63 72 6f 20 65  OURCE_ID macro e
0fc0: 76 61 6c 75 61 74 65 73 20 74 6f 0a 2a 2a 20 61  valuates to.** a
0fd0: 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 64   string which id
0fe0: 65 6e 74 69 66 69 65 73 20 61 20 70 61 72 74 69  entifies a parti
0ff0: 63 75 6c 61 72 20 63 68 65 63 6b 2d 69 6e 20 6f  cular check-in o
1000: 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 74 68  f SQLite.** with
1010: 69 6e 20 69 74 73 20 63 6f 6e 66 69 67 75 72 61  in its configura
1020: 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20  tion management 
1030: 73 79 73 74 65 6d 2e 20 20 5e 54 68 65 20 53 51  system.  ^The SQ
1040: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 0a 2a  LITE_SOURCE_ID.*
1050: 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e  * string contain
1060: 73 20 74 68 65 20 64 61 74 65 20 61 6e 64 20 74  s the date and t
1070: 69 6d 65 20 6f 66 20 74 68 65 20 63 68 65 63 6b  ime of the check
1080: 2d 69 6e 20 28 55 54 43 29 20 61 6e 64 20 61 20  -in (UTC) and a 
1090: 53 48 41 31 0a 2a 2a 20 6f 72 20 53 48 41 33 2d  SHA1.** or SHA3-
10a0: 32 35 36 20 68 61 73 68 20 6f 66 20 74 68 65 20  256 hash of the 
10b0: 65 6e 74 69 72 65 20 73 6f 75 72 63 65 20 74 72  entire source tr
10c0: 65 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ee..**.** See al
10d0: 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62  so: [sqlite3_lib
10e0: 76 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b  version()],.** [
10f0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1100: 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73  on_number()], [s
1110: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28  qlite3_sourceid(
1120: 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76  )],.** [sqlite_v
1130: 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  ersion()] and [s
1140: 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28  qlite_source_id(
1150: 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  )]..*/.#define S
1160: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20  QLITE_VERSION   
1170: 20 20 20 20 20 22 2d 2d 56 45 52 53 2d 2d 22 0a       "--VERS--".
1180: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
1190: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 2d 2d  ERSION_NUMBER --
11a0: 56 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d 2d  VERSION-NUMBER--
11b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
11c0: 53 4f 55 52 43 45 5f 49 44 20 20 20 20 20 20 22  SOURCE_ID      "
11d0: 2d 2d 53 4f 55 52 43 45 2d 49 44 2d 2d 22 0a 0a  --SOURCE-ID--"..
11e0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
11f0: 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79  Run-Time Library
1200: 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73   Version Numbers
1210: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71  .** KEYWORDS: sq
1220: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 20 73 71  lite3_version sq
1230: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 0a 2a  lite3_sourceid.*
1240: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 72  *.** These inter
1250: 66 61 63 65 73 20 70 72 6f 76 69 64 65 20 74 68  faces provide th
1260: 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69  e same informati
1270: 6f 6e 20 61 73 20 74 68 65 20 5b 53 51 4c 49 54  on as the [SQLIT
1280: 45 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b  E_VERSION],.** [
1290: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
12a0: 55 4d 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51 4c  UMBER], and [SQL
12b0: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43  ITE_SOURCE_ID] C
12c0: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
12d0: 63 72 6f 73 0a 2a 2a 20 62 75 74 20 61 72 65 20  cros.** but are 
12e0: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
12f0: 74 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74  the library inst
1300: 65 61 64 20 6f 66 20 74 68 65 20 68 65 61 64 65  ead of the heade
1310: 72 20 66 69 6c 65 2e 20 20 5e 28 43 61 75 74 69  r file.  ^(Cauti
1320: 6f 75 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d 65  ous.** programme
1330: 72 73 20 6d 69 67 68 74 20 69 6e 63 6c 75 64 65  rs might include
1340: 20 61 73 73 65 72 74 28 29 20 73 74 61 74 65 6d   assert() statem
1350: 65 6e 74 73 20 69 6e 20 74 68 65 69 72 20 61 70  ents in their ap
1360: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20  plication to.** 
1370: 76 65 72 69 66 79 20 74 68 61 74 20 76 61 6c 75  verify that valu
1380: 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  es returned by t
1390: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
13a0: 6d 61 74 63 68 20 74 68 65 20 6d 61 63 72 6f 73  match the macros
13b0: 20 69 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64 65   in.** the heade
13c0: 72 2c 20 61 6e 64 20 74 68 75 73 20 65 6e 73 75  r, and thus ensu
13d0: 72 65 20 74 68 61 74 20 74 68 65 20 61 70 70 6c  re that the appl
13e0: 69 63 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f  ication is.** co
13f0: 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 61 74 63  mpiled with matc
1400: 68 69 6e 67 20 6c 69 62 72 61 72 79 20 61 6e 64  hing library and
1410: 20 68 65 61 64 65 72 20 66 69 6c 65 73 2e 0a 2a   header files..*
1420: 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1430: 3e 3c 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72 74  ><pre>.** assert
1440: 28 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  ( sqlite3_libver
1450: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d 53  sion_number()==S
1460: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
1470: 4d 42 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65 72  MBER );.** asser
1480: 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65  t( strcmp(sqlite
1490: 33 5f 73 6f 75 72 63 65 69 64 28 29 2c 53 51 4c  3_sourceid(),SQL
14a0: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 29 3d 3d  ITE_SOURCE_ID)==
14b0: 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20  0 );.** assert( 
14c0: 73 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 6c  strcmp(sqlite3_l
14d0: 69 62 76 65 72 73 69 6f 6e 28 29 2c 53 51 4c 49  ibversion(),SQLI
14e0: 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d 30 20 29  TE_VERSION)==0 )
14f0: 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
1500: 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a  ckquote>)^.**.**
1510: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 65   ^The sqlite3_ve
1520: 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63  rsion[] string c
1530: 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61 69 6e 73  onstant contains
1540: 20 74 68 65 20 74 65 78 74 20 6f 66 20 5b 53 51   the text of [SQ
1550: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a  LITE_VERSION].**
1560: 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65 20 73 71   macro.  ^The sq
1570: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1580: 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  () function retu
1590: 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
15a0: 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68 65 20 73   the.** to the s
15b0: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
15c0: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74   string constant
15d0: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c  .  The sqlite3_l
15e0: 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a 2a 20 66  ibversion().** f
15f0: 75 6e 63 74 69 6f 6e 20 69 73 20 70 72 6f 76 69  unction is provi
1600: 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 44  ded for use in D
1610: 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c 20 75 73  LLs since DLL us
1620: 65 72 73 20 75 73 75 61 6c 6c 79 20 64 6f 20 6e  ers usually do n
1630: 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69 72 65 63  ot have.** direc
1640: 74 20 61 63 63 65 73 73 20 74 6f 20 73 74 72 69  t access to stri
1650: 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20 77 69 74  ng constants wit
1660: 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20 20 5e 54  hin the DLL.  ^T
1670: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c 69  he.** sqlite3_li
1680: 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28  bversion_number(
1690: 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ) function retur
16a0: 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 65 71  ns an integer eq
16b0: 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54  ual to.** [SQLIT
16c0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
16d0: 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  ].  ^The sqlite3
16e0: 5f 73 6f 75 72 63 65 69 64 28 29 20 66 75 6e 63  _sourceid() func
16f0: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 0a 2a 2a  tion returns .**
1700: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
1710: 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20  string constant 
1720: 77 68 6f 73 65 20 76 61 6c 75 65 20 69 73 20 74  whose value is t
1730: 68 65 20 73 61 6d 65 20 61 73 20 74 68 65 20 0a  he same as the .
1740: 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43  ** [SQLITE_SOURC
1750: 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f 63 65  E_ID] C preproce
1760: 73 73 6f 72 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a  ssor macro..**.*
1770: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
1780: 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d 20 61  ite_version()] a
1790: 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75 72 63  nd [sqlite_sourc
17a0: 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49  e_id()]..*/.SQLI
17b0: 54 45 5f 45 58 54 45 52 4e 20 63 6f 6e 73 74 20  TE_EXTERN const 
17c0: 63 68 61 72 20 73 71 6c 69 74 65 33 5f 76 65 72  char sqlite3_ver
17d0: 73 69 6f 6e 5b 5d 3b 0a 63 6f 6e 73 74 20 63 68  sion[];.const ch
17e0: 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62 76  ar *sqlite3_libv
17f0: 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 63 6f  ersion(void);.co
1800: 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
1810: 33 5f 73 6f 75 72 63 65 69 64 28 76 6f 69 64 29  3_sourceid(void)
1820: 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69  ;.int sqlite3_li
1830: 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28  bversion_number(
1840: 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  void);../*.** CA
1850: 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65  PI3REF: Run-Time
1860: 20 4c 69 62 72 61 72 79 20 43 6f 6d 70 69 6c 61   Library Compila
1870: 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 44 69 61  tion Options Dia
1880: 67 6e 6f 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 5e  gnostics.**.** ^
1890: 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  The sqlite3_comp
18a0: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
18b0: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
18c0: 73 20 30 20 6f 72 20 31 20 0a 2a 2a 20 69 6e 64  s 0 or 1 .** ind
18d0: 69 63 61 74 69 6e 67 20 77 68 65 74 68 65 72 20  icating whether 
18e0: 74 68 65 20 73 70 65 63 69 66 69 65 64 20 6f 70  the specified op
18f0: 74 69 6f 6e 20 77 61 73 20 64 65 66 69 6e 65 64  tion was defined
1900: 20 61 74 20 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20   at .** compile 
1910: 74 69 6d 65 2e 20 20 5e 54 68 65 20 53 51 4c 49  time.  ^The SQLI
1920: 54 45 5f 20 70 72 65 66 69 78 20 6d 61 79 20 62  TE_ prefix may b
1930: 65 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74  e omitted from t
1940: 68 65 20 0a 2a 2a 20 6f 70 74 69 6f 6e 20 6e 61  he .** option na
1950: 6d 65 20 70 61 73 73 65 64 20 74 6f 20 73 71 6c  me passed to sql
1960: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
1970: 6f 6e 5f 75 73 65 64 28 29 2e 20 20 0a 2a 2a 0a  on_used().  .**.
1980: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1990: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65  compileoption_ge
19a0: 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 6c 6c  t() function all
19b0: 6f 77 73 20 69 74 65 72 61 74 69 6e 67 0a 2a 2a  ows iterating.**
19c0: 20 6f 76 65 72 20 74 68 65 20 6c 69 73 74 20 6f   over the list o
19d0: 66 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 77  f options that w
19e0: 65 72 65 20 64 65 66 69 6e 65 64 20 61 74 20 63  ere defined at c
19f0: 6f 6d 70 69 6c 65 20 74 69 6d 65 20 62 79 0a 2a  ompile time by.*
1a00: 2a 20 72 65 74 75 72 6e 69 6e 67 20 74 68 65 20  * returning the 
1a10: 4e 2d 74 68 20 63 6f 6d 70 69 6c 65 20 74 69 6d  N-th compile tim
1a20: 65 20 6f 70 74 69 6f 6e 20 73 74 72 69 6e 67 2e  e option string.
1a30: 20 20 5e 49 66 20 4e 20 69 73 20 6f 75 74 20 6f    ^If N is out o
1a40: 66 20 72 61 6e 67 65 2c 0a 2a 2a 20 73 71 6c 69  f range,.** sqli
1a50: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
1a60: 6e 5f 67 65 74 28 29 20 72 65 74 75 72 6e 73 20  n_get() returns 
1a70: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
1a80: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 0a 2a   ^The SQLITE_ .*
1a90: 2a 20 70 72 65 66 69 78 20 69 73 20 6f 6d 69 74  * prefix is omit
1aa0: 74 65 64 20 66 72 6f 6d 20 61 6e 79 20 73 74 72  ted from any str
1ab0: 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
1ac0: 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d   .** sqlite3_com
1ad0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29  pileoption_get()
1ae0: 2e 0a 2a 2a 0a 2a 2a 20 5e 53 75 70 70 6f 72 74  ..**.** ^Support
1af0: 20 66 6f 72 20 74 68 65 20 64 69 61 67 6e 6f 73   for the diagnos
1b00: 74 69 63 20 66 75 6e 63 74 69 6f 6e 73 20 73 71  tic functions sq
1b10: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1b20: 69 6f 6e 5f 75 73 65 64 28 29 0a 2a 2a 20 61 6e  ion_used().** an
1b30: 64 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  d sqlite3_compil
1b40: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 6d 61  eoption_get() ma
1b50: 79 20 62 65 20 6f 6d 69 74 74 65 64 20 62 79 20  y be omitted by 
1b60: 73 70 65 63 69 66 79 69 6e 67 20 74 68 65 20 0a  specifying the .
1b70: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  ** [SQLITE_OMIT_
1b80: 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49  COMPILEOPTION_DI
1b90: 41 47 53 5d 20 6f 70 74 69 6f 6e 20 61 74 20 63  AGS] option at c
1ba0: 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 0a 2a 2a 0a  ompile time..**.
1bb0: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 53 51 4c  ** See also: SQL
1bc0: 20 66 75 6e 63 74 69 6f 6e 73 20 5b 73 71 6c 69   functions [sqli
1bd0: 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  te_compileoption
1be0: 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20  _used()] and.** 
1bf0: 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f  [sqlite_compileo
1c00: 70 74 69 6f 6e 5f 67 65 74 28 29 5d 20 61 6e 64  ption_get()] and
1c10: 20 74 68 65 20 5b 63 6f 6d 70 69 6c 65 5f 6f 70   the [compile_op
1c20: 74 69 6f 6e 73 20 70 72 61 67 6d 61 5d 2e 0a 2a  tions pragma]..*
1c30: 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  /.#ifndef SQLITE
1c40: 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54  _OMIT_COMPILEOPT
1c50: 49 4f 4e 5f 44 49 41 47 53 0a 69 6e 74 20 73 71  ION_DIAGS.int sq
1c60: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1c70: 69 6f 6e 5f 75 73 65 64 28 63 6f 6e 73 74 20 63  ion_used(const c
1c80: 68 61 72 20 2a 7a 4f 70 74 4e 61 6d 65 29 3b 0a  har *zOptName);.
1c90: 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
1ca0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
1cb0: 6e 5f 67 65 74 28 69 6e 74 20 4e 29 3b 0a 23 65  n_get(int N);.#e
1cc0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
1cd0: 33 52 45 46 3a 20 54 65 73 74 20 54 6f 20 53 65  3REF: Test To Se
1ce0: 65 20 49 66 20 54 68 65 20 4c 69 62 72 61 72 79  e If The Library
1cf0: 20 49 73 20 54 68 72 65 61 64 73 61 66 65 0a 2a   Is Threadsafe.*
1d00: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1d10: 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 20 66  3_threadsafe() f
1d20: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1d30: 7a 65 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79  zero if and only
1d40: 20 69 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61   if.** SQLite wa
1d50: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
1d60: 6d 75 74 65 78 69 6e 67 20 63 6f 64 65 20 6f 6d  mutexing code om
1d70: 69 74 74 65 64 20 64 75 65 20 74 6f 20 74 68 65  itted due to the
1d80: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  .** [SQLITE_THRE
1d90: 41 44 53 41 46 45 5d 20 63 6f 6d 70 69 6c 65 2d  ADSAFE] compile-
1da0: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 62 65 69 6e  time option bein
1db0: 67 20 73 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a  g set to 0..**.*
1dc0: 2a 20 53 51 4c 69 74 65 20 63 61 6e 20 62 65 20  * SQLite can be 
1dd0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6f 72  compiled with or
1de0: 20 77 69 74 68 6f 75 74 20 6d 75 74 65 78 65 73   without mutexes
1df0: 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b  .  When.** the [
1e00: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1e10: 45 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f  E] C preprocesso
1e20: 72 20 6d 61 63 72 6f 20 69 73 20 31 20 6f 72 20  r macro is 1 or 
1e30: 32 2c 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72  2, mutexes.** ar
1e40: 65 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 53 51  e enabled and SQ
1e50: 4c 69 74 65 20 69 73 20 74 68 72 65 61 64 73 61  Lite is threadsa
1e60: 66 65 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a  fe.  When the.**
1e70: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
1e80: 41 46 45 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c  AFE] macro is 0,
1e90: 20 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73   .** the mutexes
1ea0: 20 61 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 57   are omitted.  W
1eb0: 69 74 68 6f 75 74 20 74 68 65 20 6d 75 74 65 78  ithout the mutex
1ec0: 65 73 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 61  es, it is not sa
1ed0: 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c  fe.** to use SQL
1ee0: 69 74 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79  ite concurrently
1ef0: 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20   from more than 
1f00: 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a  one thread..**.*
1f10: 2a 20 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78  * Enabling mutex
1f20: 65 73 20 69 6e 63 75 72 73 20 61 20 6d 65 61 73  es incurs a meas
1f30: 75 72 61 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e  urable performan
1f40: 63 65 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53  ce penalty..** S
1f50: 6f 20 69 66 20 73 70 65 65 64 20 69 73 20 6f 66  o if speed is of
1f60: 20 75 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e   utmost importan
1f70: 63 65 2c 20 69 74 20 6d 61 6b 65 73 20 73 65 6e  ce, it makes sen
1f80: 73 65 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a  se to disable.**
1f90: 20 74 68 65 20 6d 75 74 65 78 65 73 2e 20 20 42   the mutexes.  B
1fa0: 75 74 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73  ut for maximum s
1fb0: 61 66 65 74 79 2c 20 6d 75 74 65 78 65 73 20 73  afety, mutexes s
1fc0: 68 6f 75 6c 64 20 62 65 20 65 6e 61 62 6c 65 64  hould be enabled
1fd0: 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  ..** ^The defaul
1fe0: 74 20 62 65 68 61 76 69 6f 72 20 69 73 20 66 6f  t behavior is fo
1ff0: 72 20 6d 75 74 65 78 65 73 20 74 6f 20 62 65 20  r mutexes to be 
2000: 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  enabled..**.** T
2010: 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61  his interface ca
2020: 6e 20 62 65 20 75 73 65 64 20 62 79 20 61 6e 20  n be used by an 
2030: 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 6d  application to m
2040: 61 6b 65 20 73 75 72 65 20 74 68 61 74 20 74 68  ake sure that th
2050: 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20  e.** version of 
2060: 53 51 4c 69 74 65 20 74 68 61 74 20 69 74 20 69  SQLite that it i
2070: 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73  s linking agains
2080: 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  t was compiled w
2090: 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 73 69 72  ith.** the desir
20a0: 65 64 20 73 65 74 74 69 6e 67 20 6f 66 20 74 68  ed setting of th
20b0: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
20c0: 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a  SAFE] macro..**.
20d0: 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
20e0: 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f  e only reports o
20f0: 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69  n the compile-ti
2100: 6d 65 20 6d 75 74 65 78 20 73 65 74 74 69 6e 67  me mutex setting
2110: 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  .** of the [SQLI
2120: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 66  TE_THREADSAFE] f
2130: 6c 61 67 2e 20 20 49 66 20 53 51 4c 69 74 65 20  lag.  If SQLite 
2140: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
2150: 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48 52 45 41  .** SQLITE_THREA
2160: 44 53 41 46 45 3d 31 20 6f 72 20 3d 32 20 74 68  DSAFE=1 or =2 th
2170: 65 6e 20 6d 75 74 65 78 65 73 20 61 72 65 20 65  en mutexes are e
2180: 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  nabled by defaul
2190: 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20  t but.** can be 
21a0: 66 75 6c 6c 79 20 6f 72 20 70 61 72 74 69 61 6c  fully or partial
21b0: 6c 79 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e  ly disabled usin
21c0: 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  g a call to [sql
21d0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a  ite3_config()].*
21e0: 2a 20 77 69 74 68 20 74 68 65 20 76 65 72 62 73  * with the verbs
21f0: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
2200: 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b  SINGLETHREAD], [
2210: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
2220: 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f  LTITHREAD],.** o
2230: 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  r [SQLITE_CONFIG
2240: 5f 53 45 52 49 41 4c 49 5a 45 44 5d 2e 20 20 5e  _SERIALIZED].  ^
2250: 28 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75  (The return valu
2260: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c 69  e of the.** sqli
2270: 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29  te3_threadsafe()
2280: 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 20   function shows 
2290: 6f 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c 65  only the compile
22a0: 2d 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f 66  -time setting of
22b0: 0a 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65 74  .** thread safet
22c0: 79 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74  y, not any run-t
22d0: 69 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20 74  ime changes to t
22e0: 68 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64 65  hat setting made
22f0: 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   by.** sqlite3_c
2300: 6f 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68 65  onfig(). In othe
2310: 72 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65 74  r words, the ret
2320: 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  urn value from s
2330: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
2340: 65 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61 6e  e().** is unchan
2350: 67 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f 20  ged by calls to 
2360: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
2370: 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68  .)^.**.** See th
2380: 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  e [threading mod
2390: 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  e] documentation
23a0: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
23b0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
23c0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65  int sqlite3_thre
23d0: 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f  adsafe(void);../
23e0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
23f0: 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
2400: 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59  on Handle.** KEY
2410: 57 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65  WORDS: {database
2420: 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61   connection} {da
2430: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2440: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f  ns}.**.** Each o
2450: 70 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62  pen SQLite datab
2460: 61 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74  ase is represent
2470: 65 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20  ed by a pointer 
2480: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
2490: 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20  f.** the opaque 
24a0: 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20  structure named 
24b0: 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69  "sqlite3".  It i
24c0: 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e  s useful to thin
24d0: 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a  k of an sqlite3.
24e0: 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e  ** pointer as an
24f0: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73   object.  The [s
2500: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
2510: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
2520: 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
2530: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69  te3_open_v2()] i
2540: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 74  nterfaces are it
2550: 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20  s constructors, 
2560: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  and [sqlite3_clo
2570: 73 65 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  se()].** and [sq
2580: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
2590: 5d 20 61 72 65 20 69 74 73 20 64 65 73 74 72 75  ] are its destru
25a0: 63 74 6f 72 73 2e 20 20 54 68 65 72 65 20 61 72  ctors.  There ar
25b0: 65 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20  e many other.** 
25c0: 69 6e 74 65 72 66 61 63 65 73 20 28 73 75 63 68  interfaces (such
25d0: 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   as.** [sqlite3_
25e0: 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b  prepare_v2()], [
25f0: 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2600: 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a  unction()], and.
2610: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ** [sqlite3_busy
2620: 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20 6e  _timeout()] to n
2630: 61 6d 65 20 62 75 74 20 74 68 72 65 65 29 20 74  ame but three) t
2640: 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73 20  hat are methods 
2650: 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33  on an.** sqlite3
2660: 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65   object..*/.type
2670: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
2680: 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a  e3 sqlite3;../*.
2690: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34 2d  ** CAPI3REF: 64-
26a0: 42 69 74 20 49 6e 74 65 67 65 72 20 54 79 70 65  Bit Integer Type
26b0: 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73  s.** KEYWORDS: s
26c0: 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69  qlite_int64 sqli
26d0: 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20  te_uint64.**.** 
26e0: 42 65 63 61 75 73 65 20 74 68 65 72 65 20 69 73  Because there is
26f0: 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f   no cross-platfo
2700: 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69 66  rm way to specif
2710: 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72  y 64-bit integer
2720: 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65   types.** SQLite
2730: 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64 65   includes typede
2740: 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73 69  fs for 64-bit si
2750: 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e 65  gned and unsigne
2760: 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a  d integers..**.*
2770: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  * The sqlite3_in
2780: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t64 and sqlite3_
2790: 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 20 70  uint64 are the p
27a0: 72 65 66 65 72 72 65 64 20 74 79 70 65 20 64 65  referred type de
27b0: 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68  finitions..** Th
27c0: 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 61  e sqlite_int64 a
27d0: 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  nd sqlite_uint64
27e0: 20 74 79 70 65 73 20 61 72 65 20 73 75 70 70 6f   types are suppo
27f0: 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  rted for backwar
2800: 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  ds.** compatibil
2810: 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ity only..**.** 
2820: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  ^The sqlite3_int
2830: 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 69 6e  64 and sqlite_in
2840: 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73 74  t64 types can st
2850: 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  ore integer valu
2860: 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 2d 39  es.** between -9
2870: 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38  2233720368547758
2880: 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37 32 30  08 and +92233720
2890: 33 36 38 35 34 37 37 35 38 30 37 20 69 6e 63 6c  36854775807 incl
28a0: 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a 2a 20  usive.  ^The.** 
28b0: 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61  sqlite3_uint64 a
28c0: 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  nd sqlite_uint64
28d0: 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72 65   types can store
28e0: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
28f0: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e  .** between 0 an
2900: 64 20 2b 31 38 34 34 36 37 34 34 30 37 33 37 30  d +1844674407370
2910: 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73 69 76  9551615 inclusiv
2920: 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c  e..*/.#ifdef SQL
2930: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a 20  ITE_INT64_TYPE. 
2940: 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f   typedef SQLITE_
2950: 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74  INT64_TYPE sqlit
2960: 65 5f 69 6e 74 36 34 3b 0a 23 20 69 66 64 65 66  e_int64;.# ifdef
2970: 20 53 51 4c 49 54 45 5f 55 49 4e 54 36 34 5f 54   SQLITE_UINT64_T
2980: 59 50 45 0a 20 20 20 20 74 79 70 65 64 65 66 20  YPE.    typedef 
2990: 53 51 4c 49 54 45 5f 55 49 4e 54 36 34 5f 54 59  SQLITE_UINT64_TY
29a0: 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  PE sqlite_uint64
29b0: 3b 0a 23 20 65 6c 73 65 20 20 0a 20 20 20 20 74  ;.# else  .    t
29c0: 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20  ypedef unsigned 
29d0: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
29e0: 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b  E sqlite_uint64;
29f0: 0a 23 20 65 6e 64 69 66 0a 23 65 6c 69 66 20 64  .# endif.#elif d
2a00: 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29  efined(_MSC_VER)
2a10: 20 7c 7c 20 64 65 66 69 6e 65 64 28 5f 5f 42 4f   || defined(__BO
2a20: 52 4c 41 4e 44 43 5f 5f 29 0a 20 20 74 79 70 65  RLANDC__).  type
2a30: 64 65 66 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69  def __int64 sqli
2a40: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
2a50: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 5f 5f 69  def unsigned __i
2a60: 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74  nt64 sqlite_uint
2a70: 36 34 3b 0a 23 65 6c 73 65 0a 20 20 74 79 70 65  64;.#else.  type
2a80: 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e  def long long in
2a90: 74 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  t sqlite_int64;.
2aa0: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
2ab0: 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74  ed long long int
2ac0: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a   sqlite_uint64;.
2ad0: 23 65 6e 64 69 66 0a 74 79 70 65 64 65 66 20 73  #endif.typedef s
2ae0: 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69  qlite_int64 sqli
2af0: 74 65 33 5f 69 6e 74 36 34 3b 0a 74 79 70 65 64  te3_int64;.typed
2b00: 65 66 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  ef sqlite_uint64
2b10: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 3b   sqlite3_uint64;
2b20: 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70 69  ../*.** If compi
2b30: 6c 69 6e 67 20 66 6f 72 20 61 20 70 72 6f 63 65  ling for a proce
2b40: 73 73 6f 72 20 74 68 61 74 20 6c 61 63 6b 73 20  ssor that lacks 
2b50: 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 73  floating point s
2b60: 75 70 70 6f 72 74 2c 0a 2a 2a 20 73 75 62 73 74  upport,.** subst
2b70: 69 74 75 74 65 20 69 6e 74 65 67 65 72 20 66 6f  itute integer fo
2b80: 72 20 66 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e 74  r floating-point
2b90: 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49  ..*/.#ifdef SQLI
2ba0: 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47  TE_OMIT_FLOATING
2bb0: 5f 50 4f 49 4e 54 0a 23 20 64 65 66 69 6e 65 20  _POINT.# define 
2bc0: 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 69  double sqlite3_i
2bd0: 6e 74 36 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  nt64.#endif../*.
2be0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6c 6f  ** CAPI3REF: Clo
2bf0: 73 69 6e 67 20 41 20 44 61 74 61 62 61 73 65 20  sing A Database 
2c00: 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 44 45  Connection.** DE
2c10: 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65  STRUCTOR: sqlite
2c20: 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  3.**.** ^The sql
2c30: 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64  ite3_close() and
2c40: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76   sqlite3_close_v
2c50: 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65  2() routines are
2c60: 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a 2a 20   destructors.** 
2c70: 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33  for the [sqlite3
2c80: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 43 61  ] object..** ^Ca
2c90: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
2ca0: 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74  lose() and sqlit
2cb0: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 65  e3_close_v2() re
2cc0: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
2cd0: 20 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69   if.** the [sqli
2ce0: 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 73  te3] object is s
2cf0: 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74  uccessfully dest
2d00: 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73  royed and all as
2d10: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f  sociated.** reso
2d20: 75 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f  urces are deallo
2d30: 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  cated..**.** ^If
2d40: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2d50: 6e 6e 65 63 74 69 6f 6e 20 69 73 20 61 73 73 6f  nnection is asso
2d60: 63 69 61 74 65 64 20 77 69 74 68 20 75 6e 66 69  ciated with unfi
2d70: 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64  nalized prepared
2d80: 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 6f  .** statements o
2d90: 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c  r unfinished sql
2da0: 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65  ite3_backup obje
2db0: 63 74 73 20 74 68 65 6e 20 73 71 6c 69 74 65 33  cts then sqlite3
2dc0: 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c  _close().** will
2dd0: 20 6c 65 61 76 65 20 74 68 65 20 64 61 74 61 62   leave the datab
2de0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
2df0: 70 65 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 5b  pen and return [
2e00: 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a  SQLITE_BUSY]..**
2e10: 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f   ^If sqlite3_clo
2e20: 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65  se_v2() is calle
2e30: 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a  d with unfinaliz
2e40: 65 64 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ed prepared stat
2e50: 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 2f 6f 72  ements.** and/or
2e60: 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c 69   unfinished sqli
2e70: 74 65 33 5f 62 61 63 6b 75 70 73 2c 20 74 68 65  te3_backups, the
2e80: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
2e90: 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 63 6f 6d 65  onnection become
2ea0: 73 0a 2a 2a 20 61 6e 20 75 6e 75 73 61 62 6c 65  s.** an unusable
2eb0: 20 22 7a 6f 6d 62 69 65 22 20 77 68 69 63 68 20   "zombie" which 
2ec0: 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c  will automatical
2ed0: 6c 79 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  ly be deallocate
2ee0: 64 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 6c 61  d when the.** la
2ef0: 73 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74  st prepared stat
2f00: 65 6d 65 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a  ement is finaliz
2f10: 65 64 20 6f 72 20 74 68 65 20 6c 61 73 74 20 73  ed or the last s
2f20: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 69 73  qlite3_backup is
2f30: 0a 2a 2a 20 66 69 6e 69 73 68 65 64 2e 20 20 54  .** finished.  T
2f40: 68 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  he sqlite3_close
2f50: 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20  _v2() interface 
2f60: 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  is intended for 
2f70: 75 73 65 20 77 69 74 68 0a 2a 2a 20 68 6f 73 74  use with.** host
2f80: 20 6c 61 6e 67 75 61 67 65 73 20 74 68 61 74 20   languages that 
2f90: 61 72 65 20 67 61 72 62 61 67 65 20 63 6f 6c 6c  are garbage coll
2fa0: 65 63 74 65 64 2c 20 61 6e 64 20 77 68 65 72 65  ected, and where
2fb0: 20 74 68 65 20 6f 72 64 65 72 20 69 6e 20 77 68   the order in wh
2fc0: 69 63 68 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f  ich.** destructo
2fd0: 72 73 20 61 72 65 20 63 61 6c 6c 65 64 20 69 73  rs are called is
2fe0: 20 61 72 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a   arbitrary..**.*
2ff0: 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  * Applications s
3000: 68 6f 75 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66  hould [sqlite3_f
3010: 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69  inalize | finali
3020: 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70 61 72 65  ze] all [prepare
3030: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a  d statements],.*
3040: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  * [sqlite3_blob_
3050: 63 6c 6f 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61  close | close] a
3060: 6c 6c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73  ll [BLOB handles
3070: 5d 2c 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69  ], and .** [sqli
3080: 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73  te3_backup_finis
3090: 68 20 7c 20 66 69 6e 69 73 68 5d 20 61 6c 6c 20  h | finish] all 
30a0: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d  [sqlite3_backup]
30b0: 20 6f 62 6a 65 63 74 73 20 61 73 73 6f 63 69 61   objects associa
30c0: 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ted.** with the 
30d0: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
30e0: 20 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70   prior to attemp
30f0: 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68  ting to close th
3100: 65 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a  e object.  ^If.*
3110: 2a 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f  * sqlite3_close_
3120: 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20 6f  v2() is called o
3130: 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  n a [database co
3140: 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 73  nnection] that s
3150: 74 69 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75 74 73  till has.** outs
3160: 74 61 6e 64 69 6e 67 20 5b 70 72 65 70 61 72 65  tanding [prepare
3170: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b  d statements], [
3180: 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61  BLOB handles], a
3190: 6e 64 2f 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  nd/or.** [sqlite
31a0: 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74  3_backup] object
31b0: 73 20 74 68 65 6e 20 69 74 20 72 65 74 75 72 6e  s then it return
31c0: 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 61 6e  s [SQLITE_OK] an
31d0: 64 20 74 68 65 20 64 65 61 6c 6c 6f 63 61 74 69  d the deallocati
31e0: 6f 6e 0a 2a 2a 20 6f 66 20 72 65 73 6f 75 72 63  on.** of resourc
31f0: 65 73 20 69 73 20 64 65 66 65 72 72 65 64 20 75  es is deferred u
3200: 6e 74 69 6c 20 61 6c 6c 20 5b 70 72 65 70 61 72  ntil all [prepar
3210: 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20  ed statements], 
3220: 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 0a  [BLOB handles],.
3230: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
3240: 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20  backup] objects 
3250: 61 72 65 20 61 6c 73 6f 20 64 65 73 74 72 6f 79  are also destroy
3260: 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ed..**.** ^If an
3270: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
3280: 74 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 77  t is destroyed w
3290: 68 69 6c 65 20 61 20 74 72 61 6e 73 61 63 74 69  hile a transacti
32a0: 6f 6e 20 69 73 20 6f 70 65 6e 2c 0a 2a 2a 20 74  on is open,.** t
32b0: 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69  he transaction i
32c0: 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  s automatically 
32d0: 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a  rolled back..**.
32e0: 2a 2a 20 54 68 65 20 43 20 70 61 72 61 6d 65 74  ** The C paramet
32f0: 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  er to [sqlite3_c
3300: 6c 6f 73 65 28 43 29 5d 20 61 6e 64 20 5b 73 71  lose(C)] and [sq
3310: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 43  lite3_close_v2(C
3320: 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69  )].** must be ei
3330: 74 68 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70  ther a NULL.** p
3340: 6f 69 6e 74 65 72 20 6f 72 20 61 6e 20 5b 73 71  ointer or an [sq
3350: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 6f  lite3] object po
3360: 69 6e 74 65 72 20 6f 62 74 61 69 6e 65 64 0a 2a  inter obtained.*
3370: 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
3380: 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
3390: 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 0a  3_open16()], or.
33a0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ** [sqlite3_open
33b0: 5f 76 32 28 29 5d 2c 20 61 6e 64 20 6e 6f 74 20  _v2()], and not 
33c0: 70 72 65 76 69 6f 75 73 6c 79 20 63 6c 6f 73 65  previously close
33d0: 64 2e 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73  d..** ^Calling s
33e0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 6f  qlite3_close() o
33f0: 72 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f  r sqlite3_close_
3400: 76 32 28 29 20 77 69 74 68 20 61 20 4e 55 4c 4c  v2() with a NULL
3410: 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 61 72 67 75   pointer.** argu
3420: 6d 65 6e 74 20 69 73 20 61 20 68 61 72 6d 6c 65  ment is a harmle
3430: 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 69 6e 74  ss no-op..*/.int
3440: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 73   sqlite3_close(s
3450: 71 6c 69 74 65 33 2a 29 3b 0a 69 6e 74 20 73 71  qlite3*);.int sq
3460: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 73  lite3_close_v2(s
3470: 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
3480: 20 54 68 65 20 74 79 70 65 20 66 6f 72 20 61 20   The type for a 
3490: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
34a0: 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 6c 65  n..** This is le
34b0: 67 61 63 79 20 61 6e 64 20 64 65 70 72 65 63 61  gacy and depreca
34c0: 74 65 64 2e 20 20 49 74 20 69 73 20 69 6e 63 6c  ted.  It is incl
34d0: 75 64 65 64 20 66 6f 72 20 68 69 73 74 6f 72 69  uded for histori
34e0: 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69  cal.** compatibi
34f0: 6c 69 74 79 20 61 6e 64 20 69 73 20 6e 6f 74 20  lity and is not 
3500: 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74  documented..*/.t
3510: 79 70 65 64 65 66 20 69 6e 74 20 28 2a 73 71 6c  ypedef int (*sql
3520: 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76  ite3_callback)(v
3530: 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c  oid*,int,char**,
3540: 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a   char**);../*.**
3550: 20 43 41 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53   CAPI3REF: One-S
3560: 74 65 70 20 51 75 65 72 79 20 45 78 65 63 75 74  tep Query Execut
3570: 69 6f 6e 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a  ion Interface.**
3580: 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
3590: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
35a0: 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66  e3_exec() interf
35b0: 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e 69  ace is a conveni
35c0: 65 6e 63 65 20 77 72 61 70 70 65 72 20 61 72 6f  ence wrapper aro
35d0: 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  und.** [sqlite3_
35e0: 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b  prepare_v2()], [
35f0: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c  sqlite3_step()],
3600: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 69   and [sqlite3_fi
3610: 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74 68  nalize()],.** th
3620: 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70 70  at allows an app
3630: 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e 20  lication to run 
3640: 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d 65  multiple stateme
3650: 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77 69  nts of SQL.** wi
3660: 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f 20  thout having to 
3670: 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20 63  use a lot of C c
3680: 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ode. .**.** ^The
3690: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
36a0: 69 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20 7a  interface runs z
36b0: 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46 2d  ero or more UTF-
36c0: 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73 65  8 encoded,.** se
36d0: 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65  micolon-separate
36e0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
36f0: 70 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73 20  passed into its 
3700: 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a 2a  2nd argument,.**
3710: 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74 20   in the context 
3720: 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  of the [database
3730: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61 73   connection] pas
3740: 73 65 64 20 69 6e 20 61 73 20 69 74 73 20 31 73  sed in as its 1s
3750: 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20  t.** argument.  
3760: 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ^If the callback
3770: 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68 65   function of the
3780: 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f   3rd argument to
3790: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
37a0: 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  () is not NULL, 
37b0: 74 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f 6b  then it is invok
37c0: 65 64 20 66 6f 72 20 65 61 63 68 20 72 65 73 75  ed for each resu
37d0: 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e 67  lt row.** coming
37e0: 20 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61 6c   out of the eval
37f0: 75 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  uated SQL statem
3800: 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68 20  ents.  ^The 4th 
3810: 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73  argument to.** s
3820: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3830: 20 72 65 6c 61 79 65 64 20 74 68 72 6f 75 67 68   relayed through
3840: 20 74 6f 20 74 68 65 20 31 73 74 20 61 72 67 75   to the 1st argu
3850: 6d 65 6e 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20  ment of each.** 
3860: 63 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 63 61 74  callback invocat
3870: 69 6f 6e 2e 20 20 5e 49 66 20 74 68 65 20 63 61  ion.  ^If the ca
3880: 6c 6c 62 61 63 6b 20 70 6f 69 6e 74 65 72 20 74  llback pointer t
3890: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
38a0: 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  .** is NULL, the
38b0: 6e 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 20 69 73  n no callback is
38c0: 20 65 76 65 72 20 69 6e 76 6f 6b 65 64 20 61 6e   ever invoked an
38d0: 64 20 72 65 73 75 6c 74 20 72 6f 77 73 20 61 72  d result rows ar
38e0: 65 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a  e.** ignored..**
38f0: 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72 6f 72  .** ^If an error
3900: 20 6f 63 63 75 72 73 20 77 68 69 6c 65 20 65 76   occurs while ev
3910: 61 6c 75 61 74 69 6e 67 20 74 68 65 20 53 51 4c  aluating the SQL
3920: 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73   statements pass
3930: 65 64 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74  ed into.** sqlit
3940: 65 33 5f 65 78 65 63 28 29 2c 20 74 68 65 6e 20  e3_exec(), then 
3950: 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65  execution of the
3960: 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 6d 65   current stateme
3970: 6e 74 20 73 74 6f 70 73 20 61 6e 64 0a 2a 2a 20  nt stops and.** 
3980: 73 75 62 73 65 71 75 65 6e 74 20 73 74 61 74 65  subsequent state
3990: 6d 65 6e 74 73 20 61 72 65 20 73 6b 69 70 70 65  ments are skippe
39a0: 64 2e 20 20 5e 49 66 20 74 68 65 20 35 74 68 20  d.  ^If the 5th 
39b0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
39c0: 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69  ite3_exec().** i
39d0: 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20  s not NULL then 
39e0: 61 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 61 67  any error messag
39f0: 65 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74  e is written int
3a00: 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
3a10: 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  d.** from [sqlit
3a20: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64  e3_malloc()] and
3a30: 20 70 61 73 73 65 64 20 62 61 63 6b 20 74 68 72   passed back thr
3a40: 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72  ough the 5th par
3a50: 61 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f 20 61 76  ameter..** To av
3a60: 6f 69 64 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 73  oid memory leaks
3a70: 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  , the applicatio
3a80: 6e 20 73 68 6f 75 6c 64 20 69 6e 76 6f 6b 65 20  n should invoke 
3a90: 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
3aa0: 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72 20 6d 65 73  .** on error mes
3ab0: 73 61 67 65 20 73 74 72 69 6e 67 73 20 72 65 74  sage strings ret
3ac0: 75 72 6e 65 64 20 74 68 72 6f 75 67 68 20 74 68  urned through th
3ad0: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
3ae0: 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78  of.** sqlite3_ex
3af0: 65 63 28 29 20 61 66 74 65 72 20 74 68 65 20 65  ec() after the e
3b00: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
3b10: 69 6e 67 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72  ing is no longer
3b20: 20 6e 65 65 64 65 64 2e 0a 2a 2a 20 5e 49 66 20   needed..** ^If 
3b30: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
3b40: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
3b50: 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  c() is not NULL 
3b60: 61 6e 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a  and no errors.**
3b70: 20 6f 63 63 75 72 2c 20 74 68 65 6e 20 73 71 6c   occur, then sql
3b80: 69 74 65 33 5f 65 78 65 63 28 29 20 73 65 74 73  ite3_exec() sets
3b90: 20 74 68 65 20 70 6f 69 6e 74 65 72 20 69 6e 20   the pointer in 
3ba0: 69 74 73 20 35 74 68 20 70 61 72 61 6d 65 74 65  its 5th paramete
3bb0: 72 20 74 6f 0a 2a 2a 20 4e 55 4c 4c 20 62 65 66  r to.** NULL bef
3bc0: 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a  ore returning..*
3bd0: 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 73 71 6c 69  *.** ^If an sqli
3be0: 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62  te3_exec() callb
3bf0: 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ack returns non-
3c00: 7a 65 72 6f 2c 20 74 68 65 20 73 71 6c 69 74 65  zero, the sqlite
3c10: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 72 6f 75 74  3_exec().** rout
3c20: 69 6e 65 20 72 65 74 75 72 6e 73 20 53 51 4c 49  ine returns SQLI
3c30: 54 45 5f 41 42 4f 52 54 20 77 69 74 68 6f 75 74  TE_ABORT without
3c40: 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 63 61   invoking the ca
3c50: 6c 6c 62 61 63 6b 20 61 67 61 69 6e 20 61 6e 64  llback again and
3c60: 0a 2a 2a 20 77 69 74 68 6f 75 74 20 72 75 6e 6e  .** without runn
3c70: 69 6e 67 20 61 6e 79 20 73 75 62 73 65 71 75 65  ing any subseque
3c80: 6e 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  nt SQL statement
3c90: 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 32 6e  s..**.** ^The 2n
3ca0: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  d argument to th
3cb0: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3cc0: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
3cd0: 6f 6e 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  on is the.** num
3ce0: 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
3cf0: 6e 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 5e  n the result.  ^
3d00: 54 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74  The 3rd argument
3d10: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
3d20: 65 78 65 63 28 29 0a 2a 2a 20 63 61 6c 6c 62 61  exec().** callba
3d30: 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  ck is an array o
3d40: 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74  f pointers to st
3d50: 72 69 6e 67 73 20 6f 62 74 61 69 6e 65 64 20 61  rings obtained a
3d60: 73 20 69 66 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71  s if from.** [sq
3d70: 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
3d80: 74 28 29 5d 2c 20 6f 6e 65 20 66 6f 72 20 65 61  t()], one for ea
3d90: 63 68 20 63 6f 6c 75 6d 6e 2e 20 20 5e 49 66 20  ch column.  ^If 
3da0: 61 6e 20 65 6c 65 6d 65 6e 74 20 6f 66 20 61 0a  an element of a.
3db0: 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 69 73  ** result row is
3dc0: 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 63   NULL then the c
3dd0: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 73 74 72  orresponding str
3de0: 69 6e 67 20 70 6f 69 6e 74 65 72 20 66 6f 72 20  ing pointer for 
3df0: 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65  the.** sqlite3_e
3e00: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69  xec() callback i
3e10: 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
3e20: 2e 20 20 5e 54 68 65 20 34 74 68 20 61 72 67 75  .  ^The 4th argu
3e30: 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 73  ment to the.** s
3e40: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61  qlite3_exec() ca
3e50: 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72  llback is an arr
3e60: 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
3e70: 6f 20 73 74 72 69 6e 67 73 20 77 68 65 72 65 20  o strings where 
3e80: 65 61 63 68 0a 2a 2a 20 65 6e 74 72 79 20 72 65  each.** entry re
3e90: 70 72 65 73 65 6e 74 73 20 74 68 65 20 6e 61 6d  presents the nam
3ea0: 65 20 6f 66 20 63 6f 72 72 65 73 70 6f 6e 64 69  e of correspondi
3eb0: 6e 67 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  ng result column
3ec0: 20 61 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20   as obtained.** 
3ed0: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f  from [sqlite3_co
3ee0: 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a  lumn_name()]..**
3ef0: 0a 2a 2a 20 5e 49 66 20 74 68 65 20 32 6e 64 20  .** ^If the 2nd 
3f00: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
3f10: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 61  ite3_exec() is a
3f20: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 61   NULL pointer, a
3f30: 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 61   pointer.** to a
3f40: 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20  n empty string, 
3f50: 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74 68 61  or a pointer tha
3f60: 74 20 63 6f 6e 74 61 69 6e 73 20 6f 6e 6c 79 20  t contains only 
3f70: 77 68 69 74 65 73 70 61 63 65 20 61 6e 64 2f 6f  whitespace and/o
3f80: 72 20 0a 2a 2a 20 53 51 4c 20 63 6f 6d 6d 65 6e  r .** SQL commen
3f90: 74 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51 4c 20  ts, then no SQL 
3fa0: 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 65  statements are e
3fb0: 76 61 6c 75 61 74 65 64 20 61 6e 64 20 74 68 65  valuated and the
3fc0: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20   database.** is 
3fd0: 6e 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a  not changed..**.
3fe0: 2a 2a 20 52 65 73 74 72 69 63 74 69 6f 6e 73 3a  ** Restrictions:
3ff0: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
4000: 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74  li> The applicat
4010: 69 6f 6e 20 6d 75 73 74 20 65 6e 73 75 72 65 20  ion must ensure 
4020: 74 68 61 74 20 74 68 65 20 31 73 74 20 70 61 72  that the 1st par
4030: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
4040: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 20 20 20 20  3_exec().**     
4050: 20 69 73 20 61 20 76 61 6c 69 64 20 61 6e 64 20   is a valid and 
4060: 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63  open [database c
4070: 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c  onnection]..** <
4080: 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74  li> The applicat
4090: 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f  ion must not clo
40a0: 73 65 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  se the [database
40b0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65   connection] spe
40c0: 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20  cified by.**    
40d0: 20 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65    the 1st parame
40e0: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
40f0: 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69  xec() while sqli
4100: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75  te3_exec() is ru
4110: 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e 20 54  nning..** <li> T
4120: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
4130: 75 73 74 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74  ust not modify t
4140: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
4150: 20 74 65 78 74 20 70 61 73 73 65 64 20 69 6e 74   text passed int
4160: 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 32 6e  o.**      the 2n
4170: 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73  d parameter of s
4180: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68  qlite3_exec() wh
4190: 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  ile sqlite3_exec
41a0: 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  () is running..*
41b0: 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69 6e 74 20 73  * </ul>.*/.int s
41c0: 71 6c 69 74 65 33 5f 65 78 65 63 28 0a 20 20 73  qlite3_exec(.  s
41d0: 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 20 20  qlite3*,        
41e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41f0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20            /* An 
4200: 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f  open database */
4210: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  .  const char *s
4220: 71 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  ql,             
4230: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
4240: 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75   SQL to be evalu
4250: 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  ated */.  int (*
4260: 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c  callback)(void*,
4270: 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a  int,char**,char*
4280: 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b  *),  /* Callback
4290: 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76   function */.  v
42a0: 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20  oid *,          
42b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
42c0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 31 73 74            /* 1st
42d0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c   argument to cal
42e0: 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72 20  lback */.  char 
42f0: 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20 20 20  **errmsg        
4300: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4310: 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d        /* Error m
4320: 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  sg written here 
4330: 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
4340: 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 43 6f  I3REF: Result Co
4350: 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  des.** KEYWORDS:
4360: 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 20 64 65   {result code de
4370: 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a  finitions}.**.**
4380: 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e   Many SQLite fun
4390: 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e  ctions return an
43a0: 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20   integer result 
43b0: 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65  code from the se
43c0: 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20  t shown.** here 
43d0: 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69  in order to indi
43e0: 63 61 74 65 20 73 75 63 63 65 73 73 20 6f 72 20  cate success or 
43f0: 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e  failure..**.** N
4400: 65 77 20 65 72 72 6f 72 20 63 6f 64 65 73 20 6d  ew error codes m
4410: 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
4420: 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
4430: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20  f SQLite..**.** 
4440: 53 65 65 20 61 6c 73 6f 3a 20 5b 65 78 74 65 6e  See also: [exten
4450: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20  ded result code 
4460: 64 65 66 69 6e 69 74 69 6f 6e 73 5d 0a 2a 2f 0a  definitions].*/.
4470: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
4480: 4b 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20  K           0   
4490: 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20 72 65  /* Successful re
44a0: 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e  sult */./* begin
44b0: 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f  ning-of-error-co
44c0: 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  des */.#define S
44d0: 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20 20 20  QLITE_ERROR     
44e0: 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20 65 72     1   /* SQL er
44f0: 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67 20 64  ror or missing d
4500: 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69  atabase */.#defi
4510: 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 4e  ne SQLITE_INTERN
4520: 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20 49 6e  AL     2   /* In
4530: 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65 72 72  ternal logic err
4540: 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a 2f 0a  or in SQLite */.
4550: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50  #define SQLITE_P
4560: 45 52 4d 20 20 20 20 20 20 20 20 20 33 20 20 20  ERM         3   
4570: 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d 69 73  /* Access permis
4580: 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23  sion denied */.#
4590: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42  define SQLITE_AB
45a0: 4f 52 54 20 20 20 20 20 20 20 20 34 20 20 20 2f  ORT        4   /
45b0: 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69  * Callback routi
45c0: 6e 65 20 72 65 71 75 65 73 74 65 64 20 61 6e 20  ne requested an 
45d0: 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69 6e 65  abort */.#define
45e0: 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 20   SQLITE_BUSY    
45f0: 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68 65 20       5   /* The 
4600: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73  database file is
4610: 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69   locked */.#defi
4620: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44  ne SQLITE_LOCKED
4630: 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20 41 20         6   /* A 
4640: 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64 61 74  table in the dat
4650: 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65 64 20  abase is locked 
4660: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4670: 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 37  E_NOMEM        7
4680: 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28 29     /* A malloc()
4690: 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65 66 69   failed */.#defi
46a0: 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e  ne SQLITE_READON
46b0: 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20 41 74  LY     8   /* At
46c0: 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65 20 61  tempt to write a
46d0: 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61 62 61   readonly databa
46e0: 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  se */.#define SQ
46f0: 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 20 20  LITE_INTERRUPT  
4700: 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61 74 69    9   /* Operati
4710: 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20 62 79  on terminated by
4720: 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
4730: 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65 20 53  pt()*/.#define S
4740: 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20 20 20  QLITE_IOERR     
4750: 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65 20 6b    10   /* Some k
4760: 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f 4f 20  ind of disk I/O 
4770: 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64 20 2a  error occurred *
4780: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4790: 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31 31 20  _CORRUPT     11 
47a0: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
47b0: 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69 73 20  e disk image is 
47c0: 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 64 65  malformed */.#de
47d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 46  fine SQLITE_NOTF
47e0: 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f 2a 20  OUND    12   /* 
47f0: 55 6e 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65 20 69  Unknown opcode i
4800: 6e 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63  n sqlite3_file_c
4810: 6f 6e 74 72 6f 6c 28 29 20 2a 2f 0a 23 64 65 66  ontrol() */.#def
4820: 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20  ine SQLITE_FULL 
4830: 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 49         13   /* I
4840: 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65 64 20  nsertion failed 
4850: 62 65 63 61 75 73 65 20 64 61 74 61 62 61 73 65  because database
4860: 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66   is full */.#def
4870: 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f  ine SQLITE_CANTO
4880: 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a 20 55  PEN    14   /* U
4890: 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68  nable to open th
48a0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
48b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
48c0: 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35  E_PROTOCOL    15
48d0: 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 6c     /* Database l
48e0: 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72  ock protocol err
48f0: 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  or */.#define SQ
4900: 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20 20 20  LITE_EMPTY      
4910: 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73   16   /* Databas
4920: 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64  e is empty */.#d
4930: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 43 48  efine SQLITE_SCH
4940: 45 4d 41 20 20 20 20 20 20 31 37 20 20 20 2f 2a  EMA      17   /*
4950: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 73 63   The database sc
4960: 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a  hema changed */.
4970: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
4980: 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20 20 20  OOBIG      18   
4990: 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f  /* String or BLO
49a0: 42 20 65 78 63 65 65 64 73 20 73 69 7a 65 20 6c  B exceeds size l
49b0: 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20  imit */.#define 
49c0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
49d0: 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f 72 74  T  19   /* Abort
49e0: 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 61 69   due to constrai
49f0: 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a  nt violation */.
4a00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
4a10: 49 53 4d 41 54 43 48 20 20 20 20 32 30 20 20 20  ISMATCH    20   
4a20: 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d 69 73  /* Data type mis
4a30: 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65  match */.#define
4a40: 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 20   SQLITE_MISUSE  
4a50: 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 62 72      21   /* Libr
4a60: 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72 72 65  ary used incorre
4a70: 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ctly */.#define 
4a80: 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20  SQLITE_NOLFS    
4a90: 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65 73 20     22   /* Uses 
4aa0: 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f 74 20  OS features not 
4ab0: 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73  supported on hos
4ac0: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
4ad0: 49 54 45 5f 41 55 54 48 20 20 20 20 20 20 20 20  ITE_AUTH        
4ae0: 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a  23   /* Authoriz
4af0: 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a  ation denied */.
4b00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
4b10: 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20 20 20  ORMAT      24   
4b20: 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64 61 74  /* Auxiliary dat
4b30: 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65 72 72  abase format err
4b40: 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  or */.#define SQ
4b50: 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20 20 20  LITE_RANGE      
4b60: 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70 61 72   25   /* 2nd par
4b70: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
4b80: 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20 72 61  3_bind out of ra
4b90: 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nge */.#define S
4ba0: 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20 20 20  QLITE_NOTADB    
4bb0: 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f    26   /* File o
4bc0: 70 65 6e 65 64 20 74 68 61 74 20 69 73 20 6e 6f  pened that is no
4bd0: 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  t a database fil
4be0: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
4bf0: 49 54 45 5f 4e 4f 54 49 43 45 20 20 20 20 20 20  ITE_NOTICE      
4c00: 32 37 20 20 20 2f 2a 20 4e 6f 74 69 66 69 63 61  27   /* Notifica
4c10: 74 69 6f 6e 73 20 66 72 6f 6d 20 73 71 6c 69 74  tions from sqlit
4c20: 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64 65 66  e3_log() */.#def
4c30: 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e 49  ine SQLITE_WARNI
4c40: 4e 47 20 20 20 20 20 32 38 20 20 20 2f 2a 20 57  NG     28   /* W
4c50: 61 72 6e 69 6e 67 73 20 66 72 6f 6d 20 73 71 6c  arnings from sql
4c60: 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64  ite3_log() */.#d
4c70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57  efine SQLITE_ROW
4c80: 20 20 20 20 20 20 20 20 20 31 30 30 20 20 2f 2a           100  /*
4c90: 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
4ca0: 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f 77 20  has another row 
4cb0: 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65  ready */.#define
4cc0: 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20   SQLITE_DONE    
4cd0: 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71 6c 69      101  /* sqli
4ce0: 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 66  te3_step() has f
4cf0: 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e  inished executin
4d00: 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65  g */./* end-of-e
4d10: 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f  rror-codes */../
4d20: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
4d30: 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43  xtended Result C
4d40: 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  odes.** KEYWORDS
4d50: 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75  : {extended resu
4d60: 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69  lt code definiti
4d70: 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74  ons}.**.** In it
4d80: 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67  s default config
4d90: 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20  uration, SQLite 
4da0: 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74  API routines ret
4db0: 75 72 6e 20 6f 6e 65 20 6f 66 20 33 30 20 69 6e  urn one of 30 in
4dc0: 74 65 67 65 72 0a 2a 2a 20 5b 72 65 73 75 6c 74  teger.** [result
4dd0: 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65   codes].  Howeve
4de0: 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 61  r, experience ha
4df0: 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e  s shown that man
4e00: 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65  y of.** these re
4e10: 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74  sult codes are t
4e20: 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65  oo coarse-graine
4e30: 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20  d.  They do not 
4e40: 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75  provide as.** mu
4e50: 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  ch information a
4e60: 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73  bout problems as
4e70: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
4e80: 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20  ht like.  In an 
4e90: 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64  effort to.** add
4ea0: 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72  ress this, newer
4eb0: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
4ec0: 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33  ite (version 3.3
4ed0: 2e 38 20 5b 64 61 74 65 6f 66 3a 33 2e 33 2e 38  .8 [dateof:3.3.8
4ee0: 5d 0a 2a 2a 20 61 6e 64 20 6c 61 74 65 72 29 20  ].** and later) 
4ef0: 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f  include.** suppo
4f00: 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  rt for additiona
4f10: 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 74  l result codes t
4f20: 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 65  hat provide more
4f30: 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d   detailed inform
4f40: 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65  ation.** about e
4f50: 72 72 6f 72 73 2e 20 54 68 65 73 65 20 5b 65 78  rrors. These [ex
4f60: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
4f70: 64 65 73 5d 20 61 72 65 20 65 6e 61 62 6c 65 64  des] are enabled
4f80: 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20   or disabled.** 
4f90: 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62 61 73  on a per databas
4fa0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73  e connection bas
4fb0: 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  is using the.** 
4fc0: 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65  [sqlite3_extende
4fd0: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
4fe0: 5d 20 41 50 49 2e 20 20 4f 72 2c 20 74 68 65 20  ] API.  Or, the 
4ff0: 65 78 74 65 6e 64 65 64 20 63 6f 64 65 20 66 6f  extended code fo
5000: 72 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20 72 65  r.** the most re
5010: 63 65 6e 74 20 65 72 72 6f 72 20 63 61 6e 20 62  cent error can b
5020: 65 20 6f 62 74 61 69 6e 65 64 20 75 73 69 6e 67  e obtained using
5030: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74  .** [sqlite3_ext
5040: 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 5d  ended_errcode()]
5050: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
5060: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20  ITE_IOERR_READ  
5070: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5080: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c  ITE_IOERR | (1<<
5090: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
50a0: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
50b0: 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  EAD        (SQLI
50c0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38  TE_IOERR | (2<<8
50d0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
50e0: 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20  E_IOERR_WRITE   
50f0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5100: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29  E_IOERR | (3<<8)
5110: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5120: 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20  _IOERR_FSYNC    
5130: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5140: 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29  _IOERR | (4<<8))
5150: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5160: 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20  IOERR_DIR_FSYNC 
5170: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5180: 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a  IOERR | (5<<8)).
5190: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
51a0: 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20  OERR_TRUNCATE   
51b0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
51c0: 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23  OERR | (6<<8)).#
51d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
51e0: 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20  ERR_FSTAT       
51f0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5200: 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64  ERR | (7<<8)).#d
5210: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5220: 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20  RR_UNLOCK       
5230: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5240: 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65  RR | (8<<8)).#de
5250: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5260: 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_RDLOCK        
5270: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5280: 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66  R | (9<<8)).#def
5290: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
52a0: 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
52b0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
52c0: 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66   | (10<<8)).#def
52d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
52e0: 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20  _BLOCKED        
52f0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5300: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66   | (11<<8)).#def
5310: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5320: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20  _NOMEM          
5330: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5340: 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66   | (12<<8)).#def
5350: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5360: 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20  _ACCESS         
5370: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5380: 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66   | (13<<8)).#def
5390: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
53a0: 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f  _CHECKRESERVEDLO
53b0: 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52  CK (SQLITE_IOERR
53c0: 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66   | (14<<8)).#def
53d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
53e0: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  _LOCK           
53f0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5400: 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66   | (15<<8)).#def
5410: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5420: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20  _CLOSE          
5430: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5440: 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66   | (16<<8)).#def
5450: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5460: 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20  _DIR_CLOSE      
5470: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5480: 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66   | (17<<8)).#def
5490: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
54a0: 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20  _SHMOPEN        
54b0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
54c0: 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66   | (18<<8)).#def
54d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
54e0: 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20  _SHMSIZE        
54f0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5500: 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66   | (19<<8)).#def
5510: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5520: 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20  _SHMLOCK        
5530: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5540: 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66   | (20<<8)).#def
5550: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5560: 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20  _SHMMAP         
5570: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5580: 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66   | (21<<8)).#def
5590: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
55a0: 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20  _SEEK           
55b0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
55c0: 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66   | (22<<8)).#def
55d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
55e0: 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20  _DELETE_NOENT   
55f0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5600: 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66   | (23<<8)).#def
5610: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5620: 5f 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20  _MMAP           
5630: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5640: 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66   | (24<<8)).#def
5650: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5660: 5f 47 45 54 54 45 4d 50 50 41 54 48 20 20 20 20  _GETTEMPPATH    
5670: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5680: 20 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66   | (25<<8)).#def
5690: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
56a0: 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20  _CONVPATH       
56b0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
56c0: 20 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66   | (26<<8)).#def
56d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
56e0: 5f 56 4e 4f 44 45 20 20 20 20 20 20 20 20 20 20  _VNODE          
56f0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5700: 20 7c 20 28 32 37 3c 3c 38 29 29 0a 23 64 65 66   | (27<<8)).#def
5710: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5720: 5f 41 55 54 48 20 20 20 20 20 20 20 20 20 20 20  _AUTH           
5730: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5740: 20 7c 20 28 32 38 3c 3c 38 29 29 0a 23 64 65 66   | (28<<8)).#def
5750: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
5760: 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20  D_SHAREDCACHE   
5770: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45     (SQLITE_LOCKE
5780: 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65  D |  (1<<8)).#de
5790: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
57a0: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20  _RECOVERY       
57b0: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
57c0: 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64     |  (1<<8)).#d
57d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
57e0: 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20 20  Y_SNAPSHOT      
57f0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53       (SQLITE_BUS
5800: 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23  Y   |  (2<<8)).#
5810: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55  define SQLITE_BU
5820: 53 59 5f 44 45 41 44 4c 4f 43 4b 20 20 20 20 20  SY_DEADLOCK     
5830: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55        (SQLITE_BU
5840: 53 59 20 20 20 7c 20 20 28 33 3c 3c 38 29 29 0a  SY   |  (3<<8)).
5850: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5860: 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49  ANTOPEN_NOTEMPDI
5870: 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43  R      (SQLITE_C
5880: 41 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29  ANTOPEN | (1<<8)
5890: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
58a0: 5f 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20  _CANTOPEN_ISDIR 
58b0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
58c0: 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c  _CANTOPEN | (2<<
58d0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
58e0: 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c  TE_CANTOPEN_FULL
58f0: 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49  PATH       (SQLI
5900: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33  TE_CANTOPEN | (3
5910: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5920: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f  LITE_CANTOPEN_CO
5930: 4e 56 50 41 54 48 20 20 20 20 20 20 20 28 53 51  NVPATH       (SQ
5940: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20  LITE_CANTOPEN | 
5950: 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (4<<8)).#define 
5960: 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56  SQLITE_CORRUPT_V
5970: 54 41 42 20 20 20 20 20 20 20 20 20 20 20 20 28  TAB            (
5980: 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c  SQLITE_CORRUPT |
5990: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
59a0: 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59   SQLITE_READONLY
59b0: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20  _RECOVERY       
59c0: 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59  (SQLITE_READONLY
59d0: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
59e0: 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e  ne SQLITE_READON
59f0: 4c 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20  LY_CANTLOCK     
5a00: 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e    (SQLITE_READON
5a10: 4c 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  LY | (2<<8)).#de
5a20: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
5a30: 4f 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 20  ONLY_ROLLBACK   
5a40: 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44      (SQLITE_READ
5a50: 4f 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a 23  ONLY | (3<<8)).#
5a60: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
5a70: 41 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20 20  ADONLY_DBMOVED  
5a80: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45        (SQLITE_RE
5a90: 41 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29 29  ADONLY | (4<<8))
5aa0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5ab0: 41 42 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b 20 20  ABORT_ROLLBACK  
5ac0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5ad0: 41 42 4f 52 54 20 7c 20 28 32 3c 3c 38 29 29 0a  ABORT | (2<<8)).
5ae0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5af0: 4f 4e 53 54 52 41 49 4e 54 5f 43 48 45 43 4b 20  ONSTRAINT_CHECK 
5b00: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
5b10: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 31 3c 3c  ONSTRAINT | (1<<
5b20: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5b30: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 4f  TE_CONSTRAINT_CO
5b40: 4d 4d 49 54 48 4f 4f 4b 20 20 20 28 53 51 4c 49  MMITHOOK   (SQLI
5b50: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5b60: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (2<<8)).#define 
5b70: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5b80: 54 5f 46 4f 52 45 49 47 4e 4b 45 59 20 20 20 28  T_FOREIGNKEY   (
5b90: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5ba0: 54 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66  T | (3<<8)).#def
5bb0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5bc0: 52 41 49 4e 54 5f 46 55 4e 43 54 49 4f 4e 20 20  RAINT_FUNCTION  
5bd0: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5be0: 52 41 49 4e 54 20 7c 20 28 34 3c 3c 38 29 29 0a  RAINT | (4<<8)).
5bf0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5c00: 4f 4e 53 54 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c  ONSTRAINT_NOTNUL
5c10: 4c 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43  L      (SQLITE_C
5c20: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 35 3c 3c  ONSTRAINT | (5<<
5c30: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5c40: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 50 52  TE_CONSTRAINT_PR
5c50: 49 4d 41 52 59 4b 45 59 20 20 20 28 53 51 4c 49  IMARYKEY   (SQLI
5c60: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5c70: 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (6<<8)).#define 
5c80: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5c90: 54 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 28  T_TRIGGER      (
5ca0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5cb0: 54 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66  T | (7<<8)).#def
5cc0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5cd0: 52 41 49 4e 54 5f 55 4e 49 51 55 45 20 20 20 20  RAINT_UNIQUE    
5ce0: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5cf0: 52 41 49 4e 54 20 7c 20 28 38 3c 3c 38 29 29 0a  RAINT | (8<<8)).
5d00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5d10: 4f 4e 53 54 52 41 49 4e 54 5f 56 54 41 42 20 20  ONSTRAINT_VTAB  
5d20: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
5d30: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 39 3c 3c  ONSTRAINT | (9<<
5d40: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5d50: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 52 4f  TE_CONSTRAINT_RO
5d60: 57 49 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  WID        (SQLI
5d70: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 28  TE_CONSTRAINT |(
5d80: 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  10<<8)).#define 
5d90: 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45  SQLITE_NOTICE_RE
5da0: 43 4f 56 45 52 5f 57 41 4c 20 20 20 20 20 20 28  COVER_WAL      (
5db0: 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20  SQLITE_NOTICE | 
5dc0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
5dd0: 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45  SQLITE_NOTICE_RE
5de0: 43 4f 56 45 52 5f 52 4f 4c 4c 42 41 43 4b 20 28  COVER_ROLLBACK (
5df0: 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20  SQLITE_NOTICE | 
5e00: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (2<<8)).#define 
5e10: 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 5f 41  SQLITE_WARNING_A
5e20: 55 54 4f 49 4e 44 45 58 20 20 20 20 20 20 20 28  UTOINDEX       (
5e30: 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 7c  SQLITE_WARNING |
5e40: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
5e50: 20 53 51 4c 49 54 45 5f 41 55 54 48 5f 55 53 45   SQLITE_AUTH_USE
5e60: 52 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  R               
5e70: 28 53 51 4c 49 54 45 5f 41 55 54 48 20 7c 20 28  (SQLITE_AUTH | (
5e80: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5e90: 51 4c 49 54 45 5f 4f 4b 5f 4c 4f 41 44 5f 50 45  QLITE_OK_LOAD_PE
5ea0: 52 4d 41 4e 45 4e 54 4c 59 20 20 20 20 20 28 53  RMANENTLY     (S
5eb0: 51 4c 49 54 45 5f 4f 4b 20 7c 20 28 31 3c 3c 38  QLITE_OK | (1<<8
5ec0: 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  ))../*.** CAPI3R
5ed0: 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69  EF: Flags For Fi
5ee0: 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f  le Open Operatio
5ef0: 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62  ns.**.** These b
5f00: 69 74 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e  it values are in
5f10: 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69  tended for use i
5f20: 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72  n the.** 3rd par
5f30: 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ameter to the [s
5f40: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5f50: 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a  ] interface and.
5f60: 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70 61  ** in the 4th pa
5f70: 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b  rameter to the [
5f80: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
5f90: 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23 64  n] method..*/.#d
5fa0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
5fb0: 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20  N_READONLY      
5fc0: 20 20 20 30 78 30 30 30 30 30 30 30 31 20 20 2f     0x00000001  /
5fd0: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
5fe0: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
5ff0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
6000: 4e 5f 52 45 41 44 57 52 49 54 45 20 20 20 20 20  N_READWRITE     
6010: 20 20 20 30 78 30 30 30 30 30 30 30 32 20 20 2f     0x00000002  /
6020: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
6030: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
6040: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
6050: 4e 5f 43 52 45 41 54 45 20 20 20 20 20 20 20 20  N_CREATE        
6060: 20 20 20 30 78 30 30 30 30 30 30 30 34 20 20 2f     0x00000004  /
6070: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
6080: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
6090: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
60a0: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20  N_DELETEONCLOSE 
60b0: 20 20 20 30 78 30 30 30 30 30 30 30 38 20 20 2f     0x00000008  /
60c0: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
60d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
60e0: 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20  N_EXCLUSIVE     
60f0: 20 20 20 30 78 30 30 30 30 30 30 31 30 20 20 2f     0x00000010  /
6100: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
6110: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
6120: 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20 20 20 20  N_AUTOPROXY     
6130: 20 20 20 30 78 30 30 30 30 30 30 32 30 20 20 2f     0x00000020  /
6140: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
6150: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
6160: 4e 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 20  N_URI           
6170: 20 20 20 30 78 30 30 30 30 30 30 34 30 20 20 2f     0x00000040  /
6180: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
6190: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
61a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
61b0: 4e 5f 4d 45 4d 4f 52 59 20 20 20 20 20 20 20 20  N_MEMORY        
61c0: 20 20 20 30 78 30 30 30 30 30 30 38 30 20 20 2f     0x00000080  /
61d0: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
61e0: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
61f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
6200: 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20  N_MAIN_DB       
6210: 20 20 20 30 78 30 30 30 30 30 31 30 30 20 20 2f     0x00000100  /
6220: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
6230: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
6240: 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20  N_TEMP_DB       
6250: 20 20 20 30 78 30 30 30 30 30 32 30 30 20 20 2f     0x00000200  /
6260: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
6270: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
6280: 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20  N_TRANSIENT_DB  
6290: 20 20 20 30 78 30 30 30 30 30 34 30 30 20 20 2f     0x00000400  /
62a0: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
62b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
62c0: 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20  N_MAIN_JOURNAL  
62d0: 20 20 20 30 78 30 30 30 30 30 38 30 30 20 20 2f     0x00000800  /
62e0: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
62f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
6300: 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20  N_TEMP_JOURNAL  
6310: 20 20 20 30 78 30 30 30 30 31 30 30 30 20 20 2f     0x00001000  /
6320: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
6330: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
6340: 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20  N_SUBJOURNAL    
6350: 20 20 20 30 78 30 30 30 30 32 30 30 30 20 20 2f     0x00002000  /
6360: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
6370: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
6380: 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c  N_MASTER_JOURNAL
6390: 20 20 20 30 78 30 30 30 30 34 30 30 30 20 20 2f     0x00004000  /
63a0: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
63b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
63c0: 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20 20 20  N_NOMUTEX       
63d0: 20 20 20 30 78 30 30 30 30 38 30 30 30 20 20 2f     0x00008000  /
63e0: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
63f0: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
6400: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
6410: 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20 20 20  N_FULLMUTEX     
6420: 20 20 20 30 78 30 30 30 31 30 30 30 30 20 20 2f     0x00010000  /
6430: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
6440: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
6450: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
6460: 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20  N_SHAREDCACHE   
6470: 20 20 20 30 78 30 30 30 32 30 30 30 30 20 20 2f     0x00020000  /
6480: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
6490: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
64a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
64b0: 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 20  N_PRIVATECACHE  
64c0: 20 20 20 30 78 30 30 30 34 30 30 30 30 20 20 2f     0x00040000  /
64d0: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
64e0: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
64f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
6500: 4e 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20  N_WAL           
6510: 20 20 20 30 78 30 30 30 38 30 30 30 30 20 20 2f     0x00080000  /
6520: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f  * VFS only */../
6530: 2a 20 52 65 73 65 72 76 65 64 3a 20 20 20 20 20  * Reserved:     
6540: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6550: 20 20 20 20 30 78 30 30 46 30 30 30 30 30 20 2a      0x00F00000 *
6560: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
6570: 46 3a 20 44 65 76 69 63 65 20 43 68 61 72 61 63  F: Device Charac
6580: 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20  teristics.**.** 
6590: 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61  The xDeviceChara
65a0: 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f  cteristics metho
65b0: 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  d of the [sqlite
65c0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  3_io_methods].**
65d0: 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73 20   object returns 
65e0: 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68  an integer which
65f0: 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66 20   is a vector of 
6600: 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c  these.** bit val
6610: 75 65 73 20 65 78 70 72 65 73 73 69 6e 67 20 49  ues expressing I
6620: 2f 4f 20 63 68 61 72 61 63 74 65 72 69 73 74 69  /O characteristi
6630: 63 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73  cs of the mass s
6640: 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65  torage.** device
6650: 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20   that holds the 
6660: 66 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73  file that the [s
6670: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
6680: 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e  s].** refers to.
6690: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  .**.** The SQLIT
66a0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70  E_IOCAP_ATOMIC p
66b0: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
66c0: 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66  at all writes of
66d0: 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65  .** any size are
66e0: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
66f0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6700: 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d  Cnnn values.** m
6710: 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20  ean that writes 
6720: 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61  of blocks that a
6730: 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20  re nnn bytes in 
6740: 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20  size and.** are 
6750: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64  aligned to an ad
6760: 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61  dress which is a
6770: 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70  n integer multip
6780: 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65  le of.** nnn are
6790: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
67a0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
67b0: 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61  APPEND value mea
67c0: 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20  ns.** that when 
67d0: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
67e0: 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20   to a file, the 
67f0: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
6800: 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74  .** first then t
6810: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66  he size of the f
6820: 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c  ile is extended,
6830: 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72   never the other
6840: 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20  .** way around. 
6850: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6860: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f  P_SEQUENTIAL pro
6870: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
6880: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
6890: 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69  is written to di
68a0: 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f  sk in the same o
68b0: 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a  rder as calls.**
68c0: 20 74 6f 20 78 57 72 69 74 65 28 29 2e 20 20 54   to xWrite().  T
68d0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
68e0: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
68f0: 49 54 45 20 70 72 6f 70 65 72 74 79 20 6d 65 61  ITE property mea
6900: 6e 73 20 74 68 61 74 0a 2a 2a 20 61 66 74 65 72  ns that.** after
6910: 20 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77 69 6e   reboot followin
6920: 67 20 61 20 63 72 61 73 68 20 6f 72 20 70 6f 77  g a crash or pow
6930: 65 72 20 6c 6f 73 73 2c 20 74 68 65 20 6f 6e 6c  er loss, the onl
6940: 79 20 62 79 74 65 73 20 69 6e 20 61 0a 2a 2a 20  y bytes in a.** 
6950: 66 69 6c 65 20 74 68 61 74 20 77 65 72 65 20 77  file that were w
6960: 72 69 74 74 65 6e 20 61 74 20 74 68 65 20 61 70  ritten at the ap
6970: 70 6c 69 63 61 74 69 6f 6e 20 6c 65 76 65 6c 20  plication level 
6980: 6d 69 67 68 74 20 68 61 76 65 20 63 68 61 6e 67  might have chang
6990: 65 64 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 61  ed.** and that a
69a0: 64 6a 61 63 65 6e 74 20 62 79 74 65 73 2c 20 65  djacent bytes, e
69b0: 76 65 6e 20 62 79 74 65 73 20 77 69 74 68 69 6e  ven bytes within
69c0: 20 74 68 65 20 73 61 6d 65 20 73 65 63 74 6f 72   the same sector
69d0: 20 61 72 65 0a 2a 2a 20 67 75 61 72 61 6e 74 65   are.** guarante
69e0: 65 64 20 74 6f 20 62 65 20 75 6e 63 68 61 6e 67  ed to be unchang
69f0: 65 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ed.  The SQLITE_
6a00: 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c  IOCAP_UNDELETABL
6a10: 45 5f 57 48 45 4e 5f 4f 50 45 4e 0a 2a 2a 20 66  E_WHEN_OPEN.** f
6a20: 6c 61 67 20 69 6e 64 69 63 61 74 65 73 20 74 68  lag indicates th
6a30: 61 74 20 61 20 66 69 6c 65 20 63 61 6e 6e 6f 74  at a file cannot
6a40: 20 62 65 20 64 65 6c 65 74 65 64 20 77 68 65 6e   be deleted when
6a50: 20 6f 70 65 6e 2e 20 20 54 68 65 0a 2a 2a 20 53   open.  The.** S
6a60: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55  QLITE_IOCAP_IMMU
6a70: 54 41 42 4c 45 20 66 6c 61 67 20 69 6e 64 69 63  TABLE flag indic
6a80: 61 74 65 73 20 74 68 61 74 20 74 68 65 20 66 69  ates that the fi
6a90: 6c 65 20 69 73 20 6f 6e 0a 2a 2a 20 72 65 61 64  le is on.** read
6aa0: 2d 6f 6e 6c 79 20 6d 65 64 69 61 20 61 6e 64 20  -only media and 
6ab0: 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65  cannot be change
6ac0: 64 20 65 76 65 6e 20 62 79 20 70 72 6f 63 65 73  d even by proces
6ad0: 73 65 73 20 77 69 74 68 0a 2a 2a 20 65 6c 65 76  ses with.** elev
6ae0: 61 74 65 64 20 70 72 69 76 69 6c 65 67 65 73 2e  ated privileges.
6af0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
6b00: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
6b10: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6b20: 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69  0x00000001.#defi
6b30: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6b40: 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20  ATOMIC512       
6b50: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
6b60: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
6b70: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20  _IOCAP_ATOMIC1K 
6b80: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6b90: 30 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65  00000004.#define
6ba0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6bb0: 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20 20 20  OMIC2K          
6bc0: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0a       0x00000008.
6bd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6be0: 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20  OCAP_ATOMIC4K   
6bf0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6c00: 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53  000010.#define S
6c10: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6c20: 49 43 38 4b 20 20 20 20 20 20 20 20 20 20 20 20  IC8K            
6c30: 20 20 20 30 78 30 30 30 30 30 30 32 30 0a 23 64     0x00000020.#d
6c40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6c50: 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20  AP_ATOMIC16K    
6c60: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6c70: 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0040.#define SQL
6c80: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6c90: 33 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  32K             
6ca0: 20 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66   0x00000080.#def
6cb0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6cc0: 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20  _ATOMIC64K      
6cd0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31          0x000001
6ce0: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
6cf0: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50  E_IOCAP_SAFE_APP
6d00: 45 4e 44 20 20 20 20 20 20 20 20 20 20 20 20 30  END            0
6d10: 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e  x00000200.#defin
6d20: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
6d30: 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20 20  EQUENTIAL       
6d40: 20 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30        0x00000400
6d50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6d60: 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c  IOCAP_UNDELETABL
6d70: 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78 30  E_WHEN_OPEN  0x0
6d80: 30 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20  0000800.#define 
6d90: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57  SQLITE_IOCAP_POW
6da0: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45  ERSAFE_OVERWRITE
6db0: 20 20 20 20 30 78 30 30 30 30 31 30 30 30 0a 23      0x00001000.#
6dc0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6dd0: 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 20 20  CAP_IMMUTABLE   
6de0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6df0: 30 32 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  02000../*.** CAP
6e00: 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b  I3REF: File Lock
6e10: 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a  ing Levels.**.**
6e20: 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65   SQLite uses one
6e30: 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 65   of these intege
6e40: 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20  r values as the 
6e50: 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65  second.** argume
6e60: 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d  nt to calls it m
6e70: 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63  akes to the xLoc
6e80: 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28  k() and xUnlock(
6e90: 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20  ) methods.** of 
6ea0: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  an [sqlite3_io_m
6eb0: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a  ethods] object..
6ec0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6ed0: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20  E_LOCK_NONE     
6ee0: 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53       0.#define S
6ef0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
6f00: 44 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69  D        1.#defi
6f10: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52  ne SQLITE_LOCK_R
6f20: 45 53 45 52 56 45 44 20 20 20 20 20 20 32 0a 23  ESERVED      2.#
6f30: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
6f40: 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20  CK_PENDING      
6f50: 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   3.#define SQLIT
6f60: 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45  E_LOCK_EXCLUSIVE
6f70: 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41       4../*.** CA
6f80: 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e  PI3REF: Synchron
6f90: 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61  ization Type Fla
6fa0: 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51  gs.**.** When SQ
6fb0: 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65  Lite invokes the
6fc0: 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20   xSync() method 
6fd0: 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65  of an.** [sqlite
6fe0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
6ff0: 6a 65 63 74 20 69 74 20 75 73 65 73 20 61 20 63  ject it uses a c
7000: 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a  ombination of.**
7010: 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76   these integer v
7020: 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63  alues as the sec
7030: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  ond argument..**
7040: 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c  .** When the SQL
7050: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c  ITE_SYNC_DATAONL
7060: 59 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20  Y flag is used, 
7070: 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  it means that th
7080: 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74  e.** sync operat
7090: 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74  ion only needs t
70a0: 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20  o flush data to 
70b0: 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49  mass storage.  I
70c0: 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  node.** informat
70d0: 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20  ion need not be 
70e0: 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68 65 20  flushed. If the 
70f0: 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20  lower four bits 
7100: 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65  of the flag.** e
7110: 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43  qual SQLITE_SYNC
7120: 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65  _NORMAL, that me
7130: 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61  ans to use norma
7140: 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74  l fsync() semant
7150: 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c  ics..** If the l
7160: 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 65  ower four bits e
7170: 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43  qual SQLITE_SYNC
7180: 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e  _FULL, that mean
7190: 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20  s.** to use Mac 
71a0: 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73  OS X style fulls
71b0: 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66  ync instead of f
71c0: 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f  sync()..**.** Do
71d0: 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74 68 65   not confuse the
71e0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52   SQLITE_SYNC_NOR
71f0: 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53  MAL and SQLITE_S
7200: 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a  YNC_FULL flags.*
7210: 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52 41 47  * with the [PRAG
7220: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d  MA synchronous]=
7230: 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47  NORMAL and [PRAG
7240: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d  MA synchronous]=
7250: 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73  FULL.** settings
7260: 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e  .  The [synchron
7270: 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65 74 65  ous pragma] dete
7280: 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c  rmines when call
7290: 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e  s to the.** xSyn
72a0: 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f 63 63  c VFS method occ
72b0: 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73 20 75  ur and applies u
72c0: 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20  niformly across 
72d0: 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a  all platforms..*
72e0: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e  * The SQLITE_SYN
72f0: 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c  C_NORMAL and SQL
7300: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c  ITE_SYNC_FULL fl
7310: 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20 68 6f  ags determine ho
7320: 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63 20 6f  w.** energetic o
7330: 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f  r rigorous or fo
7340: 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e 63 20  rceful the sync 
7350: 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20 61  operations are a
7360: 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20  nd.** only make 
7370: 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 20  a difference on 
7380: 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68 65 20  Mac OSX for the 
7390: 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65 20 63  default SQLite c
73a0: 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70  ode..** (Third-p
73b0: 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65 6d 65  arty VFS impleme
73c0: 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 61  ntations might a
73d0: 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64 69 73  lso make the dis
73e0: 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77  tinction.** betw
73f0: 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  een SQLITE_SYNC_
7400: 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54  NORMAL and SQLIT
7410: 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74  E_SYNC_FULL, but
7420: 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70   among the.** op
7430: 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 73 20  erating systems 
7440: 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f 72 74  natively support
7450: 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e  ed by SQLite, on
7460: 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61  ly Mac OSX.** ca
7470: 72 65 73 20 61 62 6f 75 74 20 74 68 65 20 64 69  res about the di
7480: 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64  fference.).*/.#d
7490: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e  efine SQLITE_SYN
74a0: 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20  C_NORMAL        
74b0: 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20  0x00002.#define 
74c0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
74d0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
74e0: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
74f0: 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20  _SYNC_DATAONLY  
7500: 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a      0x00010../*.
7510: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20  ** CAPI3REF: OS 
7520: 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46  Interface Open F
7530: 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a  ile Handle.**.**
7540: 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c   An [sqlite3_fil
7550: 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73  e] object repres
7560: 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c  ents an open fil
7570: 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71  e in the .** [sq
7580: 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53 20 69  lite3_vfs | OS i
7590: 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 5d 2e  nterface layer].
75a0: 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20    Individual OS 
75b0: 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70  interface.** imp
75c0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c  lementations wil
75d0: 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62  l.** want to sub
75e0: 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63  class this objec
75f0: 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61  t by appending a
7600: 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73  dditional fields
7610: 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77  .** for their ow
7620: 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74  n use.  The pMet
7630: 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61 20  hods entry is a 
7640: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
7650: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
7660: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61  hods] object tha
7670: 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64  t defines method
7680: 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67  s for performing
7690: 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f  .** I/O operatio
76a0: 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66  ns on the open f
76b0: 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ile..*/.typedef 
76c0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66  struct sqlite3_f
76d0: 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  ile sqlite3_file
76e0: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
76f0: 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20  _file {.  const 
7700: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
7710: 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68  o_methods *pMeth
7720: 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73  ods;  /* Methods
7730: 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c   for an open fil
7740: 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e */.};../*.** C
7750: 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65  API3REF: OS Inte
7760: 72 66 61 63 65 20 46 69 6c 65 20 56 69 72 74 75  rface File Virtu
7770: 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63  al Methods Objec
7780: 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69  t.**.** Every fi
7790: 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65  le opened by the
77a0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
77b0: 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70 75  pen] method popu
77c0: 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c  lates an.** [sql
77d0: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
77e0: 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d  t (or, more comm
77f0: 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73  only, a subclass
7800: 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
7810: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
7820: 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72  ) with a pointer
7830: 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
7840: 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a  of this object..
7850: 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64  ** This object d
7860: 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f  efines the metho
7870: 64 73 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f  ds used to perfo
7880: 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61  rm various opera
7890: 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74  tions.** against
78a0: 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72   the open file r
78b0: 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 74 68  epresented by th
78c0: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  e [sqlite3_file]
78d0: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49   object..**.** I
78e0: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  f the [sqlite3_v
78f0: 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64  fs.xOpen] method
7900: 20 73 65 74 73 20 74 68 65 20 73 71 6c 69 74 65   sets the sqlite
7910: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
7920: 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61  element .** to a
7930: 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65   non-NULL pointe
7940: 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69  r, then the sqli
7950: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78  te3_io_methods.x
7960: 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20  Close method.** 
7970: 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 65  may be invoked e
7980: 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71 6c 69  ven if the [sqli
7990: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 72  te3_vfs.xOpen] r
79a0: 65 70 6f 72 74 65 64 20 74 68 61 74 20 69 74 20  eported that it 
79b0: 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20  failed.  The.** 
79c0: 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 65 76  only way to prev
79d0: 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 78 43  ent a call to xC
79e0: 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  lose following a
79f0: 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74 65 33   failed [sqlite3
7a00: 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69  _vfs.xOpen].** i
7a10: 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  s for the [sqlit
7a20: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74 6f  e3_vfs.xOpen] to
7a30: 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33   set the sqlite3
7a40: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65  _file.pMethods e
7a50: 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c  lement.** to NUL
7a60: 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61  L..**.** The fla
7a70: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
7a80: 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20  Sync may be one 
7a90: 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f  of [SQLITE_SYNC_
7aa0: 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53  NORMAL] or.** [S
7ab0: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d  QLITE_SYNC_FULL]
7ac0: 2e 20 20 54 68 65 20 66 69 72 73 74 20 63 68 6f  .  The first cho
7ad0: 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61  ice is the norma
7ae0: 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68  l fsync()..** Th
7af0: 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20  e second choice 
7b00: 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73 74  is a Mac OS X st
7b10: 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54  yle fullsync.  T
7b20: 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f  he [SQLITE_SYNC_
7b30: 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61  DATAONLY].** fla
7b40: 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e  g may be ORed in
7b50: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61   to indicate tha
7b60: 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20  t only the data 
7b70: 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61  of the file.** a
7b80: 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65  nd not its inode
7b90: 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e   needs to be syn
7ba0: 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  ced..**.** The i
7bb0: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f  nteger values to
7bc0: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e   xLock() and xUn
7bd0: 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f  lock() are one o
7be0: 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  f.** <ul>.** <li
7bf0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e  > [SQLITE_LOCK_N
7c00: 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  ONE],.** <li> [S
7c10: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
7c20: 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  D],.** <li> [SQL
7c30: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45  ITE_LOCK_RESERVE
7c40: 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  D],.** <li> [SQL
7c50: 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47  ITE_LOCK_PENDING
7c60: 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  ], or.** <li> [S
7c70: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
7c80: 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  SIVE]..** </ul>.
7c90: 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65  ** xLock() incre
7ca0: 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78  ases the lock. x
7cb0: 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73  Unlock() decreas
7cc0: 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20  es the lock..** 
7cd0: 54 68 65 20 78 43 68 65 63 6b 52 65 73 65 72 76  The xCheckReserv
7ce0: 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20  edLock() method 
7cf0: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 61  checks whether a
7d00: 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ny database conn
7d10: 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65  ection,.** eithe
7d20: 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73  r in this proces
7d30: 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68  s or in some oth
7d40: 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68  er process, is h
7d50: 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56 45  olding a RESERVE
7d60: 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f  D,.** PENDING, o
7d70: 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b  r EXCLUSIVE lock
7d80: 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49   on the file.  I
7d90: 74 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a  t returns true.*
7da0: 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b  * if such a lock
7db0: 20 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73   exists and fals
7dc0: 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a  e otherwise..**.
7dd0: 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74  ** The xFileCont
7de0: 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20  rol() method is 
7df0: 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66  a generic interf
7e00: 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20  ace that allows 
7e10: 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d  custom.** VFS im
7e20: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f  plementations to
7e30: 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f   directly contro
7e40: 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75  l an open file u
7e50: 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  sing the.** [sql
7e60: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
7e70: 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20  l()] interface. 
7e80: 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22   The second "op"
7e90: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a   argument is an.
7ea0: 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64  ** integer opcod
7eb0: 65 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72  e.  The third ar
7ec0: 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65  gument is a gene
7ed0: 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65  ric pointer inte
7ee0: 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74  nded to.** point
7ef0: 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 65 20   to a structure 
7f00: 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e  that may contain
7f10: 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70   arguments or sp
7f20: 61 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a  ace in which to.
7f30: 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e 20  ** write return 
7f40: 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69  values.  Potenti
7f50: 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c  al uses for xFil
7f60: 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74  eControl() might
7f70: 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73   be.** functions
7f80: 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b   to enable block
7f90: 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74  ing locks with t
7fa0: 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e  imeouts, to chan
7fb0: 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e  ge the.** lockin
7fc0: 67 20 73 74 72 61 74 65 67 79 20 28 66 6f 72 20  g strategy (for 
7fd0: 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64  example to use d
7fe0: 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20  ot-file locks), 
7ff0: 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62  to inquire.** ab
8000: 6f 75 74 20 74 68 65 20 73 74 61 74 75 73 20 6f  out the status o
8010: 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20  f a lock, or to 
8020: 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b  break stale lock
8030: 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a  s.  The SQLite.*
8040: 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65 73 20  * core reserves 
8050: 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73  all opcodes less
8060: 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74   than 100 for it
8070: 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20  s own use..** A 
8080: 5b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70  [file control op
8090: 63 6f 64 65 73 20 7c 20 6c 69 73 74 20 6f 66 20  codes | list of 
80a0: 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68  opcodes] less th
80b0: 61 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c 61  an 100 is availa
80c0: 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74  ble..** Applicat
80d0: 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65  ions that define
80e0: 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43   a custom xFileC
80f0: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68  ontrol method sh
8100: 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73  ould use opcodes
8110: 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e  .** greater than
8120: 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f   100 to avoid co
8130: 6e 66 6c 69 63 74 73 2e 20 20 56 46 53 20 69 6d  nflicts.  VFS im
8140: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68  plementations sh
8150: 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  ould.** return [
8160: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d  SQLITE_NOTFOUND]
8170: 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72 6f   for file contro
8180: 6c 20 6f 70 63 6f 64 65 73 20 74 68 61 74 20 74  l opcodes that t
8190: 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65  hey do not.** re
81a0: 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54  cognize..**.** T
81b0: 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29  he xSectorSize()
81c0: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
81d0: 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20  the sector size 
81e0: 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65  of the.** device
81f0: 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20   that underlies 
8200: 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73  the file.  The s
8210: 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68  ector size is th
8220: 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69  e.** minimum wri
8230: 74 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70  te that can be p
8240: 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74  erformed without
8250: 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f   disturbing.** o
8260: 74 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68  ther bytes in th
8270: 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65  e file.  The xDe
8280: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
8290: 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20  ics().** method 
82a0: 72 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65  returns a bit ve
82b0: 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20  ctor describing 
82c0: 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65  behaviors of the
82d0: 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64  .** underlying d
82e0: 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  evice:.**.** <ul
82f0: 3e 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 5d 0a  E_IOCAP_ATOMIC].
8310: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8320: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d  IOCAP_ATOMIC512]
8330: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8340: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d  _IOCAP_ATOMIC1K]
8350: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8360: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d  _IOCAP_ATOMIC2K]
8370: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8380: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d  _IOCAP_ATOMIC4K]
8390: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
83a0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d  _IOCAP_ATOMIC8K]
83b0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
83c0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b  _IOCAP_ATOMIC16K
83d0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
83e0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32  E_IOCAP_ATOMIC32
83f0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
8400: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36  TE_IOCAP_ATOMIC6
8410: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  4K].** <li> [SQL
8420: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
8430: 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  PPEND].** <li> [
8440: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
8450: 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  UENTIAL].** <li>
8460: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55   [SQLITE_IOCAP_U
8470: 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f  NDELETABLE_WHEN_
8480: 4f 50 45 4e 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  OPEN].** <li> [S
8490: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45  QLITE_IOCAP_POWE
84a0: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d  RSAFE_OVERWRITE]
84b0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
84c0: 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45  _IOCAP_IMMUTABLE
84d0: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  ].** </ul>.**.**
84e0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
84f0: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74  P_ATOMIC propert
8500: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c  y means that all
8510: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e   writes of.** an
8520: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69  y size are atomi
8530: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
8540: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76  OCAP_ATOMICnnn v
8550: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68  alues.** mean th
8560: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f  at writes of blo
8570: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e  cks that are nnn
8580: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
8590: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65  nd.** are aligne
85a0: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20  d to an address 
85b0: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65  which is an inte
85c0: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a  ger multiple of.
85d0: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69  ** nnn are atomi
85e0: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
85f0: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
8600: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20   value means.** 
8610: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69  that when data i
8620: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20  s appended to a 
8630: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69  file, the data i
8640: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69  s appended.** fi
8650: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a  rst then the siz
8660: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73  e of the file is
8670: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72   extended, never
8680: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61   the other.** wa
8690: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53  y around.  The S
86a0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
86b0: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20  ENTIAL property 
86c0: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e  means that.** in
86d0: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69  formation is wri
86e0: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20  tten to disk in 
86f0: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61  the same order a
8700: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57  s calls.** to xW
8710: 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66  rite()..**.** If
8720: 20 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73   xRead() returns
8730: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
8740: 4f 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74  ORT_READ it must
8750: 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e   also fill.** in
8760: 20 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74   the unread port
8770: 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66  ions of the buff
8780: 65 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20  er with zeros.  
8790: 41 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61  A VFS that.** fa
87a0: 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c  ils to zero-fill
87b0: 20 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67   short reads mig
87c0: 68 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e  ht seem to work.
87d0: 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61    However,.** fa
87e0: 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69  ilure to zero-fi
87f0: 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77  ll short reads w
8800: 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c  ill eventually l
8810: 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61  ead to.** databa
8820: 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a  se corruption..*
8830: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
8840: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
8850: 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ods sqlite3_io_m
8860: 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
8870: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
8880: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  s {.  int iVersi
8890: 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f  on;.  int (*xClo
88a0: 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  se)(sqlite3_file
88b0: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61  *);.  int (*xRea
88c0: 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  d)(sqlite3_file*
88d0: 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d  , void*, int iAm
88e0: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
88f0: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28   iOfst);.  int (
8900: 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33  *xWrite)(sqlite3
8910: 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f  _file*, const vo
8920: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73  id*, int iAmt, s
8930: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
8940: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72  st);.  int (*xTr
8950: 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f  uncate)(sqlite3_
8960: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
8970: 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e  nt64 size);.  in
8980: 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74  t (*xSync)(sqlit
8990: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c  e3_file*, int fl
89a0: 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  ags);.  int (*xF
89b0: 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33  ileSize)(sqlite3
89c0: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
89d0: 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20  int64 *pSize);. 
89e0: 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71   int (*xLock)(sq
89f0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
8a00: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f  );.  int (*xUnlo
8a10: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
8a20: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
8a30: 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c  *xCheckReservedL
8a40: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
8a50: 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74  e*, int *pResOut
8a60: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65  );.  int (*xFile
8a70: 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33  Control)(sqlite3
8a80: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20  _file*, int op, 
8a90: 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69  void *pArg);.  i
8aa0: 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65  nt (*xSectorSize
8ab0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
8ac0: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63  ;.  int (*xDevic
8ad0: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
8ae0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
8af0: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
8b00: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
8b10: 6f 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a  or version 1 */.
8b20: 20 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29    int (*xShmMap)
8b30: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8b40: 69 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73  int iPg, int pgs
8b50: 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c  z, int, void vol
8b60: 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20  atile**);.  int 
8b70: 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69  (*xShmLock)(sqli
8b80: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f  te3_file*, int o
8b90: 66 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e  ffset, int n, in
8ba0: 74 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64  t flags);.  void
8bb0: 20 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28   (*xShmBarrier)(
8bc0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
8bd0: 20 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61    int (*xShmUnma
8be0: 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  p)(sqlite3_file*
8bf0: 2c 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67  , int deleteFlag
8c00: 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  );.  /* Methods 
8c10: 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20  above are valid 
8c20: 66 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f  for version 2 */
8c30: 0a 20 20 69 6e 74 20 28 2a 78 46 65 74 63 68 29  .  int (*xFetch)
8c40: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8c50: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f  sqlite3_int64 iO
8c60: 66 73 74 2c 20 69 6e 74 20 69 41 6d 74 2c 20 76  fst, int iAmt, v
8c70: 6f 69 64 20 2a 2a 70 70 29 3b 0a 20 20 69 6e 74  oid **pp);.  int
8c80: 20 28 2a 78 55 6e 66 65 74 63 68 29 28 73 71 6c   (*xUnfetch)(sql
8c90: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69  ite3_file*, sqli
8ca0: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c  te3_int64 iOfst,
8cb0: 20 76 6f 69 64 20 2a 70 29 3b 0a 20 20 2f 2a 20   void *p);.  /* 
8cc0: 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  Methods above ar
8cd0: 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73  e valid for vers
8ce0: 69 6f 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20 41 64  ion 3 */.  /* Ad
8cf0: 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73  ditional methods
8d00: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
8d10: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
8d20: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
8d30: 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64  PI3REF: Standard
8d40: 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70   File Control Op
8d50: 63 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  codes.** KEYWORD
8d60: 53 3a 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  S: {file control
8d70: 20 6f 70 63 6f 64 65 73 7d 20 7b 66 69 6c 65 20   opcodes} {file 
8d80: 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 7d 0a  control opcode}.
8d90: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
8da0: 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ger constants ar
8db0: 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68  e opcodes for th
8dc0: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  e xFileControl m
8dd0: 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20  ethod.** of the 
8de0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
8df0: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20  ods] object and 
8e00: 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33  for the [sqlite3
8e10: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
8e20: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  .** interface..*
8e30: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
8e40: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
8e50: 4c 4f 43 4b 53 54 41 54 45 5d 5d 0a 2a 2a 20 54  LOCKSTATE]].** T
8e60: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
8e70: 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f  _LOCKSTATE] opco
8e80: 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64  de is used for d
8e90: 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a  ebugging.  This.
8ea0: 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73  ** opcode causes
8eb0: 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   the xFileContro
8ec0: 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74  l method to writ
8ed0: 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74  e the current st
8ee0: 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f  ate of.** the lo
8ef0: 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49  ck (one of [SQLI
8f00: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b  TE_LOCK_NONE], [
8f10: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
8f20: 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ED],.** [SQLITE_
8f30: 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20  LOCK_RESERVED], 
8f40: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e  [SQLITE_LOCK_PEN
8f50: 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  DING], or [SQLIT
8f60: 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45  E_LOCK_EXCLUSIVE
8f70: 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e  ]).** into an in
8f80: 74 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70  teger that the p
8f90: 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  Arg argument poi
8fa0: 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70  nts to. This cap
8fb0: 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73  ability.** is us
8fc0: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
8fd0: 67 20 61 6e 64 20 69 73 20 6f 6e 6c 79 20 61 76  g and is only av
8fe0: 61 69 6c 61 62 6c 65 20 77 68 65 6e 20 74 68 65  ailable when the
8ff0: 20 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20   SQLITE_TEST.** 
9000: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
9010: 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  ion is used..**.
9020: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
9030: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d  FCNTL_SIZE_HINT]
9040: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
9050: 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54  _FCNTL_SIZE_HINT
9060: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
9070: 20 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67 69   by SQLite to gi
9080: 76 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61  ve the VFS.** la
9090: 79 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68 6f  yer a hint of ho
90a0: 77 20 6c 61 72 67 65 20 74 68 65 20 64 61 74 61  w large the data
90b0: 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 67  base file will g
90c0: 72 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e 67  row to be during
90d0: 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20   the.** current 
90e0: 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68  transaction.  Th
90f0: 69 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20 67  is hint is not g
9100: 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20  uaranteed to be 
9110: 61 63 63 75 72 61 74 65 20 62 75 74 20 69 74 0a  accurate but it.
9120: 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73  ** is often clos
9130: 65 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69  e.  The underlyi
9140: 6e 67 20 56 46 53 20 6d 69 67 68 74 20 63 68 6f  ng VFS might cho
9150: 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61  ose to prealloca
9160: 74 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66  te database.** f
9170: 69 6c 65 20 73 70 61 63 65 20 62 61 73 65 64 20  ile space based 
9180: 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e 20  on this hint in 
9190: 6f 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77 72  order to help wr
91a0: 69 74 65 73 20 74 6f 20 74 68 65 20 64 61 74 61  ites to the data
91b0: 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e  base.** file run
91c0: 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c   faster..**.** <
91d0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
91e0: 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a  L_CHUNK_SIZE]].*
91f0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
9200: 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20  NTL_CHUNK_SIZE] 
9210: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
9220: 6f 20 72 65 71 75 65 73 74 20 74 68 61 74 20 74  o request that t
9230: 68 65 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64  he VFS.** extend
9240: 73 20 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20  s and truncates 
9250: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
9260: 65 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61  e in chunks of a
9270: 20 73 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a   size specified.
9280: 2a 2a 20 62 79 20 74 68 65 20 75 73 65 72 2e 20  ** by the user. 
9290: 54 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  The fourth argum
92a0: 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ent to [sqlite3_
92b0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
92c0: 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74  should .** point
92d0: 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28   to an integer (
92e0: 74 79 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69  type int) contai
92f0: 6e 69 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75  ning the new chu
9300: 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a  nk-size to use.*
9310: 2a 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61  * for the nomina
9320: 74 65 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c  ted database. Al
9330: 6c 6f 63 61 74 69 6e 67 20 64 61 74 61 62 61 73  locating databas
9340: 65 20 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20  e file space in 
9350: 6c 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20  large.** chunks 
9360: 28 73 61 79 20 31 4d 42 20 61 74 20 61 20 74 69  (say 1MB at a ti
9370: 6d 65 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20  me), may reduce 
9380: 66 69 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67  file-system frag
9390: 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a  mentation and.**
93a0: 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d   improve perform
93b0: 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73  ance on some sys
93c0: 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  tems..**.** <li>
93d0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46  [[SQLITE_FCNTL_F
93e0: 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a  ILE_POINTER]].**
93f0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
9400: 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d  TL_FILE_POINTER]
9410: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
9420: 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e  to obtain a poin
9430: 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73  ter.** to the [s
9440: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
9450: 65 63 74 20 61 73 73 6f 63 69 61 74 65 64 20 77  ect associated w
9460: 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72  ith a particular
9470: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
9480: 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 61 6c  nection.  See al
9490: 73 6f 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  so [SQLITE_FCNTL
94a0: 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52  _JOURNAL_POINTER
94b0: 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  ]..**.** <li>[[S
94c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52  QLITE_FCNTL_JOUR
94d0: 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a  NAL_POINTER]].**
94e0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
94f0: 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54  TL_JOURNAL_POINT
9500: 45 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  ER] opcode is us
9510: 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70  ed to obtain a p
9520: 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ointer.** to the
9530: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
9540: 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65  object associate
9550: 64 20 77 69 74 68 20 74 68 65 20 6a 6f 75 72 6e  d with the journ
9560: 61 6c 20 66 69 6c 65 20 28 65 69 74 68 65 72 0a  al file (either.
9570: 2a 2a 20 74 68 65 20 5b 72 6f 6c 6c 62 61 63 6b  ** the [rollback
9580: 20 6a 6f 75 72 6e 61 6c 5d 20 6f 72 20 74 68 65   journal] or the
9590: 20 5b 77 72 69 74 65 2d 61 68 65 61 64 20 6c 6f   [write-ahead lo
95a0: 67 5d 29 20 66 6f 72 20 61 20 70 61 72 74 69 63  g]) for a partic
95b0: 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a  ular database.**
95c0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65   connection.  Se
95d0: 65 20 61 6c 73 6f 20 5b 53 51 4c 49 54 45 5f 46  e also [SQLITE_F
95e0: 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45  CNTL_FILE_POINTE
95f0: 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  R]..**.** <li>[[
9600: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e  SQLITE_FCNTL_SYN
9610: 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20 4e  C_OMITTED]].** N
9620: 6f 20 6c 6f 6e 67 65 72 20 69 6e 20 75 73 65 2e  o longer in use.
9630: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
9640: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 5d  ITE_FCNTL_SYNC]]
9650: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
9660: 46 43 4e 54 4c 5f 53 59 4e 43 5d 20 6f 70 63 6f  FCNTL_SYNC] opco
9670: 64 65 20 69 73 20 67 65 6e 65 72 61 74 65 64 20  de is generated 
9680: 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51  internally by SQ
9690: 4c 69 74 65 20 61 6e 64 0a 2a 2a 20 73 65 6e 74  Lite and.** sent
96a0: 20 74 6f 20 74 68 65 20 56 46 53 20 69 6d 6d 65   to the VFS imme
96b0: 64 69 61 74 65 6c 79 20 62 65 66 6f 72 65 20 74  diately before t
96c0: 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 20  he xSync method 
96d0: 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 0a  is invoked on a.
96e0: 2a 2a 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  ** database file
96f0: 20 64 65 73 63 72 69 70 74 6f 72 2e 20 4f 72 2c   descriptor. Or,
9700: 20 69 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65   if the xSync me
9710: 74 68 6f 64 20 69 73 20 6e 6f 74 20 69 6e 76 6f  thod is not invo
9720: 6b 65 64 20 0a 2a 2a 20 62 65 63 61 75 73 65 20  ked .** because 
9730: 74 68 65 20 75 73 65 72 20 68 61 73 20 63 6f 6e  the user has con
9740: 66 69 67 75 72 65 64 20 53 51 4c 69 74 65 20 77  figured SQLite w
9750: 69 74 68 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 20  ith .** [PRAGMA 
9760: 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50 52  synchronous | PR
9770: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
9780: 3d 4f 46 46 5d 20 69 74 20 69 73 20 69 6e 76 6f  =OFF] it is invo
9790: 6b 65 64 20 69 6e 20 70 6c 61 63 65 20 0a 2a 2a  ked in place .**
97a0: 20 6f 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65   of the xSync me
97b0: 74 68 6f 64 2e 20 49 6e 20 6d 6f 73 74 20 63 61  thod. In most ca
97c0: 73 65 73 2c 20 74 68 65 20 70 6f 69 6e 74 65 72  ses, the pointer
97d0: 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64   argument passed
97e0: 20 77 69 74 68 0a 2a 2a 20 74 68 69 73 20 66 69   with.** this fi
97f0: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 4e 55  le-control is NU
9800: 4c 4c 2e 20 48 6f 77 65 76 65 72 2c 20 69 66 20  LL. However, if 
9810: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
9820: 65 20 69 73 20 62 65 69 6e 67 20 73 79 6e 63 65  e is being synce
9830: 64 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20  d.** as part of 
9840: 61 20 6d 75 6c 74 69 2d 64 61 74 61 62 61 73 65  a multi-database
9850: 20 63 6f 6d 6d 69 74 2c 20 74 68 65 20 61 72 67   commit, the arg
9860: 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 20  ument points to 
9870: 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64  a nul-terminated
9880: 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61  .** string conta
9890: 69 6e 69 6e 67 20 74 68 65 20 74 72 61 6e 73 61  ining the transa
98a0: 63 74 69 6f 6e 73 20 6d 61 73 74 65 72 2d 6a 6f  ctions master-jo
98b0: 75 72 6e 61 6c 20 66 69 6c 65 20 6e 61 6d 65 2e  urnal file name.
98c0: 20 56 46 53 65 73 20 74 68 61 74 20 0a 2a 2a 20   VFSes that .** 
98d0: 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73  do not need this
98e0: 20 73 69 67 6e 61 6c 20 73 68 6f 75 6c 64 20 73   signal should s
98f0: 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74  ilently ignore t
9900: 68 69 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c  his opcode. Appl
9910: 69 63 61 74 69 6f 6e 73 20 0a 2a 2a 20 73 68 6f  ications .** sho
9920: 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 20 5b 73 71  uld not call [sq
9930: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
9940: 6f 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73 20  ol()] with this 
9950: 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20  opcode as doing 
9960: 73 6f 20 6d 61 79 20 0a 2a 2a 20 64 69 73 72 75  so may .** disru
9970: 70 74 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  pt the operation
9980: 20 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c 69   of the speciali
9990: 7a 65 64 20 56 46 53 65 73 20 74 68 61 74 20 64  zed VFSes that d
99a0: 6f 20 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a  o require it.  .
99b0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
99c0: 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f  TE_FCNTL_COMMIT_
99d0: 50 48 41 53 45 54 57 4f 5d 5d 0a 2a 2a 20 54 68  PHASETWO]].** Th
99e0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
99f0: 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d  COMMIT_PHASETWO]
9a00: 20 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72   opcode is gener
9a10: 61 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  ated internally 
9a20: 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64  by SQLite.** and
9a30: 20 73 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53   sent to the VFS
9a40: 20 61 66 74 65 72 20 61 20 74 72 61 6e 73 61 63   after a transac
9a50: 74 69 6f 6e 20 68 61 73 20 62 65 65 6e 20 63 6f  tion has been co
9a60: 6d 6d 69 74 74 65 64 20 69 6d 6d 65 64 69 61 74  mmitted immediat
9a70: 65 6c 79 0a 2a 2a 20 62 75 74 20 62 65 66 6f 72  ely.** but befor
9a80: 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  e the database i
9a90: 73 20 75 6e 6c 6f 63 6b 65 64 2e 20 56 46 53 65  s unlocked. VFSe
9aa0: 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 20 6e 65  s that do not ne
9ab0: 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c 0a 2a  ed this signal.*
9ac0: 2a 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c  * should silentl
9ad0: 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70  y ignore this op
9ae0: 63 6f 64 65 2e 20 41 70 70 6c 69 63 61 74 69 6f  code. Applicatio
9af0: 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61  ns should not ca
9b00: 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  ll.** [sqlite3_f
9b10: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77  ile_control()] w
9b20: 69 74 68 20 74 68 69 73 20 6f 70 63 6f 64 65 20  ith this opcode 
9b30: 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20  as doing so may 
9b40: 64 69 73 72 75 70 74 20 74 68 65 20 0a 2a 2a 20  disrupt the .** 
9b50: 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65  operation of the
9b60: 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53   specialized VFS
9b70: 65 73 20 74 68 61 74 20 64 6f 20 72 65 71 75 69  es that do requi
9b80: 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c  re it.  .**.** <
9b90: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
9ba0: 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59  L_WIN32_AV_RETRY
9bb0: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
9bc0: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41  TE_FCNTL_WIN32_A
9bd0: 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f 64 65 20  V_RETRY] opcode 
9be0: 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69  is used to confi
9bf0: 67 75 72 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a  gure automatic.*
9c00: 2a 20 72 65 74 72 79 20 63 6f 75 6e 74 73 20 61  * retry counts a
9c10: 6e 64 20 69 6e 74 65 72 76 61 6c 73 20 66 6f 72  nd intervals for
9c20: 20 63 65 72 74 61 69 6e 20 64 69 73 6b 20 49 2f   certain disk I/
9c30: 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 66 6f 72  O operations for
9c40: 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20   the.** windows 
9c50: 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74  [VFS] in order t
9c60: 6f 20 70 72 6f 76 69 64 65 20 72 6f 62 75 73 74  o provide robust
9c70: 6e 65 73 73 20 69 6e 20 74 68 65 20 70 72 65 73  ness in the pres
9c80: 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d  ence of.** anti-
9c90: 76 69 72 75 73 20 70 72 6f 67 72 61 6d 73 2e 20  virus programs. 
9ca0: 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65   By default, the
9cb0: 20 77 69 6e 64 6f 77 73 20 56 46 53 20 77 69 6c   windows VFS wil
9cc0: 6c 20 72 65 74 72 79 20 66 69 6c 65 20 72 65 61  l retry file rea
9cd0: 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72 69 74 65  d,.** file write
9ce0: 2c 20 61 6e 64 20 66 69 6c 65 20 64 65 6c 65 74  , and file delet
9cf0: 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 75 70 20  e operations up 
9d00: 74 6f 20 31 30 20 74 69 6d 65 73 2c 20 77 69 74  to 10 times, wit
9d10: 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20  h a delay.** of 
9d20: 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  25 milliseconds 
9d30: 62 65 66 6f 72 65 20 74 68 65 20 66 69 72 73 74  before the first
9d40: 20 72 65 74 72 79 20 61 6e 64 20 77 69 74 68 20   retry and with 
9d50: 74 68 65 20 64 65 6c 61 79 20 69 6e 63 72 65 61  the delay increa
9d60: 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64  sing.** by an ad
9d70: 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c  ditional 25 mill
9d80: 69 73 65 63 6f 6e 64 73 20 77 69 74 68 20 65 61  iseconds with ea
9d90: 63 68 20 73 75 62 73 65 71 75 65 6e 74 20 72 65  ch subsequent re
9da0: 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70  try.  This.** op
9db0: 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74 68 65 73  code allows thes
9dc0: 65 20 74 77 6f 20 76 61 6c 75 65 73 20 28 31 30  e two values (10
9dd0: 20 72 65 74 72 69 65 73 20 61 6e 64 20 32 35 20   retries and 25 
9de0: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
9df0: 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20  delay).** to be 
9e00: 61 64 6a 75 73 74 65 64 2e 20 20 54 68 65 20 76  adjusted.  The v
9e10: 61 6c 75 65 73 20 61 72 65 20 63 68 61 6e 67 65  alues are change
9e20: 64 20 66 6f 72 20 61 6c 6c 20 64 61 74 61 62 61  d for all databa
9e30: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a  se connections.*
9e40: 2a 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d  * within the sam
9e50: 65 20 70 72 6f 63 65 73 73 2e 20 20 54 68 65 20  e process.  The 
9e60: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
9e70: 69 6e 74 65 72 20 74 6f 20 61 6e 20 61 72 72 61  inter to an arra
9e80: 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65  y of two.** inte
9e90: 67 65 72 73 20 77 68 65 72 65 20 74 68 65 20 66  gers where the f
9ea0: 69 72 73 74 20 69 6e 74 65 67 65 72 20 69 73 20  irst integer is 
9eb0: 74 68 65 20 6e 65 77 20 72 65 74 72 79 20 63 6f  the new retry co
9ec0: 75 6e 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f  unt and the seco
9ed0: 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 69 73  nd.** integer is
9ee0: 20 74 68 65 20 64 65 6c 61 79 2e 20 20 49 66 20   the delay.  If 
9ef0: 65 69 74 68 65 72 20 69 6e 74 65 67 65 72 20 69  either integer i
9f00: 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
9f10: 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20   the setting.** 
9f20: 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 62  is not changed b
9f30: 75 74 20 69 6e 73 74 65 61 64 20 74 68 65 20 70  ut instead the p
9f40: 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68  rior value of th
9f50: 61 74 20 73 65 74 74 69 6e 67 20 69 73 20 77 72  at setting is wr
9f60: 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68  itten.** into th
9f70: 65 20 61 72 72 61 79 20 65 6e 74 72 79 2c 20 61  e array entry, a
9f80: 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63 75 72 72  llowing the curr
9f90: 65 6e 74 20 72 65 74 72 79 20 73 65 74 74 69 6e  ent retry settin
9fa0: 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e 74 65  gs to be.** inte
9fb0: 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65 20 7a  rrogated.  The z
9fc0: 44 62 4e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  DbName parameter
9fd0: 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a   is ignored..**.
9fe0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
9ff0: 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41  FCNTL_PERSIST_WA
a000: 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  L]].** ^The [SQL
a010: 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53  ITE_FCNTL_PERSIS
a020: 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20 69 73  T_WAL] opcode is
a030: 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20   used to set or 
a040: 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72  query the.** per
a050: 73 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c 20 57  sistent [WAL | W
a060: 72 69 74 65 20 41 68 65 61 64 20 4c 6f 67 5d 20  rite Ahead Log] 
a070: 73 65 74 74 69 6e 67 2e 20 20 42 79 20 64 65 66  setting.  By def
a080: 61 75 6c 74 2c 20 74 68 65 20 61 75 78 69 6c 69  ault, the auxili
a090: 61 72 79 0a 2a 2a 20 77 72 69 74 65 20 61 68 65  ary.** write ahe
a0a0: 61 64 20 6c 6f 67 20 61 6e 64 20 73 68 61 72 65  ad log and share
a0b0: 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 75  d memory files u
a0c0: 73 65 64 20 66 6f 72 20 74 72 61 6e 73 61 63 74  sed for transact
a0d0: 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61  ion control.** a
a0e0: 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  re automatically
a0f0: 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68   deleted when th
a100: 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65 63 74  e latest connect
a110: 69 6f 6e 20 74 6f 20 74 68 65 20 64 61 74 61 62  ion to the datab
a120: 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20 20  ase.** closes.  
a130: 53 65 74 74 69 6e 67 20 70 65 72 73 69 73 74 65  Setting persiste
a140: 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63 61 75 73  nt WAL mode caus
a150: 65 73 20 74 68 6f 73 65 20 66 69 6c 65 73 20 74  es those files t
a160: 6f 20 70 65 72 73 69 73 74 20 61 66 74 65 72 0a  o persist after.
a170: 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72 73 69  ** close.  Persi
a180: 73 74 69 6e 67 20 74 68 65 20 66 69 6c 65 73 20  sting the files 
a190: 69 73 20 75 73 65 66 75 6c 20 77 68 65 6e 20 6f  is useful when o
a1a0: 74 68 65 72 20 70 72 6f 63 65 73 73 65 73 20 74  ther processes t
a1b0: 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61  hat do not.** ha
a1c0: 76 65 20 77 72 69 74 65 20 70 65 72 6d 69 73 73  ve write permiss
a1d0: 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72 65 63  ion on the direc
a1e0: 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20  tory containing 
a1f0: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
a200: 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 65 61  e want.** to rea
a210: 64 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  d the database f
a220: 69 6c 65 2c 20 61 73 20 74 68 65 20 57 41 4c 20  ile, as the WAL 
a230: 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72  and shared memor
a240: 79 20 66 69 6c 65 73 20 6d 75 73 74 20 65 78 69  y files must exi
a250: 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 66  st.** in order f
a260: 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20  or the database 
a270: 74 6f 20 62 65 20 72 65 61 64 61 62 6c 65 2e 20  to be readable. 
a280: 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   The fourth para
a290: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c  meter to.** [sql
a2a0: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
a2b0: 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70  l()] for this op
a2c0: 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61  code should be a
a2d0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
a2e0: 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20  nteger..** That 
a2f0: 69 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f 20  integer is 0 to 
a300: 64 69 73 61 62 6c 65 20 70 65 72 73 69 73 74 65  disable persiste
a310: 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72 20 31  nt WAL mode or 1
a320: 20 74 6f 20 65 6e 61 62 6c 65 20 70 65 72 73 69   to enable persi
a330: 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64  stent.** WAL mod
a340: 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65 67  e.  If the integ
a350: 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69  er is -1, then i
a360: 74 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e  t is overwritten
a370: 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e   with the curren
a380: 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69 73 74  t.** WAL persist
a390: 65 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a  ence setting..**
a3a0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
a3b0: 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45  _FCNTL_POWERSAFE
a3c0: 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20  _OVERWRITE]].** 
a3d0: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
a3e0: 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  TL_POWERSAFE_OVE
a3f0: 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69  RWRITE] opcode i
a400: 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72  s used to set or
a410: 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65   query the.** pe
a420: 72 73 69 73 74 65 6e 74 20 22 70 6f 77 65 72 73  rsistent "powers
a430: 61 66 65 2d 6f 76 65 72 77 72 69 74 65 22 20 6f  afe-overwrite" o
a440: 72 20 22 50 53 4f 57 22 20 73 65 74 74 69 6e 67  r "PSOW" setting
a450: 2e 20 20 54 68 65 20 50 53 4f 57 20 73 65 74 74  .  The PSOW sett
a460: 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65  ing.** determine
a470: 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 49 4f  s the [SQLITE_IO
a480: 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  CAP_POWERSAFE_OV
a490: 45 52 57 52 49 54 45 5d 20 62 69 74 20 6f 66 20  ERWRITE] bit of 
a4a0: 74 68 65 0a 2a 2a 20 78 44 65 76 69 63 65 43 68  the.** xDeviceCh
a4b0: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65  aracteristics me
a4c0: 74 68 6f 64 73 2e 20 54 68 65 20 66 6f 75 72 74  thods. The fourt
a4d0: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  h parameter to.*
a4e0: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  * [sqlite3_file_
a4f0: 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74  control()] for t
a500: 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c  his opcode shoul
a510: 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74  d be a pointer t
a520: 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a  o an integer..**
a530: 20 54 68 61 74 20 69 6e 74 65 67 65 72 20 69 73   That integer is
a540: 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 7a 65   0 to disable ze
a550: 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 6f  ro-damage mode o
a560: 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 7a 65  r 1 to enable ze
a570: 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64  ro-damage.** mod
a580: 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65 67  e.  If the integ
a590: 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69  er is -1, then i
a5a0: 74 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e  t is overwritten
a5b0: 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e   with the curren
a5c0: 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61 67 65  t.** zero-damage
a5d0: 20 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e 0a 2a   mode setting..*
a5e0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
a5f0: 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54  E_FCNTL_OVERWRIT
a600: 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  E]].** ^The [SQL
a610: 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52  ITE_FCNTL_OVERWR
a620: 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 69  ITE] opcode is i
a630: 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65  nvoked by SQLite
a640: 20 61 66 74 65 72 20 6f 70 65 6e 69 6e 67 0a 2a   after opening.*
a650: 2a 20 61 20 77 72 69 74 65 20 74 72 61 6e 73 61  * a write transa
a660: 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63 61 74  ction to indicat
a670: 65 20 74 68 61 74 2c 20 75 6e 6c 65 73 73 20 69  e that, unless i
a680: 74 20 69 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b  t is rolled back
a690: 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72 65 61   for some.** rea
a6a0: 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72 65 20  son, the entire 
a6b0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69  database file wi
a6c0: 6c 6c 20 62 65 20 6f 76 65 72 77 72 69 74 74 65  ll be overwritte
a6d0: 6e 20 62 79 20 74 68 65 20 63 75 72 72 65 6e 74  n by the current
a6e0: 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e   .** transaction
a6f0: 2e 20 54 68 69 73 20 69 73 20 75 73 65 64 20 62  . This is used b
a700: 79 20 56 41 43 55 55 4d 20 6f 70 65 72 61 74 69  y VACUUM operati
a710: 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ons..**.** <li>[
a720: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46  [SQLITE_FCNTL_VF
a730: 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20  SNAME]].** ^The 
a740: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46  [SQLITE_FCNTL_VF
a750: 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20 63 61  SNAME] opcode ca
a760: 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74  n be used to obt
a770: 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66  ain the names of
a780: 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73 5d 20  .** all [VFSes] 
a790: 69 6e 20 74 68 65 20 56 46 53 20 73 74 61 63 6b  in the VFS stack
a7a0: 2e 20 20 54 68 65 20 6e 61 6d 65 73 20 61 72 65  .  The names are
a7b0: 20 6f 66 20 61 6c 6c 20 56 46 53 20 73 68 69 6d   of all VFS shim
a7c0: 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 69 6e  s and the.** fin
a7d0: 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20  al bottom-level 
a7e0: 56 46 53 20 61 72 65 20 77 72 69 74 74 65 6e 20  VFS are written 
a7f0: 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61  into memory obta
a800: 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73  ined from .** [s
a810: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
a820: 20 61 6e 64 20 74 68 65 20 72 65 73 75 6c 74 20   and the result 
a830: 69 73 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65  is stored in the
a840: 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65 0a   char* variable.
a850: 2a 2a 20 74 68 61 74 20 74 68 65 20 66 6f 75 72  ** that the four
a860: 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  th parameter of 
a870: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
a880: 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74 73 20  ntrol()] points 
a890: 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 65  to..** The calle
a8a0: 72 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  r is responsible
a8b0: 20 66 6f 72 20 66 72 65 65 69 6e 67 20 74 68 65   for freeing the
a8c0: 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64 6f 6e   memory when don
a8d0: 65 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a 20 61  e.  As with.** a
a8e0: 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20  ll file-control 
a8f0: 61 63 74 69 6f 6e 73 2c 20 74 68 65 72 65 20 69  actions, there i
a900: 73 20 6e 6f 20 67 75 61 72 61 6e 74 65 65 20 74  s no guarantee t
a910: 68 61 74 20 74 68 69 73 20 77 69 6c 6c 20 61 63  hat this will ac
a920: 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79  tually.** do any
a930: 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72 73 20  thing.  Callers 
a940: 73 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c 69 7a  should initializ
a950: 65 20 74 68 65 20 63 68 61 72 2a 20 76 61 72 69  e the char* vari
a960: 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a  able to a NULL.*
a970: 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20 63 61 73  * pointer in cas
a980: 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74  e this file-cont
a990: 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65  rol is not imple
a9a0: 6d 65 6e 74 65 64 2e 20 20 54 68 69 73 20 66 69  mented.  This fi
a9b0: 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73  le-control.** is
a9c0: 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 64 69   intended for di
a9d0: 61 67 6e 6f 73 74 69 63 20 75 73 65 20 6f 6e 6c  agnostic use onl
a9e0: 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  y..**.** <li>[[S
a9f0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f  QLITE_FCNTL_VFS_
aa00: 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 5e 54 68  POINTER]].** ^Th
aa10: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
aa20: 56 46 53 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63  VFS_POINTER] opc
aa30: 6f 64 65 20 66 69 6e 64 73 20 61 20 70 6f 69 6e  ode finds a poin
aa40: 74 65 72 20 74 6f 20 74 68 65 20 74 6f 70 2d 6c  ter to the top-l
aa50: 65 76 65 6c 0a 2a 2a 20 5b 56 46 53 65 73 5d 20  evel.** [VFSes] 
aa60: 63 75 72 72 65 6e 74 6c 79 20 69 6e 20 75 73 65  currently in use
aa70: 2e 20 20 5e 28 54 68 65 20 61 72 67 75 6d 65 6e  .  ^(The argumen
aa80: 74 20 58 20 69 6e 0a 2a 2a 20 73 71 6c 69 74 65  t X in.** sqlite
aa90: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 64  3_file_control(d
aaa0: 62 2c 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56  b,SQLITE_FCNTL_V
aab0: 46 53 5f 50 4f 49 4e 54 45 52 2c 58 29 20 6d 75  FS_POINTER,X) mu
aac0: 73 74 20 62 65 0a 2a 2a 20 6f 66 20 74 79 70 65  st be.** of type
aad0: 20 22 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20   "[sqlite3_vfs] 
aae0: 2a 2a 22 2e 20 20 54 68 69 73 20 6f 70 63 6f 64  **".  This opcod
aaf0: 65 73 20 77 69 6c 6c 20 73 65 74 20 2a 58 0a 2a  es will set *X.*
ab00: 2a 20 74 6f 20 61 20 70 6f 69 6e 74 65 72 20 74  * to a pointer t
ab10: 6f 20 74 68 65 20 74 6f 70 2d 6c 65 76 65 6c 20  o the top-level 
ab20: 56 46 53 2e 29 5e 0a 2a 2a 20 5e 57 68 65 6e 20  VFS.)^.** ^When 
ab30: 74 68 65 72 65 20 61 72 65 20 6d 75 6c 74 69 70  there are multip
ab40: 6c 65 20 56 46 53 20 73 68 69 6d 73 20 69 6e 20  le VFS shims in 
ab50: 74 68 65 20 73 74 61 63 6b 2c 20 74 68 69 73 20  the stack, this 
ab60: 6f 70 63 6f 64 65 20 66 69 6e 64 73 20 74 68 65  opcode finds the
ab70: 0a 2a 2a 20 75 70 70 65 72 2d 6d 6f 73 74 20 73  .** upper-most s
ab80: 68 69 6d 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20  him only..**.** 
ab90: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
aba0: 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e  TL_PRAGMA]].** ^
abb0: 57 68 65 6e 65 76 65 72 20 61 20 5b 50 52 41 47  Whenever a [PRAG
abc0: 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73  MA] statement is
abd0: 20 70 61 72 73 65 64 2c 20 61 6e 20 5b 53 51 4c   parsed, an [SQL
abe0: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
abf0: 5d 20 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72  ] .** file contr
ac00: 6f 6c 20 69 73 20 73 65 6e 74 20 74 6f 20 74 68  ol is sent to th
ac10: 65 20 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f  e open [sqlite3_
ac20: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 63 6f 72  file] object cor
ac30: 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f  responding.** to
ac40: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
ac50: 6c 65 20 74 6f 20 77 68 69 63 68 20 74 68 65 20  le to which the 
ac60: 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74  pragma statement
ac70: 20 72 65 66 65 72 73 2e 20 5e 54 68 65 20 61 72   refers. ^The ar
ac80: 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65  gument.** to the
ac90: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
aca0: 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74  RAGMA] file cont
acb0: 72 6f 6c 20 69 73 20 61 6e 20 61 72 72 61 79 20  rol is an array 
acc0: 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74  of.** pointers t
acd0: 6f 20 73 74 72 69 6e 67 73 20 28 63 68 61 72 2a  o strings (char*
ace0: 2a 29 20 69 6e 20 77 68 69 63 68 20 74 68 65 20  *) in which the 
acf0: 73 65 63 6f 6e 64 20 65 6c 65 6d 65 6e 74 20 6f  second element o
ad00: 66 20 74 68 65 20 61 72 72 61 79 0a 2a 2a 20 69  f the array.** i
ad10: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
ad20: 65 20 70 72 61 67 6d 61 20 61 6e 64 20 74 68 65  e pragma and the
ad30: 20 74 68 69 72 64 20 65 6c 65 6d 65 6e 74 20 69   third element i
ad40: 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74  s the argument t
ad50: 6f 20 74 68 65 0a 2a 2a 20 70 72 61 67 6d 61 20  o the.** pragma 
ad60: 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 70  or NULL if the p
ad70: 72 61 67 6d 61 20 68 61 73 20 6e 6f 20 61 72 67  ragma has no arg
ad80: 75 6d 65 6e 74 2e 20 20 5e 54 68 65 20 68 61 6e  ument.  ^The han
ad90: 64 6c 65 72 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b  dler for an.** [
ada0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
adb0: 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  GMA] file contro
adc0: 6c 20 63 61 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79  l can optionally
add0: 20 6d 61 6b 65 20 74 68 65 20 66 69 72 73 74 20   make the first 
ade0: 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20 74 68  element.** of th
adf0: 65 20 63 68 61 72 2a 2a 20 61 72 67 75 6d 65 6e  e char** argumen
ae00: 74 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72  t point to a str
ae10: 69 6e 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ing obtained fro
ae20: 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  m [sqlite3_mprin
ae30: 74 66 28 29 5d 0a 2a 2a 20 6f 72 20 74 68 65 20  tf()].** or the 
ae40: 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 64 20 74  equivalent and t
ae50: 68 61 74 20 73 74 72 69 6e 67 20 77 69 6c 6c 20  hat string will 
ae60: 62 65 63 6f 6d 65 20 74 68 65 20 72 65 73 75 6c  become the resul
ae70: 74 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20  t of the pragma 
ae80: 6f 72 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20  or.** the error 
ae90: 6d 65 73 73 61 67 65 20 69 66 20 74 68 65 20 70  message if the p
aea0: 72 61 67 6d 61 20 66 61 69 6c 73 2e 20 5e 49 66  ragma fails. ^If
aeb0: 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
aec0: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69  FCNTL_PRAGMA] fi
aed0: 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72  le control retur
aee0: 6e 73 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  ns [SQLITE_NOTFO
aef0: 55 4e 44 5d 2c 20 74 68 65 6e 20 6e 6f 72 6d 61  UND], then norma
af00: 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d 20 70  l .** [PRAGMA] p
af10: 72 6f 63 65 73 73 69 6e 67 20 63 6f 6e 74 69 6e  rocessing contin
af20: 75 65 73 2e 20 20 5e 49 66 20 74 68 65 20 5b 53  ues.  ^If the [S
af30: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
af40: 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74  MA].** file cont
af50: 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  rol returns [SQL
af60: 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20 74 68  ITE_OK], then th
af70: 65 20 70 61 72 73 65 72 20 61 73 73 75 6d 65 73  e parser assumes
af80: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 56 46 53   that the.** VFS
af90: 20 68 61 73 20 68 61 6e 64 6c 65 64 20 74 68 65   has handled the
afa0: 20 50 52 41 47 4d 41 20 69 74 73 65 6c 66 20 61   PRAGMA itself a
afb0: 6e 64 20 74 68 65 20 70 61 72 73 65 72 20 67 65  nd the parser ge
afc0: 6e 65 72 61 74 65 73 20 61 20 6e 6f 2d 6f 70 0a  nerates a no-op.
afd0: 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ** prepared stat
afe0: 65 6d 65 6e 74 20 69 66 20 72 65 73 75 6c 74 20  ement if result 
aff0: 73 74 72 69 6e 67 20 69 73 20 4e 55 4c 4c 2c 20  string is NULL, 
b000: 6f 72 20 74 68 61 74 20 72 65 74 75 72 6e 73 20  or that returns 
b010: 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65  a copy.** of the
b020: 20 72 65 73 75 6c 74 20 73 74 72 69 6e 67 20 69   result string i
b030: 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 20  f the string is 
b040: 6e 6f 6e 2d 4e 55 4c 4c 2e 0a 2a 2a 20 5e 49 66  non-NULL..** ^If
b050: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   the [SQLITE_FCN
b060: 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20  TL_PRAGMA] file 
b070: 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 0a  control returns.
b080: 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74 20 63 6f  ** any result co
b090: 64 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  de other than [S
b0a0: 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53 51  QLITE_OK] or [SQ
b0b0: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20  LITE_NOTFOUND], 
b0c0: 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 68  that means.** th
b0d0: 61 74 20 74 68 65 20 56 46 53 20 65 6e 63 6f 75  at the VFS encou
b0e0: 6e 74 65 72 65 64 20 61 6e 20 65 72 72 6f 72 20  ntered an error 
b0f0: 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e 67 20 74  while handling t
b100: 68 65 20 5b 50 52 41 47 4d 41 5d 20 61 6e 64 20  he [PRAGMA] and 
b110: 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74 69  the.** compilati
b120: 6f 6e 20 6f 66 20 74 68 65 20 50 52 41 47 4d 41  on of the PRAGMA
b130: 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e 20 65   fails with an e
b140: 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b 53 51 4c  rror.  ^The [SQL
b150: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
b160: 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f  ].** file contro
b170: 6c 20 6f 63 63 75 72 73 20 61 74 20 74 68 65 20  l occurs at the 
b180: 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 70 72 61  beginning of pra
b190: 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  gma statement an
b1a0: 61 6c 79 73 69 73 20 61 6e 64 20 73 6f 0a 2a 2a  alysis and so.**
b1b0: 20 69 74 20 69 73 20 61 62 6c 65 20 74 6f 20 6f   it is able to o
b1c0: 76 65 72 72 69 64 65 20 62 75 69 6c 74 2d 69 6e  verride built-in
b1d0: 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d   [PRAGMA] statem
b1e0: 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ents..**.** <li>
b1f0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42  [[SQLITE_FCNTL_B
b200: 55 53 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a 2a 20  USYHANDLER]].** 
b210: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
b220: 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 0a  TL_BUSYHANDLER].
b230: 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20  ** file-control 
b240: 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 62  may be invoked b
b250: 79 20 53 51 4c 69 74 65 20 6f 6e 20 74 68 65 20  y SQLite on the 
b260: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 68 61  database file ha
b270: 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c 79 20  ndle.** shortly 
b280: 61 66 74 65 72 20 69 74 20 69 73 20 6f 70 65 6e  after it is open
b290: 65 64 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70  ed in order to p
b2a0: 72 6f 76 69 64 65 20 61 20 63 75 73 74 6f 6d 20  rovide a custom 
b2b0: 56 46 53 20 77 69 74 68 20 61 63 63 65 73 73 0a  VFS with access.
b2c0: 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6e 6e 65 63  ** to the connec
b2d0: 74 69 6f 6e 73 20 62 75 73 79 2d 68 61 6e 64 6c  tions busy-handl
b2e0: 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 54 68 65  er callback. The
b2f0: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 66 20   argument is of 
b300: 74 79 70 65 20 28 76 6f 69 64 20 2a 2a 29 0a 2a  type (void **).*
b310: 2a 20 2d 20 61 6e 20 61 72 72 61 79 20 6f 66 20  * - an array of 
b320: 74 77 6f 20 28 76 6f 69 64 20 2a 29 20 76 61 6c  two (void *) val
b330: 75 65 73 2e 20 54 68 65 20 66 69 72 73 74 20 28  ues. The first (
b340: 76 6f 69 64 20 2a 29 20 61 63 74 75 61 6c 6c 79  void *) actually
b350: 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 61 20   points.** to a 
b360: 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65  function of type
b370: 20 28 69 6e 74 20 28 2a 29 28 76 6f 69 64 20 2a   (int (*)(void *
b380: 29 29 2e 20 49 6e 20 6f 72 64 65 72 20 74 6f 20  )). In order to 
b390: 69 6e 76 6f 6b 65 20 74 68 65 20 63 6f 6e 6e 65  invoke the conne
b3a0: 63 74 69 6f 6e 73 0a 2a 2a 20 62 75 73 79 2d 68  ctions.** busy-h
b3b0: 61 6e 64 6c 65 72 2c 20 74 68 69 73 20 66 75 6e  andler, this fun
b3c0: 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20  ction should be 
b3d0: 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 68 65  invoked with the
b3e0: 20 73 65 63 6f 6e 64 20 28 76 6f 69 64 20 2a 29   second (void *)
b3f0: 20 69 6e 0a 2a 2a 20 74 68 65 20 61 72 72 61 79   in.** the array
b400: 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 61 72 67   as the only arg
b410: 75 6d 65 6e 74 2e 20 49 66 20 69 74 20 72 65 74  ument. If it ret
b420: 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
b430: 68 65 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f  hen the operatio
b440: 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72  n.** should be r
b450: 65 74 72 69 65 64 2e 20 49 66 20 69 74 20 72 65  etried. If it re
b460: 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20  turns zero, the 
b470: 63 75 73 74 6f 6d 20 56 46 53 20 73 68 6f 75 6c  custom VFS shoul
b480: 64 20 61 62 61 6e 64 6f 6e 20 74 68 65 0a 2a 2a  d abandon the.**
b490: 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69   current operati
b4a0: 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  on..**.** <li>[[
b4b0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d  SQLITE_FCNTL_TEM
b4c0: 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e  PFILENAME]].** ^
b4d0: 41 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20  Application can 
b4e0: 69 6e 76 6f 6b 65 20 74 68 65 20 5b 53 51 4c 49  invoke the [SQLI
b4f0: 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c  TE_FCNTL_TEMPFIL
b500: 45 4e 41 4d 45 5d 20 66 69 6c 65 2d 63 6f 6e 74  ENAME] file-cont
b510: 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76 65 20 53  rol.** to have S
b520: 51 4c 69 74 65 20 67 65 6e 65 72 61 74 65 20 61  QLite generate a
b530: 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69  .** temporary fi
b540: 6c 65 6e 61 6d 65 20 75 73 69 6e 67 20 74 68 65  lename using the
b550: 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20   same algorithm 
b560: 74 68 61 74 20 69 73 20 66 6f 6c 6c 6f 77 65 64  that is followed
b570: 20 74 6f 20 67 65 6e 65 72 61 74 65 0a 2a 2a 20   to generate.** 
b580: 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61  temporary filena
b590: 6d 65 73 20 66 6f 72 20 54 45 4d 50 20 74 61 62  mes for TEMP tab
b5a0: 6c 65 73 20 61 6e 64 20 6f 74 68 65 72 20 69 6e  les and other in
b5b0: 74 65 72 6e 61 6c 20 75 73 65 73 2e 20 20 54 68  ternal uses.  Th
b5c0: 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68  e.** argument sh
b5d0: 6f 75 6c 64 20 62 65 20 61 20 63 68 61 72 2a 2a  ould be a char**
b5e0: 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65 20 66   which will be f
b5f0: 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 66  illed with the f
b600: 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72 69 74 74  ilename.** writt
b610: 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  en into memory o
b620: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
b630: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
b640: 20 20 54 68 65 20 63 61 6c 6c 65 72 20 73 68 6f    The caller sho
b650: 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20 5b 73  uld.** invoke [s
b660: 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f  qlite3_free()] o
b670: 6e 20 74 68 65 20 72 65 73 75 6c 74 20 74 6f 20  n the result to 
b680: 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20 6c  avoid a memory l
b690: 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  eak..**.** <li>[
b6a0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d  [SQLITE_FCNTL_MM
b6b0: 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65  AP_SIZE]].** The
b6c0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d   [SQLITE_FCNTL_M
b6d0: 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63  MAP_SIZE] file c
b6e0: 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20 74  ontrol is used t
b6f0: 6f 20 71 75 65 72 79 20 6f 72 20 73 65 74 20 74  o query or set t
b700: 68 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20 6e 75  he.** maximum nu
b710: 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 74 68  mber of bytes th
b720: 61 74 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20  at will be used 
b730: 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61 70 70 65  for memory-mappe
b740: 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20 61 72  d I/O..** The ar
b750: 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
b760: 74 65 72 20 74 6f 20 61 20 76 61 6c 75 65 20 6f  ter to a value o
b770: 66 20 74 79 70 65 20 73 71 6c 69 74 65 33 5f 69  f type sqlite3_i
b780: 6e 74 36 34 20 74 68 61 74 0a 2a 2a 20 69 73 20  nt64 that.** is 
b790: 61 6e 20 61 64 76 69 73 6f 72 79 20 6d 61 78 69  an advisory maxi
b7a0: 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  mum number of by
b7b0: 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 20  tes in the file 
b7c0: 74 6f 20 6d 65 6d 6f 72 79 20 6d 61 70 2e 20 20  to memory map.  
b7d0: 54 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69  The.** pointer i
b7e0: 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69  s overwritten wi
b7f0: 74 68 20 74 68 65 20 6f 6c 64 20 76 61 6c 75 65  th the old value
b800: 2e 20 20 54 68 65 20 6c 69 6d 69 74 20 69 73 20  .  The limit is 
b810: 6e 6f 74 20 63 68 61 6e 67 65 64 20 69 66 0a 2a  not changed if.*
b820: 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 72 69 67  * the value orig
b830: 69 6e 61 6c 6c 79 20 70 6f 69 6e 74 65 64 20 74  inally pointed t
b840: 6f 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 61  o is negative, a
b850: 6e 64 20 73 6f 20 74 68 65 20 63 75 72 72 65 6e  nd so the curren
b860: 74 20 6c 69 6d 69 74 20 0a 2a 2a 20 63 61 6e 20  t limit .** can 
b870: 62 65 20 71 75 65 72 69 65 64 20 62 79 20 70 61  be queried by pa
b880: 73 73 69 6e 67 20 69 6e 20 61 20 70 6f 69 6e 74  ssing in a point
b890: 65 72 20 74 6f 20 61 20 6e 65 67 61 74 69 76 65  er to a negative
b8a0: 20 6e 75 6d 62 65 72 2e 20 20 54 68 69 73 0a 2a   number.  This.*
b8b0: 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69  * file-control i
b8c0: 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c  s used internall
b8d0: 79 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b  y to implement [
b8e0: 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65  PRAGMA mmap_size
b8f0: 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  ]..**.** <li>[[S
b900: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43  QLITE_FCNTL_TRAC
b910: 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  E]].** The [SQLI
b920: 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20  TE_FCNTL_TRACE] 
b930: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 70 72 6f  file control pro
b940: 76 69 64 65 73 20 61 64 76 69 73 6f 72 79 20 69  vides advisory i
b950: 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 74 6f  nformation.** to
b960: 20 74 68 65 20 56 46 53 20 61 62 6f 75 74 20 77   the VFS about w
b970: 68 61 74 20 74 68 65 20 68 69 67 68 65 72 20 6c  hat the higher l
b980: 61 79 65 72 73 20 6f 66 20 74 68 65 20 53 51 4c  ayers of the SQL
b990: 69 74 65 20 73 74 61 63 6b 20 61 72 65 20 64 6f  ite stack are do
b9a0: 69 6e 67 2e 0a 2a 2a 20 54 68 69 73 20 66 69 6c  ing..** This fil
b9b0: 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65  e control is use
b9c0: 64 20 62 79 20 73 6f 6d 65 20 56 46 53 20 61 63  d by some VFS ac
b9d0: 74 69 76 69 74 79 20 74 72 61 63 69 6e 67 20 5b  tivity tracing [
b9e0: 73 68 69 6d 73 5d 2e 0a 2a 2a 20 54 68 65 20 61  shims]..** The a
b9f0: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 7a 65 72  rgument is a zer
ba00: 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
ba10: 69 6e 67 2e 20 20 48 69 67 68 65 72 20 6c 61 79  ing.  Higher lay
ba20: 65 72 73 20 69 6e 20 74 68 65 0a 2a 2a 20 53 51  ers in the.** SQ
ba30: 4c 69 74 65 20 73 74 61 63 6b 20 6d 61 79 20 67  Lite stack may g
ba40: 65 6e 65 72 61 74 65 20 69 6e 73 74 61 6e 63 65  enerate instance
ba50: 73 20 6f 66 20 74 68 69 73 20 66 69 6c 65 20 63  s of this file c
ba60: 6f 6e 74 72 6f 6c 20 69 66 0a 2a 2a 20 74 68 65  ontrol if.** the
ba70: 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 46 43 4e   [SQLITE_USE_FCN
ba80: 54 4c 5f 54 52 41 43 45 5d 20 63 6f 6d 70 69 6c  TL_TRACE] compil
ba90: 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73  e-time option is
baa0: 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20   enabled..**.** 
bab0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
bac0: 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 5d 0a 2a  TL_HAS_MOVED]].*
bad0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
bae0: 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 20 66  NTL_HAS_MOVED] f
baf0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 6e 74 65  ile control inte
bb00: 72 70 72 65 74 73 20 69 74 73 20 61 72 67 75 6d  rprets its argum
bb10: 65 6e 74 20 61 73 20 61 0a 2a 2a 20 70 6f 69 6e  ent as a.** poin
bb20: 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
bb30: 72 20 61 6e 64 20 69 74 20 77 72 69 74 65 73 20  r and it writes 
bb40: 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 74 6f 20 74  a boolean into t
bb50: 68 61 74 20 69 6e 74 65 67 65 72 20 64 65 70 65  hat integer depe
bb60: 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20 77 68 65 74  nding.** on whet
bb70: 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 66  her or not the f
bb80: 69 6c 65 20 68 61 73 20 62 65 65 6e 20 72 65 6e  ile has been ren
bb90: 61 6d 65 64 2c 20 6d 6f 76 65 64 2c 20 6f 72 20  amed, moved, or 
bba0: 64 65 6c 65 74 65 64 20 73 69 6e 63 65 20 69 74  deleted since it
bbb0: 0a 2a 2a 20 77 61 73 20 66 69 72 73 74 20 6f 70  .** was first op
bbc0: 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ened..**.** <li>
bbd0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57  [[SQLITE_FCNTL_W
bbe0: 49 4e 33 32 5f 47 45 54 5f 48 41 4e 44 4c 45 5d  IN32_GET_HANDLE]
bbf0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
bc00: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54  _FCNTL_WIN32_GET
bc10: 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 65 20  _HANDLE] opcode 
bc20: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
bc30: 62 74 61 69 6e 20 74 68 65 0a 2a 2a 20 75 6e 64  btain the.** und
bc40: 65 72 6c 79 69 6e 67 20 6e 61 74 69 76 65 20 66  erlying native f
bc50: 69 6c 65 20 68 61 6e 64 6c 65 20 61 73 73 6f 63  ile handle assoc
bc60: 69 61 74 65 64 20 77 69 74 68 20 61 20 66 69 6c  iated with a fil
bc70: 65 20 68 61 6e 64 6c 65 2e 20 20 54 68 69 73 20  e handle.  This 
bc80: 66 69 6c 65 0a 2a 2a 20 63 6f 6e 74 72 6f 6c 20  file.** control 
bc90: 69 6e 74 65 72 70 72 65 74 73 20 69 74 73 20 61  interprets its a
bca0: 72 67 75 6d 65 6e 74 20 61 73 20 61 20 70 6f 69  rgument as a poi
bcb0: 6e 74 65 72 20 74 6f 20 61 20 6e 61 74 69 76 65  nter to a native
bcc0: 20 66 69 6c 65 20 68 61 6e 64 6c 65 20 61 6e 64   file handle and
bcd0: 0a 2a 2a 20 77 72 69 74 65 73 20 74 68 65 20 72  .** writes the r
bce0: 65 73 75 6c 74 69 6e 67 20 76 61 6c 75 65 20 74  esulting value t
bcf0: 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  here..**.** <li>
bd00: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57  [[SQLITE_FCNTL_W
bd10: 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d  IN32_SET_HANDLE]
bd20: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
bd30: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54  _FCNTL_WIN32_SET
bd40: 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 65 20  _HANDLE] opcode 
bd50: 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 62 75  is used for debu
bd60: 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20  gging.  This.** 
bd70: 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 74 68  opcode causes th
bd80: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  e xFileControl m
bd90: 65 74 68 6f 64 20 74 6f 20 73 77 61 70 20 74 68  ethod to swap th
bda0: 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 20 77 69  e file handle wi
bdb0: 74 68 20 74 68 65 20 6f 6e 65 0a 2a 2a 20 70 6f  th the one.** po
bdc0: 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20  inted to by the 
bdd0: 70 41 72 67 20 61 72 67 75 6d 65 6e 74 2e 20 20  pArg argument.  
bde0: 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 20  This capability 
bdf0: 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74  is used during t
be00: 65 73 74 69 6e 67 0a 2a 2a 20 61 6e 64 20 6f 6e  esting.** and on
be10: 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73  ly needs to be s
be20: 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51  upported when SQ
be30: 4c 49 54 45 5f 54 45 53 54 20 69 73 20 64 65 66  LITE_TEST is def
be40: 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ined..**.** <li>
be50: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57  [[SQLITE_FCNTL_W
be60: 41 4c 5f 42 4c 4f 43 4b 5d 5d 0a 2a 2a 20 54 68  AL_BLOCK]].** Th
be70: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
be80: 57 41 4c 5f 42 4c 4f 43 4b 5d 20 69 73 20 61 20  WAL_BLOCK] is a 
be90: 73 69 67 6e 61 6c 20 74 6f 20 74 68 65 20 56 46  signal to the VF
bea0: 53 20 6c 61 79 65 72 20 74 68 61 74 20 69 74 20  S layer that it 
beb0: 6d 69 67 68 74 0a 2a 2a 20 62 65 20 61 64 76 61  might.** be adva
bec0: 6e 74 61 67 65 6f 75 73 20 74 6f 20 62 6c 6f 63  ntageous to bloc
bed0: 6b 20 6f 6e 20 74 68 65 20 6e 65 78 74 20 57 41  k on the next WA
bee0: 4c 20 6c 6f 63 6b 20 69 66 20 74 68 65 20 6c 6f  L lock if the lo
bef0: 63 6b 20 69 73 20 6e 6f 74 20 69 6d 6d 65 64 69  ck is not immedi
bf00: 61 74 65 6c 79 0a 2a 2a 20 61 76 61 69 6c 61 62  ately.** availab
bf10: 6c 65 2e 20 20 54 68 65 20 57 41 4c 20 73 75 62  le.  The WAL sub
bf20: 73 79 73 74 65 6d 20 69 73 73 75 65 73 20 74 68  system issues th
bf30: 69 73 20 73 69 67 6e 61 6c 20 64 75 72 69 6e 67  is signal during
bf40: 20 72 61 72 65 0a 2a 2a 20 63 69 72 63 75 6d 73   rare.** circums
bf50: 74 61 6e 63 65 73 20 69 6e 20 6f 72 64 65 72 20  tances in order 
bf60: 74 6f 20 66 69 78 20 61 20 70 72 6f 62 6c 65 6d  to fix a problem
bf70: 20 77 69 74 68 20 70 72 69 6f 72 69 74 79 20 69   with priority i
bf80: 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 41 70 70  nversion..** App
bf90: 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  lications should
bfa0: 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20 75 73   <em>not</em> us
bfb0: 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74  e this file-cont
bfc0: 72 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  rol..**.** <li>[
bfd0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49  [SQLITE_FCNTL_ZI
bfe0: 50 56 46 53 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  PVFS]].** The [S
bff0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56  QLITE_FCNTL_ZIPV
c000: 46 53 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6d  FS] opcode is im
c010: 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 7a 69 70  plemented by zip
c020: 76 66 73 20 6f 6e 6c 79 2e 20 41 6c 6c 20 6f 74  vfs only. All ot
c030: 68 65 72 0a 2a 2a 20 56 46 53 20 73 68 6f 75 6c  her.** VFS shoul
c040: 64 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  d return SQLITE_
c050: 4e 4f 54 46 4f 55 4e 44 20 66 6f 72 20 74 68 69  NOTFOUND for thi
c060: 73 20 6f 70 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20  s opcode..**.** 
c070: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
c080: 54 4c 5f 52 42 55 5d 5d 0a 2a 2a 20 54 68 65 20  TL_RBU]].** The 
c090: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42  [SQLITE_FCNTL_RB
c0a0: 55 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6d 70  U] opcode is imp
c0b0: 6c 65 6d 65 6e 74 65 64 20 62 79 20 74 68 65 20  lemented by the 
c0c0: 73 70 65 63 69 61 6c 20 56 46 53 20 75 73 65 64  special VFS used
c0d0: 20 62 79 0a 2a 2a 20 74 68 65 20 52 42 55 20 65   by.** the RBU e
c0e0: 78 74 65 6e 73 69 6f 6e 20 6f 6e 6c 79 2e 20 20  xtension only.  
c0f0: 41 6c 6c 20 6f 74 68 65 72 20 56 46 53 20 73 68  All other VFS sh
c100: 6f 75 6c 64 20 72 65 74 75 72 6e 20 53 51 4c 49  ould return SQLI
c110: 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f 72 0a  TE_NOTFOUND for.
c120: 2a 2a 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20  ** this opcode. 
c130: 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64   .** </ul>.*/.#d
c140: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
c150: 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20  TL_LOCKSTATE    
c160: 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65             1.#de
c170: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c180: 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  L_GET_LOCKPROXYF
c190: 49 4c 45 20 20 20 20 20 20 20 32 0a 23 64 65 66  ILE       2.#def
c1a0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c1b0: 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _SET_LOCKPROXYFI
c1c0: 4c 45 20 20 20 20 20 20 20 33 0a 23 64 65 66 69  LE       3.#defi
c1d0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c1e0: 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20  LAST_ERRNO      
c1f0: 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e          4.#defin
c200: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  e SQLITE_FCNTL_S
c210: 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20 20 20  IZE_HINT        
c220: 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65         5.#define
c230: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48   SQLITE_FCNTL_CH
c240: 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20 20 20  UNK_SIZE        
c250: 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20        6.#define 
c260: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c  SQLITE_FCNTL_FIL
c270: 45 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20  E_POINTER       
c280: 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53       7.#define S
c290: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
c2a0: 5f 4f 4d 49 54 54 45 44 20 20 20 20 20 20 20 20  _OMITTED        
c2b0: 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51      8.#define SQ
c2c0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
c2d0: 5f 41 56 5f 52 45 54 52 59 20 20 20 20 20 20 20  _AV_RETRY       
c2e0: 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c     9.#define SQL
c2f0: 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53  ITE_FCNTL_PERSIS
c300: 54 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20  T_WAL           
c310: 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   10.#define SQLI
c320: 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49  TE_FCNTL_OVERWRI
c330: 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
c340: 31 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  11.#define SQLIT
c350: 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 20  E_FCNTL_VFSNAME 
c360: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
c370: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
c380: 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45  _FCNTL_POWERSAFE
c390: 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 31 33  _OVERWRITE    13
c3a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c3b0: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20 20  FCNTL_PRAGMA    
c3c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 34 0a               14.
c3d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c3e0: 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52  CNTL_BUSYHANDLER
c3f0: 20 20 20 20 20 20 20 20 20 20 20 20 31 35 0a 23              15.#
c400: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
c410: 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45  NTL_TEMPFILENAME
c420: 20 20 20 20 20 20 20 20 20 20 20 31 36 0a 23 64             16.#d
c430: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
c440: 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20  TL_MMAP_SIZE    
c450: 20 20 20 20 20 20 20 20 20 20 31 38 0a 23 64 65            18.#de
c460: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c470: 4c 5f 54 52 41 43 45 20 20 20 20 20 20 20 20 20  L_TRACE         
c480: 20 20 20 20 20 20 20 20 20 31 39 0a 23 64 65 66           19.#def
c490: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c4a0: 5f 48 41 53 5f 4d 4f 56 45 44 20 20 20 20 20 20  _HAS_MOVED      
c4b0: 20 20 20 20 20 20 20 20 32 30 0a 23 64 65 66 69          20.#defi
c4c0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c4d0: 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20  SYNC            
c4e0: 20 20 20 20 20 20 20 32 31 0a 23 64 65 66 69 6e         21.#defin
c4f0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43  e SQLITE_FCNTL_C
c500: 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 20 20  OMMIT_PHASETWO  
c510: 20 20 20 20 20 20 32 32 0a 23 64 65 66 69 6e 65        22.#define
c520: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49   SQLITE_FCNTL_WI
c530: 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 20 20  N32_SET_HANDLE  
c540: 20 20 20 20 20 32 33 0a 23 64 65 66 69 6e 65 20       23.#define 
c550: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c  SQLITE_FCNTL_WAL
c560: 5f 42 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20  _BLOCK          
c570: 20 20 20 20 32 34 0a 23 64 65 66 69 6e 65 20 53      24.#define S
c580: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56  QLITE_FCNTL_ZIPV
c590: 46 53 20 20 20 20 20 20 20 20 20 20 20 20 20 20  FS              
c5a0: 20 20 20 32 35 0a 23 64 65 66 69 6e 65 20 53 51     25.#define SQ
c5b0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 20 20  LITE_FCNTL_RBU  
c5c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
c5d0: 20 20 32 36 0a 23 64 65 66 69 6e 65 20 53 51 4c    26.#define SQL
c5e0: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f  ITE_FCNTL_VFS_PO
c5f0: 49 4e 54 45 52 20 20 20 20 20 20 20 20 20 20 20  INTER           
c600: 20 32 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   27.#define SQLI
c610: 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c  TE_FCNTL_JOURNAL
c620: 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20  _POINTER        
c630: 32 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  28.#define SQLIT
c640: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45  E_FCNTL_WIN32_GE
c650: 54 5f 48 41 4e 44 4c 45 20 20 20 20 20 20 20 32  T_HANDLE       2
c660: 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  9.#define SQLITE
c670: 5f 46 43 4e 54 4c 5f 50 44 42 20 20 20 20 20 20  _FCNTL_PDB      
c680: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 33 30                30
c690: 0a 0a 2f 2a 20 64 65 70 72 65 63 61 74 65 64 20  ../* deprecated 
c6a0: 6e 61 6d 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65  names */.#define
c6b0: 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b   SQLITE_GET_LOCK
c6c0: 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 53  PROXYFILE      S
c6d0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f  QLITE_FCNTL_GET_
c6e0: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64  LOCKPROXYFILE.#d
c6f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54  efine SQLITE_SET
c700: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20  _LOCKPROXYFILE  
c710: 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c      SQLITE_FCNTL
c720: 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _SET_LOCKPROXYFI
c730: 4c 45 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  LE.#define SQLIT
c740: 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20  E_LAST_ERRNO    
c750: 20 20 20 20 20 20 20 20 20 53 51 4c 49 54 45 5f           SQLITE_
c760: 46 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f  FCNTL_LAST_ERRNO
c770: 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
c780: 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a  F: Mutex Handle.
c790: 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20  **.** The mutex 
c7a0: 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51  module within SQ
c7b0: 4c 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71  Lite defines [sq
c7c0: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20  lite3_mutex] to 
c7d0: 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63  be an.** abstrac
c7e0: 74 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74  t type for a mut
c7f0: 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20  ex object.  The 
c800: 53 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65  SQLite core neve
c810: 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68  r looks.** at th
c820: 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65  e internal repre
c830: 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20  sentation of an 
c840: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e  [sqlite3_mutex].
c850: 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61    It only.** dea
c860: 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73  ls with pointers
c870: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
c880: 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a  _mutex] object..
c890: 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72  **.** Mutexes ar
c8a0: 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20  e created using 
c8b0: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61  [sqlite3_mutex_a
c8c0: 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65  lloc()]..*/.type
c8d0: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
c8e0: 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33  e3_mutex sqlite3
c8f0: 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _mutex;../*.** C
c900: 41 50 49 33 52 45 46 3a 20 4c 6f 61 64 61 62 6c  API3REF: Loadabl
c910: 65 20 45 78 74 65 6e 73 69 6f 6e 20 54 68 75 6e  e Extension Thun
c920: 6b 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65  k.**.** A pointe
c930: 72 20 74 6f 20 74 68 65 20 6f 70 61 71 75 65 20  r to the opaque 
c940: 73 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74  sqlite3_api_rout
c950: 69 6e 65 73 20 73 74 72 75 63 74 75 72 65 20 69  ines structure i
c960: 73 20 70 61 73 73 65 64 20 61 73 0a 2a 2a 20 74  s passed as.** t
c970: 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
c980: 65 72 20 74 6f 20 65 6e 74 72 79 20 70 6f 69 6e  er to entry poin
c990: 74 73 20 6f 66 20 5b 6c 6f 61 64 61 62 6c 65 20  ts of [loadable 
c9a0: 65 78 74 65 6e 73 69 6f 6e 73 5d 2e 20 20 54 68  extensions].  Th
c9b0: 69 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  is.** structure 
c9c0: 6d 75 73 74 20 62 65 20 74 79 70 65 64 65 66 65  must be typedefe
c9d0: 64 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 77 6f  d in order to wo
c9e0: 72 6b 20 61 72 6f 75 6e 64 20 63 6f 6d 70 69 6c  rk around compil
c9f0: 65 72 20 77 61 72 6e 69 6e 67 73 0a 2a 2a 20 6f  er warnings.** o
ca00: 6e 20 73 6f 6d 65 20 70 6c 61 74 66 6f 72 6d 73  n some platforms
ca10: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
ca20: 75 63 74 20 73 71 6c 69 74 65 33 5f 61 70 69 5f  uct sqlite3_api_
ca30: 72 6f 75 74 69 6e 65 73 20 73 71 6c 69 74 65 33  routines sqlite3
ca40: 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73 3b 0a 0a  _api_routines;..
ca50: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
ca60: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a  OS Interface Obj
ca70: 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  ect.**.** An ins
ca80: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c  tance of the sql
ca90: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20  ite3_vfs object 
caa0: 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
cab0: 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a  rface between.**
cac0: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
cad0: 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79   and the underly
cae0: 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79  ing operating sy
caf0: 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22  stem.  The "vfs"
cb00: 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20  .** in the name 
cb10: 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74  of the object st
cb20: 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61  ands for "virtua
cb30: 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 20  l file system". 
cb40: 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53   See.** the [VFS
cb50: 20 7c 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 61   | VFS documenta
cb60: 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 65  tion] for furthe
cb70: 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  r information..*
cb80: 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f  *.** The value o
cb90: 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66  f the iVersion f
cba0: 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c  ield is initiall
cbb0: 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c  y 1 but may be l
cbc0: 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75  arger in.** futu
cbd0: 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
cbe0: 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e  QLite.  Addition
cbf0: 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65  al fields may be
cc00: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69   appended to thi
cc10: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e  s.** object when
cc20: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61   the iVersion va
cc30: 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 65 64  lue is increased
cc40: 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  .  Note that the
cc50: 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66   structure.** of
cc60: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
cc70: 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20   object changes 
cc80: 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  in the transacti
cc90: 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51  on between.** SQ
cca0: 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
ccb0: 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64  .9 and 3.6.0 and
ccc0: 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69 6f   yet the iVersio
ccd0: 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a  n field was not.
cce0: 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a  ** modified..**.
ccf0: 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20  ** The szOsFile 
cd00: 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a  field is the siz
cd10: 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73  e of the subclas
cd20: 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  sed [sqlite3_fil
cd30: 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  e].** structure 
cd40: 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46 53  used by this VFS
cd50: 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73  .  mxPathname is
cd60: 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e   the maximum len
cd70: 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68  gth of.** a path
cd80: 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53  name in this VFS
cd90: 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72  ..**.** Register
cda0: 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  ed sqlite3_vfs o
cdb0: 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74 20  bjects are kept 
cdc0: 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74  on a linked list
cdd0: 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68   formed by.** th
cde0: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e  e pNext pointer.
cdf0: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76    The [sqlite3_v
ce00: 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a  fs_register()].*
ce10: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76  * and [sqlite3_v
ce20: 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d  fs_unregister()]
ce30: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61   interfaces mana
ce40: 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20  ge this list.** 
ce50: 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 65  in a thread-safe
ce60: 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69   way.  The [sqli
ce70: 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20  te3_vfs_find()] 
ce80: 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61  interface.** sea
ce90: 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20  rches the list. 
cea0: 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70 70   Neither the app
ceb0: 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f  lication code no
cec0: 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70  r the VFS.** imp
ced0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75  lementation shou
cee0: 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78 74  ld use the pNext
cef0: 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
cf00: 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20  The pNext field 
cf10: 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c  is the only fiel
cf20: 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  d in the sqlite3
cf30: 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72  _vfs.** structur
cf40: 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  e that SQLite wi
cf50: 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20  ll ever modify. 
cf60: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c   SQLite will onl
cf70: 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d  y access.** or m
cf80: 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c 64  odify this field
cf90: 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61   while holding a
cfa0: 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 74   particular stat
cfb0: 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65  ic mutex..** The
cfc0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
cfd0: 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79  uld never modify
cfe0: 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e   anything within
cff0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
d000: 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20  .** object once 
d010: 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62  the object has b
d020: 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a  een registered..
d030: 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20  **.** The zName 
d040: 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20  field holds the 
d050: 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20  name of the VFS 
d060: 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d  module.  The nam
d070: 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69  e must.** be uni
d080: 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56  que across all V
d090: 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a  FS modules..**.*
d0a0: 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  * [[sqlite3_vfs.
d0b0: 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69  xOpen]].** ^SQLi
d0c0: 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  te guarantees th
d0d0: 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65  at the zFilename
d0e0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f   parameter to xO
d0f0: 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72  pen.** is either
d100: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
d110: 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e  or string obtain
d120: 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c  ed.** from xFull
d130: 50 61 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20  Pathname() with 
d140: 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66  an optional suff
d150: 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66  ix added..** ^If
d160: 20 61 20 73 75 66 66 69 78 20 69 73 20 61 64 64   a suffix is add
d170: 65 64 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e  ed to the zFilen
d180: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69  ame parameter, i
d190: 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73  t will.** consis
d1a0: 74 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d  t of a single "-
d1b0: 22 20 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c  " character foll
d1c0: 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20  owed by no more 
d1d0: 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61  than.** 11 alpha
d1e0: 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22  numeric and/or "
d1f0: 2d 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  -" characters..*
d200: 2a 20 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65  * ^SQLite furthe
d210: 72 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  r guarantees tha
d220: 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20  t.** the string 
d230: 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e  will be valid an
d240: 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69  d unchanged unti
d250: 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a  l xClose() is.**
d260: 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65   called. Because
d270: 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75 73   of the previous
d280: 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68   sentence,.** th
d290: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  e [sqlite3_file]
d2a0: 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72   can safely stor
d2b0: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  e a pointer to t
d2c0: 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69  he.** filename i
d2d0: 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65  f it needs to re
d2e0: 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e  member the filen
d2f0: 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61  ame for some rea
d300: 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a  son..** If the z
d310: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
d320: 65 72 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61  er to xOpen is a
d330: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
d340: 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74  en xOpen.** must
d350: 20 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20   invent its own 
d360: 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66  temporary name f
d370: 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57  or the file.  ^W
d380: 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20  henever the .** 
d390: 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  xFilename parame
d3a0: 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77  ter is NULL it w
d3b0: 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20  ill also be the 
d3c0: 63 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a  case that the.**
d3d0: 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
d3e0: 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53   will include [S
d3f0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
d400: 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a  EONCLOSE]..**.**
d410: 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   The flags argum
d420: 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69  ent to xOpen() i
d430: 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73  ncludes all bits
d440: 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66   set in.** the f
d450: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
d460: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
d470: 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71  2()].  Or if [sq
d480: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a  lite3_open()].**
d490: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
d4a0: 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20  n16()] is used, 
d4b0: 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75  then flags inclu
d4c0: 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20  des at least.** 
d4d0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
d4e0: 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54  DWRITE] | [SQLIT
d4f0: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20  E_OPEN_CREATE]. 
d500: 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f  .** If xOpen() o
d510: 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64  pens a file read
d520: 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65  -only then it se
d530: 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f  ts *pOutFlags to
d540: 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c  .** include [SQL
d550: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
d560: 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20  Y].  Other bits 
d570: 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61  in *pOutFlags ma
d580: 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20  y be set..**.** 
d590: 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  ^(SQLite will al
d5a0: 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68  so add one of th
d5b0: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67  e following flag
d5c0: 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29  s to the xOpen()
d5d0: 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64  .** call, depend
d5e0: 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63  ing on the objec
d5f0: 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a  t being opened:.
d600: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
d610: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
d620: 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  _MAIN_DB].** <li
d630: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
d640: 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  MAIN_JOURNAL].**
d650: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
d660: 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20  PEN_TEMP_DB].** 
d670: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
d680: 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d  EN_TEMP_JOURNAL]
d690: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
d6a0: 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54  E_OPEN_TRANSIENT
d6b0: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
d6c0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f  QLITE_OPEN_SUBJO
d6d0: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
d6e0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53  [SQLITE_OPEN_MAS
d6f0: 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  TER_JOURNAL].** 
d700: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
d710: 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e  EN_WAL].** </ul>
d720: 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c  )^.**.** The fil
d730: 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61  e I/O implementa
d740: 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65  tion can use the
d750: 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61   object type fla
d760: 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20  gs to.** change 
d770: 74 68 65 20 77 61 79 20 69 74 20 64 65 61 6c 73  the way it deals
d780: 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f   with files.  Fo
d790: 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70  r example, an ap
d7a0: 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61  plication.** tha
d7b0: 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20  t does not care 
d7c0: 61 62 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f  about crash reco
d7d0: 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b  very or rollback
d7e0: 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74   might make.** t
d7f0: 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75  he open of a jou
d800: 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f  rnal file a no-o
d810: 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68  p.  Writes to th
d820: 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64  is journal would
d830: 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f  .** also be no-o
d840: 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65  ps, and any atte
d850: 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68 65 20  mpt to read the 
d860: 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65  journal would re
d870: 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49  turn.** SQLITE_I
d880: 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d  OERR.  Or the im
d890: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67  plementation mig
d8a0: 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61  ht recognize tha
d8b0: 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  t a database.** 
d8c0: 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69  file will be doi
d8d0: 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20  ng page-aligned 
d8e0: 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64  sector reads and
d8f0: 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e   writes in a ran
d900: 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64  dom.** order and
d910: 20 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20   set up its I/O 
d920: 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64  subsystem accord
d930: 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  ingly..**.** SQL
d940: 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61  ite might also a
d950: 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  dd one of the fo
d960: 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f  llowing flags to
d970: 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   the xOpen metho
d980: 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  d:.**.** <ul>.**
d990: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50   <li> [SQLITE_OP
d9a0: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
d9b0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
d9c0: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
d9d0: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  ].** </ul>.**.**
d9e0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   The [SQLITE_OPE
d9f0: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
da00: 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20   flag means the 
da10: 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a  file should be.*
da20: 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69  * deleted when i
da30: 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54  t is closed.  ^T
da40: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
da50: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a  DELETEONCLOSE].*
da60: 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f  * will be set fo
da70: 72 20 54 45 4d 50 20 64 61 74 61 62 61 73 65 73  r TEMP databases
da80: 20 61 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e   and their journ
da90: 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a  als, transient.*
daa0: 2a 20 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64  * databases, and
dab0: 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a   subjournals..**
dac0: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
dad0: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d  _OPEN_EXCLUSIVE]
dae0: 20 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20   flag is always 
daf0: 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74  used in conjunct
db00: 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ion.** with the 
db10: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
db20: 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68  ATE] flag, which
db30: 20 61 72 65 20 62 6f 74 68 20 64 69 72 65 63 74   are both direct
db40: 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20  ly.** analogous 
db50: 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e  to the O_EXCL an
db60: 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20  d O_CREAT flags 
db70: 6f 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65  of the POSIX ope
db80: 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65  n().** API.  The
db90: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43   SQLITE_OPEN_EXC
dba0: 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65  LUSIVE flag, whe
dbb0: 6e 20 70 61 69 72 65 64 20 77 69 74 68 20 74 68  n paired with th
dbc0: 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45  e .** SQLITE_OPE
dbd0: 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73 65  N_CREATE, is use
dbe0: 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  d to indicate th
dbf0: 61 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61  at file should a
dc00: 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61  lways.** be crea
dc10: 74 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74  ted, and that it
dc20: 20 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20   is an error if 
dc30: 69 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  it already exist
dc40: 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e  s..** It is <i>n
dc50: 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69  ot</i> used to i
dc60: 6e 64 69 63 61 74 65 20 74 68 65 20 66 69 6c 65  ndicate the file
dc70: 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65   should be opene
dc80: 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73  d .** for exclus
dc90: 69 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a  ive access..**.*
dca0: 2a 20 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73  * ^At least szOs
dcb0: 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65  File bytes of me
dcc0: 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74  mory are allocat
dcd0: 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ed by SQLite.** 
dce0: 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71  to hold the  [sq
dcf0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75  lite3_file] stru
dd00: 63 74 75 72 65 20 70 61 73 73 65 64 20 61 73 20  cture passed as 
dd10: 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67  the third.** arg
dd20: 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20  ument to xOpen. 
dd30: 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   The xOpen metho
dd40: 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  d does not have 
dd50: 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74  to.** allocate t
dd60: 68 65 20 73 74 72 75 63 74 75 72 65 3b 20 69 74  he structure; it
dd70: 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c   should just fil
dd80: 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74  l it in.  Note t
dd90: 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e  hat.** the xOpen
dda0: 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74   method must set
ddb0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
ddc0: 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69  e.pMethods to ei
ddd0: 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20  ther.** a valid 
dde0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
ddf0: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74  ods] object or t
de00: 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d  o NULL.  xOpen m
de10: 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65  ust do.** this e
de20: 76 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20  ven if the open 
de30: 66 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65  fails.  SQLite e
de40: 78 70 65 63 74 73 20 74 68 61 74 20 74 68 65 20  xpects that the 
de50: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
de60: 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74  thods.** element
de70: 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61   will be valid a
de80: 66 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72  fter xOpen retur
de90: 6e 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ns regardless of
dea0: 20 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20   the success.** 
deb0: 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68  or failure of th
dec0: 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a  e xOpen call..**
ded0: 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66  .** [[sqlite3_vf
dee0: 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e  s.xAccess]].** ^
def0: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
df00: 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20  nt to xAccess() 
df10: 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41  may be [SQLITE_A
df20: 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a  CCESS_EXISTS].**
df30: 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65   to test for the
df40: 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20   existence of a 
df50: 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45  file, or [SQLITE
df60: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
df70: 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68  E] to.** test wh
df80: 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20  ether a file is 
df90: 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69  readable and wri
dfa0: 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54  table, or [SQLIT
dfb0: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a  E_ACCESS_READ].*
dfc0: 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65  * to test whethe
dfd0: 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c  r a file is at l
dfe0: 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20  east readable.  
dff0: 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65   The file can be
e000: 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e   a.** directory.
e010: 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  .**.** ^SQLite w
e020: 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63  ill always alloc
e030: 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50  ate at least mxP
e040: 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20  athname+1 bytes 
e050: 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75  for the.** outpu
e060: 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61  t buffer xFullPa
e070: 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61  thname.  The exa
e080: 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f  ct size of the o
e090: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20  utput buffer.** 
e0a0: 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61  is also passed a
e0b0: 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f  s a parameter to
e0c0: 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20   both  methods. 
e0d0: 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75  If the output bu
e0e0: 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c  ffer.** is not l
e0f0: 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51  arge enough, [SQ
e100: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73  LITE_CANTOPEN] s
e110: 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  hould be returne
e120: 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 73  d. Since this is
e130: 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61  .** handled as a
e140: 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20   fatal error by 
e150: 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c  SQLite, vfs impl
e160: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75  ementations shou
e170: 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74  ld endeavor.** t
e180: 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62  o prevent this b
e190: 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68  y setting mxPath
e1a0: 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63  name to a suffic
e1b0: 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c  iently large val
e1c0: 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52  ue..**.** The xR
e1d0: 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c  andomness(), xSl
e1e0: 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54  eep(), xCurrentT
e1f0: 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72  ime(), and xCurr
e200: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a  entTimeInt64().*
e210: 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  * interfaces are
e220: 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20   not strictly a 
e230: 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65  part of the file
e240: 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79  system, but they
e250: 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64   are.** included
e260: 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 75   in the VFS stru
e270: 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65  cture for comple
e280: 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78  teness..** The x
e290: 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e  Randomness() fun
e2a0: 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74  ction attempts t
e2b0: 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20  o return nBytes 
e2c0: 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64  bytes.** of good
e2d0: 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e  -quality randomn
e2e0: 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20  ess into zOut.  
e2f0: 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  The return value
e300: 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61   is.** the actua
e310: 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  l number of byte
e320: 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20  s of randomness 
e330: 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  obtained..** The
e340: 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64   xSleep() method
e350: 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c   causes the call
e360: 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c  ing thread to sl
e370: 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65  eep for at.** le
e380: 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ast the number o
e390: 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67  f microseconds g
e3a0: 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72  iven.  ^The xCur
e3b0: 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65  rentTime().** me
e3c0: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a  thod returns a J
e3d0: 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72  ulian Day Number
e3e0: 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74   for the current
e3f0: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61   date and time a
e400: 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20  s.** a floating 
e410: 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20  point value..** 
e420: 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d  ^The xCurrentTim
e430: 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20  eInt64() method 
e440: 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69  returns, as an i
e450: 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69  nteger, the Juli
e460: 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72  an.** Day Number
e470: 20 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38   multiplied by 8
e480: 36 34 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d  6400000 (the num
e490: 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ber of milliseco
e4a0: 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d  nds in .** a 24-
e4b0: 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20  hour day).  .** 
e4c0: 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65  ^SQLite will use
e4d0: 20 74 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d   the xCurrentTim
e4e0: 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20  eInt64() method 
e4f0: 74 6f 20 67 65 74 20 74 68 65 20 63 75 72 72 65  to get the curre
e500: 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74  nt.** date and t
e510: 69 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74 68  ime if that meth
e520: 6f 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20  od is available 
e530: 28 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20  (if iVersion is 
e540: 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72  2 or .** greater
e550: 20 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f   and the functio
e560: 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74  n pointer is not
e570: 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20   NULL) and will 
e580: 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20  fall back.** to 
e590: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69  xCurrentTime() i
e5a0: 66 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  f xCurrentTimeIn
e5b0: 74 36 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c  t64() is unavail
e5c0: 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  able..**.** ^The
e5d0: 20 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28   xSetSystemCall(
e5e0: 29 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c  ), xGetSystemCal
e5f0: 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79  l(), and xNestSy
e600: 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72  stemCall() inter
e610: 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74  faces.** are not
e620: 20 75 73 65 64 20 62 79 20 74 68 65 20 53 51 4c   used by the SQL
e630: 69 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65  ite core.  These
e640: 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66   optional interf
e650: 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65  aces are provide
e660: 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53  d.** by some VFS
e670: 65 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65  es to facilitate
e680: 20 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20   testing of the 
e690: 56 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65  VFS code. By ove
e6a0: 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74  rriding .** syst
e6b0: 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75  em calls with fu
e6c0: 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74  nctions under it
e6d0: 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73  s control, a tes
e6e0: 74 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a  t program can.**
e6f0: 20 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73   simulate faults
e700: 20 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69   and error condi
e710: 74 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64  tions that would
e720: 20 6f 74 68 65 72 77 69 73 65 20 62 65 20 64 69   otherwise be di
e730: 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d  fficult.** or im
e740: 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75  possible to indu
e750: 63 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20  ce.  The set of 
e760: 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61  system calls tha
e770: 74 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64  t can be overrid
e780: 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72  den.** varies fr
e790: 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e  om one VFS to an
e7a0: 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20  other, and from 
e7b0: 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74  one version of t
e7c0: 68 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74  he same VFS to t
e7d0: 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70  he.** next.  App
e7e0: 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75  lications that u
e7f0: 73 65 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  se these interfa
e800: 63 65 73 20 6d 75 73 74 20 62 65 20 70 72 65 70  ces must be prep
e810: 61 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20  ared for any.** 
e820: 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20  or all of these 
e830: 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62 65  interfaces to be
e840: 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65   NULL or for the
e850: 69 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63  ir behavior to c
e860: 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e  hange.** from on
e870: 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65  e release to the
e880: 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74   next.  Applicat
e890: 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74  ions must not at
e8a0: 74 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a  tempt to access.
e8b0: 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  ** any of these 
e8c0: 6d 65 74 68 6f 64 73 20 69 66 20 74 68 65 20 69  methods if the i
e8d0: 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56  Version of the V
e8e0: 46 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  FS is less than 
e8f0: 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  3..*/.typedef st
e900: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73  ruct sqlite3_vfs
e910: 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79   sqlite3_vfs;.ty
e920: 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c  pedef void (*sql
e930: 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72  ite3_syscall_ptr
e940: 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20  )(void);.struct 
e950: 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20  sqlite3_vfs {.  
e960: 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20  int iVersion;   
e970: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75           /* Stru
e980: 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75  cture version nu
e990: 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20  mber (currently 
e9a0: 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73  3) */.  int szOs
e9b0: 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20  File;           
e9c0: 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63   /* Size of subc
e9d0: 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66  lassed sqlite3_f
e9e0: 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50  ile */.  int mxP
e9f0: 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20  athname;        
ea00: 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c    /* Maximum fil
ea10: 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74  e pathname lengt
ea20: 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76  h */.  sqlite3_v
ea30: 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20  fs *pNext;      
ea40: 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72  /* Next register
ea50: 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73  ed VFS */.  cons
ea60: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20  t char *zName;  
ea70: 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
ea80: 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c  this virtual fil
ea90: 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f  e system */.  vo
eaa0: 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20  id *pAppData;   
eab0: 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65         /* Pointe
eac0: 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e  r to application
ead0: 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a  -specific data *
eae0: 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29  /.  int (*xOpen)
eaf0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
eb00: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
eb10: 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  , sqlite3_file*,
eb20: 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
eb30: 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a  int flags, int *
eb40: 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e  pOutFlags);.  in
eb50: 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c  t (*xDelete)(sql
eb60: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
eb70: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
eb80: 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e  t syncDir);.  in
eb90: 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c  t (*xAccess)(sql
eba0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
ebb0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
ebc0: 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52  t flags, int *pR
ebd0: 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a  esOut);.  int (*
ebe0: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73  xFullPathname)(s
ebf0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
ec00: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
ec10: 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a  int nOut, char *
ec20: 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28  zOut);.  void *(
ec30: 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65  *xDlOpen)(sqlite
ec40: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
ec50: 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a  ar *zFilename);.
ec60: 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f    void (*xDlErro
ec70: 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  r)(sqlite3_vfs*,
ec80: 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72   int nByte, char
ec90: 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f   *zErrMsg);.  vo
eca0: 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73  id (*(*xDlSym)(s
ecb0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64  qlite3_vfs*,void
ecc0: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
ecd0: 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a  Symbol))(void);.
ece0: 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73    void (*xDlClos
ecf0: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
ed00: 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28   void*);.  int (
ed10: 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71  *xRandomness)(sq
ed20: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
ed30: 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75  nByte, char *zOu
ed40: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65  t);.  int (*xSle
ed50: 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ep)(sqlite3_vfs*
ed60: 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e  , int microsecon
ed70: 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75  ds);.  int (*xCu
ed80: 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74  rrentTime)(sqlit
ed90: 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a  e3_vfs*, double*
eda0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c  );.  int (*xGetL
edb0: 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65  astError)(sqlite
edc0: 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61  3_vfs*, int, cha
edd0: 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  r *);.  /*.  ** 
ede0: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
edf0: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
ee00: 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   1 of the sqlite
ee10: 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a  _vfs object.  **
ee20: 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68   definition.  Th
ee30: 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20  ose that follow 
ee40: 61 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 72  are added in ver
ee50: 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a  sion 2 or later.
ee60: 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75    */.  int (*xCu
ee70: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28  rrentTimeInt64)(
ee80: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71  sqlite3_vfs*, sq
ee90: 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20  lite3_int64*);. 
eea0: 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74   /*.  ** The met
eeb0: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
eec0: 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64  n versions 1 and
eed0: 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   2 of the sqlite
eee0: 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a  _vfs object..  *
eef0: 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72  * Those below ar
ef00: 65 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20  e for version 3 
ef10: 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a  and greater..  *
ef20: 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79  /.  int (*xSetSy
ef30: 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
ef40: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
ef50: 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74  ar *zName, sqlit
ef60: 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b  e3_syscall_ptr);
ef70: 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61  .  sqlite3_sysca
ef80: 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73  ll_ptr (*xGetSys
ef90: 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33  temCall)(sqlite3
efa0: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
efb0: 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e  r *zName);.  con
efc0: 73 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74  st char *(*xNext
efd0: 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69  SystemCall)(sqli
efe0: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
eff0: 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20  char *zName);.  
f000: 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68  /*.  ** The meth
f010: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
f020: 20 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f   versions 1 thro
f030: 75 67 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c  ugh 3 of the sql
f040: 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a  ite_vfs object..
f050: 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20    ** New fields 
f060: 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20  may be appended 
f070: 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f  in future versio
f080: 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f  ns.  The iVersio
f090: 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c  n.  ** value wil
f0a0: 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e  l increment when
f0b0: 65 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e  ever this happen
f0c0: 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  s. .  */.};../*.
f0d0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
f0e0: 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65  gs for the xAcce
f0f0: 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a  ss VFS method.**
f100: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65  .** These intege
f110: 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20  r constants can 
f120: 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74  be used as the t
f130: 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
f140: 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73  o.** the xAccess
f150: 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73   method of an [s
f160: 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
f170: 63 74 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d  ct.  They determ
f180: 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64  ine.** what kind
f190: 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20   of permissions 
f1a0: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
f1b0: 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f  od is looking fo
f1c0: 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  r..** With SQLIT
f1d0: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c  E_ACCESS_EXISTS,
f1e0: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
f1f0: 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68  hod.** simply ch
f200: 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65  ecks whether the
f210: 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a   file exists..**
f220: 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43   With SQLITE_ACC
f230: 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74  ESS_READWRITE, t
f240: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
f250: 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74  d.** checks whet
f260: 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69  her the named di
f270: 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20  rectory is both 
f280: 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69  readable and wri
f290: 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68  table.** (in oth
f2a0: 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c  er words, if fil
f2b0: 65 73 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c  es can be added,
f2c0: 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65   removed, and re
f2d0: 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20  named within.** 
f2e0: 74 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a  the directory)..
f2f0: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43  ** The SQLITE_AC
f300: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 63  CESS_READWRITE c
f310: 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72 65  onstant is curre
f320: 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62  ntly used only b
f330: 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73  y the.** [temp_s
f340: 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70  tore_directory p
f350: 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74  ragma], though t
f360: 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65  his could change
f370: 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20   in a future.** 
f380: 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
f390: 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  e..** With SQLIT
f3a0: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74  E_ACCESS_READ, t
f3b0: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
f3c0: 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74  d.** checks whet
f3d0: 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20  her the file is 
f3e0: 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53  readable.  The S
f3f0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
f400: 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a  D constant is.**
f410: 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65   currently unuse
f420: 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67  d, though it mig
f430: 68 74 20 62 65 20 75 73 65 64 20 69 6e 20 61 20  ht be used in a 
f440: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f  future release o
f450: 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  f.** SQLite..*/.
f460: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
f470: 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 20  CCESS_EXISTS    
f480: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
f490: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
f4a0: 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79  E 1   /* Used by
f4b0: 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f   PRAGMA temp_sto
f4c0: 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a  re_directory */.
f4d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
f4e0: 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20  CCESS_READ      
f4f0: 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f  2   /* Unused */
f500: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
f510: 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20  : Flags for the 
f520: 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74  xShmLock VFS met
f530: 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  hod.**.** These 
f540: 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
f550: 73 20 64 65 66 69 6e 65 20 74 68 65 20 76 61 72  s define the var
f560: 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65  ious locking ope
f570: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77  rations.** allow
f580: 65 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f  ed by the xShmLo
f590: 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71  ck method of [sq
f5a0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
f5b0: 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f  ].  The.** follo
f5c0: 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c  wing are the onl
f5d0: 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74  y legal combinat
f5e0: 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f  ions of flags to
f5f0: 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b   the.** xShmLock
f600: 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c   method:.**.** <
f610: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  ul>.** <li>  SQL
f620: 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53  ITE_SHM_LOCK | S
f630: 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44  QLITE_SHM_SHARED
f640: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
f650: 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49  _SHM_LOCK | SQLI
f660: 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
f670: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
f680: 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51  _SHM_UNLOCK | SQ
f690: 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a  LITE_SHM_SHARED.
f6a0: 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
f6b0: 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c  SHM_UNLOCK | SQL
f6c0: 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56  ITE_SHM_EXCLUSIV
f6d0: 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  E.** </ul>.**.**
f6e0: 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c   When unlocking,
f6f0: 20 74 68 65 20 73 61 6d 65 20 53 48 41 52 45 44   the same SHARED
f700: 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c   or EXCLUSIVE fl
f710: 61 67 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c  ag must be suppl
f720: 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69  ied as.** was gi
f730: 76 65 6e 20 6f 6e 20 74 68 65 20 63 6f 72 72 65  ven on the corre
f740: 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20  sponding lock.  
f750: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c  .**.** The xShmL
f760: 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74  ock method can t
f770: 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65  ransition betwee
f780: 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53  n unlocked and S
f790: 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77  HARED or.** betw
f7a0: 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64  een unlocked and
f7b0: 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20   EXCLUSIVE.  It 
f7c0: 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f  cannot transitio
f7d0: 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52 45 44  n between SHARED
f7e0: 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56  .** and EXCLUSIV
f7f0: 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  E..*/.#define SQ
f800: 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20  LITE_SHM_UNLOCK 
f810: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
f820: 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
f830: 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
f840: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41  e SQLITE_SHM_SHA
f850: 52 45 44 20 20 20 20 20 20 20 34 0a 23 64 65 66  RED       4.#def
f860: 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  ine SQLITE_SHM_E
f870: 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f  XCLUSIVE    8../
f880: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
f890: 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20  aximum xShmLock 
f8a0: 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20  index.**.** The 
f8b0: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20  xShmLock method 
f8c0: 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  on [sqlite3_io_m
f8d0: 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20  ethods] may use 
f8e0: 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65  values.** betwee
f8f0: 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75 70 70  n 0 and this upp
f900: 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20  er bound as its 
f910: 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e  "offset" argumen
f920: 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  t..** The SQLite
f930: 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72   core will never
f940: 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75   attempt to acqu
f950: 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61  ire or release a
f960: 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65  .** lock outside
f970: 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a   of this range.*
f980: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
f990: 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20  _SHM_NLOCK      
f9a0: 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    8.../*.** CAPI
f9b0: 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65  3REF: Initialize
f9c0: 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72   The SQLite Libr
f9d0: 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ary.**.** ^The s
f9e0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
f9f0: 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74  e() routine init
fa00: 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53  ializes the.** S
fa10: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20  QLite library.  
fa20: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75  ^The sqlite3_shu
fa30: 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a  tdown() routine.
fa40: 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61  ** deallocates a
fa50: 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 61  ny resources tha
fa60: 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64  t were allocated
fa70: 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   by sqlite3_init
fa80: 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65  ialize()..** The
fa90: 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
faa0: 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20  designed to aid 
fab0: 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69  in process initi
fac0: 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a  alization and.**
fad0: 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62   shutdown on emb
fae0: 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20  edded systems.  
faf0: 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c  Workstation appl
fb00: 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a  ications using.*
fb10: 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c  * SQLite normall
fb20: 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f  y do not need to
fb30: 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f   invoke either o
fb40: 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
fb50: 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  ..**.** A call t
fb60: 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  o sqlite3_initia
fb70: 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66  lize() is an "ef
fb80: 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66  fective" call if
fb90: 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69   it is.** the fi
fba0: 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33  rst time sqlite3
fbb0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
fbc0: 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20   invoked during 
fbd0: 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a  the lifetime of.
fbe0: 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20  ** the process, 
fbf0: 6f 72 20 69 66 20 69 74 20 69 73 20 74 68 65 20  or if it is the 
fc00: 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74  first time sqlit
fc10: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
fc20: 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f  is invoked.** fo
fc30: 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74  llowing a call t
fc40: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
fc50: 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e  wn().  ^(Only an
fc60: 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a   effective call.
fc70: 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e  ** of sqlite3_in
fc80: 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20  itialize() does 
fc90: 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  any initializati
fca0: 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63  on.  All other c
fcb0: 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d  alls.** are harm
fcc0: 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a  less no-ops.)^.*
fcd0: 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73  *.** A call to s
fce0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
fcf0: 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69  ) is an "effecti
fd00: 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69  ve" call if it i
fd10: 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63  s the first.** c
fd20: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
fd30: 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20  hutdown() since 
fd40: 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33  the last sqlite3
fd50: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20  _initialize().  
fd60: 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66  ^(Only.** an eff
fd70: 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73  ective call to s
fd80: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
fd90: 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69  ) does any deini
fda0: 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20  tialization..** 
fdb0: 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20  All other valid 
fdc0: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
fdd0: 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20  _shutdown() are 
fde0: 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e  harmless no-ops.
fdf0: 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  )^.**.** The sql
fe00: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
fe10: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  ) interface is t
fe20: 68 72 65 61 64 73 61 66 65 2c 20 62 75 74 20 73  hreadsafe, but s
fe30: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
fe40: 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68  ).** is not.  Th
fe50: 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  e sqlite3_shutdo
fe60: 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d  wn() interface m
fe70: 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c  ust only be call
fe80: 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e  ed from a.** sin
fe90: 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c  gle thread.  All
fea0: 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20   open [database 
feb0: 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73  connections] mus
fec0: 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20  t be closed and 
fed0: 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c  all.** other SQL
fee0: 69 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75  ite resources mu
fef0: 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  st be deallocate
ff00: 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b  d prior to invok
ff10: 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  ing.** sqlite3_s
ff20: 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a  hutdown()..**.**
ff30: 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69   Among other thi
ff40: 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e  ngs, ^sqlite3_in
ff50: 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20  itialize() will 
ff60: 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  invoke.** sqlite
ff70: 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69  3_os_init().  Si
ff80: 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65  milarly, ^sqlite
ff90: 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20  3_shutdown().** 
ffa0: 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69  will invoke sqli
ffb0: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a  te3_os_end()..**
ffc0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
ffd0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f  _initialize() ro
ffe0: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53  utine returns [S
fff0: 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
10000 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72  cess..** ^If for
10010 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71   some reason, sq
10020 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
10030 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  () is unable to 
10040 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68  initialize.** th
10050 65 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 61  e library (perha
10060 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20  ps it is unable 
10070 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65  to allocate a ne
10080 65 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 75  eded resource su
10090 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78  ch.** as a mutex
100a0 29 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20  ) it returns an 
100b0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68  [error code] oth
100c0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
100d0 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  OK]..**.** ^The 
100e0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
100f0 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  ze() routine is 
10100 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c  called internall
10110 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a  y by many other.
10120 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ** SQLite interf
10130 61 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20  aces so that an 
10140 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61  application usua
10150 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  lly does not nee
10160 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73  d to.** invoke s
10170 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
10180 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46  e() directly.  F
10190 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c  or example, [sql
101a0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20  ite3_open()].** 
101b0 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e  calls sqlite3_in
101c0 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68  itialize() so th
101d0 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
101e0 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74   will be automat
101f0 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61  ically.** initia
10200 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69  lized when [sqli
10210 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63  te3_open()] is c
10220 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 20  alled if it has 
10230 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a  not be initializ
10240 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20  ed.** already.  
10250 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c  ^However, if SQL
10260 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
10270 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
10280 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a  _OMIT_AUTOINIT].
10290 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  ** compile-time 
102a0 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  option, then the
102b0 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73   automatic calls
102c0 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   to sqlite3_init
102d0 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20  ialize().** are 
102e0 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 20  omitted and the 
102f0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
10300 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e   call sqlite3_in
10310 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63  itialize() direc
10320 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  tly.** prior to 
10330 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  using any other 
10340 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
10350 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70  .  For maximum p
10360 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69  ortability,.** i
10370 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
10380 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f   that applicatio
10390 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65  ns always invoke
103a0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
103b0 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c  ize().** directl
103c0 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67  y prior to using
103d0 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74   any other SQLit
103e0 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75  e interface.  Fu
103f0 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a  ture releases.**
10400 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72   of SQLite may r
10410 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e  equire this.  In
10420 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
10430 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62  e behavior exhib
10440 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c  ited.** when SQL
10450 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
10460 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49  with [SQLITE_OMI
10470 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68  T_AUTOINIT] migh
10480 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20  t become the.** 
10490 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72  default behavior
104a0 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20   in some future 
104b0 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
104c0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e..**.** The sql
104d0 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72  ite3_os_init() r
104e0 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72  outine does oper
104f0 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65  ating-system spe
10500 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c  cific.** initial
10510 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53  ization of the S
10520 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20  QLite library.  
10530 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  The sqlite3_os_e
10540 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  nd().** routine 
10550 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63  undoes the effec
10560 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f  t of sqlite3_os_
10570 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c  init().  Typical
10580 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72   tasks.** perfor
10590 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75  med by these rou
105a0 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c  tines include al
105b0 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c  location or deal
105c0 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73  location.** of s
105d0 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c  tatic resources,
105e0 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
105f0 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62  of global variab
10600 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20  les,.** setting 
10610 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71  up a default [sq
10620 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c  lite3_vfs] modul
10630 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70  e, or setting up
10640 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f  .** a default co
10650 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e  nfiguration usin
10660 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  g [sqlite3_confi
10670 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  g()]..**.** The 
10680 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
10690 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20  ld never invoke 
106a0 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f  either sqlite3_o
106b0 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73  s_init().** or s
106c0 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20  qlite3_os_end() 
106d0 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61  directly.  The a
106e0 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
106f0 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a  d only invoke.**
10700 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
10710 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ize() and sqlite
10720 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54  3_shutdown().  T
10730 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  he sqlite3_os_in
10740 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  it().** interfac
10750 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f  e is called auto
10760 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c  matically by sql
10770 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
10780 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ) and.** sqlite3
10790 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c  _os_end() is cal
107a0 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73  led by sqlite3_s
107b0 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72  hutdown().  Appr
107c0 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65  opriate.** imple
107d0 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73  mentations for s
107e0 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
107f0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f   and sqlite3_os_
10800 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69  end().** are bui
10810 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77  lt into SQLite w
10820 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c  hen it is compil
10830 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e  ed for Unix, Win
10840 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a  dows, or OS/2..*
10850 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62  * When [custom b
10860 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f  uilds | built fo
10870 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d  r other platform
10880 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65  s].** (using the
10890 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45   [SQLITE_OS_OTHE
108a0 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  R=1] compile-tim
108b0 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65  e.** option) the
108c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
108d0 74 20 73 75 70 70 6c 79 20 61 20 73 75 69 74 61  t supply a suita
108e0 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ble implementati
108f0 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  on for.** sqlite
10900 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20  3_os_init() and 
10910 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
10920 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f  .  An applicatio
10930 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d  n-supplied.** im
10940 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
10950 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
10960 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  ) or sqlite3_os_
10970 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65  end().** must re
10980 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
10990 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20   on success and 
109a0 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f  some other [erro
109b0 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20  r code] upon.** 
109c0 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20  failure..*/.int 
109d0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
109e0 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71  ze(void);.int sq
109f0 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76  lite3_shutdown(v
10a00 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  oid);.int sqlite
10a10 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b  3_os_init(void);
10a20 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f  .int sqlite3_os_
10a30 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a  end(void);../*.*
10a40 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
10a50 69 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69  iguring The SQLi
10a60 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a  te Library.**.**
10a70 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e   The sqlite3_con
10a80 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
10a90 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20  is used to make 
10aa0 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61  global configura
10ab0 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20  tion.** changes 
10ac0 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64  to SQLite in ord
10ad0 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74  er to tune SQLit
10ae0 65 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69  e to the specifi
10af0 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68  c needs of.** th
10b00 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20  e application.  
10b10 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  The default conf
10b20 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63  iguration is rec
10b30 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73  ommended for mos
10b40 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  t.** application
10b50 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f  s and so this ro
10b60 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79  utine is usually
10b70 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20   not necessary. 
10b80 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64   It is.** provid
10b90 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61  ed to support ra
10ba0 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  re applications 
10bb0 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65  with unusual nee
10bc0 64 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 54 68 65  ds..**.** <b>The
10bd0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
10be0 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  ) interface is n
10bf0 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 20 54  ot threadsafe. T
10c00 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a  he application.*
10c10 2a 20 6d 75 73 74 20 65 6e 73 75 72 65 20 74 68  * must ensure th
10c20 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69  at no other SQLi
10c30 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  te interfaces ar
10c40 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68  e invoked by oth
10c50 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68  er.** threads wh
10c60 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ile sqlite3_conf
10c70 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e  ig() is running.
10c80 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  </b>.**.** The s
10c90 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
10ca0 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 6d 61 79  interface.** may
10cb0 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64   only be invoked
10cc0 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72   prior to librar
10cd0 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  y initialization
10ce0 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
10cf0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d  e3_initialize()]
10d00 20 6f 72 20 61 66 74 65 72 20 73 68 75 74 64 6f   or after shutdo
10d10 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73  wn by [sqlite3_s
10d20 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e  hutdown()]..** ^
10d30 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  If sqlite3_confi
10d40 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 66  g() is called af
10d50 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69  ter [sqlite3_ini
10d60 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62  tialize()] and b
10d70 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  efore.** [sqlite
10d80 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 68  3_shutdown()] th
10d90 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72  en it will retur
10da0 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e  n SQLITE_MISUSE.
10db0 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65  .** Note, howeve
10dc0 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 65 33  r, that ^sqlite3
10dd0 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65  _config() can be
10de0 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20   called as part 
10df0 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d  of the.** implem
10e00 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61  entation of an a
10e10 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
10e20 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69  ed [sqlite3_os_i
10e30 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  nit()]..**.** Th
10e40 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
10e50 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66   to sqlite3_conf
10e60 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67  ig() is an integ
10e70 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61  er.** [configura
10e80 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61  tion option] tha
10e90 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20  t determines.** 
10ea0 77 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66  what property of
10eb0 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65   SQLite is to be
10ec0 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75   configured.  Su
10ed0 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e  bsequent argumen
10ee0 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e  ts.** vary depen
10ef0 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e  ding on the [con
10f00 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
10f10 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72  n].** in the fir
10f20 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  st argument..**.
10f30 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69  ** ^When a confi
10f40 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
10f50 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f  is set, sqlite3_
10f60 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73  config() returns
10f70 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a   [SQLITE_OK]..**
10f80 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20   ^If the option 
10f90 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51  is unknown or SQ
10fa0 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74  Lite is unable t
10fb0 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e  o set the option
10fc0 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f  .** then this ro
10fd0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20  utine returns a 
10fe0 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20  non-zero [error 
10ff0 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  code]..*/.int sq
11000 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74  lite3_config(int
11010 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , ...);../*.** C
11020 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75  API3REF: Configu
11030 72 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  re database conn
11040 65 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f  ections.** METHO
11050 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
11060 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f   The sqlite3_db_
11070 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
11080 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61  ce is used to ma
11090 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ke configuration
110a0 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61  .** changes to a
110b0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
110c0 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74  ction].  The int
110d0 65 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61  erface is simila
110e0 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  r to.** [sqlite3
110f0 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70  _config()] excep
11100 74 20 74 68 61 74 20 74 68 65 20 63 68 61 6e 67  t that the chang
11110 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69  es apply to a si
11120 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ngle.** [databas
11130 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73  e connection] (s
11140 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20  pecified in the 
11150 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e  first argument).
11160 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  .**.** The secon
11170 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  d argument to sq
11180 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
11190 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65  D,V,...)  is the
111a0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f  .** [SQLITE_DBCO
111b0 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c  NFIG_LOOKASIDE |
111c0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76   configuration v
111d0 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65  erb] - an intege
111e0 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20  r code .** that 
111f0 69 6e 64 69 63 61 74 65 73 20 77 68 61 74 20 61  indicates what a
11200 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61  spect of the [da
11210 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
11220 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66  n] is being conf
11230 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65  igured..** Subse
11240 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 20  quent arguments 
11250 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f  vary depending o
11260 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74  n the configurat
11270 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20  ion verb..**.** 
11280 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65  ^Calls to sqlite
11290 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65  3_db_config() re
112a0 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69  turn SQLITE_OK i
112b0 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
112c0 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e   the call is con
112d0 73 69 64 65 72 65 64 20 73 75 63 63 65 73 73 66  sidered successf
112e0 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ul..*/.int sqlit
112f0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c  e3_db_config(sql
11300 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e  ite3*, int op, .
11310 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ..);../*.** CAPI
11320 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c  3REF: Memory All
11330 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73  ocation Routines
11340 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e  .**.** An instan
11350 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
11360 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e  t defines the in
11370 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 20  terface between 
11380 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f  SQLite.** and lo
11390 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61  w-level memory a
113a0 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
113b0 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f  es..**.** This o
113c0 62 6a 65 63 74 20 69 73 20 75 73 65 64 20 69 6e  bject is used in
113d0 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20   only one place 
113e0 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e  in the SQLite in
113f0 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f  terface..** A po
11400 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
11410 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
11420 65 63 74 20 69 73 20 74 68 65 20 61 72 67 75 6d  ect is the argum
11430 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ent to.** [sqlit
11440 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65  e3_config()] whe
11450 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74  n the configurat
11460 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a  ion option is.**
11470 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
11480 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49  MALLOC] or [SQLI
11490 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
114a0 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72  LOC].  .** By cr
114b0 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e  eating an instan
114c0 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
114d0 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67  t.** and passing
114e0 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f   it to [sqlite3_
114f0 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f  config]([SQLITE_
11500 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a  CONFIG_MALLOC]).
11510 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67  ** during config
11520 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c  uration, an appl
11530 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63  ication can spec
11540 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69  ify an alternati
11550 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c  ve.** memory all
11560 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65  ocation subsyste
11570 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20  m for SQLite to 
11580 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  use for all of i
11590 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65  ts.** dynamic me
115a0 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a  mory needs..**.*
115b0 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69  * Note that SQLi
115c0 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65  te comes with se
115d0 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20  veral [built-in 
115e0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
115f0 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70  s].** that are p
11600 65 72 66 65 63 74 6c 79 20 61 64 65 71 75 61 74  erfectly adequat
11610 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68  e for the overwh
11620 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20  elming majority 
11630 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  of applications.
11640 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69 73  ** and that this
11650 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20   object is only 
11660 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79  useful to a tiny
11670 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70   minority of app
11680 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74  lications.** wit
11690 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65  h specialized me
116a0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
116b0 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54  requirements.  T
116c0 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a  his object is.**
116d0 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e   also used durin
116e0 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c  g testing of SQL
116f0 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ite in order to 
11700 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72  specify an alter
11710 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79  native.** memory
11720 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20   allocator that 
11730 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79  simulates memory
11740 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63   out-of-memory c
11750 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20  onditions in.** 
11760 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66 79 20  order to verify 
11770 74 68 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f  that SQLite reco
11780 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20  vers gracefully 
11790 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e  from such.** con
117a0 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54  ditions..**.** T
117b0 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61  he xMalloc, xRea
117c0 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65 65 20  lloc, and xFree 
117d0 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72  methods must wor
117e0 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61  k like the.** ma
117f0 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28  lloc(), realloc(
11800 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e  ) and free() fun
11810 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20  ctions from the 
11820 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
11830 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67  ry..** ^SQLite g
11840 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74  uarantees that t
11850 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
11860 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f  nt to.** xReallo
11870 63 20 69 73 20 61 6c 77 61 79 73 20 61 20 76 61  c is always a va
11880 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
11890 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20  a prior call to 
118a0 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20  xRoundup..**.** 
118b0 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74  xSize should ret
118c0 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65  urn the allocate
118d0 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f  d size of a memo
118e0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ry allocation.**
118f0 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61   previously obta
11900 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f  ined from xMallo
11910 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20  c or xRealloc.  
11920 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69  The allocated si
11930 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20  ze.** is always 
11940 61 74 20 6c 65 61 73 74 20 61 73 20 62 69 67 20  at least as big 
11950 61 73 20 74 68 65 20 72 65 71 75 65 73 74 65 64  as the requested
11960 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65   size but may be
11970 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54   larger..**.** T
11980 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68  he xRoundup meth
11990 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61 74 20  od returns what 
119a0 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c  would be the all
119b0 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a  ocated size of.*
119c0 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  * a memory alloc
119d0 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61  ation given a pa
119e0 72 74 69 63 75 6c 61 72 20 72 65 71 75 65 73 74  rticular request
119f0 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d  ed size.  Most m
11a00 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
11a10 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d  ors round up mem
11a20 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20  ory allocations 
11a30 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20  at least to the 
11a40 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a  next multiple.**
11a50 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c   of 8.  Some all
11a60 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70  ocators round up
11a70 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c   to a larger mul
11a80 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f  tiple or to a po
11a90 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65  wer of 2..** Eve
11aa0 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ry memory alloca
11ab0 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d  tion request com
11ac0 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b  ing in through [
11ad0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
11ae0 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ].** or [sqlite3
11af0 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73  _realloc()] firs
11b00 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70  t calls xRoundup
11b10 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72  .  If xRoundup r
11b20 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68  eturns 0, .** th
11b30 61 74 20 63 61 75 73 65 73 20 74 68 65 20 63 6f  at causes the co
11b40 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f  rresponding memo
11b50 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f  ry allocation to
11b60 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   fail..**.** The
11b70 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e   xInit method in
11b80 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65  itializes the me
11b90 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20  mory allocator. 
11ba0 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a   For example,.**
11bb0 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61   it might alloca
11bc0 74 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d  te any require m
11bd0 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61  utexes or initia
11be0 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61  lize internal da
11bf0 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73  ta.** structures
11c00 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e  .  The xShutdown
11c10 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b   method is invok
11c20 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20  ed (indirectly) 
11c30 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  by.** [sqlite3_s
11c40 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73  hutdown()] and s
11c50 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65  hould deallocate
11c60 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61   any resources a
11c70 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49  cquired.** by xI
11c80 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 61  nit.  The pAppDa
11c90 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73  ta pointer is us
11ca0 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70  ed as the only p
11cb0 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78  arameter to.** x
11cc0 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f  Init and xShutdo
11cd0 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  wn..**.** SQLite
11ce0 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49   holds the [SQLI
11cf0 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
11d00 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68  MASTER] mutex wh
11d10 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a  en it invokes.**
11d20 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f   the xInit metho
11d30 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20  d, so the xInit 
11d40 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20  method need not 
11d50 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 20  be threadsafe.  
11d60 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e  The.** xShutdown
11d70 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20   method is only 
11d80 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c  called from [sql
11d90 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
11da0 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e   so it does.** n
11db0 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68  ot need to be th
11dc0 72 65 61 64 73 61 66 65 20 65 69 74 68 65 72 2e  readsafe either.
11dd0 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20    For all other 
11de0 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a  methods, SQLite.
11df0 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51  ** holds the [SQ
11e00 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
11e10 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20  C_MEM] mutex as 
11e20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b  long as the.** [
11e30 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
11e40 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75  MSTATUS] configu
11e50 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
11e60 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63   turned on (whic
11e70 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65  h.** it is by de
11e80 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68  fault) and so th
11e90 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75  e methods are au
11ea0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69  tomatically seri
11eb0 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76  alized..** Howev
11ec0 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43  er, if [SQLITE_C
11ed0 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
11ee0 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68   is disabled, th
11ef0 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20  en the other.** 
11f00 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20  methods must be 
11f10 74 68 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c  threadsafe or el
11f20 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77  se make their ow
11f30 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66  n arrangements f
11f40 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74  or.** serializat
11f50 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ion..**.** SQLit
11f60 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76  e will never inv
11f70 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65  oke xInit() more
11f80 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f   than once witho
11f90 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e  ut an intervenin
11fa0 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68  g.** call to xSh
11fb0 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70  utdown()..*/.typ
11fc0 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
11fd0 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20  te3_mem_methods 
11fe0 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
11ff0 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ods;.struct sqli
12000 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20  te3_mem_methods 
12010 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c  {.  void *(*xMal
12020 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20  loc)(int);      
12030 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c     /* Memory all
12040 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e  ocation function
12050 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72   */.  void (*xFr
12060 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  ee)(void*);     
12070 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70       /* Free a p
12080 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
12090 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65  */.  void *(*xRe
120a0 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74  alloc)(void*,int
120b0 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e  );  /* Resize an
120c0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
120d0 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f   int (*xSize)(vo
120e0 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20  id*);           
120f0 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 69  /* Return the si
12100 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74  ze of an allocat
12110 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ion */.  int (*x
12120 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20  Roundup)(int);  
12130 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64          /* Round
12140 20 75 70 20 72 65 71 75 65 73 74 20 73 69 7a 65   up request size
12150 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73   to allocation s
12160 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ize */.  int (*x
12170 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20  Init)(void*);   
12180 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69          /* Initi
12190 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79  alize the memory
121a0 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20   allocator */.  
121b0 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e  void (*xShutdown
121c0 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f  )(void*);      /
121d0 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74  * Deinitialize t
121e0 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
121f0 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70  tor */.  void *p
12200 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20  AppData;        
12210 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d          /* Argum
12220 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61  ent to xInit() a
12230 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a  nd xShutdown() *
12240 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
12250 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74  3REF: Configurat
12260 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b  ion Options.** K
12270 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67  EYWORDS: {config
12280 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a  uration option}.
12290 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
122a0 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76  tants are the av
122b0 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20  ailable integer 
122c0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
122d0 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61  tions that.** ca
122e0 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  n be passed as t
122f0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
12300 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  t to the [sqlite
12310 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  3_config()] inte
12320 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  rface..**.** New
12330 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
12340 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64  ptions may be ad
12350 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
12360 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
12370 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f  ..** Existing co
12380 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
12390 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73  ons might be dis
123a0 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c  continued.  Appl
123b0 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75  ications.** shou
123c0 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74  ld check the ret
123d0 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73  urn code from [s
123e0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
123f0 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
12400 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77  at.** the call w
12410 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c  orked.  The [sql
12420 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69  ite3_config()] i
12430 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65  nterface will re
12440 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65  turn a.** non-ze
12450 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ro [error code] 
12460 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65  if a discontinue
12470 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64  d or unsupported
12480 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
12490 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f  ption.** is invo
124a0 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  ked..**.** <dl>.
124b0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
124c0 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d  IG_SINGLETHREAD]
124d0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
124e0 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
124f0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
12500 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
12510 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
12520 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f  on.  ^This optio
12530 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74  n sets the.** [t
12540 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74  hreading mode] t
12550 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e  o Single-thread.
12560 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
12570 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a  , it disables.**
12580 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e   all mutexing an
12590 64 20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e  d puts SQLite in
125a0 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20  to a mode where 
125b0 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75  it can only be u
125c0 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67  sed.** by a sing
125d0 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66  le thread.   ^If
125e0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
125f0 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
12600 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
12610 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
12620 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
12630 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
12640 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20  en.** it is not 
12650 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e  possible to chan
12660 67 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ge the [threadin
12670 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73  g mode] from its
12680 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75   default.** valu
12690 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65  e of Single-thre
126a0 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74  ad and so [sqlit
126b0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c  e3_config()] wil
126c0 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51  l return .** [SQ
126d0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
126e0 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 53  alled with the S
126f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
12700 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e  GLETHREAD.** con
12710 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
12720 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  n.</dd>.**.** [[
12730 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
12740 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e  LTITHREAD]] <dt>
12750 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
12760 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a  LTITHREAD</dt>.*
12770 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
12780 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
12790 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54  this option.  ^T
127a0 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20  his option sets 
127b0 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e  the.** [threadin
127c0 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69  g mode] to Multi
127d0 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68  -thread.  In oth
127e0 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73  er words, it dis
127f0 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e  ables.** mutexin
12800 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  g on [database c
12810 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b  onnection] and [
12820 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
12830 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20  nt] objects..** 
12840 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
12850 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
12860 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61  or serializing a
12870 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74  ccess to.** [dat
12880 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
12890 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  s] and [prepared
128a0 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42   statements].  B
128b0 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73  ut other mutexes
128c0 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20  .** are enabled 
128d0 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  so that SQLite w
128e0 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75  ill be safe to u
128f0 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68  se in a multi-th
12900 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f  readed.** enviro
12910 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73  nment as long as
12920 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20   no two threads 
12930 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74  attempt to use t
12940 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61  he same.** [data
12950 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
12960 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
12970 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69  e.  ^If SQLite i
12980 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
12990 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
129a0 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
129b0 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
129c0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
129d0 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
129e0 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
129f0 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69  to set the Multi
12a00 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69  -thread [threadi
12a10 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20  ng mode] and.** 
12a20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
12a30 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  )] will return [
12a40 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
12a50 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65   called with the
12a60 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  .** SQLITE_CONFI
12a70 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f  G_MULTITHREAD co
12a80 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
12a90 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  on.</dd>.**.** [
12aa0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
12ab0 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e  ERIALIZED]] <dt>
12ac0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
12ad0 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a  RIALIZED</dt>.**
12ae0 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
12af0 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
12b00 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
12b10 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
12b20 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
12b30 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c   mode] to Serial
12b40 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77  ized. In other w
12b50 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f  ords, this optio
12b60 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c  n enables.** all
12b70 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69   mutexes includi
12b80 6e 67 20 74 68 65 20 72 65 63 75 72 73 69 76 65  ng the recursive
12b90 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b  .** mutexes on [
12ba0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
12bb0 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ion] and [prepar
12bc0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62  ed statement] ob
12bd0 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69  jects..** In thi
12be0 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73  s mode (which is
12bf0 20 74 68 65 20 64 65 66 61 75 6c 74 20 77 68 65   the default whe
12c00 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  n SQLite is comp
12c10 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51  iled with.** [SQ
12c20 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
12c30 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c  1]) the SQLite l
12c40 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65  ibrary will itse
12c50 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63  lf serialize acc
12c60 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62  ess.** to [datab
12c70 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
12c80 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
12c90 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68  tatements] so th
12ca0 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63  at the.** applic
12cb0 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f  ation is free to
12cc0 20 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64   use the same [d
12cd0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
12ce0 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61  on] or the.** sa
12cf0 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  me [prepared sta
12d00 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65  tement] in diffe
12d10 72 65 6e 74 20 74 68 72 65 61 64 73 20 61 74 20  rent threads at 
12d20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a  the same time..*
12d30 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20  * ^If SQLite is 
12d40 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
12d50 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
12d60 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
12d70 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
12d80 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
12d90 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73  on then.** it is
12da0 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f   not possible to
12db0 20 73 65 74 20 74 68 65 20 53 65 72 69 61 6c 69   set the Seriali
12dc0 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  zed [threading m
12dd0 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ode] and.** [sql
12de0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
12df0 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
12e00 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c  TE_ERROR] if cal
12e10 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
12e20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
12e30 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75  RIALIZED configu
12e40 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f  ration option.</
12e50 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
12e60 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
12e70 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
12e80 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e  NFIG_MALLOC</dt>
12e90 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
12ea0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
12eb0 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  LOC option takes
12ec0 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
12ed0 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20  nt which is .** 
12ee0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
12ef0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
12f00 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
12f10 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
12f20 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74  .** The argument
12f30 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c   specifies.** al
12f40 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65  ternative low-le
12f50 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  vel memory alloc
12f60 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74  ation routines t
12f70 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61  o be used in pla
12f80 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d  ce of.** the mem
12f90 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
12fa0 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e  outines built in
12fb0 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51  to SQLite.)^ ^SQ
12fc0 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74  Lite makes.** it
12fd0 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f  s own private co
12fe0 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e  py of the conten
12ff0 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  t of the [sqlite
13000 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73  3_mem_methods] s
13010 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f  tructure.** befo
13020 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  re the [sqlite3_
13030 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72  config()] call r
13040 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a  eturns.</dd>.**.
13050 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
13060 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c  IG_GETMALLOC]] <
13070 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
13080 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a  _GETMALLOC</dt>.
13090 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51  ** <dd> ^(The SQ
130a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
130b0 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b  ALLOC option tak
130c0 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
130d0 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73  ment which.** is
130e0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
130f0 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
13100 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
13110 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
13120 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  ..** The [sqlite
13130 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a  3_mem_methods].*
13140 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66  * structure is f
13150 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63  illed with the c
13160 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
13170 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
13180 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a  on routines.)^.*
13190 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61  * This option ca
131a0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65  n be used to ove
131b0 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c  rload the defaul
131c0 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  t memory allocat
131d0 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ion.** routines 
131e0 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74  with a wrapper t
131f0 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20  hat simulations 
13200 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
13210 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20  n failure or.** 
13220 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73  tracks memory us
13230 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65  age, for example
13240 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  . </dd>.**.** [[
13250 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
13260 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51  MSTATUS]] <dt>SQ
13270 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
13280 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  TATUS</dt>.** <d
13290 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  d> ^The SQLITE_C
132a0 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20  ONFIG_MEMSTATUS 
132b0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e  option takes sin
132c0 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  gle argument of 
132d0 74 79 70 65 20 69 6e 74 2c 0a 2a 2a 20 69 6e 74  type int,.** int
132e0 65 72 70 72 65 74 65 64 20 61 73 20 61 20 62 6f  erpreted as a bo
132f0 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61  olean, which ena
13300 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73  bles or disables
13310 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20   the collection 
13320 6f 66 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c  of.** memory all
13330 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69  ocation statisti
13340 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72  cs. ^(When memor
13350 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  y allocation sta
13360 74 69 73 74 69 63 73 20 61 72 65 0a 2a 2a 20 64  tistics are.** d
13370 69 73 61 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c  isabled, the fol
13380 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e  lowing SQLite in
13390 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20  terfaces become 
133a0 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a  non-operational:
133b0 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20  .**   <ul>.**   
133c0 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65  <li> [sqlite3_me
133d0 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20  mory_used()].** 
133e0 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
133f0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
13400 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ()].**   <li> [s
13410 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70  qlite3_soft_heap
13420 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20  _limit64()].**  
13430 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73   <li> [sqlite3_s
13440 74 61 74 75 73 36 34 28 29 5d 0a 2a 2a 20 20 20  tatus64()].**   
13450 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f  </ul>)^.** ^Memo
13460 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74  ry allocation st
13470 61 74 69 73 74 69 63 73 20 61 72 65 20 65 6e 61  atistics are ena
13480 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20  bled by default 
13490 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73  unless SQLite is
134a0 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  .** compiled wit
134b0 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c  h [SQLITE_DEFAUL
134c0 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69  T_MEMSTATUS]=0 i
134d0 6e 20 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d  n which case mem
134e0 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f  ory.** allocatio
134f0 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65  n statistics are
13500 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
13510 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a  ault..** </dd>.*
13520 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
13530 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c  NFIG_SCRATCH]] <
13540 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
13550 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a  _SCRATCH</dt>.**
13560 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54   <dd> ^The SQLIT
13570 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
13580 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65   option specifie
13590 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72  s a static memor
135a0 79 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74  y buffer.** that
135b0 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20   SQLite can use 
135c0 66 6f 72 20 73 63 72 61 74 63 68 20 6d 65 6d 6f  for scratch memo
135d0 72 79 2e 20 20 5e 28 54 68 65 72 65 20 61 72 65  ry.  ^(There are
135e0 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73   three arguments
135f0 0a 2a 2a 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f  .** to SQLITE_CO
13600 4e 46 49 47 5f 53 43 52 41 54 43 48 3a 20 20 41  NFIG_SCRATCH:  A
13610 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79   pointer an 8-by
13620 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65  te.** aligned me
13630 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d  mory buffer from
13640 20 77 68 69 63 68 20 74 68 65 20 73 63 72 61 74   which the scrat
13650 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77  ch allocations w
13660 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c  ill be.** drawn,
13670 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63   the size of eac
13680 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61  h scratch alloca
13690 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e  tion (sz),.** an
136a0 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d the maximum nu
136b0 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63 68 20  mber of scratch 
136c0 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e  allocations (N).
136d0 29 5e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  )^.** The first 
136e0 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65  argument must be
136f0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
13700 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20   8-byte aligned 
13710 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20  buffer.** of at 
13720 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73  least sz*N bytes
13730 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e   of memory..** ^
13740 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 6f 74 20  SQLite will not 
13750 75 73 65 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  use more than on
13760 65 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72  e scratch buffer
13770 73 20 70 65 72 20 74 68 72 65 61 64 2e 0a 2a 2a  s per thread..**
13780 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65   ^SQLite will ne
13790 76 65 72 20 72 65 71 75 65 73 74 20 61 20 73 63  ver request a sc
137a0 72 61 74 63 68 20 62 75 66 66 65 72 20 74 68 61  ratch buffer tha
137b0 74 20 69 73 20 6d 6f 72 65 20 74 68 61 6e 20 36  t is more than 6
137c0 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65 20 64 61  .** times the da
137d0 74 61 62 61 73 65 20 70 61 67 65 20 73 69 7a 65  tabase page size
137e0 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20  ..** ^If SQLite 
137f0 6e 65 65 64 73 20 6e 65 65 64 73 20 61 64 64 69  needs needs addi
13800 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63  tional.** scratc
13810 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20  h memory beyond 
13820 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64  what is provided
13830 20 62 79 20 74 68 69 73 20 63 6f 6e 66 69 67 75   by this configu
13840 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74  ration option, t
13850 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  hen .** [sqlite3
13860 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20  _malloc()] will 
13870 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  be used to obtai
13880 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65  n the memory nee
13890 64 65 64 2e 3c 70 3e 0a 2a 2a 20 5e 57 68 65 6e  ded.<p>.** ^When
138a0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
138b0 20 70 72 6f 76 69 64 65 73 20 61 6e 79 20 61 6d   provides any am
138c0 6f 75 6e 74 20 6f 66 20 73 63 72 61 74 63 68 20  ount of scratch 
138d0 6d 65 6d 6f 72 79 20 75 73 69 6e 67 0a 2a 2a 20  memory using.** 
138e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
138f0 52 41 54 43 48 2c 20 53 51 4c 69 74 65 20 61 76  RATCH, SQLite av
13900 6f 69 64 73 20 75 6e 6e 65 63 65 73 73 61 72 79  oids unnecessary
13910 20 6c 61 72 67 65 0a 2a 2a 20 5b 73 71 6c 69 74   large.** [sqlit
13920 65 33 5f 6d 61 6c 6c 6f 63 7c 68 65 61 70 20 61  e3_malloc|heap a
13930 6c 6c 6f 63 61 74 69 6f 6e 73 5d 2e 0a 2a 2a 20  llocations]..** 
13940 54 68 69 73 20 63 61 6e 20 68 65 6c 70 20 5b 52  This can help [R
13950 6f 62 73 6f 6e 20 70 72 6f 6f 66 7c 70 72 65 76  obson proof|prev
13960 65 6e 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ent memory alloc
13970 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 73 5d 20  ation failures] 
13980 64 75 65 20 74 6f 20 68 65 61 70 0a 2a 2a 20 66  due to heap.** f
13990 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 20  ragmentation in 
139a0 6c 6f 77 2d 6d 65 6d 6f 72 79 20 65 6d 62 65 64  low-memory embed
139b0 64 65 64 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 20  ded systems..** 
139c0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
139d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
139e0 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49  CACHE]] <dt>SQLI
139f0 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
13a00 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  CHE</dt>.** <dd>
13a10 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e   ^The SQLITE_CON
13a20 46 49 47 5f 50 41 47 45 43 41 43 48 45 20 6f 70  FIG_PAGECACHE op
13a30 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61  tion specifies a
13a40 20 6d 65 6d 6f 72 79 20 70 6f 6f 6c 0a 2a 2a 20   memory pool.** 
13a50 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20  that SQLite can 
13a60 75 73 65 20 66 6f 72 20 74 68 65 20 64 61 74 61  use for the data
13a70 62 61 73 65 20 70 61 67 65 20 63 61 63 68 65 20  base page cache 
13a80 77 69 74 68 20 74 68 65 20 64 65 66 61 75 6c 74  with the default
13a90 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69   page.** cache i
13aa0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20  mplementation.  
13ab0 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75  .** This configu
13ac0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
13ad0 20 61 20 6e 6f 2d 6f 70 20 69 66 20 61 6e 20 61   a no-op if an a
13ae0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
13af0 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20  e page.** cache 
13b00 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
13b10 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74  s loaded using t
13b20 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  he [SQLITE_CONFI
13b30 47 5f 50 43 41 43 48 45 32 5d 2e 0a 2a 2a 20 5e  G_PCACHE2]..** ^
13b40 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20  There are three 
13b50 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c  arguments to SQL
13b60 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
13b70 41 43 48 45 3a 20 41 20 70 6f 69 6e 74 65 72 20  ACHE: A pointer 
13b80 74 6f 0a 2a 2a 20 38 2d 62 79 74 65 20 61 6c 69  to.** 8-byte ali
13b90 67 6e 65 64 20 6d 65 6d 6f 72 79 20 28 70 4d 65  gned memory (pMe
13ba0 6d 29 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20  m), the size of 
13bb0 65 61 63 68 20 70 61 67 65 20 63 61 63 68 65 20  each page cache 
13bc0 6c 69 6e 65 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e  line (sz),.** an
13bd0 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  d the number of 
13be0 63 61 63 68 65 20 6c 69 6e 65 73 20 28 4e 29 2e  cache lines (N).
13bf0 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d  .** The sz argum
13c00 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68  ent should be th
13c10 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61  e size of the la
13c20 72 67 65 73 74 20 64 61 74 61 62 61 73 65 20 70  rgest database p
13c30 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20  age.** (a power 
13c40 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35  of two between 5
13c50 31 32 20 61 6e 64 20 36 35 35 33 36 29 20 70 6c  12 and 65536) pl
13c60 75 73 20 73 6f 6d 65 20 65 78 74 72 61 20 62 79  us some extra by
13c70 74 65 73 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20  tes for each.** 
13c80 70 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54  page header.  ^T
13c90 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74  he number of ext
13ca0 72 61 20 62 79 74 65 73 20 6e 65 65 64 65 64 20  ra bytes needed 
13cb0 62 79 20 74 68 65 20 70 61 67 65 20 68 65 61 64  by the page head
13cc0 65 72 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74  er.** can be det
13cd0 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 20 5b 53  ermined using [S
13ce0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
13cf0 43 48 45 5f 48 44 52 53 5a 5d 2e 0a 2a 2a 20 5e  CHE_HDRSZ]..** ^
13d00 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20  It is harmless, 
13d10 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77  apart from the w
13d20 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a  asted memory,.**
13d30 20 66 6f 72 20 74 68 65 20 73 7a 20 70 61 72 61   for the sz para
13d40 6d 65 74 65 72 20 74 6f 20 62 65 20 6c 61 72 67  meter to be larg
13d50 65 72 20 74 68 61 6e 20 6e 65 63 65 73 73 61 72  er than necessar
13d60 79 2e 20 20 54 68 65 20 70 4d 65 6d 0a 2a 2a 20  y.  The pMem.** 
13d70 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65  argument must be
13d80 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70   either a NULL p
13d90 6f 69 6e 74 65 72 20 6f 72 20 61 20 70 6f 69 6e  ointer or a poin
13da0 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ter to an 8-byte
13db0 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 62 6c 6f 63  .** aligned bloc
13dc0 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 6f 66 20 61  k of memory of a
13dd0 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74  t least sz*N byt
13de0 65 73 2c 20 6f 74 68 65 72 77 69 73 65 0a 2a 2a  es, otherwise.**
13df0 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61   subsequent beha
13e00 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
13e10 64 2e 0a 2a 2a 20 5e 57 68 65 6e 20 70 4d 65 6d  d..** ^When pMem
13e20 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51   is not NULL, SQ
13e30 4c 69 74 65 20 77 69 6c 6c 20 73 74 72 69 76 65  Lite will strive
13e40 20 74 6f 20 75 73 65 20 74 68 65 20 6d 65 6d 6f   to use the memo
13e50 72 79 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 74  ry provided.** t
13e60 6f 20 73 61 74 69 73 66 79 20 70 61 67 65 20 63  o satisfy page c
13e70 61 63 68 65 20 6e 65 65 64 73 2c 20 66 61 6c 6c  ache needs, fall
13e80 69 6e 67 20 62 61 63 6b 20 74 6f 20 5b 73 71 6c  ing back to [sql
13e90 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69  ite3_malloc()] i
13ea0 66 0a 2a 2a 20 61 20 70 61 67 65 20 63 61 63 68  f.** a page cach
13eb0 65 20 6c 69 6e 65 20 69 73 20 6c 61 72 67 65 72  e line is larger
13ec0 20 74 68 61 6e 20 73 7a 20 62 79 74 65 73 20 6f   than sz bytes o
13ed0 72 20 69 66 20 61 6c 6c 20 6f 66 20 74 68 65 20  r if all of the 
13ee0 70 4d 65 6d 20 62 75 66 66 65 72 0a 2a 2a 20 69  pMem buffer.** i
13ef0 73 20 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20  s exhausted..** 
13f00 5e 49 66 20 70 4d 65 6d 20 69 73 20 4e 55 4c 4c  ^If pMem is NULL
13f10 20 61 6e 64 20 4e 20 69 73 20 6e 6f 6e 2d 7a 65   and N is non-ze
13f20 72 6f 2c 20 74 68 65 6e 20 65 61 63 68 20 64 61  ro, then each da
13f30 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
13f40 6e 0a 2a 2a 20 64 6f 65 73 20 61 6e 20 69 6e 69  n.** does an ini
13f50 74 69 61 6c 20 62 75 6c 6b 20 61 6c 6c 6f 63 61  tial bulk alloca
13f60 74 69 6f 6e 20 66 6f 72 20 70 61 67 65 20 63 61  tion for page ca
13f70 63 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 66 72  che memory.** fr
13f80 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
13f90 6f 63 28 29 5d 20 73 75 66 66 69 63 69 65 6e 74  oc()] sufficient
13fa0 20 66 6f 72 20 4e 20 63 61 63 68 65 20 6c 69 6e   for N cache lin
13fb0 65 73 20 69 66 20 4e 20 69 73 20 70 6f 73 69 74  es if N is posit
13fc0 69 76 65 20 6f 72 0a 2a 2a 20 6f 66 20 2d 31 30  ive or.** of -10
13fd0 32 34 2a 4e 20 62 79 74 65 73 20 69 66 20 4e 20  24*N bytes if N 
13fe0 69 73 20 6e 65 67 61 74 69 76 65 2c 20 2e 20 5e  is negative, . ^
13ff0 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  If additional.**
14000 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f   page cache memo
14010 72 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 79  ry is needed bey
14020 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76  ond what is prov
14030 69 64 65 64 20 62 79 20 74 68 65 20 69 6e 69 74  ided by the init
14040 69 61 6c 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f  ial.** allocatio
14050 6e 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 67  n, then SQLite g
14060 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  oes to [sqlite3_
14070 6d 61 6c 6c 6f 63 28 29 5d 20 73 65 70 61 72 61  malloc()] separa
14080 74 65 6c 79 20 66 6f 72 20 65 61 63 68 0a 2a 2a  tely for each.**
14090 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 61 63 68   additional cach
140a0 65 20 6c 69 6e 65 2e 20 3c 2f 64 64 3e 0a 2a 2a  e line. </dd>.**
140b0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
140c0 46 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53  FIG_HEAP]] <dt>S
140d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
140e0 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  P</dt>.** <dd> ^
140f0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
14100 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20 73 70  G_HEAP option sp
14110 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63  ecifies a static
14120 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 0a   memory buffer .
14130 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  ** that SQLite w
14140 69 6c 6c 20 75 73 65 20 66 6f 72 20 61 6c 6c 20  ill use for all 
14150 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d  of its dynamic m
14160 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
14170 20 6e 65 65 64 73 0a 2a 2a 20 62 65 79 6f 6e 64   needs.** beyond
14180 20 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64 20   those provided 
14190 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43  for by [SQLITE_C
141a0 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61  ONFIG_SCRATCH] a
141b0 6e 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  nd.** [SQLITE_CO
141c0 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e  NFIG_PAGECACHE].
141d0 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  .** ^The SQLITE_
141e0 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 69  CONFIG_HEAP opti
141f0 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c  on is only avail
14200 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69  able if SQLite i
14210 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69  s compiled.** wi
14220 74 68 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  th either [SQLIT
14230 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33  E_ENABLE_MEMSYS3
14240 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41  ] or [SQLITE_ENA
14250 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 6e 64  BLE_MEMSYS5] and
14260 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c   returns.** [SQL
14270 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 69 6e  ITE_ERROR] if in
14280 76 6f 6b 65 64 20 6f 74 68 65 72 77 69 73 65 2e  voked otherwise.
14290 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72 65 20 74  .** ^There are t
142a0 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74  hree arguments t
142b0 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  o SQLITE_CONFIG_
142c0 48 45 41 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79  HEAP:.** An 8-by
142d0 74 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74  te aligned point
142e0 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79  er to the memory
142f0 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  ,.** the number 
14300 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
14310 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61  memory buffer, a
14320 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61  nd the minimum a
14330 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a  llocation size..
14340 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73 74  ** ^If the first
14350 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65   pointer (the me
14360 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73  mory pointer) is
14370 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69   NULL, then SQLi
14380 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f  te reverts.** to
14390 20 75 73 69 6e 67 20 69 74 73 20 64 65 66 61 75   using its defau
143a0 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  lt memory alloca
143b0 74 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d 20  tor (the system 
143c0 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65  malloc() impleme
143d0 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64  ntation),.** und
143e0 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69  oing any prior i
143f0 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51  nvocation of [SQ
14400 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
14410 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  OC].  ^If the.**
14420 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20   memory pointer 
14430 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e  is not NULL then
14440 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65   the alternative
14450 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
14460 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20  ator is engaged 
14470 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66  to handle all of
14480 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20   SQLites memory 
14490 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
144a0 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70  ..** The first p
144b0 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f  ointer (the memo
144c0 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74  ry pointer) must
144d0 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61   be aligned to a
144e0 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e  n 8-byte.** boun
144f0 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65  dary or subseque
14500 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53  nt behavior of S
14510 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e  QLite will be un
14520 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20  defined..** The 
14530 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69  minimum allocati
14540 6f 6e 20 73 69 7a 65 20 69 73 20 63 61 70 70 65  on size is cappe
14550 64 20 61 74 20 32 2a 2a 31 32 2e 20 52 65 61 73  d at 2**12. Reas
14560 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a  onable values.**
14570 20 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d   for the minimum
14580 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
14590 20 61 72 65 20 32 2a 2a 35 20 74 68 72 6f 75 67   are 2**5 throug
145a0 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a  h 2**8.</dd>.**.
145b0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
145c0 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53  IG_MUTEX]] <dt>S
145d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
145e0 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  EX</dt>.** <dd> 
145f0 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  ^(The SQLITE_CON
14600 46 49 47 5f 4d 55 54 45 58 20 6f 70 74 69 6f 6e  FIG_MUTEX option
14610 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
14620 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
14630 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  s a.** pointer t
14640 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
14650 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
14660 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
14670 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61  ucture..** The a
14680 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65  rgument specifie
14690 73 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f  s alternative lo
146a0 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f  w-level mutex ro
146b0 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65  utines to be use
146c0 64 0a 2a 2a 20 69 6e 20 70 6c 61 63 65 20 74 68  d.** in place th
146d0 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73  e mutex routines
146e0 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69   built into SQLi
146f0 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d  te.)^  ^SQLite m
14700 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a  akes a copy of.*
14710 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  * the content of
14720 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
14730 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
14740 75 63 74 75 72 65 20 62 65 66 6f 72 65 20 74 68  ucture before th
14750 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  e call to.** [sq
14760 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
14770 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c  returns. ^If SQL
14780 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
14790 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
147a0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
147b0 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
147c0 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
147d0 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
147e0 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74  * the entire mut
147f0 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20  exing subsystem 
14800 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  is omitted from 
14810 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65  the build and he
14820 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  nce calls to.** 
14830 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
14840 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  )] with the SQLI
14850 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20  TE_CONFIG_MUTEX 
14860 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
14870 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74  tion will.** ret
14880 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
14890 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  R].</dd>.**.** [
148a0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
148b0 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51  ETMUTEX]] <dt>SQ
148c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
148d0 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  UTEX</dt>.** <dd
148e0 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43  > ^(The SQLITE_C
148f0 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 6f  ONFIG_GETMUTEX o
14900 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
14910 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
14920 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e  ich.** is a poin
14930 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
14940 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
14950 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
14960 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  ] structure.  Th
14970 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75  e.** [sqlite3_mu
14980 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  tex_methods].** 
14990 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c  structure is fil
149a0 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72  led with the cur
149b0 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d  rently defined m
149c0 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e  utex routines.)^
149d0 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  .** This option 
149e0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
149f0 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61  verload the defa
14a00 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61  ult mutex alloca
14a10 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  tion.** routines
14a20 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20   with a wrapper 
14a30 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75  used to track mu
14a40 74 65 78 20 75 73 61 67 65 20 66 6f 72 20 70 65  tex usage for pe
14a50 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f  rformance.** pro
14a60 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e  filing or testin
14a70 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20  g, for example. 
14a80 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20    ^If SQLite is 
14a90 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
14aa0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
14ab0 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
14ac0 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
14ad0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
14ae0 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65  on then.** the e
14af0 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73  ntire mutexing s
14b00 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74  ubsystem is omit
14b10 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69  ted from the bui
14b20 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c  ld and hence cal
14b30 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ls to.** [sqlite
14b40 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68  3_config()] with
14b50 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
14b60 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66  IG_GETMUTEX conf
14b70 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
14b80 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20   will.** return 
14b90 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c  [SQLITE_ERROR].<
14ba0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
14bb0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
14bc0 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  SIDE]] <dt>SQLIT
14bd0 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
14be0 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  DE</dt>.** <dd> 
14bf0 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  ^(The SQLITE_CON
14c00 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f 70  FIG_LOOKASIDE op
14c10 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61  tion takes two a
14c20 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65  rguments that de
14c30 74 65 72 6d 69 6e 65 0a 2a 2a 20 74 68 65 20 64  termine.** the d
14c40 65 66 61 75 6c 74 20 73 69 7a 65 20 6f 66 20 6c  efault size of l
14c50 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
14c60 6f 6e 20 65 61 63 68 20 5b 64 61 74 61 62 61 73  on each [databas
14c70 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a  e connection]..*
14c80 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
14c90 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73  ment is the.** s
14ca0 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b  ize of each look
14cb0 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f  aside buffer slo
14cc0 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  t and the second
14cd0 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
14ce0 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63  f.** slots alloc
14cf0 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 74  ated to each dat
14d00 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
14d10 2e 29 5e 20 20 5e 28 53 51 4c 49 54 45 5f 43 4f  .)^  ^(SQLITE_CO
14d20 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a  NFIG_LOOKASIDE.*
14d30 2a 20 73 65 74 73 20 74 68 65 20 3c 69 3e 64 65  * sets the <i>de
14d40 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73  fault</i> lookas
14d50 69 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53  ide size. The [S
14d60 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
14d70 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 6f 70 74  OOKASIDE].** opt
14d80 69 6f 6e 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ion to [sqlite3_
14d90 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e  db_config()] can
14da0 20 62 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e   be used to chan
14db0 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65  ge the lookaside
14dc0 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  .** configuratio
14dd0 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20  n on individual 
14de0 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c  connections.)^ <
14df0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
14e00 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
14e10 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  E2]] <dt>SQLITE_
14e20 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 3c 2f  CONFIG_PCACHE2</
14e30 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
14e40 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14e50 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74  PCACHE2 option t
14e60 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
14e70 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
14e80 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
14e90 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61   an [sqlite3_pca
14ea0 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62  che_methods2] ob
14eb0 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65  ject.  This obje
14ec0 63 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  ct specifies.** 
14ed0 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f  the interface to
14ee0 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63   a custom page c
14ef0 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
14f00 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74  ion.)^.** ^SQLit
14f10 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
14f20 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70  f the [sqlite3_p
14f30 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20  cache_methods2] 
14f40 6f 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a  object.</dd>.**.
14f50 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
14f60 49 47 5f 47 45 54 50 43 41 43 48 45 32 5d 5d 20  IG_GETPCACHE2]] 
14f70 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
14f80 47 5f 47 45 54 50 43 41 43 48 45 32 3c 2f 64 74  G_GETPCACHE2</dt
14f90 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20  >.** <dd> ^(The 
14fa0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
14fb0 54 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20  TPCACHE2 option 
14fc0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
14fd0 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a  rgument which.**
14fe0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
14ff0 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61   an [sqlite3_pca
15000 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62  che_methods2] ob
15010 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f  ject.  SQLite co
15020 70 69 65 73 20 6f 66 0a 2a 2a 20 74 68 65 20 63  pies of.** the c
15030 75 72 72 65 6e 74 20 70 61 67 65 20 63 61 63 68  urrent page cach
15040 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
15050 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63   into that objec
15060 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  t.)^ </dd>.**.**
15070 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
15080 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  _LOG]] <dt>SQLIT
15090 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74  E_CONFIG_LOG</dt
150a0 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53 51  >.** <dd> The SQ
150b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
150c0 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  option is used t
150d0 6f 20 63 6f 6e 66 69 67 75 72 65 20 74 68 65 20  o configure the 
150e0 53 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c  SQLite.** global
150f0 20 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a   [error log]..**
15100 20 28 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   (^The SQLITE_CO
15110 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20  NFIG_LOG option 
15120 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65  takes two argume
15130 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74  nts: a pointer t
15140 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  o a.** function 
15150 77 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e  with a call sign
15160 61 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29  ature of void(*)
15170 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
15180 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64   char*), .** and
15190 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f   a pointer to vo
151a0 69 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63  id. ^If the func
151b0 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20  tion pointer is 
151c0 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a  not NULL, it is.
151d0 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73  ** invoked by [s
151e0 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f  qlite3_log()] to
151f0 20 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f   process each lo
15200 67 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49  gging event.  ^I
15210 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  f the.** functio
15220 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c  n pointer is NUL
15230 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  L, the [sqlite3_
15240 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  log()] interface
15250 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70   becomes a no-op
15260 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70  ..** ^The void p
15270 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 74  ointer that is t
15280 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
15290 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e  nt to SQLITE_CON
152a0 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61  FIG_LOG is.** pa
152b0 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20  ssed through as 
152c0 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
152d0 74 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69  ter to the appli
152e0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c  cation-defined l
152f0 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  ogger.** functio
15300 6e 20 77 68 65 6e 65 76 65 72 20 74 68 61 74 20  n whenever that 
15310 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f  function is invo
15320 6b 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e  ked.  ^The secon
15330 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  d parameter to.*
15340 2a 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e  * the logger fun
15350 63 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20  ction is a copy 
15360 6f 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72  of the first par
15370 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f  ameter to the co
15380 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b  rresponding.** [
15390 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63  sqlite3_log()] c
153a0 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e  all and is inten
153b0 64 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73  ded to be a [res
153c0 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a  ult code] or an.
153d0 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
153e0 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65  ult code].  ^The
153f0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
15400 20 70 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c   passed to the l
15410 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20  ogger is.** log 
15420 6d 65 73 73 61 67 65 20 61 66 74 65 72 20 66 6f  message after fo
15430 72 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71  rmatting via [sq
15440 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
15450 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  ]..** The SQLite
15460 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61   logging interfa
15470 63 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72  ce is not reentr
15480 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20  ant; the logger 
15490 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70  function.** supp
154a0 6c 69 65 64 20 62 79 20 74 68 65 20 61 70 70 6c  lied by the appl
154b0 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
154c0 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69   invoke any SQLi
154d0 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  te interface..**
154e0 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65   In a multi-thre
154f0 61 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e  aded application
15500 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  , the applicatio
15510 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72  n-defined logger
15520 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  .** function mus
15530 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e  t be threadsafe.
15540 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
15550 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
15560 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
15570 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e  NFIG_URI.** <dd>
15580 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  ^(The SQLITE_CON
15590 46 49 47 5f 55 52 49 20 6f 70 74 69 6f 6e 20 74  FIG_URI option t
155a0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
155b0 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69  gument of type i
155c0 6e 74 2e 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65  nt..** If non-ze
155d0 72 6f 2c 20 74 68 65 6e 20 55 52 49 20 68 61 6e  ro, then URI han
155e0 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c  dling is globall
155f0 79 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 74 68  y enabled. If th
15600 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 7a  e parameter is z
15610 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 55 52 49  ero,.** then URI
15620 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f   handling is glo
15630 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e 29  bally disabled.)
15640 5e 20 5e 49 66 20 55 52 49 20 68 61 6e 64 6c 69  ^ ^If URI handli
15650 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a  ng is globally.*
15660 2a 20 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66  * enabled, all f
15670 69 6c 65 6e 61 6d 65 73 20 70 61 73 73 65 64 20  ilenames passed 
15680 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
15690 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
156a0 65 6e 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71  en_v2()],.** [sq
156b0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20  lite3_open16()] 
156c0 6f 72 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20  or.** specified 
156d0 61 73 20 70 61 72 74 20 6f 66 20 5b 41 54 54 41  as part of [ATTA
156e0 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65  CH] commands are
156f0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
15700 55 52 49 73 2c 20 72 65 67 61 72 64 6c 65 73 73  URIs, regardless
15710 0a 2a 2a 20 6f 66 20 77 68 65 74 68 65 72 20 6f  .** of whether o
15720 72 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54  r not the [SQLIT
15730 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67  E_OPEN_URI] flag
15740 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65   is set when the
15750 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
15760 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65  nection is opene
15770 64 2e 20 5e 49 66 20 69 74 20 69 73 20 67 6c 6f  d. ^If it is glo
15780 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c 20  bally disabled, 
15790 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a  filenames are.**
157a0 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65 74 65   only interprete
157b0 64 20 61 73 20 55 52 49 73 20 69 66 20 74 68 65  d as URIs if the
157c0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49   SQLITE_OPEN_URI
157d0 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65   flag is set whe
157e0 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  n the.** databas
157f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
15800 6f 70 65 6e 65 64 2e 20 5e 28 42 79 20 64 65 66  opened. ^(By def
15810 61 75 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c 69  ault, URI handli
15820 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a  ng is globally.*
15830 2a 20 64 69 73 61 62 6c 65 64 2e 20 54 68 65 20  * disabled. The 
15840 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6d 61  default value ma
15850 79 20 62 65 20 63 68 61 6e 67 65 64 20 62 79 20  y be changed by 
15860 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 74  compiling with t
15870 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53  he.** [SQLITE_US
15880 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65  E_URI] symbol de
15890 66 69 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  fined.)^.**.** [
158a0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43  [SQLITE_CONFIG_C
158b0 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43  OVERING_INDEX_SC
158c0 41 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  AN]] <dt>SQLITE_
158d0 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f  CONFIG_COVERING_
158e0 49 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64  INDEX_SCAN.** <d
158f0 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  d>^The SQLITE_CO
15900 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e  NFIG_COVERING_IN
15910 44 45 58 5f 53 43 41 4e 20 6f 70 74 69 6f 6e 20  DEX_SCAN option 
15920 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 69  takes a single i
15930 6e 74 65 67 65 72 0a 2a 2a 20 61 72 67 75 6d 65  nteger.** argume
15940 6e 74 20 77 68 69 63 68 20 69 73 20 69 6e 74 65  nt which is inte
15950 72 70 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f  rpreted as a boo
15960 6c 65 61 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f  lean in order to
15970 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62   enable or disab
15980 6c 65 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66  le.** the use of
15990 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65   covering indice
159a0 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65  s for full table
159b0 20 73 63 61 6e 73 20 69 6e 20 74 68 65 20 71 75   scans in the qu
159c0 65 72 79 20 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a  ery optimizer..*
159d0 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73  * ^The default s
159e0 65 74 74 69 6e 67 20 69 73 20 64 65 74 65 72 6d  etting is determ
159f0 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b  ined.** by the [
15a00 53 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56  SQLITE_ALLOW_COV
15a10 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e  ERING_INDEX_SCAN
15a20 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
15a30 70 74 69 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e  ption, or is "on
15a40 22 0a 2a 2a 20 69 66 20 74 68 61 74 20 63 6f 6d  ".** if that com
15a50 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
15a60 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20   is omitted..** 
15a70 54 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 64  The ability to d
15a80 69 73 61 62 6c 65 20 74 68 65 20 75 73 65 20 6f  isable the use o
15a90 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63  f covering indic
15aa0 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c  es for full tabl
15ab0 65 20 73 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65  e scans.** is be
15ac0 63 61 75 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72  cause some incor
15ad0 72 65 63 74 6c 79 20 63 6f 64 65 64 20 6c 65 67  rectly coded leg
15ae0 61 63 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  acy applications
15af0 20 6d 69 67 68 74 20 6d 61 6c 66 75 6e 63 74 69   might malfuncti
15b00 6f 6e 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 6f  on.** when the o
15b10 70 74 69 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65  ptimization is e
15b20 6e 61 62 6c 65 64 2e 20 20 50 72 6f 76 69 64 69  nabled.  Providi
15b30 6e 67 20 74 68 65 20 61 62 69 6c 69 74 79 20 74  ng the ability t
15b40 6f 0a 2a 2a 20 64 69 73 61 62 6c 65 20 74 68 65  o.** disable the
15b50 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c   optimization al
15b60 6c 6f 77 73 20 74 68 65 20 6f 6c 64 65 72 2c 20  lows the older, 
15b70 62 75 67 67 79 20 61 70 70 6c 69 63 61 74 69 6f  buggy applicatio
15b80 6e 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a  n code to work.*
15b90 2a 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 65  * without change
15ba0 20 65 76 65 6e 20 77 69 74 68 20 6e 65 77 65 72   even with newer
15bb0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
15bc0 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  ite..**.** [[SQL
15bd0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
15be0 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  E]] [[SQLITE_CON
15bf0 46 49 47 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a  FIG_GETPCACHE]].
15c00 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
15c10 4e 46 49 47 5f 50 43 41 43 48 45 20 61 6e 64 20  NFIG_PCACHE and 
15c20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
15c30 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20  TPCACHE.** <dd> 
15c40 54 68 65 73 65 20 6f 70 74 69 6f 6e 73 20 61 72  These options ar
15c50 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20 73  e obsolete and s
15c60 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65  hould not be use
15c70 64 20 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a  d by new code..*
15c80 2a 20 54 68 65 79 20 61 72 65 20 72 65 74 61 69  * They are retai
15c90 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64  ned for backward
15ca0 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  s compatibility 
15cb0 62 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f  but are now no-o
15cc0 70 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a  ps..** </dd>.**.
15cd0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
15ce0 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c  IG_SQLLOG]].** <
15cf0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
15d00 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54  _SQLLOG.** <dd>T
15d10 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e  his option is on
15d20 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20  ly available if 
15d30 73 71 6c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  sqlite is compil
15d40 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  ed with the.** [
15d50 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 51  SQLITE_ENABLE_SQ
15d60 4c 4c 4f 47 5d 20 70 72 65 2d 70 72 6f 63 65 73  LLOG] pre-proces
15d70 73 6f 72 20 6d 61 63 72 6f 20 64 65 66 69 6e 65  sor macro define
15d80 64 2e 20 54 68 65 20 66 69 72 73 74 20 61 72 67  d. The first arg
15d90 75 6d 65 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20  ument should.** 
15da0 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  be a pointer to 
15db0 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79  a function of ty
15dc0 70 65 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  pe void(*)(void*
15dd0 2c 73 71 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20  ,sqlite3*,const 
15de0 63 68 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20  char*, int)..** 
15df0 54 68 65 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c  The second shoul
15e00 64 20 62 65 20 6f 66 20 74 79 70 65 20 28 76 6f  d be of type (vo
15e10 69 64 2a 29 2e 20 54 68 65 20 63 61 6c 6c 62 61  id*). The callba
15e20 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79  ck is invoked by
15e30 20 74 68 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20   the library.** 
15e40 69 6e 20 74 68 72 65 65 20 73 65 70 61 72 61 74  in three separat
15e50 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c  e circumstances,
15e60 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74   identified by t
15e70 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20  he value passed 
15e80 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68  as the.** fourth
15e90 20 70 61 72 61 6d 65 74 65 72 2e 20 49 66 20 74   parameter. If t
15ea0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
15eb0 74 65 72 20 69 73 20 30 2c 20 74 68 65 6e 20 74  ter is 0, then t
15ec0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
15ed0 65 63 74 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64  ection.** passed
15ee0 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   as the second a
15ef0 72 67 75 6d 65 6e 74 20 68 61 73 20 6a 75 73 74  rgument has just
15f00 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68   been opened. Th
15f10 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
15f20 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 61 20  .** points to a 
15f30 62 75 66 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e  buffer containin
15f40 67 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  g the name of th
15f50 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20  e main database 
15f60 66 69 6c 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20  file. If the.** 
15f70 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
15f80 20 69 73 20 31 2c 20 74 68 65 6e 20 74 68 65 20   is 1, then the 
15f90 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68  SQL statement th
15fa0 61 74 20 74 68 65 20 74 68 69 72 64 20 70 61 72  at the third par
15fb0 61 6d 65 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73  ameter.** points
15fc0 20 74 6f 20 68 61 73 20 6a 75 73 74 20 62 65 65   to has just bee
15fd0 6e 20 65 78 65 63 75 74 65 64 2e 20 4f 72 2c 20  n executed. Or, 
15fe0 69 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  if the fourth pa
15ff0 72 61 6d 65 74 65 72 20 69 73 20 32 2c 20 74 68  rameter is 2, th
16000 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63  en.** the connec
16010 74 69 6f 6e 20 62 65 69 6e 67 20 70 61 73 73 65  tion being passe
16020 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
16030 70 61 72 61 6d 65 74 65 72 20 69 73 20 62 65 69  parameter is bei
16040 6e 67 20 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a  ng closed. The.*
16050 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  * third paramete
16060 72 20 69 73 20 70 61 73 73 65 64 20 4e 55 4c 4c  r is passed NULL
16070 20 49 6e 20 74 68 69 73 20 63 61 73 65 2e 20 20   In this case.  
16080 41 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 75 73  An example of us
16090 69 6e 67 20 74 68 69 73 0a 2a 2a 20 63 6f 6e 66  ing this.** conf
160a0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
160b0 20 63 61 6e 20 62 65 20 73 65 65 6e 20 69 6e 20   can be seen in 
160c0 74 68 65 20 22 74 65 73 74 5f 73 71 6c 6c 6f 67  the "test_sqllog
160d0 2e 63 22 20 73 6f 75 72 63 65 20 66 69 6c 65 20  .c" source file 
160e0 69 6e 0a 2a 2a 20 74 68 65 20 63 61 6e 6f 6e 69  in.** the canoni
160f0 63 61 6c 20 53 51 4c 69 74 65 20 73 6f 75 72 63  cal SQLite sourc
16100 65 20 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a  e tree.</dd>.**.
16110 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
16120 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a  IG_MMAP_SIZE]].*
16130 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
16140 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a  FIG_MMAP_SIZE.**
16150 20 3c 64 64 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e   <dd>^SQLITE_CON
16160 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 74 61  FIG_MMAP_SIZE ta
16170 6b 65 73 20 74 77 6f 20 36 34 2d 62 69 74 20 69  kes two 64-bit i
16180 6e 74 65 67 65 72 20 28 73 71 6c 69 74 65 33 5f  nteger (sqlite3_
16190 69 6e 74 36 34 29 20 76 61 6c 75 65 73 0a 2a 2a  int64) values.**
161a0 20 74 68 61 74 20 61 72 65 20 74 68 65 20 64 65   that are the de
161b0 66 61 75 6c 74 20 6d 6d 61 70 20 73 69 7a 65 20  fault mmap size 
161c0 6c 69 6d 69 74 20 28 74 68 65 20 64 65 66 61 75  limit (the defau
161d0 6c 74 20 73 65 74 74 69 6e 67 20 66 6f 72 0a 2a  lt setting for.*
161e0 2a 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73  * [PRAGMA mmap_s
161f0 69 7a 65 5d 29 20 61 6e 64 20 74 68 65 20 6d 61  ize]) and the ma
16200 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d  ximum allowed mm
16210 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a  ap size limit..*
16220 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73  * ^The default s
16230 65 74 74 69 6e 67 20 63 61 6e 20 62 65 20 6f 76  etting can be ov
16240 65 72 72 69 64 64 65 6e 20 62 79 20 65 61 63 68  erridden by each
16250 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
16260 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 65 69  tion using.** ei
16270 74 68 65 72 20 74 68 65 20 5b 50 52 41 47 4d 41  ther the [PRAGMA
16280 20 6d 6d 61 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d   mmap_size] comm
16290 61 6e 64 2c 20 6f 72 20 62 79 20 75 73 69 6e 67  and, or by using
162a0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
162b0 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d  FCNTL_MMAP_SIZE]
162c0 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20 20   file control.  
162d0 5e 28 54 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c  ^(The maximum al
162e0 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a  lowed mmap size.
162f0 2a 2a 20 77 69 6c 6c 20 62 65 20 73 69 6c 65 6e  ** will be silen
16300 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 69 66  tly truncated if
16310 20 6e 65 63 65 73 73 61 72 79 20 73 6f 20 74 68   necessary so th
16320 61 74 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 65  at it does not e
16330 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 63 6f 6d  xceed the.** com
16340 70 69 6c 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75  pile-time maximu
16350 6d 20 6d 6d 61 70 20 73 69 7a 65 20 73 65 74 20  m mmap size set 
16360 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  by the.** [SQLIT
16370 45 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d  E_MAX_MMAP_SIZE]
16380 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
16390 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65  tion.)^.** ^If e
163a0 69 74 68 65 72 20 61 72 67 75 6d 65 6e 74 20 74  ither argument t
163b0 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73  o this option is
163c0 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
163d0 74 68 61 74 20 61 72 67 75 6d 65 6e 74 20 69 73  that argument is
163e0 0a 2a 2a 20 63 68 61 6e 67 65 64 20 74 6f 20 69  .** changed to i
163f0 74 73 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  ts compile-time 
16400 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b  default..**.** [
16410 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57  [SQLITE_CONFIG_W
16420 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a  IN32_HEAPSIZE]].
16430 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
16440 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53  NFIG_WIN32_HEAPS
16450 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20  IZE.** <dd>^The 
16460 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49  SQLITE_CONFIG_WI
16470 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 6f 70 74  N32_HEAPSIZE opt
16480 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69  ion is only avai
16490 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20  lable if SQLite 
164a0 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 66  is.** compiled f
164b0 6f 72 20 57 69 6e 64 6f 77 73 20 77 69 74 68 20  or Windows with 
164c0 74 68 65 20 5b 53 51 4c 49 54 45 5f 57 49 4e 33  the [SQLITE_WIN3
164d0 32 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d 70 72  2_MALLOC] pre-pr
164e0 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a  ocessor macro.**
164f0 20 64 65 66 69 6e 65 64 2e 20 5e 53 51 4c 49 54   defined. ^SQLIT
16500 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48  E_CONFIG_WIN32_H
16510 45 41 50 53 49 5a 45 20 74 61 6b 65 73 20 61 20  EAPSIZE takes a 
16520 33 32 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20  32-bit unsigned 
16530 69 6e 74 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a  integer value.**
16540 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 20   that specifies 
16550 74 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65  the maximum size
16560 20 6f 66 20 74 68 65 20 63 72 65 61 74 65 64 20   of the created 
16570 68 65 61 70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  heap..**.** [[SQ
16580 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
16590 48 45 5f 48 44 52 53 5a 5d 5d 0a 2a 2a 20 3c 64  HE_HDRSZ]].** <d
165a0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
165b0 50 43 41 43 48 45 5f 48 44 52 53 5a 0a 2a 2a 20  PCACHE_HDRSZ.** 
165c0 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f  <dd>^The SQLITE_
165d0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44  CONFIG_PCACHE_HD
165e0 52 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  RSZ option takes
165f0 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65   a single parame
16600 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ter which.** is 
16610 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
16620 69 6e 74 65 67 65 72 20 61 6e 64 20 77 72 69 74  integer and writ
16630 65 73 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74  es into that int
16640 65 67 65 72 20 74 68 65 20 6e 75 6d 62 65 72 20  eger the number 
16650 6f 66 20 65 78 74 72 61 0a 2a 2a 20 62 79 74 65  of extra.** byte
16660 73 20 70 65 72 20 70 61 67 65 20 72 65 71 75 69  s per page requi
16670 72 65 64 20 66 6f 72 20 65 61 63 68 20 70 61 67  red for each pag
16680 65 20 69 6e 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  e in [SQLITE_CON
16690 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a  FIG_PAGECACHE]..
166a0 2a 2a 20 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66  ** The amount of
166b0 20 65 78 74 72 61 20 73 70 61 63 65 20 72 65 71   extra space req
166c0 75 69 72 65 64 20 63 61 6e 20 63 68 61 6e 67 65  uired can change
166d0 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
166e0 65 20 63 6f 6d 70 69 6c 65 72 2c 0a 2a 2a 20 74  e compiler,.** t
166f0 61 72 67 65 74 20 70 6c 61 74 66 6f 72 6d 2c 20  arget platform, 
16700 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69  and SQLite versi
16710 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  on..**.** [[SQLI
16720 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 5d  TE_CONFIG_PMASZ]
16730 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
16740 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 0a 2a 2a 20  CONFIG_PMASZ.** 
16750 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f  <dd>^The SQLITE_
16760 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 6f 70 74  CONFIG_PMASZ opt
16770 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
16780 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 69  le parameter whi
16790 63 68 0a 2a 2a 20 69 73 20 61 6e 20 75 6e 73 69  ch.** is an unsi
167a0 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64  gned integer and
167b0 20 73 65 74 73 20 74 68 65 20 22 4d 69 6e 69 6d   sets the "Minim
167c0 75 6d 20 50 4d 41 20 53 69 7a 65 22 20 66 6f 72  um PMA Size" for
167d0 20 74 68 65 20 6d 75 6c 74 69 74 68 72 65 61 64   the multithread
167e0 65 64 0a 2a 2a 20 73 6f 72 74 65 72 20 74 6f 20  ed.** sorter to 
167f0 74 68 61 74 20 69 6e 74 65 67 65 72 2e 20 20 54  that integer.  T
16800 68 65 20 64 65 66 61 75 6c 74 20 6d 69 6e 69 6d  he default minim
16810 75 6d 20 50 4d 41 20 53 69 7a 65 20 69 73 20 73  um PMA Size is s
16820 65 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51  et by the.** [SQ
16830 4c 49 54 45 5f 53 4f 52 54 45 52 5f 50 4d 41 53  LITE_SORTER_PMAS
16840 5a 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  Z] compile-time 
16850 6f 70 74 69 6f 6e 2e 20 20 4e 65 77 20 74 68 72  option.  New thr
16860 65 61 64 73 20 61 72 65 20 6c 61 75 6e 63 68 65  eads are launche
16870 64 0a 2a 2a 20 74 6f 20 68 65 6c 70 20 77 69 74  d.** to help wit
16880 68 20 73 6f 72 74 20 6f 70 65 72 61 74 69 6f 6e  h sort operation
16890 73 20 77 68 65 6e 20 6d 75 6c 74 69 74 68 72 65  s when multithre
168a0 61 64 65 64 20 73 6f 72 74 69 6e 67 0a 2a 2a 20  aded sorting.** 
168b0 69 73 20 65 6e 61 62 6c 65 64 20 28 75 73 69 6e  is enabled (usin
168c0 67 20 74 68 65 20 5b 50 52 41 47 4d 41 20 74 68  g the [PRAGMA th
168d0 72 65 61 64 73 5d 20 63 6f 6d 6d 61 6e 64 29 20  reads] command) 
168e0 61 6e 64 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f  and the amount o
168f0 66 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 74 6f 20  f content.** to 
16900 62 65 20 73 6f 72 74 65 64 20 65 78 63 65 65 64  be sorted exceed
16910 73 20 74 68 65 20 70 61 67 65 20 73 69 7a 65 20  s the page size 
16920 74 69 6d 65 73 20 74 68 65 20 6d 69 6e 69 6d 75  times the minimu
16930 6d 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 50 52 41  m of the.** [PRA
16940 47 4d 41 20 63 61 63 68 65 5f 73 69 7a 65 5d 20  GMA cache_size] 
16950 73 65 74 74 69 6e 67 20 61 6e 64 20 74 68 69 73  setting and this
16960 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b   value..**.** [[
16970 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54  SQLITE_CONFIG_ST
16980 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 5d 5d 0a 2a  MTJRNL_SPILL]].*
16990 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
169a0 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49  FIG_STMTJRNL_SPI
169b0 4c 4c 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53  LL.** <dd>^The S
169c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d  QLITE_CONFIG_STM
169d0 54 4a 52 4e 4c 5f 53 50 49 4c 4c 20 6f 70 74 69  TJRNL_SPILL opti
169e0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
169f0 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63  e parameter whic
16a00 68 0a 2a 2a 20 62 65 63 6f 6d 65 73 20 74 68 65  h.** becomes the
16a10 20 5b 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72   [statement jour
16a20 6e 61 6c 5d 20 73 70 69 6c 6c 2d 74 6f 2d 64 69  nal] spill-to-di
16a30 73 6b 20 74 68 72 65 73 68 6f 6c 64 2e 20 20 0a  sk threshold.  .
16a40 2a 2a 20 5b 53 74 61 74 65 6d 65 6e 74 20 6a 6f  ** [Statement jo
16a50 75 72 6e 61 6c 73 5d 20 61 72 65 20 68 65 6c 64  urnals] are held
16a60 20 69 6e 20 6d 65 6d 6f 72 79 20 75 6e 74 69 6c   in memory until
16a70 20 74 68 65 69 72 20 73 69 7a 65 20 28 69 6e 20   their size (in 
16a80 62 79 74 65 73 29 0a 2a 2a 20 65 78 63 65 65 64  bytes).** exceed
16a90 73 20 74 68 69 73 20 74 68 72 65 73 68 6f 6c 64  s this threshold
16aa0 2c 20 61 74 20 77 68 69 63 68 20 70 6f 69 6e 74  , at which point
16ab0 20 74 68 65 79 20 61 72 65 20 77 72 69 74 74 65   they are writte
16ac0 6e 20 74 6f 20 64 69 73 6b 2e 0a 2a 2a 20 4f 72  n to disk..** Or
16ad0 20 69 66 20 74 68 65 20 74 68 72 65 73 68 6f 6c   if the threshol
16ae0 64 20 69 73 20 2d 31 2c 20 73 74 61 74 65 6d 65  d is -1, stateme
16af0 6e 74 20 6a 6f 75 72 6e 61 6c 73 20 61 72 65 20  nt journals are 
16b00 61 6c 77 61 79 73 20 68 65 6c 64 0a 2a 2a 20 65  always held.** e
16b10 78 63 6c 75 73 69 76 65 6c 79 20 69 6e 20 6d 65  xclusively in me
16b20 6d 6f 72 79 2e 0a 2a 2a 20 53 69 6e 63 65 20 6d  mory..** Since m
16b30 61 6e 79 20 73 74 61 74 65 6d 65 6e 74 20 6a 6f  any statement jo
16b40 75 72 6e 61 6c 73 20 6e 65 76 65 72 20 62 65 63  urnals never bec
16b50 6f 6d 65 20 6c 61 72 67 65 2c 20 73 65 74 74 69  ome large, setti
16b60 6e 67 20 74 68 65 20 73 70 69 6c 6c 0a 2a 2a 20  ng the spill.** 
16b70 74 68 72 65 73 68 6f 6c 64 20 74 6f 20 61 20 76  threshold to a v
16b80 61 6c 75 65 20 73 75 63 68 20 61 73 20 36 34 4b  alue such as 64K
16b90 69 42 20 63 61 6e 20 67 72 65 61 74 6c 79 20 72  iB can greatly r
16ba0 65 64 75 63 65 20 74 68 65 20 61 6d 6f 75 6e 74  educe the amount
16bb0 20 6f 66 0a 2a 2a 20 49 2f 4f 20 72 65 71 75 69   of.** I/O requi
16bc0 72 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 73  red to support s
16bd0 74 61 74 65 6d 65 6e 74 20 72 6f 6c 6c 62 61 63  tatement rollbac
16be0 6b 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c  k..** The defaul
16bf0 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68 69 73  t value for this
16c00 20 73 65 74 74 69 6e 67 20 69 73 20 63 6f 6e 74   setting is cont
16c10 72 6f 6c 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a  rolled by the.**
16c20 20 5b 53 51 4c 49 54 45 5f 53 54 4d 54 4a 52 4e   [SQLITE_STMTJRN
16c30 4c 5f 53 50 49 4c 4c 5d 20 63 6f 6d 70 69 6c 65  L_SPILL] compile
16c40 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a  -time option..**
16c50 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
16c60 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16c70 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20  SINGLETHREAD  1 
16c80 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
16c90 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
16ca0 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20 32  _MULTITHREAD   2
16cb0 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66    /* nil */.#def
16cc0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
16cd0 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20  G_SERIALIZED    
16ce0 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65  3  /* nil */.#de
16cf0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16d00 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20  IG_MALLOC       
16d10 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d   4  /* sqlite3_m
16d20 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  em_methods* */.#
16d30 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
16d40 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20  NFIG_GETMALLOC  
16d50 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33     5  /* sqlite3
16d60 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  _mem_methods* */
16d70 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16d80 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20  CONFIG_SCRATCH  
16d90 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a       6  /* void*
16da0 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20  , int sz, int N 
16db0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16dc0 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
16dd0 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69  HE     7  /* voi
16de0 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20  d*, int sz, int 
16df0 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  N */.#define SQL
16e00 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20  ITE_CONFIG_HEAP 
16e10 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76           8  /* v
16e20 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c  oid*, int nByte,
16e30 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66   int min */.#def
16e40 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
16e50 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20  G_MEMSTATUS     
16e60 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f  9  /* boolean */
16e70 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16e80 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20  CONFIG_MUTEX    
16e90 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74      10  /* sqlit
16ea0 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
16eb0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
16ec0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
16ed0 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73  TEX     11  /* s
16ee0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
16ef0 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76  hods* */./* prev
16f00 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f  iously SQLITE_CO
16f10 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20  NFIG_CHUNKALLOC 
16f20 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20  12 which is now 
16f30 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66  unused. */ .#def
16f40 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
16f50 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31  G_LOOKASIDE    1
16f60 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f  3  /* int int */
16f70 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16f80 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20  CONFIG_PCACHE   
16f90 20 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70      14  /* no-op
16fa0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16fb0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
16fc0 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20 6e 6f  CHE    15  /* no
16fd0 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  -op */.#define S
16fe0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
16ff0 20 20 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a            16  /*
17000 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f   xFunc, void* */
17010 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17020 43 4f 4e 46 49 47 5f 55 52 49 20 20 20 20 20 20  CONFIG_URI      
17030 20 20 20 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a      17  /* int *
17040 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17050 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20  _CONFIG_PCACHE2 
17060 20 20 20 20 20 31 38 20 20 2f 2a 20 73 71 6c 69       18  /* sqli
17070 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
17080 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ds2* */.#define 
17090 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
170a0 54 50 43 41 43 48 45 32 20 20 20 31 39 20 20 2f  TPCACHE2   19  /
170b0 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65  * sqlite3_pcache
170c0 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64  _methods2* */.#d
170d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
170e0 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  FIG_COVERING_IND
170f0 45 58 5f 53 43 41 4e 20 32 30 20 20 2f 2a 20 69  EX_SCAN 20  /* i
17100 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  nt */.#define SQ
17110 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c  LITE_CONFIG_SQLL
17120 4f 47 20 20 20 20 20 20 20 32 31 20 20 2f 2a 20  OG       21  /* 
17130 78 53 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20 2a  xSqllog, void* *
17140 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17150 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a  _CONFIG_MMAP_SIZ
17160 45 20 20 20 20 32 32 20 20 2f 2a 20 73 71 6c 69  E    22  /* sqli
17170 74 65 33 5f 69 6e 74 36 34 2c 20 73 71 6c 69 74  te3_int64, sqlit
17180 65 33 5f 69 6e 74 36 34 20 2a 2f 0a 23 64 65 66  e3_int64 */.#def
17190 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
171a0 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45  G_WIN32_HEAPSIZE
171b0 20 20 20 20 20 20 32 33 20 20 2f 2a 20 69 6e 74        23  /* int
171c0 20 6e 42 79 74 65 20 2a 2f 0a 23 64 65 66 69 6e   nByte */.#defin
171d0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
171e0 50 43 41 43 48 45 5f 48 44 52 53 5a 20 20 20 20  PCACHE_HDRSZ    
171f0 20 20 20 20 32 34 20 20 2f 2a 20 69 6e 74 20 2a      24  /* int *
17200 70 73 7a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  psz */.#define S
17210 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41  QLITE_CONFIG_PMA
17220 53 5a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  SZ              
17230 20 32 35 20 20 2f 2a 20 75 6e 73 69 67 6e 65 64   25  /* unsigned
17240 20 69 6e 74 20 73 7a 50 6d 61 20 2a 2f 0a 23 64   int szPma */.#d
17250 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
17260 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49  FIG_STMTJRNL_SPI
17270 4c 4c 20 20 20 20 20 20 32 36 20 20 2f 2a 20 69  LL      26  /* i
17280 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 0a 2f 2a 0a  nt nByte */../*.
17290 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74  ** CAPI3REF: Dat
172a0 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
172b0 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f   Configuration O
172c0 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ptions.**.** The
172d0 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  se constants are
172e0 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69   the available i
172f0 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61  nteger configura
17300 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61  tion options tha
17310 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73  t.** can be pass
17320 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
17330 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
17340 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
17350 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
17360 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66  ..**.** New conf
17370 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
17380 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
17390 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
173a0 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20  s of SQLite..** 
173b0 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75  Existing configu
173c0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
173d0 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69  ight be disconti
173e0 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69  nued.  Applicati
173f0 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68  ons.** should ch
17400 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63  eck the return c
17410 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ode from [sqlite
17420 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74  3_db_config()] t
17430 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74  o make sure that
17440 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72  .** the call wor
17450 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69  ked.  ^The [sqli
17460 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
17470 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
17480 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d  return a.** non-
17490 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
174a0 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e  ] if a discontin
174b0 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74  ued or unsupport
174c0 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ed configuration
174d0 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e   option.** is in
174e0 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  voked..**.** <dl
174f0 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  >.** <dt>SQLITE_
17500 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
17510 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  DE</dt>.** <dd> 
17520 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  ^This option tak
17530 65 73 20 74 68 72 65 65 20 61 64 64 69 74 69 6f  es three additio
17540 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68  nal arguments th
17550 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65  at determine the
17560 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20   .** [lookaside 
17570 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
17580 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  ] configuration 
17590 66 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61 73  for the [databas
175a0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a  e connection]..*
175b0 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
175c0 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72 64  ument (the third
175d0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
175e0 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
175f0 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e  ()] is a.** poin
17600 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20  ter to a memory 
17610 62 75 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f  buffer to use fo
17620 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  r lookaside memo
17630 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  ry..** ^The firs
17640 74 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65 72  t argument after
17650 20 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f   the SQLITE_DBCO
17660 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76  NFIG_LOOKASIDE v
17670 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55  erb.** may be NU
17680 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65  LL in which case
17690 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c   SQLite will all
176a0 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f  ocate the.** loo
176b0 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 69 74  kaside buffer it
176c0 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69  self using [sqli
176d0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e  te3_malloc()]. ^
176e0 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
176f0 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69  ent is the.** si
17700 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61  ze of each looka
17710 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74  side buffer slot
17720 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 61 72  .  ^The third ar
17730 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75  gument is the nu
17740 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73  mber of.** slots
17750 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74  .  The size of t
17760 68 65 20 62 75 66 66 65 72 20 69 6e 20 74 68 65  he buffer in the
17770 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
17780 6d 75 73 74 20 62 65 20 67 72 65 61 74 65 72 20  must be greater 
17790 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c  than.** or equal
177a0 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20   to the product 
177b0 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e  of the second an
177c0 64 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  d third argument
177d0 73 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a 2a  s.  The buffer.*
177e0 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65  * must be aligne
177f0 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62  d to an 8-byte b
17800 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 68  oundary.  ^If th
17810 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
17820 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44  t to.** SQLITE_D
17830 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
17840 45 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69  E is not a multi
17850 70 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20  ple of 8, it is 
17860 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f  internally.** ro
17870 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68  unded down to th
17880 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d  e next smaller m
17890 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e  ultiple of 8.  ^
178a0 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d  (The lookaside m
178b0 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75  emory.** configu
178c0 72 61 74 69 6f 6e 20 66 6f 72 20 61 20 64 61 74  ration for a dat
178d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
178e0 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61   can only be cha
178f0 6e 67 65 64 20 77 68 65 6e 20 74 68 61 74 0a 2a  nged when that.*
17900 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  * connection is 
17910 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 75 73  not currently us
17920 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  ing lookaside me
17930 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65  mory, or in othe
17940 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20  r words.** when 
17950 74 68 65 20 22 63 75 72 72 65 6e 74 20 76 61 6c  the "current val
17960 75 65 22 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ue" returned by.
17970 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73  ** [sqlite3_db_s
17980 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45  tatus](D,[SQLITE
17990 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
179a0 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e  E],...) is zero.
179b0 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20  .** Any attempt 
179c0 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f  to change the lo
179d0 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 63  okaside memory c
179e0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 77 68 65  onfiguration whe
179f0 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d  n lookaside.** m
17a00 65 6d 6f 72 79 20 69 73 20 69 6e 20 75 73 65 20  emory is in use 
17a10 6c 65 61 76 65 73 20 74 68 65 20 63 6f 6e 66 69  leaves the confi
17a20 67 75 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67  guration unchang
17a30 65 64 20 61 6e 64 20 72 65 74 75 72 6e 73 20 0a  ed and returns .
17a40 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ** [SQLITE_BUSY]
17a50 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  .)^</dd>.**.** <
17a60 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
17a70 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f  IG_ENABLE_FKEY</
17a80 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
17a90 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  s option is used
17aa0 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69   to enable or di
17ab0 73 61 62 6c 65 20 74 68 65 20 65 6e 66 6f 72 63  sable the enforc
17ac0 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72  ement of.** [for
17ad0 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61  eign key constra
17ae0 69 6e 74 73 5d 2e 20 20 54 68 65 72 65 20 73 68  ints].  There sh
17af0 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69  ould be two addi
17b00 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
17b10 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ..** The first a
17b20 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e  rgument is an in
17b30 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30  teger which is 0
17b40 20 74 6f 20 64 69 73 61 62 6c 65 20 46 4b 20 65   to disable FK e
17b50 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70  nforcement,.** p
17b60 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c  ositive to enabl
17b70 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  e FK enforcement
17b80 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20   or negative to 
17b90 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f 72 63 65  leave FK enforce
17ba0 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65  ment.** unchange
17bb0 64 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70  d.  The second p
17bc0 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f  arameter is a po
17bd0 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
17be0 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a  ger into which.*
17bf0 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f  * is written 0 o
17c00 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20  r 1 to indicate 
17c10 77 68 65 74 68 65 72 20 46 4b 20 65 6e 66 6f 72  whether FK enfor
17c20 63 65 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f 72  cement is off or
17c30 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67   on.** following
17c40 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65   this call.  The
17c50 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
17c60 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20  r may be a NULL 
17c70 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77  pointer, in.** w
17c80 68 69 63 68 20 63 61 73 65 20 74 68 65 20 46 4b  hich case the FK
17c90 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65 74   enforcement set
17ca0 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f  ting is not repo
17cb0 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e  rted back. </dd>
17cc0 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
17cd0 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
17ce0 45 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a  E_TRIGGER</dt>.*
17cf0 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
17d00 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65  ion is used to e
17d10 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65  nable or disable
17d20 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52   [CREATE TRIGGER
17d30 20 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a   | triggers]..**
17d40 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65   There should be
17d50 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
17d60 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68  arguments..** Th
17d70 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
17d80 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77   is an integer w
17d90 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73  hich is 0 to dis
17da0 61 62 6c 65 20 74 72 69 67 67 65 72 73 2c 0a 2a  able triggers,.*
17db0 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e  * positive to en
17dc0 61 62 6c 65 20 74 72 69 67 67 65 72 73 20 6f 72  able triggers or
17dd0 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61   negative to lea
17de0 76 65 20 74 68 65 20 73 65 74 74 69 6e 67 20 75  ve the setting u
17df0 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65  nchanged..** The
17e00 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
17e10 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  r is a pointer t
17e20 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74  o an integer int
17e30 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72  o which.** is wr
17e40 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20  itten 0 or 1 to 
17e50 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72  indicate whether
17e60 20 74 72 69 67 67 65 72 73 20 61 72 65 20 64 69   triggers are di
17e70 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65  sabled or enable
17e80 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74  d.** following t
17e90 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73  his call.  The s
17ea0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
17eb0 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f  may be a NULL po
17ec0 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69  inter, in.** whi
17ed0 63 68 20 63 61 73 65 20 74 68 65 20 74 72 69 67  ch case the trig
17ee0 67 65 72 20 73 65 74 74 69 6e 67 20 69 73 20 6e  ger setting is n
17ef0 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  ot reported back
17f00 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  . </dd>.**.** <d
17f10 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
17f20 47 5f 45 4e 41 42 4c 45 5f 46 54 53 33 5f 54 4f  G_ENABLE_FTS3_TO
17f30 4b 45 4e 49 5a 45 52 3c 2f 64 74 3e 0a 2a 2a 20  KENIZER</dt>.** 
17f40 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
17f50 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61  n is used to ena
17f60 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74  ble or disable t
17f70 68 65 20 74 77 6f 2d 61 72 67 75 6d 65 6e 74 0a  he two-argument.
17f80 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68  ** version of th
17f90 65 20 5b 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65  e [fts3_tokenize
17fa0 72 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 77 68  r()] function wh
17fb0 69 63 68 20 69 73 20 70 61 72 74 20 6f 66 20 74  ich is part of t
17fc0 68 65 0a 2a 2a 20 5b 46 54 53 33 5d 20 66 75 6c  he.** [FTS3] ful
17fd0 6c 2d 74 65 78 74 20 73 65 61 72 63 68 20 65 6e  l-text search en
17fe0 67 69 6e 65 20 65 78 74 65 6e 73 69 6f 6e 2e 0a  gine extension..
17ff0 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20  ** There should 
18000 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61  be two additiona
18010 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20  l arguments..** 
18020 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
18030 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  nt is an integer
18040 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64   which is 0 to d
18050 69 73 61 62 6c 65 20 66 74 73 33 5f 74 6f 6b 65  isable fts3_toke
18060 6e 69 7a 65 72 28 29 20 6f 72 0a 2a 2a 20 70 6f  nizer() or.** po
18070 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65  sitive to enable
18080 20 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28   fts3_tokenizer(
18090 29 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f  ) or negative to
180a0 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69   leave the setti
180b0 6e 67 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e  ng.** unchanged.
180c0 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70  .** The second p
180d0 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f  arameter is a po
180e0 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
180f0 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a  ger into which.*
18100 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f  * is written 0 o
18110 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20  r 1 to indicate 
18120 77 68 65 74 68 65 72 20 66 74 73 33 5f 74 6f 6b  whether fts3_tok
18130 65 6e 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c  enizer is disabl
18140 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a  ed or enabled.**
18150 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20   following this 
18160 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e  call.  The secon
18170 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  d parameter may 
18180 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  be a NULL pointe
18190 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63  r, in.** which c
181a0 61 73 65 20 74 68 65 20 6e 65 77 20 73 65 74 74  ase the new sett
181b0 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72  ing is not repor
181c0 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a  ted back. </dd>.
181d0 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
181e0 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
181f0 5f 4c 4f 41 44 5f 45 58 54 45 4e 53 49 4f 4e 3c  _LOAD_EXTENSION<
18200 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
18210 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  is option is use
18220 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64  d to enable or d
18230 69 73 61 62 6c 65 20 74 68 65 20 5b 73 71 6c 69  isable the [sqli
18240 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  te3_load_extensi
18250 6f 6e 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61  on()].** interfa
18260 63 65 20 69 6e 64 65 70 65 6e 64 65 6e 74 6c 79  ce independently
18270 20 6f 66 20 74 68 65 20 5b 6c 6f 61 64 5f 65 78   of the [load_ex
18280 74 65 6e 73 69 6f 6e 28 29 5d 20 53 51 4c 20 66  tension()] SQL f
18290 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20  unction..** The 
182a0 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f  [sqlite3_enable_
182b0 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
182c0 5d 20 41 50 49 20 65 6e 61 62 6c 65 73 20 6f 72  ] API enables or
182d0 20 64 69 73 61 62 6c 65 73 20 62 6f 74 68 20 74   disables both t
182e0 68 65 0a 2a 2a 20 43 2d 41 50 49 20 5b 73 71 6c  he.** C-API [sql
182f0 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  ite3_load_extens
18300 69 6f 6e 28 29 5d 20 61 6e 64 20 74 68 65 20 53  ion()] and the S
18310 51 4c 20 66 75 6e 63 74 69 6f 6e 20 5b 6c 6f 61  QL function [loa
18320 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 2e 0a  d_extension()]..
18330 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20  ** There should 
18340 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61  be two additiona
18350 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20  l arguments..** 
18360 57 68 65 6e 20 74 68 65 20 66 69 72 73 74 20 61  When the first a
18370 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20  rgument to this 
18380 69 6e 74 65 72 66 61 63 65 20 69 73 20 31 2c 20  interface is 1, 
18390 74 68 65 6e 20 6f 6e 6c 79 20 74 68 65 20 43 2d  then only the C-
183a0 41 50 49 20 69 73 0a 2a 2a 20 65 6e 61 62 6c 65  API is.** enable
183b0 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75  d and the SQL fu
183c0 6e 63 74 69 6f 6e 20 72 65 6d 61 69 6e 73 20 64  nction remains d
183d0 69 73 61 62 6c 65 64 2e 20 20 49 66 20 74 68 65  isabled.  If the
183e0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
183f0 74 6f 0a 2a 2a 20 74 68 69 73 20 69 6e 74 65 72  to.** this inter
18400 66 61 63 65 20 69 73 20 30 2c 20 74 68 65 6e 20  face is 0, then 
18410 62 6f 74 68 20 74 68 65 20 43 2d 41 50 49 20 61  both the C-API a
18420 6e 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nd the SQL funct
18430 69 6f 6e 20 61 72 65 20 64 69 73 61 62 6c 65 64  ion are disabled
18440 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 72 73  ..** If the firs
18450 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 2d 31  t argument is -1
18460 2c 20 74 68 65 6e 20 6e 6f 20 63 68 61 6e 67 65  , then no change
18470 73 20 61 72 65 20 6d 61 64 65 20 74 6f 20 73 74  s are made to st
18480 61 74 65 20 6f 66 20 65 69 74 68 65 72 20 74 68  ate of either th
18490 65 0a 2a 2a 20 43 2d 41 50 49 20 6f 72 20 74 68  e.** C-API or th
184a0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a  e SQL function..
184b0 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  ** The second pa
184c0 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
184d0 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
184e0 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a  er into which.**
184f0 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72   is written 0 or
18500 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77   1 to indicate w
18510 68 65 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f  hether [sqlite3_
18520 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
18530 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69  ] interface.** i
18540 73 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e  s disabled or en
18550 61 62 6c 65 64 20 66 6f 6c 6c 6f 77 69 6e 67 20  abled following 
18560 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20  this call.  The 
18570 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
18580 20 6d 61 79 0a 2a 2a 20 62 65 20 61 20 4e 55 4c   may.** be a NUL
18590 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 20 77 68  L pointer, in wh
185a0 69 63 68 20 63 61 73 65 20 74 68 65 20 6e 65 77  ich case the new
185b0 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20   setting is not 
185c0 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 0a 2a  reported back..*
185d0 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  * </dd>.**.** <d
185e0 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
185f0 47 5f 4d 41 49 4e 44 42 4e 41 4d 45 3c 2f 64 74  G_MAINDBNAME</dt
18600 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
18610 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  option is used t
18620 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6e 61 6d  o change the nam
18630 65 20 6f 66 20 74 68 65 20 22 6d 61 69 6e 22 20  e of the "main" 
18640 64 61 74 61 62 61 73 65 0a 2a 2a 20 73 63 68 65  database.** sche
18650 6d 61 2e 20 20 5e 54 68 65 20 73 6f 6c 65 20 61  ma.  ^The sole a
18660 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
18670 6e 74 65 72 20 74 6f 20 61 20 63 6f 6e 73 74 61  nter to a consta
18680 6e 74 20 55 54 46 38 20 73 74 72 69 6e 67 0a 2a  nt UTF8 string.*
18690 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65 63  * which will bec
186a0 6f 6d 65 20 74 68 65 20 6e 65 77 20 73 63 68 65  ome the new sche
186b0 6d 61 20 6e 61 6d 65 20 69 6e 20 70 6c 61 63 65  ma name in place
186c0 20 6f 66 20 22 6d 61 69 6e 22 2e 20 20 5e 53 51   of "main".  ^SQ
186d0 4c 69 74 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74  Lite.** does not
186e0 20 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f 66 20   make a copy of 
186f0 74 68 65 20 6e 65 77 20 6d 61 69 6e 20 73 63 68  the new main sch
18700 65 6d 61 20 6e 61 6d 65 20 73 74 72 69 6e 67 2c  ema name string,
18710 20 73 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   so the applicat
18720 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e 73 75  ion.** must ensu
18730 72 65 20 74 68 61 74 20 74 68 65 20 61 72 67 75  re that the argu
18740 6d 65 6e 74 20 70 61 73 73 65 64 20 69 6e 74 6f  ment passed into
18750 20 74 68 69 73 20 44 42 43 4f 4e 46 49 47 20 6f   this DBCONFIG o
18760 70 74 69 6f 6e 20 69 73 20 75 6e 63 68 61 6e 67  ption is unchang
18770 65 64 0a 2a 2a 20 75 6e 74 69 6c 20 61 66 74 65  ed.** until afte
18780 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  r the database c
18790 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73  onnection closes
187a0 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
187b0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
187c0 4e 46 49 47 5f 4e 4f 5f 43 4b 50 54 5f 4f 4e 5f  NFIG_NO_CKPT_ON_
187d0 43 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  CLOSE</dt>.** <d
187e0 64 3e 20 55 73 75 61 6c 6c 79 2c 20 77 68 65 6e  d> Usually, when
187f0 20 61 20 64 61 74 61 62 61 73 65 20 69 6e 20 77   a database in w
18800 61 6c 20 6d 6f 64 65 20 69 73 20 63 6c 6f 73 65  al mode is close
18810 64 20 6f 72 20 64 65 74 61 63 68 65 64 20 66 72  d or detached fr
18820 6f 6d 20 61 20 0a 2a 2a 20 64 61 74 61 62 61 73  om a .** databas
18830 65 20 68 61 6e 64 6c 65 2c 20 53 51 4c 69 74 65  e handle, SQLite
18840 20 63 68 65 63 6b 73 20 69 66 20 74 68 69 73 20   checks if this 
18850 77 69 6c 6c 20 6d 65 61 6e 20 74 68 61 74 20 74  will mean that t
18860 68 65 72 65 20 61 72 65 20 6e 6f 77 20 6e 6f 20  here are now no 
18870 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  .** connections 
18880 61 74 20 61 6c 6c 20 74 6f 20 74 68 65 20 64 61  at all to the da
18890 74 61 62 61 73 65 2e 20 49 66 20 73 6f 2c 20 69  tabase. If so, i
188a0 74 20 70 65 72 66 6f 72 6d 73 20 61 20 63 68 65  t performs a che
188b0 63 6b 70 6f 69 6e 74 20 0a 2a 2a 20 6f 70 65 72  ckpoint .** oper
188c0 61 74 69 6f 6e 20 62 65 66 6f 72 65 20 63 6c 6f  ation before clo
188d0 73 69 6e 67 20 74 68 65 20 63 6f 6e 6e 65 63 74  sing the connect
188e0 69 6f 6e 2e 20 54 68 69 73 20 6f 70 74 69 6f 6e  ion. This option
188f0 20 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f 0a   may be used to.
18900 2a 2a 20 6f 76 65 72 72 69 64 65 20 74 68 69 73  ** override this
18910 20 62 65 68 61 76 69 6f 75 72 2e 20 54 68 65 20   behaviour. The 
18920 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
18930 70 61 73 73 65 64 20 74 6f 20 74 68 69 73 20 6f  passed to this o
18940 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 61  peration.** is a
18950 6e 20 69 6e 74 65 67 65 72 20 2d 20 6e 6f 6e 2d  n integer - non-
18960 7a 65 72 6f 20 74 6f 20 64 69 73 61 62 6c 65 20  zero to disable 
18970 63 68 65 63 6b 70 6f 69 6e 74 73 2d 6f 6e 2d 63  checkpoints-on-c
18980 6c 6f 73 65 2c 20 6f 72 20 7a 65 72 6f 20 28 74  lose, or zero (t
18990 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 29 20 74  he.** default) t
189a0 6f 20 65 6e 61 62 6c 65 20 74 68 65 6d 2e 20 54  o enable them. T
189b0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
189c0 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ter is a pointer
189d0 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a   to an integer.*
189e0 2a 20 69 6e 74 6f 20 77 68 69 63 68 20 69 73 20  * into which is 
189f0 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74  written 0 or 1 t
18a00 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68  o indicate wheth
18a10 65 72 20 63 68 65 63 6b 70 6f 69 6e 74 73 2d 6f  er checkpoints-o
18a20 6e 2d 63 6c 6f 73 65 0a 2a 2a 20 68 61 76 65 20  n-close.** have 
18a30 62 65 65 6e 20 64 69 73 61 62 6c 65 64 20 2d 20  been disabled - 
18a40 30 20 69 66 20 74 68 65 79 20 61 72 65 20 6e 6f  0 if they are no
18a50 74 20 64 69 73 61 62 6c 65 64 2c 20 31 20 69 66  t disabled, 1 if
18a60 20 74 68 65 79 20 61 72 65 2e 0a 2a 2a 20 3c 2f   they are..** </
18a70 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a  dd>.**.** </dl>.
18a80 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18a90 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 49 4e 44  E_DBCONFIG_MAIND
18aa0 42 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20  BNAME           
18ab0 20 31 30 30 30 20 2f 2a 20 63 6f 6e 73 74 20 63   1000 /* const c
18ac0 68 61 72 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  har* */.#define 
18ad0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
18ae0 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 20 20 20  LOOKASIDE       
18af0 20 20 20 20 20 20 31 30 30 31 20 2f 2a 20 76 6f        1001 /* vo
18b00 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23  id* int int */.#
18b10 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
18b20 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b  CONFIG_ENABLE_FK
18b30 45 59 20 20 20 20 20 20 20 20 20 20 20 31 30 30  EY           100
18b40 32 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f  2 /* int int* */
18b50 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18b60 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
18b70 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 31  TRIGGER        1
18b80 30 30 33 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20  003 /* int int* 
18b90 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18ba0 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
18bb0 45 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a 45 52  E_FTS3_TOKENIZER
18bc0 20 31 30 30 34 20 2f 2a 20 69 6e 74 20 69 6e 74   1004 /* int int
18bd0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
18be0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
18bf0 42 4c 45 5f 4c 4f 41 44 5f 45 58 54 45 4e 53 49  BLE_LOAD_EXTENSI
18c00 4f 4e 20 31 30 30 35 20 2f 2a 20 69 6e 74 20 69  ON 1005 /* int i
18c10 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nt* */.#define S
18c20 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4e  QLITE_DBCONFIG_N
18c30 4f 5f 43 4b 50 54 5f 4f 4e 5f 43 4c 4f 53 45 20  O_CKPT_ON_CLOSE 
18c40 20 20 20 20 20 31 30 30 36 20 2f 2a 20 69 6e 74       1006 /* int
18c50 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a   int* */.../*.**
18c60 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c   CAPI3REF: Enabl
18c70 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74  e Or Disable Ext
18c80 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64  ended Result Cod
18c90 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  es.** METHOD: sq
18ca0 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lite3.**.** ^The
18cb0 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
18cc0 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
18cd0 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73   routine enables
18ce0 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65   or disables the
18cf0 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
18d00 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74  sult codes] feat
18d10 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e  ure of SQLite. ^
18d20 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73  The extended res
18d30 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65  ult.** codes are
18d40 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
18d50 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69  ault for histori
18d60 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  cal compatibilit
18d70 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  y..*/.int sqlite
18d80 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
18d90 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a  t_codes(sqlite3*
18da0 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f  , int onoff);../
18db0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c  *.** CAPI3REF: L
18dc0 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64  ast Insert Rowid
18dd0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
18de0 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20  te3.**.** ^Each 
18df0 65 6e 74 72 79 20 69 6e 20 6d 6f 73 74 20 53 51  entry in most SQ
18e00 4c 69 74 65 20 74 61 62 6c 65 73 20 28 65 78 63  Lite tables (exc
18e10 65 70 74 20 66 6f 72 20 5b 57 49 54 48 4f 55 54  ept for [WITHOUT
18e20 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 29 0a   ROWID] tables).
18e30 2a 2a 20 68 61 73 20 61 20 75 6e 69 71 75 65 20  ** has a unique 
18e40 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a  64-bit signed.**
18e50 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c   integer key cal
18e60 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c  led the [ROWID |
18e70 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20   "rowid"]. ^The 
18e80 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20  rowid is always 
18e90 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20  available.** as 
18ea0 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f  an undeclared co
18eb0 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44  lumn named ROWID
18ec0 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44  , OID, or _ROWID
18ed0 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f  _ as long as tho
18ee0 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20  se.** names are 
18ef0 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79  not also used by
18f00 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c   explicitly decl
18f10 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49  ared columns. ^I
18f20 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68  f.** the table h
18f30 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  as a column of t
18f40 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49  ype [INTEGER PRI
18f50 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74  MARY KEY] then t
18f60 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73  hat column.** is
18f70 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66   another alias f
18f80 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a  or the rowid..**
18f90 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
18fa0 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
18fb0 69 64 28 44 29 20 69 6e 74 65 72 66 61 63 65 20  id(D) interface 
18fc0 75 73 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20  usually returns 
18fd0 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 0a 2a  the [rowid] of.*
18fe0 2a 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  * the most recen
18ff0 74 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e  t successful [IN
19000 53 45 52 54 5d 20 69 6e 74 6f 20 61 20 72 6f 77  SERT] into a row
19010 69 64 20 74 61 62 6c 65 20 6f 72 20 5b 76 69 72  id table or [vir
19020 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f  tual table].** o
19030 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  n database conne
19040 63 74 69 6f 6e 20 44 2e 20 5e 49 6e 73 65 72 74  ction D. ^Insert
19050 73 20 69 6e 74 6f 20 5b 57 49 54 48 4f 55 54 20  s into [WITHOUT 
19060 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 20 61 72  ROWID] tables ar
19070 65 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 72 64 65  e not.** recorde
19080 64 2e 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73  d. ^If no succes
19090 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 20 69  sful [INSERT]s i
190a0 6e 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 73  nto rowid tables
190b0 20 68 61 76 65 20 65 76 65 72 20 6f 63 63 75 72   have ever occur
190c0 72 65 64 20 0a 2a 2a 20 6f 6e 20 74 68 65 20 64  red .** on the d
190d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
190e0 6f 6e 20 44 2c 20 74 68 65 6e 20 73 71 6c 69 74  on D, then sqlit
190f0 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
19100 6f 77 69 64 28 44 29 20 72 65 74 75 72 6e 73 20  owid(D) returns 
19110 0a 2a 2a 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20  .** zero..**.** 
19120 41 73 20 77 65 6c 6c 20 61 73 20 62 65 69 6e 67  As well as being
19130 20 73 65 74 20 61 75 74 6f 6d 61 74 69 63 61 6c   set automatical
19140 6c 79 20 61 73 20 72 6f 77 73 20 61 72 65 20 69  ly as rows are i
19150 6e 73 65 72 74 65 64 20 69 6e 74 6f 20 64 61 74  nserted into dat
19160 61 62 61 73 65 0a 2a 2a 20 74 61 62 6c 65 73 2c  abase.** tables,
19170 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
19180 6e 65 64 20 62 79 20 74 68 69 73 20 66 75 6e 63  ned by this func
19190 74 69 6f 6e 20 6d 61 79 20 62 65 20 73 65 74 20  tion may be set 
191a0 65 78 70 6c 69 63 69 74 6c 79 20 62 79 0a 2a 2a  explicitly by.**
191b0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61   [sqlite3_set_la
191c0 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
191d0 29 5d 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 76 69  )].**.** Some vi
191e0 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c  rtual table impl
191f0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20  ementations may 
19200 49 4e 53 45 52 54 20 72 6f 77 73 20 69 6e 74 6f  INSERT rows into
19210 20 72 6f 77 69 64 20 74 61 62 6c 65 73 20 61 73   rowid tables as
19220 0a 2a 2a 20 70 61 72 74 20 6f 66 20 63 6f 6d 6d  .** part of comm
19230 69 74 74 69 6e 67 20 61 20 74 72 61 6e 73 61 63  itting a transac
19240 74 69 6f 6e 20 28 65 2e 67 2e 20 74 6f 20 66 6c  tion (e.g. to fl
19250 75 73 68 20 64 61 74 61 20 61 63 63 75 6d 75 6c  ush data accumul
19260 61 74 65 64 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a  ated in memory.*
19270 2a 20 74 6f 20 64 69 73 6b 29 2e 20 49 6e 20 74  * to disk). In t
19280 68 69 73 20 63 61 73 65 20 73 75 62 73 65 71 75  his case subsequ
19290 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 74 68 69  ent calls to thi
192a0 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
192b0 6e 20 74 68 65 20 72 6f 77 69 64 0a 2a 2a 20 61  n the rowid.** a
192c0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
192d0 68 65 73 65 20 69 6e 74 65 72 6e 61 6c 20 49 4e  hese internal IN
192e0 53 45 52 54 20 6f 70 65 72 61 74 69 6f 6e 73 2c  SERT operations,
192f0 20 77 68 69 63 68 20 6c 65 61 64 73 20 74 6f 20   which leads to 
19300 0a 2a 2a 20 75 6e 69 6e 74 75 69 74 69 76 65 20  .** unintuitive 
19310 72 65 73 75 6c 74 73 2e 20 56 69 72 74 75 61 6c  results. Virtual
19320 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74   table implement
19330 61 74 69 6f 6e 73 20 74 68 61 74 20 64 6f 20 77  ations that do w
19340 72 69 74 65 20 74 6f 20 72 6f 77 69 64 0a 2a 2a  rite to rowid.**
19350 20 74 61 62 6c 65 73 20 69 6e 20 74 68 69 73 20   tables in this 
19360 77 61 79 20 63 61 6e 20 61 76 6f 69 64 20 74 68  way can avoid th
19370 69 73 20 70 72 6f 62 6c 65 6d 20 62 79 20 72 65  is problem by re
19380 73 74 6f 72 69 6e 67 20 74 68 65 20 6f 72 69 67  storing the orig
19390 69 6e 61 6c 20 0a 2a 2a 20 72 6f 77 69 64 20 76  inal .** rowid v
193a0 61 6c 75 65 20 75 73 69 6e 67 20 5b 73 71 6c 69  alue using [sqli
193b0 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73  te3_set_last_ins
193c0 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 62 65 66  ert_rowid()] bef
193d0 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 20 0a 2a  ore returning .*
193e0 2a 20 63 6f 6e 74 72 6f 6c 20 74 6f 20 74 68 65  * control to the
193f0 20 75 73 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49   user..**.** ^(I
19400 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63  f an [INSERT] oc
19410 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 72  curs within a tr
19420 69 67 67 65 72 20 74 68 65 6e 20 74 68 69 73 20  igger then this 
19430 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 0a 2a 2a  routine will .**
19440 20 72 65 74 75 72 6e 20 74 68 65 20 5b 72 6f 77   return the [row
19450 69 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72  id] of the inser
19460 74 65 64 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20  ted row as long 
19470 61 73 20 74 68 65 20 74 72 69 67 67 65 72 20 69  as the trigger i
19480 73 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 2e 20 4f  s .** running. O
19490 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 72 20  nce the trigger 
194a0 70 72 6f 67 72 61 6d 20 65 6e 64 73 2c 20 74 68  program ends, th
194b0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
194c0 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f 75   .** by this rou
194d0 74 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f 20  tine reverts to 
194e0 77 68 61 74 20 69 74 20 77 61 73 20 62 65 66 6f  what it was befo
194f0 72 65 20 74 68 65 20 74 72 69 67 67 65 72 20 77  re the trigger w
19500 61 73 20 66 69 72 65 64 2e 29 5e 0a 2a 2a 0a 2a  as fired.)^.**.*
19510 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74  * ^An [INSERT] t
19520 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f  hat fails due to
19530 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69   a constraint vi
19540 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61  olation is not a
19550 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b  .** successful [
19560 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73  INSERT] and does
19570 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
19580 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
19590 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e  y this.** routin
195a0 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54  e.  ^Thus INSERT
195b0 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54   OR FAIL, INSERT
195c0 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45   OR IGNORE, INSE
195d0 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a  RT OR ROLLBACK,.
195e0 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52  ** and INSERT OR
195f0 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63   ABORT make no c
19600 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65  hanges to the re
19610 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
19620 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68  is.** routine wh
19630 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74 69  en their inserti
19640 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65  on fails.  ^(Whe
19650 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c  n INSERT OR REPL
19660 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72  ACE.** encounter
19670 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76  s a constraint v
19680 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65  iolation, it doe
19690 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65  s not fail.  The
196a0 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69  .** INSERT conti
196b0 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69  nues to completi
196c0 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e  on after deletin
196d0 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 75 73  g rows that caus
196e0 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72  ed.** the constr
196f0 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20  aint problem so 
19700 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43  INSERT OR REPLAC
19710 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68  E will always ch
19720 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75  ange.** the retu
19730 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73  rn value of this
19740 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a   interface.)^.**
19750 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72  .** ^For the pur
19760 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f  poses of this ro
19770 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52  utine, an [INSER
19780 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64  T] is considered
19790 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73   to.** be succes
197a0 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20  sful even if it 
197b0 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20  is subsequently 
197c0 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a  rolled back..**.
197d0 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** This function
197e0 20 69 73 20 61 63 63 65 73 73 69 62 6c 65 20 74   is accessible t
197f0 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  o SQL statements
19800 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73   via the.** [las
19810 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
19820 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a   SQL function]..
19830 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72  **.** If a separ
19840 61 74 65 20 74 68 72 65 61 64 20 70 65 72 66 6f  ate thread perfo
19850 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52  rms a new [INSER
19860 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a  T] on the same.*
19870 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
19880 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20  ction while the 
19890 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e  [sqlite3_last_in
198a0 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a  sert_rowid()].**
198b0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
198c0 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68  ning and thus ch
198d0 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20 69  anges the last i
198e0 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a  nsert [rowid],.*
198f0 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  * then the value
19900 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
19910 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
19920 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a  t_rowid()] is.**
19930 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
19940 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75  nd might not equ
19950 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c  al either the ol
19960 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20  d or the new.** 
19970 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77  last insert [row
19980 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f  id]..*/.sqlite3_
19990 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61  int64 sqlite3_la
199a0 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
199b0 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
199c0 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 20  * CAPI3REF: Set 
199d0 74 68 65 20 4c 61 73 74 20 49 6e 73 65 72 74 20  the Last Insert 
199e0 52 6f 77 69 64 20 76 61 6c 75 65 2e 0a 2a 2a 20  Rowid value..** 
199f0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
19a00 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
19a10 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72  3_set_last_inser
19a20 74 5f 72 6f 77 69 64 28 44 2c 20 52 29 20 6d 65  t_rowid(D, R) me
19a30 74 68 6f 64 20 61 6c 6c 6f 77 73 20 74 68 65 20  thod allows the 
19a40 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a  application to.*
19a50 2a 20 73 65 74 20 74 68 65 20 76 61 6c 75 65 20  * set the value 
19a60 72 65 74 75 72 6e 65 64 20 62 79 20 63 61 6c 6c  returned by call
19a70 69 6e 67 20 73 71 6c 69 74 65 33 5f 6c 61 73 74  ing sqlite3_last
19a80 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29  _insert_rowid(D)
19a90 20 74 6f 20 52 20 0a 2a 2a 20 77 69 74 68 6f 75   to R .** withou
19aa0 74 20 69 6e 73 65 72 74 69 6e 67 20 61 20 72 6f  t inserting a ro
19ab0 77 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62  w into the datab
19ac0 61 73 65 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  ase..*/.void sql
19ad0 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e  ite3_set_last_in
19ae0 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74  sert_rowid(sqlit
19af0 65 33 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36  e3*,sqlite3_int6
19b00 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  4);../*.** CAPI3
19b10 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e  REF: Count The N
19b20 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f  umber Of Rows Mo
19b30 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48 4f 44  dified.** METHOD
19b40 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
19b50 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72  ^This function r
19b60 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
19b70 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69  r of rows modifi
19b80 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 0a  ed, inserted or.
19b90 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20 74 68  ** deleted by th
19ba0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20  e most recently 
19bb0 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54  completed INSERT
19bc0 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45  , UPDATE or DELE
19bd0 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  TE.** statement 
19be0 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  on the database 
19bf0 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 70 65 63 69  connection speci
19c00 66 69 65 64 20 62 79 20 74 68 65 20 6f 6e 6c 79  fied by the only
19c10 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e   parameter..** ^
19c20 45 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f 74  Executing any ot
19c30 68 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c 20  her type of SQL 
19c40 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e  statement does n
19c50 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20 76 61  ot modify the va
19c60 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lue.** returned 
19c70 62 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  by this function
19c80 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 63 68  ..**.** ^Only ch
19c90 61 6e 67 65 73 20 6d 61 64 65 20 64 69 72 65 63  anges made direc
19ca0 74 6c 79 20 62 79 20 74 68 65 20 49 4e 53 45 52  tly by the INSER
19cb0 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c  T, UPDATE or DEL
19cc0 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 61 72  ETE statement ar
19cd0 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20  e.** considered 
19ce0 2d 20 61 75 78 69 6c 69 61 72 79 20 63 68 61 6e  - auxiliary chan
19cf0 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b 43  ges caused by [C
19d00 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20  REATE TRIGGER | 
19d10 74 72 69 67 67 65 72 73 5d 2c 20 0a 2a 2a 20 5b  triggers], .** [
19d20 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69  foreign key acti
19d30 6f 6e 73 5d 20 6f 72 20 5b 52 45 50 4c 41 43 45  ons] or [REPLACE
19d40 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73  ] constraint res
19d50 6f 6c 75 74 69 6f 6e 20 61 72 65 20 6e 6f 74 20  olution are not 
19d60 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20  counted..** .** 
19d70 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65  Changes to a vie
19d80 77 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72  w that are inter
19d90 63 65 70 74 65 64 20 62 79 20 0a 2a 2a 20 5b 49  cepted by .** [I
19da0 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65  NSTEAD OF trigge
19db0 72 20 7c 20 49 4e 53 54 45 41 44 20 4f 46 20 74  r | INSTEAD OF t
19dc0 72 69 67 67 65 72 73 5d 20 61 72 65 20 6e 6f 74  riggers] are not
19dd0 20 63 6f 75 6e 74 65 64 2e 20 5e 54 68 65 20 76   counted. ^The v
19de0 61 6c 75 65 20 0a 2a 2a 20 72 65 74 75 72 6e 65  alue .** returne
19df0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61  d by sqlite3_cha
19e00 6e 67 65 73 28 29 20 69 6d 6d 65 64 69 61 74 65  nges() immediate
19e10 6c 79 20 61 66 74 65 72 20 61 6e 20 49 4e 53 45  ly after an INSE
19e20 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 0a 2a  RT, UPDATE or .*
19e30 2a 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65  * DELETE stateme
19e40 6e 74 20 72 75 6e 20 6f 6e 20 61 20 76 69 65 77  nt run on a view
19e50 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2e   is always zero.
19e60 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61   Only changes ma
19e70 64 65 20 74 6f 20 72 65 61 6c 20 0a 2a 2a 20 74  de to real .** t
19e80 61 62 6c 65 73 20 61 72 65 20 63 6f 75 6e 74 65  ables are counte
19e90 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 67 73 20  d..**.** Things 
19ea0 61 72 65 20 6d 6f 72 65 20 63 6f 6d 70 6c 69 63  are more complic
19eb0 61 74 65 64 20 69 66 20 74 68 65 20 73 71 6c 69  ated if the sqli
19ec0 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66 75  te3_changes() fu
19ed0 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 65 78 65  nction is.** exe
19ee0 63 75 74 65 64 20 77 68 69 6c 65 20 61 20 74 72  cuted while a tr
19ef0 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 69 73  igger program is
19f00 20 72 75 6e 6e 69 6e 67 2e 20 54 68 69 73 20 6d   running. This m
19f10 61 79 20 68 61 70 70 65 6e 20 69 66 20 74 68 65  ay happen if the
19f20 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 65 73  .** program uses
19f30 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20   the [changes() 
19f40 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2c 20 6f  SQL function], o
19f50 72 20 69 66 20 73 6f 6d 65 20 6f 74 68 65 72 20  r if some other 
19f60 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63  callback.** func
19f70 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 73 71 6c  tion invokes sql
19f80 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 64  ite3_changes() d
19f90 69 72 65 63 74 6c 79 2e 20 45 73 73 65 6e 74 69  irectly. Essenti
19fa0 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c  ally:.** .** <ul
19fb0 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 42 65  >.**   <li> ^(Be
19fc0 66 6f 72 65 20 65 6e 74 65 72 69 6e 67 20 61 20  fore entering a 
19fd0 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20  trigger program 
19fe0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
19ff0 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20  ed by.**        
1a000 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
1a010 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 73 61  ) function is sa
1a020 76 65 64 2e 20 41 66 74 65 72 20 74 68 65 20 74  ved. After the t
1a030 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 0a  rigger program .
1a040 2a 2a 20 20 20 20 20 20 20 20 68 61 73 20 66 69  **        has fi
1a050 6e 69 73 68 65 64 2c 20 74 68 65 20 6f 72 69 67  nished, the orig
1a060 69 6e 61 6c 20 76 61 6c 75 65 20 69 73 20 72 65  inal value is re
1a070 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20 0a 2a 2a  stored.)^.** .**
1a080 20 20 20 3c 6c 69 3e 20 5e 28 57 69 74 68 69 6e     <li> ^(Within
1a090 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72   a trigger progr
1a0a0 61 6d 20 65 61 63 68 20 49 4e 53 45 52 54 2c 20  am each INSERT, 
1a0b0 55 50 44 41 54 45 20 61 6e 64 20 44 45 4c 45 54  UPDATE and DELET
1a0c0 45 20 0a 2a 2a 20 20 20 20 20 20 20 20 73 74 61  E .**        sta
1a0d0 74 65 6d 65 6e 74 20 73 65 74 73 20 74 68 65 20  tement sets the 
1a0e0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
1a0f0 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  y sqlite3_change
1a100 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 75  s() .**        u
1a110 70 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61  pon completion a
1a120 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20 63 6f 75  s normal. Of cou
1a130 72 73 65 2c 20 74 68 69 73 20 76 61 6c 75 65 20  rse, this value 
1a140 77 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c 75 64 65  will not include
1a150 20 0a 2a 2a 20 20 20 20 20 20 20 20 61 6e 79 20   .**        any 
1a160 63 68 61 6e 67 65 73 20 70 65 72 66 6f 72 6d 65  changes performe
1a170 64 20 62 79 20 73 75 62 2d 74 72 69 67 67 65 72  d by sub-trigger
1a180 73 2c 20 61 73 20 74 68 65 20 73 71 6c 69 74 65  s, as the sqlite
1a190 33 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20  3_changes() .** 
1a1a0 20 20 20 20 20 20 20 76 61 6c 75 65 20 77 69 6c         value wil
1a1b0 6c 20 62 65 20 73 61 76 65 64 20 61 6e 64 20 72  l be saved and r
1a1c0 65 73 74 6f 72 65 64 20 61 66 74 65 72 20 65 61  estored after ea
1a1d0 63 68 20 73 75 62 2d 74 72 69 67 67 65 72 20 68  ch sub-trigger h
1a1e0 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f 75  as run.)^.** </u
1a1f0 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68 69 73 20  l>.** .** ^This 
1a200 6d 65 61 6e 73 20 74 68 61 74 20 69 66 20 74 68  means that if th
1a210 65 20 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20  e changes() SQL 
1a220 66 75 6e 63 74 69 6f 6e 20 28 6f 72 20 73 69 6d  function (or sim
1a230 69 6c 61 72 29 20 69 73 20 75 73 65 64 0a 2a 2a  ilar) is used.**
1a240 20 62 79 20 74 68 65 20 66 69 72 73 74 20 49 4e   by the first IN
1a250 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20  SERT, UPDATE or 
1a260 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74  DELETE statement
1a270 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65   within a trigge
1a280 72 2c 20 69 74 20 0a 2a 2a 20 72 65 74 75 72 6e  r, it .** return
1a290 73 20 74 68 65 20 76 61 6c 75 65 20 61 73 20 73  s the value as s
1a2a0 65 74 20 77 68 65 6e 20 74 68 65 20 63 61 6c 6c  et when the call
1a2b0 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 62 65  ing statement be
1a2c0 67 61 6e 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a  gan executing..*
1a2d0 2a 20 5e 49 66 20 69 74 20 69 73 20 75 73 65 64  * ^If it is used
1a2e0 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 6f   by the second o
1a2f0 72 20 73 75 62 73 65 71 75 65 6e 74 20 73 75 63  r subsequent suc
1a300 68 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  h statement with
1a310 69 6e 20 61 20 74 72 69 67 67 65 72 20 0a 2a 2a  in a trigger .**
1a320 20 70 72 6f 67 72 61 6d 2c 20 74 68 65 20 76 61   program, the va
1a330 6c 75 65 20 72 65 74 75 72 6e 65 64 20 72 65 66  lue returned ref
1a340 6c 65 63 74 73 20 74 68 65 20 6e 75 6d 62 65 72  lects the number
1a350 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 65   of rows modifie
1a360 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 70 72 65  d by the .** pre
1a370 76 69 6f 75 73 20 49 4e 53 45 52 54 2c 20 55 50  vious INSERT, UP
1a380 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73  DATE or DELETE s
1a390 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
1a3a0 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72  the same trigger
1a3b0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
1a3c0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f   the [sqlite3_to
1a3d0 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  tal_changes()] i
1a3e0 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a  nterface, the.**
1a3f0 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20   [count_changes 
1a400 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65  pragma], and the
1a410 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20   [changes() SQL 
1a420 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  function]..**.**
1a430 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
1a440 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e  hread makes chan
1a450 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ges on the same 
1a460 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1a470 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71  ion.** while [sq
1a480 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d  lite3_changes()]
1a490 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
1a4a0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
1a4b0 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64  ned.** is unpred
1a4c0 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20  ictable and not 
1a4d0 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69  meaningful..*/.i
1a4e0 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  nt sqlite3_chang
1a4f0 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  es(sqlite3*);../
1a500 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
1a510 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52  otal Number Of R
1a520 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20  ows Modified.** 
1a530 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
1a540 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
1a550 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
1a560 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66   total number of
1a570 20 72 6f 77 73 20 69 6e 73 65 72 74 65 64 2c 20   rows inserted, 
1a580 6d 6f 64 69 66 69 65 64 20 6f 72 0a 2a 2a 20 64  modified or.** d
1a590 65 6c 65 74 65 64 20 62 79 20 61 6c 6c 20 5b 49  eleted by all [I
1a5a0 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d  NSERT], [UPDATE]
1a5b0 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61   or [DELETE] sta
1a5c0 74 65 6d 65 6e 74 73 20 63 6f 6d 70 6c 65 74 65  tements complete
1a5d0 64 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 64  d.** since the d
1a5e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1a5f0 6f 6e 20 77 61 73 20 6f 70 65 6e 65 64 2c 20 69  on was opened, i
1a600 6e 63 6c 75 64 69 6e 67 20 74 68 6f 73 65 20 65  ncluding those e
1a610 78 65 63 75 74 65 64 20 61 73 0a 2a 2a 20 70 61  xecuted as.** pa
1a620 72 74 20 6f 66 20 74 72 69 67 67 65 72 20 70 72  rt of trigger pr
1a630 6f 67 72 61 6d 73 2e 20 5e 45 78 65 63 75 74 69  ograms. ^Executi
1a640 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70  ng any other typ
1a650 65 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65  e of SQL stateme
1a660 6e 74 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 61  nt.** does not a
1a670 66 66 65 63 74 20 74 68 65 20 76 61 6c 75 65 20  ffect the value 
1a680 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
1a690 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
1a6a0 73 28 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 61  s()..** .** ^Cha
1a6b0 6e 67 65 73 20 6d 61 64 65 20 61 73 20 70 61 72  nges made as par
1a6c0 74 20 6f 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65  t of [foreign ke
1a6d0 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 69  y actions] are i
1a6e0 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 0a 2a  ncluded in the.*
1a6f0 2a 20 63 6f 75 6e 74 2c 20 62 75 74 20 74 68 6f  * count, but tho
1a700 73 65 20 6d 61 64 65 20 61 73 20 70 61 72 74 20  se made as part 
1a710 6f 66 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74  of REPLACE const
1a720 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e  raint resolution
1a730 20 61 72 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 68   are.** not. ^Ch
1a740 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20  anges to a view 
1a750 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 63 65  that are interce
1a760 70 74 65 64 20 62 79 20 49 4e 53 54 45 41 44 20  pted by INSTEAD 
1a770 4f 46 20 74 72 69 67 67 65 72 73 20 0a 2a 2a 20  OF triggers .** 
1a780 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e  are not counted.
1a790 0a 2a 2a 20 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  .** .** See also
1a7a0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68   the [sqlite3_ch
1a7b0 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61  anges()] interfa
1a7c0 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e  ce, the.** [coun
1a7d0 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61  t_changes pragma
1a7e0 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61  ], and the [tota
1a7f0 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20  l_changes() SQL 
1a800 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  function]..**.**
1a810 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
1a820 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e  hread makes chan
1a830 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ges on the same 
1a840 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1a850 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71  ion.** while [sq
1a860 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
1a870 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e  ges()] is runnin
1a880 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  g then the value
1a890 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20  .** returned is 
1a8a0 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
1a8b0 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c  d not meaningful
1a8c0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1a8d0 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73  _total_changes(s
1a8e0 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
1a8f0 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72   CAPI3REF: Inter
1a900 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e  rupt A Long-Runn
1a910 69 6e 67 20 51 75 65 72 79 0a 2a 2a 20 4d 45 54  ing Query.** MET
1a920 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
1a930 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
1a940 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e  n causes any pen
1a950 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70  ding database op
1a960 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74  eration to abort
1a970 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61   and.** return a
1a980 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f  t its earliest o
1a990 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73  pportunity. This
1a9a0 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69   routine is typi
1a9b0 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20  cally.** called 
1a9c0 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61  in response to a
1a9d0 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63   user action suc
1a9e0 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43  h as pressing "C
1a9f0 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72  ancel".** or Ctr
1aa00 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73  l-C where the us
1aa10 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20  er wants a long 
1aa20 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20  query operation 
1aa30 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64  to halt.** immed
1aa40 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49  iately..**.** ^I
1aa50 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c  t is safe to cal
1aa60 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66  l this routine f
1aa70 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66  rom a thread dif
1aa80 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a  ferent from the.
1aa90 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69  ** thread that i
1aaa0 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e  s currently runn
1aab0 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65  ing the database
1aac0 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74   operation.  But
1aad0 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61   it.** is not sa
1aae0 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20  fe to call this 
1aaf0 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b  routine with a [
1ab00 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1ab10 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20  ion] that.** is 
1ab20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20  closed or might 
1ab30 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c  close before sql
1ab40 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
1ab50 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
1ab60 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61  ^If an SQL opera
1ab70 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61  tion is very nea
1ab80 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 20  rly finished at 
1ab90 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a  the time when.**
1aba0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
1abb0 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20  pt() is called, 
1abc0 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f  then it might no
1abd0 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74  t have an opport
1abe0 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69  unity.** to be i
1abf0 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d  nterrupted and m
1ac00 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f  ight continue to
1ac10 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a   completion..**.
1ac20 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61  ** ^An SQL opera
1ac30 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74  tion that is int
1ac40 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65  errupted will re
1ac50 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54  turn [SQLITE_INT
1ac60 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20  ERRUPT]..** ^If 
1ac70 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20  the interrupted 
1ac80 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  SQL operation is
1ac90 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41   an INSERT, UPDA
1aca0 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  TE, or DELETE.**
1acb0 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20   that is inside 
1acc0 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  an explicit tran
1acd0 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68  saction, then th
1ace0 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63  e entire transac
1acf0 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  tion.** will be 
1ad00 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f  rolled back auto
1ad10 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a  matically..**.**
1ad20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
1ad30 74 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20  terrupt(D) call 
1ad40 69 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74  is in effect unt
1ad50 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79  il all currently
1ad60 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20   running.** SQL 
1ad70 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64  statements on [d
1ad80 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1ad90 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20  on] D complete. 
1ada0 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74   ^Any new SQL st
1adb0 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
1adc0 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
1add0 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  er the sqlite3_i
1ade0 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20  nterrupt() call 
1adf0 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a  and before the .
1ae00 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65  ** running state
1ae10 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65  ments reaches ze
1ae20 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70 74  ro are interrupt
1ae30 65 64 20 61 73 20 69 66 20 74 68 65 79 20 68 61  ed as if they ha
1ae40 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e  d been.** runnin
1ae50 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73  g prior to the s
1ae60 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1ae70 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53  () call.  ^New S
1ae80 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
1ae90 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65   that are starte
1aea0 64 20 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e  d after the runn
1aeb0 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  ing statement co
1aec0 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f  unt reaches zero
1aed0 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65   are.** not effe
1aee0 63 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69  cted by the sqli
1aef0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e  te3_interrupt().
1af00 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73  .** ^A call to s
1af10 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1af20 28 44 29 20 74 68 61 74 20 6f 63 63 75 72 73 20  (D) that occurs 
1af30 77 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e  when there are n
1af40 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c  o running.** SQL
1af50 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61   statements is a
1af60 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e   no-op and has n
1af70 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20  o effect on SQL 
1af80 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68  statements.** th
1af90 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61  at are started a
1afa0 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33  fter the sqlite3
1afb0 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c  _interrupt() cal
1afc0 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2f 0a 76 6f  l returns..*/.vo
1afd0 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  id sqlite3_inter
1afe0 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a  rupt(sqlite3*);.
1aff0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1b000 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e   Determine If An
1b010 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49   SQL Statement I
1b020 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a  s Complete.**.**
1b030 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
1b040 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 69 6e  are useful durin
1b050 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69  g command-line i
1b060 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e  nput to determin
1b070 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72  e if the.** curr
1b080 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65  ently entered te
1b090 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d  xt seems to form
1b0a0 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20   a complete SQL 
1b0b0 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20  statement or.** 
1b0c0 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  if additional in
1b0d0 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62 65  put is needed be
1b0e0 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65  fore sending the
1b0f0 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51   text into.** SQ
1b100 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67  Lite for parsing
1b110 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  .  ^These routin
1b120 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 20 74  es return 1 if t
1b130 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a  he input string.
1b140 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62 65  ** appears to be
1b150 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20   a complete SQL 
1b160 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73  statement.  ^A s
1b170 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67  tatement is judg
1b180 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70  ed to be.** comp
1b190 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 73 20  lete if it ends 
1b1a0 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e  with a semicolon
1b1b0 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f   token and is no
1b1c0 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 61 0a  t a prefix of a.
1b1d0 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43  ** well-formed C
1b1e0 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73 74  REATE TRIGGER st
1b1f0 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63  atement.  ^Semic
1b200 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65  olons that are e
1b210 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a  mbedded within.*
1b220 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  * string literal
1b230 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e  s or quoted iden
1b240 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20  tifier names or 
1b250 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74  comments are not
1b260 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20  .** independent 
1b270 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65  tokens (they are
1b280 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b   part of the tok
1b290 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65 79  en in which they
1b2a0 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64   are.** embedded
1b2b0 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f  ) and thus do no
1b2c0 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61  t count as a sta
1b2d0 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f  tement terminato
1b2e0 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65 0a  r.  ^Whitespace.
1b2f0 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20  ** and comments 
1b300 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20  that follow the 
1b310 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20  final semicolon 
1b320 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a  are ignored..**.
1b330 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
1b340 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 20 74  es return 0 if t
1b350 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
1b360 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66  incomplete.  ^If
1b370 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c   a.** memory all
1b380 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74  ocation fails, t
1b390 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  hen SQLITE_NOMEM
1b3a0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
1b3b0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
1b3c0 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65  nes do not parse
1b3d0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
1b3e0 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c  nts thus.** will
1b3f0 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74   not detect synt
1b400 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72  actically incorr
1b410 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  ect SQL..**.** ^
1b420 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e  (If SQLite has n
1b430 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69  ot been initiali
1b440 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  zed using [sqlit
1b450 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d  e3_initialize()]
1b460 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e   prior .** to in
1b470 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  voking sqlite3_c
1b480 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e  omplete16() then
1b490 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
1b4a0 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
1b4b0 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
1b4c0 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d  y by sqlite3_com
1b4d0 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20 74  plete16().  If t
1b4e0 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  hat initializati
1b4f0 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65  on fails,.** the
1b500 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  n the return val
1b510 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
1b520 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c  complete16() wil
1b530 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a  l be non-zero.**
1b540 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   regardless of w
1b550 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
1b560 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63  e input SQL is c
1b570 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a  omplete.)^.**.**
1b580 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73   The input to [s
1b590 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28  qlite3_complete(
1b5a0 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72  )] must be a zer
1b5b0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
1b5c0 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a  UTF-8 string..**
1b5d0 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f  .** The input to
1b5e0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65   [sqlite3_comple
1b5f0 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20  te16()] must be 
1b600 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
1b610 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69  d.** UTF-16 stri
1b620 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74  ng in native byt
1b630 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20  e order..*/.int 
1b640 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
1b650 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  (const char *sql
1b660 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
1b670 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20  omplete16(const 
1b680 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a  void *sql);../*.
1b690 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67  ** CAPI3REF: Reg
1b6a0 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b  ister A Callback
1b6b0 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54   To Handle SQLIT
1b6c0 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a  E_BUSY Errors.**
1b6d0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 62 75 73 79   KEYWORDS: {busy
1b6e0 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63  -handler callbac
1b6f0 6b 7d 20 7b 62 75 73 79 20 68 61 6e 64 6c 65 72  k} {busy handler
1b700 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  }.** METHOD: sql
1b710 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ite3.**.** ^The 
1b720 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
1b730 64 6c 65 72 28 44 2c 58 2c 50 29 20 72 6f 75 74  dler(D,X,P) rout
1b740 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62  ine sets a callb
1b750 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 0a 2a  ack function X.*
1b760 2a 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20  * that might be 
1b770 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 72 67  invoked with arg
1b780 75 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 65 72  ument P whenever
1b790 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69  .** an attempt i
1b7a0 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73  s made to access
1b7b0 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c   a database tabl
1b7c0 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  e associated wit
1b7d0 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  h.** [database c
1b7e0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 77 68 65  onnection] D whe
1b7f0 6e 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64  n another thread
1b800 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68  .** or process h
1b810 61 73 20 74 68 65 20 74 61 62 6c 65 20 6c 6f 63  as the table loc
1b820 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ked..** The sqli
1b830 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
1b840 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
1b850 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
1b860 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75  t.** [sqlite3_bu
1b870 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 61 6e  sy_timeout()] an
1b880 64 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74  d [PRAGMA busy_t
1b890 69 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  imeout]..**.** ^
1b8a0 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c  If the busy call
1b8b0 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68  back is NULL, th
1b8c0 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  en [SQLITE_BUSY]
1b8d0 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
1b8e0 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e  immediately upon
1b8f0 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68   encountering th
1b900 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65  e lock.  ^If the
1b910 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a   busy callback.*
1b920 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74  * is not NULL, t
1b930 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
1b940 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65   might be invoke
1b950 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d  d with two argum
1b960 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ents..**.** ^The
1b970 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
1b980 74 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  to the busy hand
1b990 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ler is a copy of
1b9a0 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74   the void* point
1b9b0 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74  er which.** is t
1b9c0 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
1b9d0 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73  t to sqlite3_bus
1b9e0 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54  y_handler().  ^T
1b9f0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
1ba00 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73  nt to.** the bus
1ba10 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  y handler callba
1ba20 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  ck is the number
1ba30 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 74   of times that t
1ba40 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
1ba50 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f  has.** been invo
1ba60 6b 65 64 20 70 72 65 76 69 6f 75 73 6c 79 20 66  ked previously f
1ba70 6f 72 20 74 68 65 20 73 61 6d 65 20 6c 6f 63 6b  or the same lock
1ba80 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20  ing event.  ^If 
1ba90 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c  the.** busy call
1baa0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20  back returns 0, 
1bab0 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e  then no addition
1bac0 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 20  al attempts are 
1bad0 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73  made to.** acces
1bae0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61  s the database a
1baf0 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  nd [SQLITE_BUSY]
1bb00 20 69 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20   is returned.** 
1bb10 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  to the applicati
1bb20 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63  on..** ^If the c
1bb30 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
1bb40 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61  non-zero, then a
1bb50 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a  nother attempt.*
1bb60 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63  * is made to acc
1bb70 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ess the database
1bb80 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72   and the cycle r
1bb90 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  epeats..**.** Th
1bba0 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20  e presence of a 
1bbb0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65  busy handler doe
1bbc0 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20  s not guarantee 
1bbd0 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20  that it will be 
1bbe0 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20  invoked.** when 
1bbf0 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f  there is lock co
1bc00 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51  ntention. ^If SQ
1bc10 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20  Lite determines 
1bc20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68  that invoking th
1bc30 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65  e busy.** handle
1bc40 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69  r could result i
1bc50 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74  n a deadlock, it
1bc60 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61   will go ahead a
1bc70 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  nd return [SQLIT
1bc80 45 5f 42 55 53 59 5d 0a 2a 2a 20 74 6f 20 74 68  E_BUSY].** to th
1bc90 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 6e  e application in
1bca0 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e  stead of invokin
1bcb0 67 20 74 68 65 20 0a 2a 2a 20 62 75 73 79 20 68  g the .** busy h
1bcc0 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69  andler..** Consi
1bcd0 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77  der a scenario w
1bce0 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73  here one process
1bcf0 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65   is holding a re
1bd00 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20  ad lock that.** 
1bd10 69 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20  it is trying to 
1bd20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73  promote to a res
1bd30 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a  erved lock and.*
1bd40 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  * a second proce
1bd50 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  ss is holding a 
1bd60 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68  reserved lock th
1bd70 61 74 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a  at it is trying.
1bd80 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f  ** to promote to
1bd90 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f   an exclusive lo
1bda0 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20 70  ck.  The first p
1bdb0 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72  rocess cannot pr
1bdc0 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65  oceed.** because
1bdd0 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62   it is blocked b
1bde0 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64  y the second and
1bdf0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63   the second proc
1be00 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72  ess cannot.** pr
1be10 6f 63 65 65 64 20 62 65 63 61 75 73 65 20 69 74  oceed because it
1be20 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74   is blocked by t
1be30 68 65 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f  he first.  If bo
1be40 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20  th processes.** 
1be50 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20  invoke the busy 
1be60 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65  handlers, neithe
1be70 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20  r will make any 
1be80 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65  progress.  There
1be90 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20  fore,.** SQLite 
1bea0 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
1beb0 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69  BUSY] for the fi
1bec0 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70  rst process, hop
1bed0 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a  ing that this.**
1bee0 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65   will induce the
1bef0 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 74   first process t
1bf00 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20 72 65  o release its re
1bf10 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f  ad lock and allo
1bf20 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20  w.** the second 
1bf30 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65  process to proce
1bf40 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64  ed..**.** ^The d
1bf50 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c  efault busy call
1bf60 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a  back is NULL..**
1bf70 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20  .** ^(There can 
1bf80 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65  only be a single
1bf90 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65   busy handler de
1bfa0 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a  fined for each.*
1bfb0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
1bfc0 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e  ection].  Settin
1bfd0 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e  g a new busy han
1bfe0 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a  dler clears any.
1bff0 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65  ** previously se
1c000 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e  t handler.)^  ^N
1c010 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67  ote that calling
1c020 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74   [sqlite3_busy_t
1c030 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 6f 72 20  imeout()].** or 
1c040 65 76 61 6c 75 61 74 69 6e 67 20 5b 50 52 41 47  evaluating [PRAG
1c050 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 3d  MA busy_timeout=
1c060 4e 5d 20 77 69 6c 6c 20 63 68 61 6e 67 65 20 74  N] will change t
1c070 68 65 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c  he.** busy handl
1c080 65 72 20 61 6e 64 20 74 68 75 73 20 63 6c 65 61  er and thus clea
1c090 72 20 61 6e 79 20 70 72 65 76 69 6f 75 73 6c 79  r any previously
1c0a0 20 73 65 74 20 62 75 73 79 20 68 61 6e 64 6c 65   set busy handle
1c0b0 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73  r..**.** The bus
1c0c0 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c  y callback shoul
1c0d0 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61  d not take any a
1c0e0 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64  ctions which mod
1c0f0 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  ify the.** datab
1c100 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
1c110 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
1c120 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 49  busy handler.  I
1c130 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 0a 2a  n other words,.*
1c140 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  * the busy handl
1c150 65 72 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72  er is not reentr
1c160 61 6e 74 2e 20 20 41 6e 79 20 73 75 63 68 20 61  ant.  Any such a
1c170 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74  ctions.** result
1c180 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65   in undefined be
1c190 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41  havior..** .** A
1c1a0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75   busy handler mu
1c1b0 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65  st not close the
1c1c0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1c1d0 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70  tion.** or [prep
1c1e0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
1c1f0 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
1c200 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a   busy handler..*
1c210 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75  /.int sqlite3_bu
1c220 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74  sy_handler(sqlit
1c230 65 33 2a 2c 69 6e 74 28 2a 29 28 76 6f 69 64 2a  e3*,int(*)(void*
1c240 2c 69 6e 74 29 2c 76 6f 69 64 2a 29 3b 0a 0a 2f  ,int),void*);../
1c250 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
1c260 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75  et A Busy Timeou
1c270 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
1c280 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ite3.**.** ^This
1c290 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20   routine sets a 
1c2a0 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61  [sqlite3_busy_ha
1c2b0 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e  ndler | busy han
1c2c0 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70  dler] that sleep
1c2d0 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69  s.** for a speci
1c2e0 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74  fied amount of t
1c2f0 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65  ime when a table
1c300 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68   is locked.  ^Th
1c310 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c  e handler.** wil
1c320 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65  l sleep multiple
1c330 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20   times until at 
1c340 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69  least "ms" milli
1c350 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
1c360 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75  ing.** have accu
1c370 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72  mulated.  ^After
1c380 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d   at least "ms" m
1c390 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
1c3a0 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20  leeping,.** the 
1c3b0 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20  handler returns 
1c3c0 30 20 77 68 69 63 68 20 63 61 75 73 65 73 20 5b  0 which causes [
1c3d0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1c3e0 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51  to return.** [SQ
1c3f0 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a  LITE_BUSY]..**.*
1c400 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20  * ^Calling this 
1c410 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20  routine with an 
1c420 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68  argument less th
1c430 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a  an or equal to z
1c440 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66  ero.** turns off
1c450 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65   all busy handle
1c460 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72  rs..**.** ^(Ther
1c470 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20  e can only be a 
1c480 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64  single busy hand
1c490 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 69 63  ler for a partic
1c4a0 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ular.** [databas
1c4b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74  e connection] at
1c4c0 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e   any given momen
1c4d0 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62  t.  If another b
1c4e0 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77  usy handler.** w
1c4f0 61 73 20 64 65 66 69 6e 65 64 20 20 28 75 73 69  as defined  (usi
1c500 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ng [sqlite3_busy
1c510 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69  _handler()]) pri
1c520 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a  or to calling.**
1c530 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74   this routine, t
1c540 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 20 68  hat other busy h
1c550 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65  andler is cleare
1c560 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  d.)^.**.** See a
1c570 6c 73 6f 3a 20 20 5b 50 52 41 47 4d 41 20 62 75  lso:  [PRAGMA bu
1c580 73 79 5f 74 69 6d 65 6f 75 74 5d 0a 2a 2f 0a 69  sy_timeout].*/.i
1c590 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  nt sqlite3_busy_
1c5a0 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a  timeout(sqlite3*
1c5b0 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a  , int ms);../*.*
1c5c0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76  * CAPI3REF: Conv
1c5d0 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73  enience Routines
1c5e0 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65   For Running Que
1c5f0 72 69 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ries.** METHOD: 
1c600 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68  sqlite3.**.** Th
1c610 69 73 20 69 73 20 61 20 6c 65 67 61 63 79 20 69  is is a legacy i
1c620 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 69 73  nterface that is
1c630 20 70 72 65 73 65 72 76 65 64 20 66 6f 72 20 62   preserved for b
1c640 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
1c650 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f  bility..** Use o
1c660 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  f this interface
1c670 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e   is not recommen
1c680 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e  ded..**.** Defin
1c690 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75  ition: A <b>resu
1c6a0 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20  lt table</b> is 
1c6b0 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75  memory data stru
1c6c0 63 74 75 72 65 20 63 72 65 61 74 65 64 20 62 79  cture created by
1c6d0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
1c6e0 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e  _get_table()] in
1c6f0 74 65 72 66 61 63 65 2e 20 20 41 20 72 65 73 75  terface.  A resu
1c700 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73  lt table records
1c710 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65   the.** complete
1c720 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 66   query results f
1c730 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  rom one or more 
1c740 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  queries..**.** T
1c750 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74  he table concept
1c760 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62  ually has a numb
1c770 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63  er of rows and c
1c780 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20  olumns.  But.** 
1c790 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72  these numbers ar
1c7a0 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68  e not part of th
1c7b0 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  e result table i
1c7c0 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a  tself.  These.**
1c7d0 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74   numbers are obt
1c7e0 61 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79  ained separately
1c7f0 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20  .  Let N be the 
1c800 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a  number of rows.*
1c810 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e  * and M be the n
1c820 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
1c830 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74  ..**.** A result
1c840 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72   table is an arr
1c850 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
1c860 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  o zero-terminate
1c870 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e  d UTF-8 strings.
1c880 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e  .** There are (N
1c890 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69  +1)*M elements i
1c8a0 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20 54 68  n the array.  Th
1c8b0 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65  e first M pointe
1c8c0 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a  rs point.** to z
1c8d0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73  ero-terminated s
1c8e0 74 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e  trings that  con
1c8f0 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f  tain the names o
1c900 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a  f the columns..*
1c910 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20  * The remaining 
1c920 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e  entries all poin
1c930 74 20 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c  t to query resul
1c940 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73  ts.  NULL values
1c950 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55   result.** in NU
1c960 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c  LL pointers.  Al
1c970 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61  l other values a
1c980 72 65 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d  re in their UTF-
1c990 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  8 zero-terminate
1c9a0 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72  d.** string repr
1c9b0 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65  esentation as re
1c9c0 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
1c9d0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
1c9e0 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c  ]..**.** A resul
1c9f0 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f  t table might co
1ca00 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20  nsist of one or 
1ca10 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  more memory allo
1ca20 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69  cations..** It i
1ca30 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61  s not safe to pa
1ca40 73 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c  ss a result tabl
1ca50 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73  e directly to [s
1ca60 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
1ca70 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  ** A result tabl
1ca80 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c  e should be deal
1ca90 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73  located using [s
1caa0 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
1cab0 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73  e()]..**.** ^(As
1cac0 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74   an example of t
1cad0 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
1cae0 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20  format, suppose 
1caf0 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a  a query result.*
1cb00 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  * is as follows:
1cb10 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1cb20 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20  te><pre>.**     
1cb30 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c     Name        |
1cb40 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d   Age.**        -
1cb50 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1cb60 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20  ------.**       
1cb70 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34   Alice       | 4
1cb80 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20  3.**        Bob 
1cb90 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20          | 28.** 
1cba0 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20         Cindy    
1cbb0 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65     | 21.** </pre
1cbc0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1cbd0 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74  *.** There are t
1cbe0 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29  wo column (M==2)
1cbf0 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20   and three rows 
1cc00 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68  (N==3).  Thus th
1cc10 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c  e.** result tabl
1cc20 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e  e has 8 entries.
1cc30 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 65    Suppose the re
1cc40 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74  sult table is st
1cc50 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72  ored.** in an ar
1cc60 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75  ray names azResu
1cc70 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75  lt.  Then azResu
1cc80 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f  lt holds this co
1cc90 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  ntent:.**.** <bl
1cca0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1ccb0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1ccc0 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65  t&#91;0] = "Name
1ccd0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1cce0 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22  esult&#91;1] = "
1ccf0 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  Age";.**        
1cd00 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20  azResult&#91;2] 
1cd10 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20  = "Alice";.**   
1cd20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1cd30 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20  1;3] = "43";.** 
1cd40 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1cd50 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a  #91;4] = "Bob";.
1cd60 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1cd70 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22  lt&#91;5] = "28"
1cd80 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1cd90 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43  sult&#91;6] = "C
1cda0 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20  indy";.**       
1cdb0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d   azResult&#91;7]
1cdc0 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72   = "21";.** </pr
1cdd0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29  e></blockquote>)
1cde0 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ^.**.** ^The sql
1cdf0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1ce00 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61   function evalua
1ce10 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a  tes one or more.
1ce20 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70  ** semicolon-sep
1ce30 61 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65  arated SQL state
1ce40 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72  ments in the zer
1ce50 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
1ce60 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20  -8.** string of 
1ce70 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65  its 2nd paramete
1ce80 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  r and returns a 
1ce90 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20  result table to 
1cea0 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67  the.** pointer g
1ceb0 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20  iven in its 3rd 
1cec0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
1ced0 20 41 66 74 65 72 20 74 68 65 20 61 70 70 6c 69   After the appli
1cee0 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73  cation has finis
1cef0 68 65 64 20 77 69 74 68 20 74 68 65 20 72 65 73  hed with the res
1cf00 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ult from sqlite3
1cf10 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a  _get_table(),.**
1cf20 20 69 74 20 6d 75 73 74 20 70 61 73 73 20 74 68   it must pass th
1cf30 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70  e result table p
1cf40 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ointer to sqlite
1cf50 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69  3_free_table() i
1cf60 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65  n order to.** re
1cf70 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  lease the memory
1cf80 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63   that was malloc
1cf90 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20  ed.  Because of 
1cfa0 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b  the way the.** [
1cfb0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1cfc0 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e  ] happens within
1cfd0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1cfe0 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e  le(), the callin
1cff0 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75  g.** function mu
1d000 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61  st not try to ca
1d010 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ll [sqlite3_free
1d020 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f  ()] directly.  O
1d030 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nly.** [sqlite3_
1d040 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73  free_table()] is
1d050 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65   able to release
1d060 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70   the memory prop
1d070 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e  erly and safely.
1d080 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
1d090 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69  e3_get_table() i
1d0a0 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c  nterface is impl
1d0b0 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72 61  emented as a wra
1d0c0 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b  pper around.** [
1d0d0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e  sqlite3_exec()].
1d0e0 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65    The sqlite3_ge
1d0f0 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e  t_table() routin
1d100 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  e does not have 
1d110 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79  access.** to any
1d120 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73   internal data s
1d130 74 72 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c  tructures of SQL
1d140 69 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e  ite.  It uses on
1d150 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a  ly the public.**
1d160 20 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e   interface defin
1d170 65 64 20 68 65 72 65 2e 20 20 41 73 20 61 20 63  ed here.  As a c
1d180 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f  onsequence, erro
1d190 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e  rs that occur in
1d1a0 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20   the.** wrapper 
1d1b0 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66  layer outside of
1d1c0 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73   the internal [s
1d1d0 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63  qlite3_exec()] c
1d1e0 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72  all are not.** r
1d1f0 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73  eflected in subs
1d200 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
1d210 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
1d220 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
1d230 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f  e3_errmsg()]..*/
1d240 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74  .int sqlite3_get
1d250 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65  _table(.  sqlite
1d260 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
1d270 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62  /* An open datab
1d280 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ase */.  const c
1d290 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f  har *zSql,     /
1d2a0 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c  * SQL to be eval
1d2b0 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20  uated */.  char 
1d2c0 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20  ***pazResult,   
1d2d0 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74   /* Results of t
1d2e0 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e  he query */.  in
1d2f0 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20  t *pnRow,       
1d300 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66      /* Number of
1d310 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69   result rows wri
1d320 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69  tten here */.  i
1d330 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20  nt *pnColumn,   
1d340 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f       /* Number o
1d350 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73  f result columns
1d360 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
1d370 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d  .  char **pzErrm
1d380 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f  sg       /* Erro
1d390 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65  r msg written he
1d3a0 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71  re */.);.void sq
1d3b0 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
1d3c0 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b  (char **result);
1d3d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1d3e0 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69  : Formatted Stri
1d3f0 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63  ng Printing Func
1d400 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
1d410 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77  e routines are w
1d420 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68  ork-alikes of th
1d430 65 20 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d  e "printf()" fam
1d440 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73  ily of functions
1d450 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61  .** from the sta
1d460 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
1d470 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
1d480 65 73 20 75 6e 64 65 72 73 74 61 6e 64 20 6d 6f  es understand mo
1d490 73 74 20 6f 66 20 74 68 65 20 63 6f 6d 6d 6f 6e  st of the common
1d4a0 20 4b 26 52 20 66 6f 72 6d 61 74 74 69 6e 67 20   K&R formatting 
1d4b0 6f 70 74 69 6f 6e 73 2c 0a 2a 2a 20 70 6c 75 73  options,.** plus
1d4c0 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c   some additional
1d4d0 20 6e 6f 6e 2d 73 74 61 6e 64 61 72 64 20 66 6f   non-standard fo
1d4e0 72 6d 61 74 73 2c 20 64 65 74 61 69 6c 65 64 20  rmats, detailed 
1d4f0 62 65 6c 6f 77 2e 0a 2a 2a 20 4e 6f 74 65 20 74  below..** Note t
1d500 68 61 74 20 73 6f 6d 65 20 6f 66 20 74 68 65 20  hat some of the 
1d510 6d 6f 72 65 20 6f 62 73 63 75 72 65 20 66 6f 72  more obscure for
1d520 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20  matting options 
1d530 66 72 6f 6d 20 72 65 63 65 6e 74 0a 2a 2a 20 43  from recent.** C
1d540 2d 6c 69 62 72 61 72 79 20 73 74 61 6e 64 61 72  -library standar
1d550 64 73 20 61 72 65 20 6f 6d 69 74 74 65 64 20 66  ds are omitted f
1d560 72 6f 6d 20 74 68 69 73 20 69 6d 70 6c 65 6d 65  rom this impleme
1d570 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  ntation..**.** ^
1d580 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  The sqlite3_mpri
1d590 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ntf() and sqlite
1d5a0 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75  3_vmprintf() rou
1d5b0 74 69 6e 65 73 20 77 72 69 74 65 20 74 68 65 69  tines write thei
1d5c0 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74  r.** results int
1d5d0 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
1d5e0 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
1d5f0 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68  malloc()]..** Th
1d600 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e  e strings return
1d610 65 64 20 62 79 20 74 68 65 73 65 20 74 77 6f 20  ed by these two 
1d620 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20  routines should 
1d630 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62  be.** released b
1d640 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  y [sqlite3_free(
1d650 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74 69  )].  ^Both routi
1d660 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20  nes return a.** 
1d670 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20  NULL pointer if 
1d680 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1d690 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  )] is unable to 
1d6a0 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a  allocate enough.
1d6b0 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c  ** memory to hol
1d6c0 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20  d the resulting 
1d6d0 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28  string..**.** ^(
1d6e0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6e 70 72  The sqlite3_snpr
1d6f0 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69  intf() routine i
1d700 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e  s similar to "sn
1d710 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a  printf()" from.*
1d720 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  * the standard C
1d730 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 72   library.  The r
1d740 65 73 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e  esult is written
1d750 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66   into the.** buf
1d760 66 65 72 20 73 75 70 70 6c 69 65 64 20 61 73 20  fer supplied as 
1d770 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
1d780 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20  eter whose size 
1d790 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74  is given by.** t
1d7a0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
1d7b0 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68  er. Note that th
1d7c0 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a  e order of the.*
1d7d0 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61 72 61  * first two para
1d7e0 6d 65 74 65 72 73 20 69 73 20 72 65 76 65 72 73  meters is revers
1d7f0 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66  ed from snprintf
1d800 28 29 2e 29 5e 20 20 54 68 69 73 20 69 73 20 61  ().)^  This is a
1d810 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20  n.** historical 
1d820 61 63 63 69 64 65 6e 74 20 74 68 61 74 20 63 61  accident that ca
1d830 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77 69  nnot be fixed wi
1d840 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a  thout breaking.*
1d850 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  * backwards comp
1d860 61 74 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f  atibility.  ^(No
1d870 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c  te also that sql
1d880 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
1d890 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ** returns a poi
1d8a0 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75 66 66  nter to its buff
1d8b0 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68  er instead of th
1d8c0 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63  e number of.** c
1d8d0 68 61 72 61 63 74 65 72 73 20 61 63 74 75 61 6c  haracters actual
1d8e0 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  ly written into 
1d8f0 74 68 65 20 62 75 66 66 65 72 2e 29 5e 20 20 57  the buffer.)^  W
1d900 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20  e admit that.** 
1d910 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
1d920 61 72 61 63 74 65 72 73 20 77 72 69 74 74 65 6e  aracters written
1d930 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65   would be a more
1d940 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a   useful return.*
1d950 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65 20 63  * value but we c
1d960 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  annot change the
1d970 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
1d980 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  of sqlite3_snpri
1d990 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74  ntf().** now wit
1d9a0 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f  hout breaking co
1d9b0 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a  mpatibility..**.
1d9c0 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74  ** ^As long as t
1d9d0 68 65 20 62 75 66 66 65 72 20 73 69 7a 65 20 69  he buffer size i
1d9e0 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a  s greater than z
1d9f0 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70  ero, sqlite3_snp
1da00 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61  rintf().** guara
1da10 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 62  ntees that the b
1da20 75 66 66 65 72 20 69 73 20 61 6c 77 61 79 73 20  uffer is always 
1da30 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e  zero-terminated.
1da40 20 20 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a 20    ^The first.** 
1da50 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73  parameter "n" is
1da60 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20   the total size 
1da70 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c 20 69  of the buffer, i
1da80 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66  ncluding space f
1da90 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74  or.** the zero t
1daa0 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74  erminator.  So t
1dab0 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e  he longest strin
1dac0 67 20 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f  g that can be co
1dad0 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74  mpletely.** writ
1dae0 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20  ten will be n-1 
1daf0 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a  characters..**.*
1db00 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
1db10 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69  snprintf() routi
1db20 6e 65 20 69 73 20 61 20 76 61 72 61 72 67 73 20  ne is a varargs 
1db30 76 65 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74  version of sqlit
1db40 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a  e3_snprintf()..*
1db50 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
1db60 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e  nes all implemen
1db70 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61  t some additiona
1db80 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20  l formatting.** 
1db90 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65  options that are
1dba0 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73   useful for cons
1dbb0 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61  tructing SQL sta
1dbc0 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20  tements..** All 
1dbd0 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70 72 69  of the usual pri
1dbe0 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e 67  ntf() formatting
1dbf0 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20   options apply. 
1dc00 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68   In addition, th
1dc10 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 25  ere.** is are "%
1dc20 71 22 2c 20 22 25 51 22 2c 20 22 25 77 22 20 61  q", "%Q", "%w" a
1dc30 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e  nd "%z" options.
1dc40 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20  .**.** ^(The %q 
1dc50 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b  option works lik
1dc60 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 20  e %s in that it 
1dc70 73 75 62 73 74 69 74 75 74 65 73 20 61 20 6e 75  substitutes a nu
1dc80 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  l-terminated.** 
1dc90 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20  string from the 
1dca0 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20  argument list.  
1dcb0 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62  But %q also doub
1dcc0 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 63  les every '\'' c
1dcd0 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20  haracter..** %q 
1dce0 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20  is designed for 
1dcf0 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 72  use inside a str
1dd00 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20  ing literal.)^  
1dd10 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68  By doubling each
1dd20 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74   '\''.** charact
1dd30 65 72 20 69 74 20 65 73 63 61 70 65 73 20 74 68  er it escapes th
1dd40 61 74 20 63 68 61 72 61 63 74 65 72 20 61 6e 64  at character and
1dd50 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65   allows it to be
1dd60 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a   inserted into.*
1dd70 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a  * the string..**
1dd80 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  .** For example,
1dd90 20 61 73 73 75 6d 65 20 74 68 65 20 73 74 72 69   assume the stri
1dda0 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78  ng variable zTex
1ddb0 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20  t contains text 
1ddc0 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
1ddd0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1dde0 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54  re>.**  char *zT
1ddf0 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68 61  ext = "It's a ha
1de00 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f  ppy day!";.** </
1de10 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1de20 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20  >.**.** One can 
1de30 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69 6e  use this text in
1de40 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
1de50 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  t as follows:.**
1de60 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1de70 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a  <pre>.**  char *
1de80 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d  zSQL = sqlite3_m
1de90 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49  printf("INSERT I
1dea0 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53  NTO table VALUES
1deb0 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b  ('%q')", zText);
1dec0 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65  .**  sqlite3_exe
1ded0 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30  c(db, zSQL, 0, 0
1dee0 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  , 0);.**  sqlite
1def0 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a  3_free(zSQL);.**
1df00 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1df10 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75  ote>.**.** Becau
1df20 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74  se the %q format
1df30 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c   string is used,
1df40 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61 63   the '\'' charac
1df50 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20  ter in zText.** 
1df60 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20 74  is escaped and t
1df70 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64  he SQL generated
1df80 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a   is as follows:.
1df90 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1dfa0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45  e><pre>.**  INSE
1dfb0 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56  RT INTO table1 V
1dfc0 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20 68  ALUES('It''s a h
1dfd0 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c  appy day!').** <
1dfe0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1dff0 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73  e>.**.** This is
1e000 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77   correct.  Had w
1e010 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65 61  e used %s instea
1e020 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e  d of %q, the gen
1e030 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f  erated SQL.** wo
1e040 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20  uld have looked 
1e050 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a  like this:.**.**
1e060 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1e070 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e  e>.**  INSERT IN
1e080 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53  TO table1 VALUES
1e090 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20 64  ('It's a happy d
1e0a0 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  ay!');.** </pre>
1e0b0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1e0c0 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20  .** This second 
1e0d0 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51  example is an SQ
1e0e0 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20  L syntax error. 
1e0f0 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75   As a general ru
1e100 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a  le you should.**
1e110 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20 69   always use %q i
1e120 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68 65  nstead of %s whe
1e130 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74  n inserting text
1e140 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c   into a string l
1e150 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28  iteral..**.** ^(
1e160 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f  The %Q option wo
1e170 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65  rks like %q exce
1e180 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20  pt it also adds 
1e190 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72  single quotes ar
1e1a0 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73  ound.** the outs
1e1b0 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c  ide of the total
1e1c0 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74 69   string.  Additi
1e1d0 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 70  onally, if the p
1e1e0 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 0a  arameter in the.
1e1f0 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74  ** argument list
1e200 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
1e210 65 72 2c 20 25 51 20 73 75 62 73 74 69 74 75 74  er, %Q substitut
1e220 65 73 20 74 68 65 20 74 65 78 74 20 22 4e 55 4c  es the text "NUL
1e230 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73  L" (without.** s
1e240 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e  ingle quotes).)^
1e250 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c    So, for exampl
1e260 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79  e, one could say
1e270 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1e280 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
1e290 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74  ar *zSQL = sqlit
1e2a0 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45  e3_mprintf("INSE
1e2b0 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41  RT INTO table VA
1e2c0 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74  LUES(%Q)", zText
1e2d0 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65  );.**  sqlite3_e
1e2e0 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c  xec(db, zSQL, 0,
1e2f0 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69   0, 0);.**  sqli
1e300 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a  te3_free(zSQL);.
1e310 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1e320 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  quote>.**.** The
1e330 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c   code above will
1e340 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63   render a correc
1e350 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  t SQL statement 
1e360 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76  in the zSQL.** v
1e370 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20  ariable even if 
1e380 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61 62  the zText variab
1e390 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  le is a NULL poi
1e3a0 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  nter..**.** ^(Th
1e3b0 65 20 22 25 77 22 20 66 6f 72 6d 61 74 74 69 6e  e "%w" formattin
1e3c0 67 20 6f 70 74 69 6f 6e 20 69 73 20 6c 69 6b 65  g option is like
1e3d0 20 22 25 71 22 20 65 78 63 65 70 74 20 74 68 61   "%q" except tha
1e3e0 74 20 69 74 20 65 78 70 65 63 74 73 20 74 6f 0a  t it expects to.
1e3f0 2a 2a 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20  ** be contained 
1e400 77 69 74 68 69 6e 20 64 6f 75 62 6c 65 2d 71 75  within double-qu
1e410 6f 74 65 73 20 69 6e 73 74 65 61 64 20 6f 66 20  otes instead of 
1e420 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 2c 20 61  single quotes, a
1e430 6e 64 20 69 74 0a 2a 2a 20 65 73 63 61 70 65 73  nd it.** escapes
1e440 20 74 68 65 20 64 6f 75 62 6c 65 2d 71 75 6f 74   the double-quot
1e450 65 20 63 68 61 72 61 63 74 65 72 20 69 6e 73 74  e character inst
1e460 65 61 64 20 6f 66 20 74 68 65 20 73 69 6e 67 6c  ead of the singl
1e470 65 2d 71 75 6f 74 65 0a 2a 2a 20 63 68 61 72 61  e-quote.** chara
1e480 63 74 65 72 2e 29 5e 20 20 54 68 65 20 22 25 77  cter.)^  The "%w
1e490 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74  " formatting opt
1e4a0 69 6f 6e 20 69 73 20 69 6e 74 65 6e 64 65 64 20  ion is intended 
1e4b0 66 6f 72 20 73 61 66 65 6c 79 20 69 6e 73 65 72  for safely inser
1e4c0 74 69 6e 67 0a 2a 2a 20 74 61 62 6c 65 20 61 6e  ting.** table an
1e4d0 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 73 20 69  d column names i
1e4e0 6e 74 6f 20 61 20 63 6f 6e 73 74 72 75 63 74 65  nto a constructe
1e4f0 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  d SQL statement.
1e500 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a  .**.** ^(The "%z
1e510 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74  " formatting opt
1e520 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22  ion works like "
1e530 25 73 22 20 62 75 74 20 77 69 74 68 20 74 68 65  %s" but with the
1e540 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 61  .** addition tha
1e550 74 20 61 66 74 65 72 20 74 68 65 20 73 74 72 69  t after the stri
1e560 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65 61 64  ng has been read
1e570 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 6f   and copied into
1e580 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c 20  .** the result, 
1e590 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1e5a0 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68   is called on th
1e5b0 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 29  e input string.)
1e5c0 5e 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74  ^.*/.char *sqlit
1e5d0 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74  e3_mprintf(const
1e5e0 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61   char*,...);.cha
1e5f0 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69  r *sqlite3_vmpri
1e600 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ntf(const char*,
1e610 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20   va_list);.char 
1e620 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  *sqlite3_snprint
1e630 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73  f(int,char*,cons
1e640 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 63  t char*, ...);.c
1e650 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e  har *sqlite3_vsn
1e660 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a  printf(int,char*
1e670 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61  ,const char*, va
1e680 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _list);../*.** C
1e690 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
1e6a0 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79  Allocation Subsy
1e6b0 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  stem.**.** The S
1e6c0 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 20  QLite core uses 
1e6d0 74 68 65 73 65 20 74 68 72 65 65 20 72 6f 75 74  these three rout
1e6e0 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20  ines for all of 
1e6f0 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72  its own.** inter
1e700 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  nal memory alloc
1e710 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f  ation needs. "Co
1e720 72 65 22 20 69 6e 20 74 68 65 20 70 72 65 76 69  re" in the previ
1e730 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20  ous sentence.** 
1e740 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
1e750 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65   operating-syste
1e760 6d 20 73 70 65 63 69 66 69 63 20 56 46 53 20 69  m specific VFS i
1e770 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20  mplementation.  
1e780 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56  The.** Windows V
1e790 46 53 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d  FS uses native m
1e7a0 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65  alloc() and free
1e7b0 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72  () for some oper
1e7c0 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ations..**.** ^T
1e7d0 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  he sqlite3_mallo
1e7e0 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  c() routine retu
1e7f0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
1e800 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d   a block.** of m
1e810 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e  emory at least N
1e820 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68   bytes in length
1e830 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
1e840 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e   parameter..** ^
1e850 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  If sqlite3_mallo
1e860 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  c() is unable to
1e870 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69 65   obtain sufficie
1e880 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72  nt free.** memor
1e890 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61 20  y, it returns a 
1e8a0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e  NULL pointer.  ^
1e8b0 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  If the parameter
1e8c0 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33   N to.** sqlite3
1e8d0 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72  _malloc() is zer
1e8e0 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68  o or negative th
1e8f0 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  en sqlite3_mallo
1e900 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  c() returns.** a
1e910 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
1e920 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1e930 33 5f 6d 61 6c 6c 6f 63 36 34 28 4e 29 20 72 6f  3_malloc64(N) ro
1e940 75 74 69 6e 65 20 77 6f 72 6b 73 20 6a 75 73 74  utine works just
1e950 20 6c 69 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33   like.** sqlite3
1e960 5f 6d 61 6c 6c 6f 63 28 4e 29 20 65 78 63 65 70  _malloc(N) excep
1e970 74 20 74 68 61 74 20 4e 20 69 73 20 61 6e 20 75  t that N is an u
1e980 6e 73 69 67 6e 65 64 20 36 34 2d 62 69 74 20 69  nsigned 64-bit i
1e990 6e 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a  nteger instead.*
1e9a0 2a 20 6f 66 20 61 20 73 69 67 6e 65 64 20 33 32  * of a signed 32
1e9b0 2d 62 69 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a  -bit integer..**
1e9c0 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c  .** ^Calling sql
1e9d0 69 74 65 33 5f 66 72 65 65 28 29 20 77 69 74 68  ite3_free() with
1e9e0 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69   a pointer previ
1e9f0 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a  ously returned.*
1ea00 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c  * by sqlite3_mal
1ea10 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33  loc() or sqlite3
1ea20 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61  _realloc() relea
1ea30 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20  ses that memory 
1ea40 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69  so.** that it mi
1ea50 67 68 74 20 62 65 20 72 65 75 73 65 64 2e 20 20  ght be reused.  
1ea60 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65  ^The sqlite3_fre
1ea70 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a  e() routine is.*
1ea80 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20  * a no-op if is 
1ea90 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55  called with a NU
1eaa0 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73  LL pointer.  Pas
1eab0 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  sing a NULL poin
1eac0 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  ter.** to sqlite
1ead0 33 5f 66 72 65 65 28 29 20 69 73 20 68 61 72 6d  3_free() is harm
1eae0 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62 65 69  less.  After bei
1eaf0 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79  ng freed, memory
1eb00 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68  .** should neith
1eb10 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77  er be read nor w
1eb20 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65  ritten.  Even re
1eb30 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79  ading previously
1eb40 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79   freed.** memory
1eb50 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e   might result in
1eb60 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20   a segmentation 
1eb70 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73  fault or other s
1eb80 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20  evere error..** 
1eb90 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f  Memory corruptio
1eba0 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f  n, a segmentatio
1ebb0 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65  n fault, or othe
1ebc0 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a  r severe error.*
1ebd0 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69  * might result i
1ebe0 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  f sqlite3_free()
1ebf0 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
1ec00 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
1ec10 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e  er that.** was n
1ec20 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ot obtained from
1ec30 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1ec40 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61  ) or sqlite3_rea
1ec50 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  lloc()..**.** ^T
1ec60 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  he sqlite3_reall
1ec70 6f 63 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63  oc(X,N) interfac
1ec80 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65  e attempts to re
1ec90 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20  size a.** prior 
1eca0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1ecb0 6e 20 58 20 74 6f 20 62 65 20 61 74 20 6c 65 61  n X to be at lea
1ecc0 73 74 20 4e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e  st N bytes..** ^
1ecd0 49 66 20 74 68 65 20 58 20 70 61 72 61 6d 65 74  If the X paramet
1ece0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
1ecf0 61 6c 6c 6f 63 28 58 2c 4e 29 0a 2a 2a 20 69 73  alloc(X,N).** is
1ed00 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
1ed10 74 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f  then its behavio
1ed20 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74  r is identical t
1ed30 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c  o calling.** sql
1ed40 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 2e 0a  ite3_malloc(N)..
1ed50 2a 2a 20 5e 49 66 20 74 68 65 20 4e 20 70 61 72  ** ^If the N par
1ed60 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
1ed70 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69  3_realloc(X,N) i
1ed80 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67  s zero or.** neg
1ed90 61 74 69 76 65 20 74 68 65 6e 20 74 68 65 20 62  ative then the b
1eda0 65 68 61 76 69 6f 72 20 69 73 20 65 78 61 63 74  ehavior is exact
1edb0 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 20 63  ly the same as c
1edc0 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  alling.** sqlite
1edd0 33 5f 66 72 65 65 28 58 29 2e 0a 2a 2a 20 5e 73  3_free(X)..** ^s
1ede0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58  qlite3_realloc(X
1edf0 2c 4e 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ,N) returns a po
1ee00 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72  inter to a memor
1ee10 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
1ee20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  of at least N by
1ee30 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e  tes in size or N
1ee40 55 4c 4c 20 69 66 20 69 6e 73 75 66 66 69 63 69  ULL if insuffici
1ee50 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 61 76  ent memory is av
1ee60 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20  ailable..** ^If 
1ee70 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66  M is the size of
1ee80 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
1ee90 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28  ation, then min(
1eea0 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66  N,M) bytes.** of
1eeb0 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
1eec0 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64  ation are copied
1eed0 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e   into the beginn
1eee0 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72 65  ing of buffer re
1eef0 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c  turned.** by sql
1ef00 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e  ite3_realloc(X,N
1ef10 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20  ) and the prior 
1ef20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72  allocation is fr
1ef30 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  eed..** ^If sqli
1ef40 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
1ef50 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e   returns NULL an
1ef60 64 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65 2c  d N is positive,
1ef70 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 70 72 69   then the.** pri
1ef80 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73  or allocation is
1ef90 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a   not freed..**.*
1efa0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
1efb0 65 61 6c 6c 6f 63 36 34 28 58 2c 4e 29 20 69 6e  ealloc64(X,N) in
1efc0 74 65 72 66 61 63 65 73 20 77 6f 72 6b 73 20 74  terfaces works t
1efd0 68 65 20 73 61 6d 65 20 61 73 0a 2a 2a 20 73 71  he same as.** sq
1efe0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
1eff0 4e 29 20 65 78 63 65 70 74 20 74 68 61 74 20 4e  N) except that N
1f000 20 69 73 20 61 20 36 34 2d 62 69 74 20 75 6e 73   is a 64-bit uns
1f010 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 69 6e  igned integer in
1f020 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 33 32  stead.** of a 32
1f030 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
1f040 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 58  ger..**.** ^If X
1f050 20 69 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   is a memory all
1f060 6f 63 61 74 69 6f 6e 20 70 72 65 76 69 6f 75 73  ocation previous
1f070 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ly obtained from
1f080 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1f090 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  ),.** sqlite3_ma
1f0a0 6c 6c 6f 63 36 34 28 29 2c 20 73 71 6c 69 74 65  lloc64(), sqlite
1f0b0 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 20 6f 72 20  3_realloc(), or 
1f0c0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36  sqlite3_realloc6
1f0d0 34 28 29 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c  4(), then.** sql
1f0e0 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65  ite3_msize(X) re
1f0f0 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f  turns the size o
1f100 66 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 61 6c  f that memory al
1f110 6c 6f 63 61 74 69 6f 6e 20 69 6e 20 62 79 74 65  location in byte
1f120 73 2e 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65  s..** ^The value
1f130 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
1f140 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 6d 69  ite3_msize(X) mi
1f150 67 68 74 20 62 65 20 6c 61 72 67 65 72 20 74 68  ght be larger th
1f160 61 6e 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a  an the number.**
1f170 20 6f 66 20 62 79 74 65 73 20 72 65 71 75 65 73   of bytes reques
1f180 74 65 64 20 77 68 65 6e 20 58 20 77 61 73 20 61  ted when X was a
1f190 6c 6c 6f 63 61 74 65 64 2e 20 20 5e 49 66 20 58  llocated.  ^If X
1f1a0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
1f1b0 65 72 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  er then.** sqlit
1f1c0 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 75  e3_msize(X) retu
1f1d0 72 6e 73 20 7a 65 72 6f 2e 20 20 49 66 20 58 20  rns zero.  If X 
1f1e0 70 6f 69 6e 74 73 20 74 6f 20 73 6f 6d 65 74 68  points to someth
1f1f0 69 6e 67 20 74 68 61 74 20 69 73 20 6e 6f 74 0a  ing that is not.
1f200 2a 2a 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  ** the beginning
1f210 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63   of memory alloc
1f220 61 74 69 6f 6e 2c 20 6f 72 20 69 66 20 69 74 20  ation, or if it 
1f230 70 6f 69 6e 74 73 20 74 6f 20 61 20 66 6f 72 6d  points to a form
1f240 65 72 6c 79 0a 2a 2a 20 76 61 6c 69 64 20 6d 65  erly.** valid me
1f250 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1f260 74 68 61 74 20 68 61 73 20 6e 6f 77 20 62 65 65  that has now bee
1f270 6e 20 66 72 65 65 64 2c 20 74 68 65 6e 20 74 68  n freed, then th
1f280 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66  e behavior.** of
1f290 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58   sqlite3_msize(X
1f2a0 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61  ) is undefined a
1f2b0 6e 64 20 70 6f 73 73 69 62 6c 79 20 68 61 72 6d  nd possibly harm
1f2c0 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ful..**.** ^The 
1f2d0 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20  memory returned 
1f2e0 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  by sqlite3_mallo
1f2f0 63 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 61  c(), sqlite3_rea
1f300 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74  lloc(),.** sqlit
1f310 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 61  e3_malloc64(), a
1f320 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  nd sqlite3_reall
1f330 6f 63 36 34 28 29 0a 2a 2a 20 69 73 20 61 6c 77  oc64().** is alw
1f340 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  ays aligned to a
1f350 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74  t least an 8 byt
1f360 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74  e boundary, or t
1f370 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f  o a.** 4 byte bo
1f380 75 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b 53  undary if the [S
1f390 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49  QLITE_4_BYTE_ALI
1f3a0 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d  GNED_MALLOC] com
1f3b0 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74  pile-time.** opt
1f3c0 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  ion is used..**.
1f3d0 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72  ** In SQLite ver
1f3e0 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33  sion 3.5.0 and 3
1f3f0 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73  .5.1, it was pos
1f400 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a  sible to define.
1f410 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d  ** the SQLITE_OM
1f420 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41  IT_MEMORY_ALLOCA
1f430 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64  TION which would
1f440 20 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 74   cause the built
1f450 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  -in.** implement
1f460 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72  ation of these r
1f470 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d  outines to be om
1f480 69 74 74 65 64 2e 20 20 54 68 61 74 20 63 61 70  itted.  That cap
1f490 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f  ability.** is no
1f4a0 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64   longer provided
1f4b0 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e  .  Only built-in
1f4c0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
1f4d0 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a  rs can be used..
1f4e0 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53  **.** Prior to S
1f4f0 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
1f500 37 2e 31 30 2c 20 74 68 65 20 57 69 6e 64 6f 77  7.10, the Window
1f510 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c  s OS interface l
1f520 61 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74  ayer called.** t
1f530 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63  he system malloc
1f540 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 64 69  () and free() di
1f550 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76  rectly when conv
1f560 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61  erting.** filena
1f570 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68 65 20  mes between the 
1f580 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75  UTF-8 encoding u
1f590 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a  sed by SQLite.**
1f5a0 20 61 6e 64 20 77 68 61 74 65 76 65 72 20 66 69   and whatever fi
1f5b0 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20  lename encoding 
1f5c0 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20 70  is used by the p
1f5d0 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77  articular Window
1f5e0 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f  s.** installatio
1f5f0 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63  n.  Memory alloc
1f600 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 77 65 72  ation errors wer
1f610 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a  e detected, but.
1f620 2a 2a 20 74 68 65 79 20 77 65 72 65 20 72 65 70  ** they were rep
1f630 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53  orted back as [S
1f640 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20  QLITE_CANTOPEN] 
1f650 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f  or.** [SQLITE_IO
1f660 45 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e  ERR] rather than
1f670 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e   [SQLITE_NOMEM].
1f680 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74  .**.** The point
1f690 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  er arguments to 
1f6a0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1f6b0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
1f6c0 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74  alloc()].** must
1f6d0 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20   be either NULL 
1f6e0 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73  or else pointers
1f6f0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61   obtained from a
1f700 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61   prior.** invoca
1f710 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
1f720 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73  _malloc()] or [s
1f730 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1f740 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e  ] that have.** n
1f750 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65  ot yet been rele
1f760 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ased..**.** The 
1f770 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
1f780 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69   not read or wri
1f790 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a  te any part of.*
1f7a0 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d  * a block of mem
1f7b0 6f 72 79 20 61 66 74 65 72 20 69 74 20 68 61 73  ory after it has
1f7c0 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75   been released u
1f7d0 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
1f7e0 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c  _free()] or [sql
1f7f0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e  ite3_realloc()].
1f800 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
1f810 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76  3_malloc(int);.v
1f820 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c  oid *sqlite3_mal
1f830 6c 6f 63 36 34 28 73 71 6c 69 74 65 33 5f 75 69  loc64(sqlite3_ui
1f840 6e 74 36 34 29 3b 0a 76 6f 69 64 20 2a 73 71 6c  nt64);.void *sql
1f850 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69  ite3_realloc(voi
1f860 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 2a  d*, int);.void *
1f870 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36  sqlite3_realloc6
1f880 34 28 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33  4(void*, sqlite3
1f890 5f 75 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73  _uint64);.void s
1f8a0 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64  qlite3_free(void
1f8b0 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 75 69 6e 74  *);.sqlite3_uint
1f8c0 36 34 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65  64 sqlite3_msize
1f8d0 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  (void*);../*.** 
1f8e0 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
1f8f0 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69   Allocator Stati
1f900 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  stics.**.** SQLi
1f910 74 65 20 70 72 6f 76 69 64 65 73 20 74 68 65 73  te provides thes
1f920 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73  e two interfaces
1f930 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f   for reporting o
1f940 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20  n the status.** 
1f950 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
1f960 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69  malloc()], [sqli
1f970 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64  te3_free()], and
1f980 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
1f990 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  c()].** routines
1f9a0 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65  , which form the
1f9b0 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79   built-in memory
1f9c0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73   allocation subs
1f9d0 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ystem..**.** ^Th
1f9e0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  e [sqlite3_memor
1f9f0 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e  y_used()] routin
1fa00 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
1fa10 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a  mber of bytes.**
1fa20 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65   of memory curre
1fa30 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67  ntly outstanding
1fa40 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e   (malloced but n
1fa50 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54  ot freed)..** ^T
1fa60 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  he [sqlite3_memo
1fa70 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
1fa80 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
1fa90 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76  the maximum.** v
1faa0 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33  alue of [sqlite3
1fab0 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
1fac0 73 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77  since the high-w
1fad0 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73  ater mark.** was
1fae0 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e 54   last reset.  ^T
1faf0 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
1fb00 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d  ed by [sqlite3_m
1fb10 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e  emory_used()] an
1fb20 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65  d.** [sqlite3_me
1fb30 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
1fb40 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76  ] include any ov
1fb50 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 20  erhead.** added 
1fb60 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73  by SQLite in its
1fb70 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
1fb80 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  of [sqlite3_mall
1fb90 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f  oc()],.** but no
1fba0 74 20 6f 76 65 72 68 65 61 64 20 61 64 64 65 64  t overhead added
1fbb0 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65   by the any unde
1fbc0 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69  rlying system li
1fbd0 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65  brary.** routine
1fbe0 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  s that [sqlite3_
1fbf0 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61  malloc()] may ca
1fc00 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d  ll..**.** ^The m
1fc10 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72  emory high-water
1fc20 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20 74   mark is reset t
1fc30 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61  o the current va
1fc40 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74  lue of.** [sqlit
1fc50 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
1fc60 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  ] if and only if
1fc70 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 74   the parameter t
1fc80 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65  o.** [sqlite3_me
1fc90 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
1fca0 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68 65  ] is true.  ^The
1fcb0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a   value returned.
1fcc0 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d  ** by [sqlite3_m
1fcd0 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
1fce0 31 29 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d  1)] is the high-
1fcf0 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72  water mark.** pr
1fd00 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65 74  ior to the reset
1fd10 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74  ..*/.sqlite3_int
1fd20 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  64 sqlite3_memor
1fd30 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71  y_used(void);.sq
1fd40 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
1fd50 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
1fd60 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c  ater(int resetFl
1fd70 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ag);../*.** CAPI
1fd80 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e  3REF: Pseudo-Ran
1fd90 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72  dom Number Gener
1fda0 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ator.**.** SQLit
1fdb0 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67  e contains a hig
1fdc0 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f  h-quality pseudo
1fdd0 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67  -random number g
1fde0 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20  enerator (PRNG) 
1fdf0 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63  used to.** selec
1fe00 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20  t random [ROWID 
1fe10 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69  | ROWIDs] when i
1fe20 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63  nserting new rec
1fe30 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c  ords into a tabl
1fe40 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64  e that.** alread
1fe50 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 67 65  y uses the large
1fe60 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57  st possible [ROW
1fe70 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69  ID].  The PRNG i
1fe80 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a  s also used for.
1fe90 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20  ** the build-in 
1fea0 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e  random() and ran
1feb0 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75  domblob() SQL fu
1fec0 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69  nctions.  This i
1fed0 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a  nterface allows.
1fee0 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** applications 
1fef0 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 73 61  to access the sa
1ff00 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65  me PRNG for othe
1ff10 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a  r purposes..**.*
1ff20 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69  * ^A call to thi
1ff30 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73  s routine stores
1ff40 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64   N bytes of rand
1ff50 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66  omness into buff
1ff60 65 72 20 50 2e 0a 2a 2a 20 5e 54 68 65 20 50 20  er P..** ^The P 
1ff70 70 61 72 61 6d 65 74 65 72 20 63 61 6e 20 62 65  parameter can be
1ff80 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
1ff90 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 69 73 20  .**.** ^If this 
1ffa0 72 6f 75 74 69 6e 65 20 68 61 73 20 6e 6f 74 20  routine has not 
1ffb0 62 65 65 6e 20 70 72 65 76 69 6f 75 73 6c 79 20  been previously 
1ffc0 63 61 6c 6c 65 64 20 6f 72 20 69 66 20 74 68 65  called or if the
1ffd0 20 70 72 65 76 69 6f 75 73 0a 2a 2a 20 63 61 6c   previous.** cal
1ffe0 6c 20 68 61 64 20 4e 20 6c 65 73 73 20 74 68 61  l had N less tha
1fff0 6e 20 6f 6e 65 20 6f 72 20 61 20 4e 55 4c 4c 20  n one or a NULL 
20000 70 6f 69 6e 74 65 72 20 66 6f 72 20 50 2c 20 74  pointer for P, t
20010 68 65 6e 20 74 68 65 20 50 52 4e 47 20 69 73 0a  hen the PRNG is.
20020 2a 2a 20 73 65 65 64 65 64 20 75 73 69 6e 67 20  ** seeded using 
20030 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69  randomness obtai
20040 6e 65 64 20 66 72 6f 6d 20 74 68 65 20 78 52 61  ned from the xRa
20050 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20  ndomness method 
20060 6f 66 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c  of.** the defaul
20070 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
20080 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 49 66 20 74  object..** ^If t
20090 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  he previous call
200a0 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   to this routine
200b0 20 68 61 64 20 61 6e 20 4e 20 6f 66 20 31 20 6f   had an N of 1 o
200c0 72 20 6d 6f 72 65 20 61 6e 64 20 61 0a 2a 2a 20  r more and a.** 
200d0 6e 6f 6e 2d 4e 55 4c 4c 20 50 20 74 68 65 6e 20  non-NULL P then 
200e0 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f  the pseudo-rando
200f0 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61 74  mness is generat
20100 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79  ed.** internally
20110 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63   and without rec
20120 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71  ourse to the [sq
20130 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64  lite3_vfs] xRand
20140 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64  omness.** method
20150 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
20160 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74  3_randomness(int
20170 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f   N, void *P);../
20180 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
20190 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68  ompile-Time Auth
201a0 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61  orization Callba
201b0 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  cks.** METHOD: s
201c0 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
201d0 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73  is routine regis
201e0 74 65 72 73 20 61 6e 20 61 75 74 68 6f 72 69 7a  ters an authoriz
201f0 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68  er callback with
20200 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a   a particular.**
20210 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
20220 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64  ction], supplied
20230 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
20240 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20  gument..** ^The 
20250 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
20260 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61  ack is invoked a
20270 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  s SQL statements
20280 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69   are being compi
20290 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74  led.** by [sqlit
202a0 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
202b0 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73   its variants [s
202c0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
202d0 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  2()],.** [sqlite
202e0 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 61  3_prepare16()] a
202f0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
20300 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41  are16_v2()].  ^A
20310 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69  t various.** poi
20320 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 20 63  nts during the c
20330 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65  ompilation proce
20340 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20  ss, as logic is 
20350 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a  being created.**
20360 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69   to perform vari
20370 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65  ous actions, the
20380 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
20390 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
203a0 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f  to.** see if tho
203b0 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61  se actions are a
203c0 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75  llowed.  ^The au
203d0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
203e0 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75  k should.** retu
203f0 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74  rn [SQLITE_OK] t
20400 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69  o allow the acti
20410 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  on, [SQLITE_IGNO
20420 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20  RE] to disallow 
20430 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20  the.** specific 
20440 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77  action but allow
20450 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
20460 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74  nt to continue t
20470 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  o be.** compiled
20480 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e  , or [SQLITE_DEN
20490 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 20  Y] to cause the 
204a0 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 65  entire SQL state
204b0 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65  ment to be.** re
204c0 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 65  jected with an e
204d0 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61  rror.  ^If the a
204e0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
204f0 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e  ck returns.** an
20500 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68  y value other th
20510 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  an [SQLITE_IGNOR
20520 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  E], [SQLITE_OK],
20530 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59   or [SQLITE_DENY
20540 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73  ].** then the [s
20550 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
20560 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65  2()] or equivale
20570 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69  nt call that tri
20580 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75  ggered.** the au
20590 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61  thorizer will fa
205a0 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  il with an error
205b0 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20   message..**.** 
205c0 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  When the callbac
205d0 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
205e0 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e  E_OK], that mean
205f0 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a  s the operation.
20600 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69 73 20  ** requested is 
20610 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63  ok.  ^When the c
20620 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
20630 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74  [SQLITE_DENY], t
20640 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  he.** [sqlite3_p
20650 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
20660 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20  equivalent call 
20670 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74  that triggered t
20680 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72  he.** authorizer
20690 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20   will fail with 
206a0 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
206b0 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74   explaining that
206c0 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64 65  .** access is de
206d0 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  nied. .**.** ^Th
206e0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
206f0 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  r to the authori
20700 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
20710 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68  a copy of the th
20720 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ird.** parameter
20730 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
20740 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
20750 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65   interface. ^The
20760 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
20770 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c  r.** to the call
20780 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67  back is an integ
20790 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20  er [SQLITE_COPY 
207a0 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74  | action code] t
207b0 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  hat specifies.**
207c0 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
207d0 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74  action to be aut
207e0 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68  horized. ^The th
207f0 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74  ird through sixt
20800 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  h parameters.** 
20810 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
20820 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  are zero-termina
20830 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74  ted strings that
20840 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f   contain additio
20850 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61  nal.** details a
20860 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20  bout the action 
20870 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
20880 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
20890 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b  action code is [
208a0 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20  SQLITE_READ].** 
208b0 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  and the callback
208c0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
208d0 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68  _IGNORE] then th
208e0 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
208f0 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d  tatement] statem
20900 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74  ent is construct
20910 65 64 20 74 6f 20 73 75 62 73 74 69 74 75 74 65  ed to substitute
20920 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65  .** a NULL value
20930 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65   in place of the
20940 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68   table column th
20950 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a  at would have.**
20960 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53   been read if [S
20970 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65  QLITE_OK] had be
20980 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  en returned.  Th
20990 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  e [SQLITE_IGNORE
209a0 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20  ].** return can 
209b0 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20  be used to deny 
209c0 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73 65  an untrusted use
209d0 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69  r access to indi
209e0 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e  vidual.** column
209f0 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a  s of a table..**
20a00 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20   ^If the action 
20a10 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  code is [SQLITE_
20a20 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20  DELETE] and the 
20a30 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
20a40 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  .** [SQLITE_IGNO
20a50 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45  RE] then the [DE
20a60 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20  LETE] operation 
20a70 70 72 6f 63 65 65 64 73 20 62 75 74 20 74 68 65  proceeds but the
20a80 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70  .** [truncate op
20a90 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64  timization] is d
20aa0 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20  isabled and all 
20ab0 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64  rows are deleted
20ac0 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a   individually..*
20ad0 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a  *.** An authoriz
20ae0 65 72 20 69 73 20 75 73 65 64 20 77 68 65 6e 20  er is used when 
20af0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
20b00 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a   | preparing].**
20b10 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
20b20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65  from an untruste
20b30 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73  d source, to ens
20b40 75 72 65 20 74 68 61 74 20 74 68 65 20 53 51 4c  ure that the SQL
20b50 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64   statements.** d
20b60 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63  o not try to acc
20b70 65 73 73 20 64 61 74 61 20 74 68 65 79 20 61 72  ess data they ar
20b80 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f  e not allowed to
20b90 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68   see, or that th
20ba0 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79  ey do not.** try
20bb0 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69   to execute mali
20bc0 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73  cious statements
20bd0 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 68 65   that damage the
20be0 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a   database.  For.
20bf0 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61  ** example, an a
20c00 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61  pplication may a
20c10 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65  llow a user to e
20c20 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a  nter arbitrary.*
20c30 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f  * SQL queries fo
20c40 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20  r evaluation by 
20c50 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 75 74  a database.  But
20c60 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
20c70 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e   does.** not wan
20c80 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 62 65  t the user to be
20c90 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72   able to make ar
20ca0 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 73 20  bitrary changes 
20cb0 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  to the.** databa
20cc0 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a  se.  An authoriz
20cd0 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65  er could then be
20ce0 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68   put in place wh
20cf0 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d  ile the.** user-
20d00 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20 62  entered SQL is b
20d10 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  eing [sqlite3_pr
20d20 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 65 64  epare | prepared
20d30 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c  ] that.** disall
20d40 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67 20 65  ows everything e
20d50 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73  xcept [SELECT] s
20d60 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
20d70 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
20d80 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65  at need to proce
20d90 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72  ss SQL from untr
20da0 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a  usted sources.**
20db0 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73   might also cons
20dc0 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65  ider lowering re
20dd0 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73  source limits us
20de0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  ing [sqlite3_lim
20df0 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d  it()].** and lim
20e00 69 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 73  iting database s
20e10 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d  ize using the [m
20e20 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b  ax_page_count] [
20e30 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64  PRAGMA].** in ad
20e40 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20  dition to using 
20e50 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a  an authorizer..*
20e60 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69  *.** ^(Only a si
20e70 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20  ngle authorizer 
20e80 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20  can be in place 
20e90 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  on a database co
20ea0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61  nnection.** at a
20eb0 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c   time.  Each cal
20ec0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74  l to sqlite3_set
20ed0 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72  _authorizer over
20ee0 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65  rides the.** pre
20ef0 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e  vious call.)^  ^
20f00 44 69 73 61 62 6c 65 20 74 68 65 20 61 75 74 68  Disable the auth
20f10 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c  orizer by instal
20f20 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c  ling a NULL call
20f30 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74  back..** The aut
20f40 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61 62  horizer is disab
20f50 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a  led by default..
20f60 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72  **.** The author
20f70 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75  izer callback mu
20f80 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69  st not do anythi
20f90 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64  ng that will mod
20fa0 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ify.** the datab
20fb0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
20fc0 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
20fd0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
20fe0 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ack..** Note tha
20ff0 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  t [sqlite3_prepa
21000 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
21010 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f  lite3_step()] bo
21020 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a  th modify their.
21030 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
21040 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20  ections for the 
21050 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69  meaning of "modi
21060 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61  fy" in this para
21070 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68  graph..**.** ^Wh
21080 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  en [sqlite3_prep
21090 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65  are_v2()] is use
210a0 64 20 74 6f 20 70 72 65 70 61 72 65 20 61 20 73  d to prepare a s
210b0 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a  tatement, the.**
210c0 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74   statement might
210d0 20 62 65 20 72 65 2d 70 72 65 70 61 72 65 64 20   be re-prepared 
210e0 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  during [sqlite3_
210f0 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61  step()] due to a
21100 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e   .** schema chan
21110 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20  ge.  Hence, the 
21120 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
21130 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  ld ensure that t
21140 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75  he.** correct au
21150 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
21160 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61  k remains in pla
21170 63 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73  ce during the [s
21180 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a  qlite3_step()]..
21190 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74  **.** ^Note that
211a0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
211b0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
211c0 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a  ked only during.
211d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
211e0 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61  are()] or its va
211f0 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69  riants.  Authori
21200 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a  zation is not.**
21210 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e   performed durin
21220 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c  g statement eval
21230 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74  uation in [sqlit
21240 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65  e3_step()], unle
21250 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20  ss.** as stated 
21260 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  in the previous 
21270 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74  paragraph, sqlit
21280 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65  e3_step() invoke
21290 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65  s.** sqlite3_pre
212a0 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70  pare_v2() to rep
212b0 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65  repare a stateme
212c0 6e 74 20 61 66 74 65 72 20 61 20 73 63 68 65 6d  nt after a schem
212d0 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74  a change..*/.int
212e0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
212f0 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74  horizer(.  sqlit
21300 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75  e3*,.  int (*xAu
21310 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  th)(void*,int,co
21320 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
21330 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
21340 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a  *,const char*),.
21350 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74    void *pUserDat
21360 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  a.);../*.** CAPI
21370 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72  3REF: Authorizer
21380 20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a   Return Codes.**
21390 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
213a0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
213b0 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  | authorizer cal
213c0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20  lback function] 
213d0 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65  must.** return e
213e0 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b  ither [SQLITE_OK
213f0 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73  ] or one of thes
21400 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20  e two constants 
21410 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73  in order.** to s
21420 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65  ignal SQLite whe
21430 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
21440 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74  action is permit
21450 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a  ted.  See the.**
21460 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
21470 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f  thorizer | autho
21480 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74  rizer documentat
21490 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f  ion] for additio
214a0 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  nal.** informati
214b0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  on..**.** Note t
214c0 68 61 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52  hat SQLITE_IGNOR
214d0 45 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 61  E is also used a
214e0 73 20 61 20 5b 63 6f 6e 66 6c 69 63 74 20 72 65  s a [conflict re
214f0 73 6f 6c 75 74 69 6f 6e 20 6d 6f 64 65 5d 0a 2a  solution mode].*
21500 2a 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20  * returned from 
21510 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 74 61  the [sqlite3_vta
21520 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d  b_on_conflict()]
21530 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23   interface..*/.#
21540 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
21550 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72  NY   1   /* Abor
21560 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
21570 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ent with an erro
21580 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
21590 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f  ITE_IGNORE 2   /
215a0 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63  * Don't allow ac
215b0 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20  cess, but don't 
215c0 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f  generate an erro
215d0 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  r */../*.** CAPI
215e0 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72  3REF: Authorizer
215f0 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a   Action Codes.**
21600 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
21610 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
21620 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  )] interface reg
21630 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63  isters a callbac
21640 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68  k function.** th
21650 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f  at is invoked to
21660 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61   authorize certa
21670 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  in SQL statement
21680 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a   actions.  The.*
21690 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
216a0 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  er to the callba
216b0 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ck is an integer
216c0 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 63 69   code that speci
216d0 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74  fies.** what act
216e0 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74  ion is being aut
216f0 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20  horized.  These 
21700 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 72 20  are the integer 
21710 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61  action codes tha
21720 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69  t.** the authori
21730 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79  zer callback may
21740 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a   be passed..**.*
21750 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63  * These action c
21760 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69  ode values signi
21770 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20  fy what kind of 
21780 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20  operation is to 
21790 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64  be.** authorized
217a0 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20 34  .  The 3rd and 4
217b0 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  th parameters to
217c0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69   the authorizati
217d0 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66  on.** callback f
217e0 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20  unction will be 
217f0 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55  parameters or NU
21800 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  LL depending on 
21810 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a  which of these.*
21820 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64 20  * codes is used 
21830 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
21840 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20  rameter.  ^(The 
21850 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
21860 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a   the.** authoriz
21870 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74  er callback is t
21880 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
21890 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c  atabase ("main",
218a0 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e   "temp",.** etc.
218b0 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e  ) if applicable.
218c0 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61 72  )^  ^The 6th par
218d0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
218e0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
218f0 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65  k.** is the name
21900 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f   of the inner-mo
21910 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  st trigger or vi
21920 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f  ew that is respo
21930 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68  nsible for.** th
21940 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  e access attempt
21950 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73   or NULL if this
21960 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20   access attempt 
21970 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d  is directly from
21980 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51  .** top-level SQ
21990 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a  L code..*/./****
219a0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
219b0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
219c0 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a  ******* 3rd ****
219d0 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a  ******** 4th ***
219e0 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e  ********/.#defin
219f0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
21a00 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 31  INDEX          1
21a10 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
21a20 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
21a30 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
21a40 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
21a50 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 20  ABLE          2 
21a60 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
21a70 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
21a80 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
21a90 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
21aa0 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20  MP_INDEX     3  
21ab0 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
21ac0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
21ad0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
21ae0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
21af0 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20 20  P_TABLE     4   
21b00 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
21b10 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
21b20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
21b30 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
21b40 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 20 2f  _TRIGGER   5   /
21b50 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
21b60 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
21b70 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
21b80 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
21b90 56 49 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a  VIEW      6   /*
21ba0 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
21bb0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
21bc0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
21bd0 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45  TE_CREATE_TRIGGE
21be0 52 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20  R        7   /* 
21bf0 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
21c00 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
21c10 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
21c20 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20 20  E_CREATE_VIEW   
21c30 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56          8   /* V
21c40 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
21c50 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
21c60 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
21c70 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
21c80 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61         9   /* Ta
21c90 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
21ca0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
21cb0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
21cc0 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20  DROP_INDEX      
21cd0 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64       10   /* Ind
21ce0 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
21cf0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
21d00 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
21d10 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20  ROP_TABLE       
21d20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c      11   /* Tabl
21d30 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
21d40 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
21d50 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
21d60 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20  OP_TEMP_INDEX   
21d70 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78     12   /* Index
21d80 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
21d90 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
21da0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
21db0 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20  P_TEMP_TABLE    
21dc0 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20    13   /* Table 
21dd0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
21de0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
21df0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
21e00 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20  _TEMP_TRIGGER   
21e10 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72   14   /* Trigger
21e20 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
21e30 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
21e40 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
21e50 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20  TEMP_VIEW       
21e60 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d  15   /* View Nam
21e70 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
21e80 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
21e90 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
21ea0 52 49 47 47 45 52 20 20 20 20 20 20 20 20 20 31  RIGGER         1
21eb0 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  6   /* Trigger N
21ec0 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
21ed0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
21ee0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49  e SQLITE_DROP_VI
21ef0 45 57 20 20 20 20 20 20 20 20 20 20 20 20 31 37  EW            17
21f00 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
21f10 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
21f20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
21f30 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20   SQLITE_INSERT  
21f40 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38 20               18 
21f50 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
21f60 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
21f70 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
21f80 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20  SQLITE_PRAGMA   
21f90 20 20 20 20 20 20 20 20 20 20 20 20 31 39 20 20              19  
21fa0 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20   /* Pragma Name 
21fb0 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e      1st arg or N
21fc0 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ULL */.#define S
21fd0 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20 20  QLITE_READ      
21fe0 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20 20             20   
21ff0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
22000 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20     Column Name  
22010 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
22020 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20  LITE_SELECT     
22030 20 20 20 20 20 20 20 20 20 20 32 31 20 20 20 2f            21   /
22040 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20  * NULL          
22050 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
22060 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22070 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20  ITE_TRANSACTION 
22080 20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a           22   /*
22090 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20   Operation      
220a0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
220b0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
220c0 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 20 20  TE_UPDATE       
220d0 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20          23   /* 
220e0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
220f0 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20  Column Name     
22100 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22110 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 20 20  E_ATTACH        
22120 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46         24   /* F
22130 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e  ilename        N
22140 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
22150 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22160 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 20 20  _DETACH         
22170 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61        25   /* Da
22180 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55  tabase Name   NU
22190 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
221a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
221b0 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20  ALTER_TABLE     
221c0 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74       26   /* Dat
221d0 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62  abase Name   Tab
221e0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
221f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
22200 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  EINDEX          
22210 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65      27   /* Inde
22220 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  x Name      NULL
22230 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
22240 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e  define SQLITE_AN
22250 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20 20  ALYZE           
22260 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65     28   /* Table
22270 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
22280 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
22290 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
222a0 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20  ATE_VTABLE      
222b0 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20    29   /* Table 
222c0 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65  Name      Module
222d0 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
222e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
222f0 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  _VTABLE         
22300 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   30   /* Table N
22310 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20  ame      Module 
22320 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
22330 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54  ine SQLITE_FUNCT
22340 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20 20  ION             
22350 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  31   /* NULL    
22360 20 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e          Function
22370 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69   Name   */.#defi
22380 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f  ne SQLITE_SAVEPO
22390 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 33  INT            3
223a0 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e  2   /* Operation
223b0 20 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74         Savepoint
223c0 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e   Name  */.#defin
223d0 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20  e SQLITE_COPY   
223e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
223f0 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20     /* No longer 
22400 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  used */.#define 
22410 53 51 4c 49 54 45 5f 52 45 43 55 52 53 49 56 45  SQLITE_RECURSIVE
22420 20 20 20 20 20 20 20 20 20 20 20 20 33 33 20 20              33  
22430 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20   /* NULL        
22440 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
22450 20 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41      */../*.** CA
22460 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20  PI3REF: Tracing 
22470 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75  And Profiling Fu
22480 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f  nctions.** METHO
22490 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
224a0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
224b0 61 72 65 20 64 65 70 72 65 63 61 74 65 64 2e 20  are deprecated. 
224c0 55 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  Use the [sqlite3
224d0 5f 74 72 61 63 65 5f 76 32 28 29 5d 20 69 6e 74  _trace_v2()] int
224e0 65 72 66 61 63 65 0a 2a 2a 20 69 6e 73 74 65 61  erface.** instea
224f0 64 20 6f 66 20 74 68 65 20 72 6f 75 74 69 6e 65  d of the routine
22500 73 20 64 65 73 63 72 69 62 65 64 20 68 65 72 65  s described here
22510 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
22520 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 72 20  utines register 
22530 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
22540 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 75  ns that can be u
22550 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69  sed for.** traci
22560 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67  ng and profiling
22570 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f   the execution o
22580 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  f SQL statements
22590 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c  ..**.** ^The cal
225a0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72  lback function r
225b0 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c  egistered by sql
225c0 69 74 65 33 5f 74 72 61 63 65 28 29 20 69 73 20  ite3_trace() is 
225d0 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61  invoked at.** va
225e0 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e  rious times when
225f0 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
22600 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62  t is being run b
22610 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  y [sqlite3_step(
22620 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  )]..** ^The sqli
22630 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c  te3_trace() call
22640 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
22650 77 69 74 68 20 61 20 55 54 46 2d 38 20 72 65 6e  with a UTF-8 ren
22660 64 65 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a  dering of the.**
22670 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
22680 65 78 74 20 61 73 20 74 68 65 20 73 74 61 74 65  ext as the state
22690 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e  ment first begin
226a0 73 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20  s executing..** 
226b0 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c  ^(Additional sql
226c0 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c  ite3_trace() cal
226d0 6c 62 61 63 6b 73 20 6d 69 67 68 74 20 6f 63 63  lbacks might occ
226e0 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72  ur.** as each tr
226f0 69 67 67 65 72 65 64 20 73 75 62 70 72 6f 67 72  iggered subprogr
22700 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20  am is entered.  
22710 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f  The callbacks fo
22720 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f  r triggers.** co
22730 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51  ntain a UTF-8 SQ
22740 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69  L comment that i
22750 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 74 72  dentifies the tr
22760 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54  igger.)^.**.** T
22770 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45  he [SQLITE_TRACE
22780 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d  _SIZE_LIMIT] com
22790 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
227a0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
227b0 6c 69 6d 69 74 0a 2a 2a 20 74 68 65 20 6c 65 6e  limit.** the len
227c0 67 74 68 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61  gth of [bound pa
227d0 72 61 6d 65 74 65 72 5d 20 65 78 70 61 6e 73 69  rameter] expansi
227e0 6f 6e 20 69 6e 20 74 68 65 20 6f 75 74 70 75 74  on in the output
227f0 20 6f 66 20 73 71 6c 69 74 65 33 5f 74 72 61 63   of sqlite3_trac
22800 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e()..**.** ^The 
22810 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
22820 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20  n registered by 
22830 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
22840 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ) is invoked.** 
22850 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 74  as each SQL stat
22860 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20  ement finishes. 
22870 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61   ^The profile ca
22880 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a  llback contains.
22890 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  ** the original 
228a0 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61  statement text a
228b0 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f  nd an estimate o
228c0 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d  f wall-clock tim
228d0 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67  e.** of how long
228e0 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20   that statement 
228f0 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54  took to run.  ^T
22900 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62  he profile callb
22910 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69  ack.** time is i
22920 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73  n units of nanos
22930 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72 20  econds, however 
22940 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c  the current impl
22950 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73  ementation.** is
22960 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f 66   only capable of
22970 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73   millisecond res
22980 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65 20 73  olution so the s
22990 69 78 20 6c 65 61 73 74 20 73 69 67 6e 69 66 69  ix least signifi
229a0 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20 69  cant.** digits i
229b0 6e 20 74 68 65 20 74 69 6d 65 20 61 72 65 20 6d  n the time are m
229c0 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75 74  eaningless.  Fut
229d0 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
229e0 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20  SQLite.** might 
229f0 70 72 6f 76 69 64 65 20 67 72 65 61 74 65 72 20  provide greater 
22a00 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68  resolution on th
22a10 65 20 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62  e profiler callb
22a20 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c  ack.  The.** sql
22a30 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 66  ite3_profile() f
22a40 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69  unction is consi
22a50 64 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e 74  dered experiment
22a60 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62  al and is.** sub
22a70 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69  ject to change i
22a80 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e  n future version
22a90 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  s of SQLite..*/.
22aa0 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
22ab0 44 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  D void *sqlite3_
22ac0 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 0a  trace(sqlite3*,.
22ad0 20 20 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29     void(*xTrace)
22ae0 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61  (void*,const cha
22af0 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c  r*), void*);.SQL
22b00 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 76  ITE_DEPRECATED v
22b10 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f  oid *sqlite3_pro
22b20 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20  file(sqlite3*,. 
22b30 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65    void(*xProfile
22b40 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68  )(void*,const ch
22b50 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74  ar*,sqlite3_uint
22b60 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  64), void*);../*
22b70 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51  .** CAPI3REF: SQ
22b80 4c 20 54 72 61 63 65 20 45 76 65 6e 74 20 43 6f  L Trace Event Co
22b90 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  des.** KEYWORDS:
22ba0 20 53 51 4c 49 54 45 5f 54 52 41 43 45 0a 2a 2a   SQLITE_TRACE.**
22bb0 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
22bc0 6e 74 73 20 69 64 65 6e 74 69 66 79 20 63 6c 61  nts identify cla
22bd0 73 73 65 73 20 6f 66 20 65 76 65 6e 74 73 20 74  sses of events t
22be0 68 61 74 20 63 61 6e 20 62 65 20 6d 6f 6e 69 74  hat can be monit
22bf0 6f 72 65 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68  ored.** using th
22c00 65 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65  e [sqlite3_trace
22c10 5f 76 32 28 29 5d 20 74 72 61 63 69 6e 67 20 6c  _v2()] tracing l
22c20 6f 67 69 63 2e 20 20 54 68 65 20 74 68 69 72 64  ogic.  The third
22c30 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20   argument.** to 
22c40 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76  [sqlite3_trace_v
22c50 32 28 29 5d 20 69 73 20 61 6e 20 4f 52 2d 65 64  2()] is an OR-ed
22c60 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 20   combination of 
22c70 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 0a 2a  one or more of.*
22c80 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  * the following 
22c90 63 6f 6e 73 74 61 6e 74 73 2e 20 20 5e 54 68 65  constants.  ^The
22ca0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
22cb0 74 6f 20 74 68 65 20 74 72 61 63 65 20 63 61 6c  to the trace cal
22cc0 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6f 6e 65 20  lback.** is one 
22cd0 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
22ce0 20 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a   constants..**.*
22cf0 2a 20 4e 65 77 20 74 72 61 63 69 6e 67 20 63 6f  * New tracing co
22d00 6e 73 74 61 6e 74 73 20 6d 61 79 20 62 65 20 61  nstants may be a
22d10 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
22d20 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  eleases..**.** ^
22d30 41 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b  A trace callback
22d40 20 68 61 73 20 66 6f 75 72 20 61 72 67 75 6d 65   has four argume
22d50 6e 74 73 3a 20 78 43 61 6c 6c 62 61 63 6b 28 54  nts: xCallback(T
22d60 2c 43 2c 50 2c 58 29 2e 0a 2a 2a 20 5e 54 68 65  ,C,P,X)..** ^The
22d70 20 54 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f   T argument is o
22d80 6e 65 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65  ne of the intege
22d90 72 20 74 79 70 65 20 63 6f 64 65 73 20 61 62 6f  r type codes abo
22da0 76 65 2e 0a 2a 2a 20 5e 54 68 65 20 43 20 61 72  ve..** ^The C ar
22db0 67 75 6d 65 6e 74 20 69 73 20 61 20 63 6f 70 79  gument is a copy
22dc0 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 78 74 20   of the context 
22dd0 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20 69  pointer passed i
22de0 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72  n as the.** four
22df0 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b  th argument to [
22e00 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32  sqlite3_trace_v2
22e10 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 50 20 61 6e  ()]..** The P an
22e20 64 20 58 20 61 72 67 75 6d 65 6e 74 73 20 61 72  d X arguments ar
22e30 65 20 70 6f 69 6e 74 65 72 73 20 77 68 6f 73 65  e pointers whose
22e40 20 6d 65 61 6e 69 6e 67 73 20 64 65 70 65 6e 64   meanings depend
22e50 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c   on T..**.** <dl
22e60 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52  >.** [[SQLITE_TR
22e70 41 43 45 5f 53 54 4d 54 5d 5d 20 3c 64 74 3e 53  ACE_STMT]] <dt>S
22e80 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54  QLITE_TRACE_STMT
22e90 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e  </dt>.** <dd>^An
22ea0 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 54   SQLITE_TRACE_ST
22eb0 4d 54 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  MT callback is i
22ec0 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61 20 70 72  nvoked when a pr
22ed0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
22ee0 0a 2a 2a 20 66 69 72 73 74 20 62 65 67 69 6e 73  .** first begins
22ef0 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 70 6f 73   running and pos
22f00 73 69 62 6c 79 20 61 74 20 6f 74 68 65 72 20 74  sibly at other t
22f10 69 6d 65 73 20 64 75 72 69 6e 67 20 74 68 65 0a  imes during the.
22f20 2a 2a 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20  ** execution of 
22f30 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
22f40 74 65 6d 65 6e 74 2c 20 73 75 63 68 20 61 73 20  tement, such as 
22f50 61 74 20 74 68 65 20 73 74 61 72 74 20 6f 66 20  at the start of 
22f60 65 61 63 68 0a 2a 2a 20 74 72 69 67 67 65 72 20  each.** trigger 
22f70 73 75 62 70 72 6f 67 72 61 6d 2e 20 5e 54 68 65  subprogram. ^The
22f80 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61   P argument is a
22f90 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a   pointer to the.
22fa0 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
22fb0 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 65 20 58 20  tement]. ^The X 
22fc0 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
22fd0 69 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e  inter to a strin
22fe0 67 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68  g which.** is th
22ff0 65 20 75 6e 65 78 70 61 6e 64 65 64 20 53 51 4c  e unexpanded SQL
23000 20 74 65 78 74 20 6f 66 20 74 68 65 20 70 72 65   text of the pre
23010 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
23020 6f 72 20 61 6e 20 53 51 4c 20 63 6f 6d 6d 65 6e  or an SQL commen
23030 74 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69 63  t .** that indic
23040 61 74 65 73 20 74 68 65 20 69 6e 76 6f 63 61 74  ates the invocat
23050 69 6f 6e 20 6f 66 20 61 20 74 72 69 67 67 65 72  ion of a trigger
23060 2e 20 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b  .  ^The callback
23070 20 63 61 6e 20 63 6f 6d 70 75 74 65 0a 2a 2a 20   can compute.** 
23080 74 68 65 20 73 61 6d 65 20 74 65 78 74 20 74 68  the same text th
23090 61 74 20 77 6f 75 6c 64 20 68 61 76 65 20 62 65  at would have be
230a0 65 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  en returned by t
230b0 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74  he legacy [sqlit
230c0 65 33 5f 74 72 61 63 65 28 29 5d 0a 2a 2a 20 69  e3_trace()].** i
230d0 6e 74 65 72 66 61 63 65 20 62 79 20 75 73 69 6e  nterface by usin
230e0 67 20 74 68 65 20 58 20 61 72 67 75 6d 65 6e 74  g the X argument
230f0 20 77 68 65 6e 20 58 20 62 65 67 69 6e 73 20 77   when X begins w
23100 69 74 68 20 22 2d 2d 22 20 61 6e 64 20 69 6e 76  ith "--" and inv
23110 6f 6b 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  oking.** [sqlite
23120 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 50  3_expanded_sql(P
23130 29 5d 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a  )] otherwise..**
23140 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41  .** [[SQLITE_TRA
23150 43 45 5f 50 52 4f 46 49 4c 45 5d 5d 20 3c 64 74  CE_PROFILE]] <dt
23160 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52  >SQLITE_TRACE_PR
23170 4f 46 49 4c 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  OFILE</dt>.** <d
23180 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 41  d>^An SQLITE_TRA
23190 43 45 5f 50 52 4f 46 49 4c 45 20 63 61 6c 6c 62  CE_PROFILE callb
231a0 61 63 6b 20 70 72 6f 76 69 64 65 73 20 61 70 70  ack provides app
231b0 72 6f 78 69 6d 61 74 65 6c 79 20 74 68 65 20 73  roximately the s
231c0 61 6d 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  ame.** informati
231d0 6f 6e 20 61 73 20 69 73 20 70 72 6f 76 69 64 65  on as is provide
231e0 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
231f0 33 5f 70 72 6f 66 69 6c 65 28 29 5d 20 63 61 6c  3_profile()] cal
23200 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 50  lback..** ^The P
23210 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
23220 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 70  ointer to the [p
23230 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
23240 74 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 58 20  t] and the.** X 
23250 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20  argument points 
23260 74 6f 20 61 20 36 34 2d 62 69 74 20 69 6e 74 65  to a 64-bit inte
23270 67 65 72 20 77 68 69 63 68 20 69 73 20 74 68 65  ger which is the
23280 20 65 73 74 69 6d 61 74 65 64 20 6f 66 0a 2a 2a   estimated of.**
23290 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6e   the number of n
232a0 61 6e 6f 73 65 63 6f 6e 64 20 74 68 61 74 20 74  anosecond that t
232b0 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
232c0 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75  ement took to ru
232d0 6e 2e 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49 54  n..** ^The SQLIT
232e0 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 20  E_TRACE_PROFILE 
232f0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
23300 6b 65 64 20 77 68 65 6e 20 74 68 65 20 73 74 61  ked when the sta
23310 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e  tement finishes.
23320 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
23330 54 52 41 43 45 5f 52 4f 57 5d 5d 20 3c 64 74 3e  TRACE_ROW]] <dt>
23340 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57  SQLITE_TRACE_ROW
23350 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e  </dt>.** <dd>^An
23360 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f   SQLITE_TRACE_RO
23370 57 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  W callback is in
23380 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61  voked whenever a
23390 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
233a0 74 65 6d 65 6e 74 20 67 65 6e 65 72 61 74 65 73  tement generates
233b0 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66   a single row of
233c0 20 72 65 73 75 6c 74 2e 20 20 0a 2a 2a 20 5e 54   result.  .** ^T
233d0 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73  he P argument is
233e0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
233f0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
23400 65 6d 65 6e 74 5d 20 61 6e 64 20 74 68 65 0a 2a  ement] and the.*
23410 2a 20 58 20 61 72 67 75 6d 65 6e 74 20 69 73 20  * X argument is 
23420 75 6e 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  unused..**.** [[
23430 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f  SQLITE_TRACE_CLO
23440 53 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  SE]] <dt>SQLITE_
23450 54 52 41 43 45 5f 43 4c 4f 53 45 3c 2f 64 74 3e  TRACE_CLOSE</dt>
23460 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49  .** <dd>^An SQLI
23470 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 20 63  TE_TRACE_CLOSE c
23480 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
23490 65 64 20 77 68 65 6e 20 61 20 64 61 74 61 62 61  ed when a databa
234a0 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
234b0 20 63 6c 6f 73 65 73 2e 0a 2a 2a 20 5e 54 68 65   closes..** ^The
234c0 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61   P argument is a
234d0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
234e0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
234f0 74 69 6f 6e 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20  tion] object.** 
23500 61 6e 64 20 74 68 65 20 58 20 61 72 67 75 6d 65  and the X argume
23510 6e 74 20 69 73 20 75 6e 75 73 65 64 2e 0a 2a 2a  nt is unused..**
23520 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
23530 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53  e SQLITE_TRACE_S
23540 54 4d 54 20 20 20 20 20 20 20 30 78 30 31 0a 23  TMT       0x01.#
23550 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52  define SQLITE_TR
23560 41 43 45 5f 50 52 4f 46 49 4c 45 20 20 20 20 30  ACE_PROFILE    0
23570 78 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  x02.#define SQLI
23580 54 45 5f 54 52 41 43 45 5f 52 4f 57 20 20 20 20  TE_TRACE_ROW    
23590 20 20 20 20 30 78 30 34 0a 23 64 65 66 69 6e 65      0x04.#define
235a0 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c   SQLITE_TRACE_CL
235b0 4f 53 45 20 20 20 20 20 20 30 78 30 38 0a 0a 2f  OSE      0x08../
235c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
235d0 51 4c 20 54 72 61 63 65 20 48 6f 6f 6b 0a 2a 2a  QL Trace Hook.**
235e0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
235f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
23600 74 65 33 5f 74 72 61 63 65 5f 76 32 28 44 2c 4d  te3_trace_v2(D,M
23610 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20  ,X,P) interface 
23620 72 65 67 69 73 74 65 72 73 20 61 20 74 72 61 63  registers a trac
23630 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75  e callback.** fu
23640 6e 63 74 69 6f 6e 20 58 20 61 67 61 69 6e 73 74  nction X against
23650 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
23660 63 74 69 6f 6e 5d 20 44 2c 20 75 73 69 6e 67 20  ction] D, using 
23670 70 72 6f 70 65 72 74 79 20 6d 61 73 6b 20 4d 0a  property mask M.
23680 2a 2a 20 61 6e 64 20 63 6f 6e 74 65 78 74 20 70  ** and context p
23690 6f 69 6e 74 65 72 20 50 2e 20 20 5e 49 66 20 74  ointer P.  ^If t
236a0 68 65 20 58 20 63 61 6c 6c 62 61 63 6b 20 69 73  he X callback is
236b0 0a 2a 2a 20 4e 55 4c 4c 20 6f 72 20 69 66 20 74  .** NULL or if t
236c0 68 65 20 4d 20 6d 61 73 6b 20 69 73 20 7a 65 72  he M mask is zer
236d0 6f 2c 20 74 68 65 6e 20 74 72 61 63 69 6e 67 20  o, then tracing 
236e0 69 73 20 64 69 73 61 62 6c 65 64 2e 20 20 54 68  is disabled.  Th
236f0 65 0a 2a 2a 20 4d 20 61 72 67 75 6d 65 6e 74 20  e.** M argument 
23700 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20 62 69  should be the bi
23710 74 77 69 73 65 20 4f 52 2d 65 64 20 63 6f 6d 62  twise OR-ed comb
23720 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 7a 65  ination of.** ze
23730 72 6f 20 6f 72 20 6d 6f 72 65 20 5b 53 51 4c 49  ro or more [SQLI
23740 54 45 5f 54 52 41 43 45 5d 20 63 6f 6e 73 74 61  TE_TRACE] consta
23750 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68  nts..**.** ^Each
23760 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20   call to either 
23770 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20  sqlite3_trace() 
23780 6f 72 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  or sqlite3_trace
23790 5f 76 32 28 29 20 6f 76 65 72 72 69 64 65 73 20  _v2() overrides 
237a0 0a 2a 2a 20 28 63 61 6e 63 65 6c 73 29 20 61 6e  .** (cancels) an
237b0 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 20 74 6f  y prior calls to
237c0 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
237d0 20 6f 72 20 73 71 6c 69 74 65 33 5f 74 72 61 63   or sqlite3_trac
237e0 65 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  e_v2()..**.** ^T
237f0 68 65 20 58 20 63 61 6c 6c 62 61 63 6b 20 69 73  he X callback is
23800 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
23810 72 20 61 6e 79 20 6f 66 20 74 68 65 20 65 76 65  r any of the eve
23820 6e 74 73 20 69 64 65 6e 74 69 66 69 65 64 20 62  nts identified b
23830 79 20 0a 2a 2a 20 6d 61 73 6b 20 4d 20 6f 63 63  y .** mask M occ
23840 75 72 2e 20 20 5e 54 68 65 20 69 6e 74 65 67 65  ur.  ^The intege
23850 72 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  r return value f
23860 72 6f 6d 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  rom the callback
23870 20 69 73 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a   is currently.**
23880 20 69 67 6e 6f 72 65 64 2c 20 74 68 6f 75 67 68   ignored, though
23890 20 74 68 69 73 20 6d 61 79 20 63 68 61 6e 67 65   this may change
238a0 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
238b0 73 65 73 2e 20 20 43 61 6c 6c 62 61 63 6b 0a 2a  ses.  Callback.*
238c0 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
238d0 73 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20  s should return 
238e0 7a 65 72 6f 20 74 6f 20 65 6e 73 75 72 65 20 66  zero to ensure f
238f0 75 74 75 72 65 20 63 6f 6d 70 61 74 69 62 69 6c  uture compatibil
23900 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 74 72  ity..**.** ^A tr
23910 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ace callback is 
23920 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 66 6f 75  invoked with fou
23930 72 20 61 72 67 75 6d 65 6e 74 73 3a 20 63 61 6c  r arguments: cal
23940 6c 62 61 63 6b 28 54 2c 43 2c 50 2c 58 29 2e 0a  lback(T,C,P,X)..
23950 2a 2a 20 5e 54 68 65 20 54 20 61 72 67 75 6d 65  ** ^The T argume
23960 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65  nt is one of the
23970 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5d 0a   [SQLITE_TRACE].
23980 2a 2a 20 63 6f 6e 73 74 61 6e 74 73 20 74 6f 20  ** constants to 
23990 69 6e 64 69 63 61 74 65 20 77 68 79 20 74 68 65  indicate why the
239a0 20 63 61 6c 6c 62 61 63 6b 20 77 61 73 20 69 6e   callback was in
239b0 76 6f 6b 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 43  voked..** ^The C
239c0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 63   argument is a c
239d0 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65  opy of the conte
239e0 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 54  xt pointer..** T
239f0 68 65 20 50 20 61 6e 64 20 58 20 61 72 67 75 6d  he P and X argum
23a00 65 6e 74 73 20 61 72 65 20 70 6f 69 6e 74 65 72  ents are pointer
23a10 73 20 77 68 6f 73 65 20 6d 65 61 6e 69 6e 67 73  s whose meanings
23a20 20 64 65 70 65 6e 64 20 6f 6e 20 54 2e 0a 2a 2a   depend on T..**
23a30 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
23a40 74 72 61 63 65 5f 76 32 28 29 20 69 6e 74 65 72  trace_v2() inter
23a50 66 61 63 65 20 69 73 20 69 6e 74 65 6e 64 65 64  face is intended
23a60 20 74 6f 20 72 65 70 6c 61 63 65 20 74 68 65 20   to replace the 
23a70 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
23a80 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 74 72  aces [sqlite3_tr
23a90 61 63 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ace()] and [sqli
23aa0 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 2c 20  te3_profile()], 
23ab0 62 6f 74 68 20 6f 66 20 77 68 69 63 68 0a 2a 2a  both of which.**
23ac0 20 61 72 65 20 64 65 70 72 65 63 61 74 65 64 2e   are deprecated.
23ad0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
23ae0 74 72 61 63 65 5f 76 32 28 0a 20 20 73 71 6c 69  trace_v2(.  sqli
23af0 74 65 33 2a 2c 0a 20 20 75 6e 73 69 67 6e 65 64  te3*,.  unsigned
23b00 20 75 4d 61 73 6b 2c 0a 20 20 69 6e 74 28 2a 78   uMask,.  int(*x
23b10 43 61 6c 6c 62 61 63 6b 29 28 75 6e 73 69 67 6e  Callback)(unsign
23b20 65 64 2c 76 6f 69 64 2a 2c 76 6f 69 64 2a 2c 76  ed,void*,void*,v
23b30 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70  oid*),.  void *p
23b40 43 74 78 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Ctx.);../*.** CA
23b50 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50 72  PI3REF: Query Pr
23b60 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73  ogress Callbacks
23b70 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
23b80 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  te3.**.** ^The s
23b90 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
23ba0 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29  handler(D,N,X,P)
23bb0 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65   interface cause
23bc0 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  s the callback.*
23bd0 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20  * function X to 
23be0 62 65 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f  be invoked perio
23bf0 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c  dically during l
23c00 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c  ong running call
23c10 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s to.** [sqlite3
23c20 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74  _exec()], [sqlit
23c30 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 20 5b  e3_step()] and [
23c40 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
23c50 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61  e()] for.** data
23c60 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
23c70 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75  D.  An example u
23c80 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69  se for this.** i
23c90 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b  nterface is to k
23ca0 65 65 70 20 61 20 47 55 49 20 75 70 64 61 74 65  eep a GUI update
23cb0 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65  d during a large
23cc0 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54   query..**.** ^T
23cd0 68 65 20 70 61 72 61 6d 65 74 65 72 20 50 20 69  he parameter P i
23ce0 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68  s passed through
23cf0 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72   as the only par
23d00 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 0a 2a  ameter to the .*
23d10 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  * callback funct
23d20 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70 61 72  ion X.  ^The par
23d30 61 6d 65 74 65 72 20 4e 20 69 73 20 74 68 65 20  ameter N is the 
23d40 61 70 70 72 6f 78 69 6d 61 74 65 20 6e 75 6d 62  approximate numb
23d50 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75  er of .** [virtu
23d60 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73 74 72  al machine instr
23d70 75 63 74 69 6f 6e 73 5d 20 74 68 61 74 20 61 72  uctions] that ar
23d80 65 20 65 76 61 6c 75 61 74 65 64 20 62 65 74 77  e evaluated betw
23d90 65 65 6e 20 73 75 63 63 65 73 73 69 76 65 0a 2a  een successive.*
23da0 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66  * invocations of
23db0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e   the callback X.
23dc0 20 20 5e 49 66 20 4e 20 69 73 20 6c 65 73 73 20    ^If N is less 
23dd0 74 68 61 6e 20 6f 6e 65 20 74 68 65 6e 20 74 68  than one then th
23de0 65 20 70 72 6f 67 72 65 73 73 0a 2a 2a 20 68 61  e progress.** ha
23df0 6e 64 6c 65 72 20 69 73 20 64 69 73 61 62 6c 65  ndler is disable
23e00 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61  d..**.** ^Only a
23e10 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65 73 73   single progress
23e20 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 62 65 20   handler may be 
23e30 64 65 66 69 6e 65 64 20 61 74 20 6f 6e 65 20 74  defined at one t
23e40 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61  ime per.** [data
23e50 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
23e60 3b 20 73 65 74 74 69 6e 67 20 61 20 6e 65 77 20  ; setting a new 
23e70 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
23e80 20 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20   cancels the.** 
23e90 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69  old one.  ^Setti
23ea0 6e 67 20 70 61 72 61 6d 65 74 65 72 20 58 20 74  ng parameter X t
23eb0 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73 20  o NULL disables 
23ec0 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  the progress han
23ed0 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72  dler..** ^The pr
23ee0 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 69  ogress handler i
23ef0 73 20 61 6c 73 6f 20 64 69 73 61 62 6c 65 64 20  s also disabled 
23f00 62 79 20 73 65 74 74 69 6e 67 20 4e 20 74 6f 20  by setting N to 
23f10 61 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20  a value less.** 
23f20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49  than 1..**.** ^I
23f30 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63  f the progress c
23f40 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
23f50 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70  non-zero, the op
23f60 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e  eration is.** in
23f70 74 65 72 72 75 70 74 65 64 2e 20 20 54 68 69 73  terrupted.  This
23f80 20 66 65 61 74 75 72 65 20 63 61 6e 20 62 65 20   feature can be 
23f90 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
23fa0 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20  t a.** "Cancel" 
23fb0 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20  button on a GUI 
23fc0 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20  progress dialog 
23fd0 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  box..**.** The p
23fe0 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
23ff0 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f  callback must no
24000 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68  t do anything th
24010 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a  at will modify.*
24020 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
24030 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
24040 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72  nvoked the progr
24050 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20  ess handler..** 
24060 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74  Note that [sqlit
24070 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
24080 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
24090 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66  ep()] both modif
240a0 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62  y their.** datab
240b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
240c0 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20  for the meaning 
240d0 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74  of "modify" in t
240e0 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a  his paragraph..*
240f0 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  *.*/.void sqlite
24100 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c  3_progress_handl
24110 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  er(sqlite3*, int
24120 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c  , int(*)(void*),
24130 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
24140 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e  CAPI3REF: Openin
24150 67 20 41 20 4e 65 77 20 44 61 74 61 62 61 73 65  g A New Database
24160 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 43   Connection.** C
24170 4f 4e 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69  ONSTRUCTOR: sqli
24180 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  te3.**.** ^These
24190 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61   routines open a
241a0 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73  n SQLite databas
241b0 65 20 66 69 6c 65 20 61 73 20 73 70 65 63 69 66  e file as specif
241c0 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 66  ied by the .** f
241d0 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
241e0 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20  . ^The filename 
241f0 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65  argument is inte
24200 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d 38  rpreted as UTF-8
24210 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
24220 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
24230 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64  e3_open_v2() and
24240 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68   as UTF-16 in th
24250 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a  e native byte.**
24260 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74   order for sqlit
24270 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41  e3_open16(). ^(A
24280 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
24290 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73  ction] handle is
242a0 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75   usually.** retu
242b0 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65  rned in *ppDb, e
242c0 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20  ven if an error 
242d0 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c  occurs.  The onl
242e0 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74  y exception is t
242f0 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65  hat.** if SQLite
24300 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
24310 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f  locate memory to
24320 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74   hold the [sqlit
24330 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61  e3] object,.** a
24340 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72   NULL will be wr
24350 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62  itten into *ppDb
24360 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f   instead of a po
24370 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  inter to the [sq
24380 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74  lite3].** object
24390 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61 74  .)^ ^(If the dat
243a0 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
243b0 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29  (and/or created)
243c0 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74   successfully, t
243d0 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  hen.** [SQLITE_O
243e0 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  K] is returned. 
243f0 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65   Otherwise an [e
24400 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
24410 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a  turned.)^ ^The.*
24420 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  * [sqlite3_errms
24430 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  g()] or [sqlite3
24440 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75  _errmsg16()] rou
24450 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65  tines can be use
24460 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61  d to obtain.** a
24470 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61  n English langua
24480 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f  ge description o
24490 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c  f the error foll
244a0 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65 20  owing a failure 
244b0 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65  of any.** of the
244c0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
244d0 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
244e0 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63  ^The default enc
244f0 6f 64 69 6e 67 20 77 69 6c 6c 20 62 65 20 55 54  oding will be UT
24500 46 2d 38 20 66 6f 72 20 64 61 74 61 62 61 73 65  F-8 for database
24510 73 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a  s created using.
24520 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
24530 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  ) or sqlite3_ope
24540 6e 5f 76 32 28 29 2e 20 20 5e 54 68 65 20 64 65  n_v2().  ^The de
24550 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66  fault encoding f
24560 6f 72 20 64 61 74 61 62 61 73 65 73 0a 2a 2a 20  or databases.** 
24570 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 73 71  created using sq
24580 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 77  lite3_open16() w
24590 69 6c 6c 20 62 65 20 55 54 46 2d 31 36 20 69 6e  ill be UTF-16 in
245a0 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
245b0 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 57 68   order..**.** Wh
245c0 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20  ether or not an 
245d0 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65  error occurs whe
245e0 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20  n it is opened, 
245f0 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73  resources.** ass
24600 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
24610 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
24620 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68  ction] handle sh
24630 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64  ould be released
24640 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69   by.** passing i
24650 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c  t to [sqlite3_cl
24660 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69  ose()] when it i
24670 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75  s no longer requ
24680 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ired..**.** The 
24690 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
246a0 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b  ) interface work
246b0 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f  s like sqlite3_o
246c0 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20  pen().** except 
246d0 74 68 61 74 20 69 74 20 61 63 63 65 70 74 73 20  that it accepts 
246e0 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70  two additional p
246f0 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64  arameters for ad
24700 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c  ditional control
24710 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77  .** over the new
24720 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
24730 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61  tion.  ^(The fla
24740 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  gs parameter to.
24750 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  ** sqlite3_open_
24760 76 32 28 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e  v2() can take on
24770 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c  e of.** the foll
24780 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75  owing three valu
24790 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63  es, optionally c
247a0 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68 65  ombined with the
247b0 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45   .** [SQLITE_OPE
247c0 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c  N_NOMUTEX], [SQL
247d0 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54  ITE_OPEN_FULLMUT
247e0 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  EX], [SQLITE_OPE
247f0 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 2c 0a  N_SHAREDCACHE],.
24800 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
24810 50 52 49 56 41 54 45 43 41 43 48 45 5d 2c 20 61  PRIVATECACHE], a
24820 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50  nd/or [SQLITE_OP
24830 45 4e 5f 55 52 49 5d 20 66 6c 61 67 73 3a 29 5e  EN_URI] flags:)^
24840 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e  .**.** <dl>.** ^
24850 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45  (<dt>[SQLITE_OPE
24860 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e  N_READONLY]</dt>
24870 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61  .** <dd>The data
24880 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69  base is opened i
24890 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65  n read-only mode
248a0 2e 20 20 49 66 20 74 68 65 20 64 61 74 61 62 61  .  If the databa
248b0 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61  se does not.** a
248c0 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e  lready exist, an
248d0 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
248e0 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  ed.</dd>)^.**.**
248f0 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f   ^(<dt>[SQLITE_O
24900 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f  PEN_READWRITE]</
24910 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64  dt>.** <dd>The d
24920 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
24930 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e  d for reading an
24940 64 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73  d writing if pos
24950 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e  sible, or readin
24960 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65  g.** only if the
24970 20 66 69 6c 65 20 69 73 20 77 72 69 74 65 20 70   file is write p
24980 72 6f 74 65 63 74 65 64 20 62 79 20 74 68 65 20  rotected by the 
24990 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
249a0 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20  .  In either.** 
249b0 63 61 73 65 20 74 68 65 20 64 61 74 61 62 61 73  case the databas
249c0 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65  e must already e
249d0 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20  xist, otherwise 
249e0 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  an error is retu
249f0 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  rned.</dd>)^.**.
24a00 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45  ** ^(<dt>[SQLITE
24a10 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
24a20 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   | [SQLITE_OPEN_
24a30 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20  CREATE]</dt>.** 
24a40 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65  <dd>The database
24a50 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
24a60 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69  eading and writi
24a70 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74  ng, and is creat
24a80 65 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73  ed if.** it does
24a90 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69   not already exi
24aa0 73 74 2e 20 54 68 69 73 20 69 73 20 74 68 65 20  st. This is the 
24ab0 62 65 68 61 76 69 6f 72 20 74 68 61 74 20 69 73  behavior that is
24ac0 20 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72   always used for
24ad0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
24ae0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
24af0 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a  pen16().</dd>)^.
24b00 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </dl>.**.** I
24b10 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
24b20 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
24b30 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20  pen_v2() is not 
24b40 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f  one of the.** co
24b50 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e  mbinations shown
24b60 20 61 62 6f 76 65 20 6f 70 74 69 6f 6e 61 6c 6c   above optionall
24b70 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20  y combined with 
24b80 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  other.** [SQLITE
24b90 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c  _OPEN_READONLY |
24ba0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20 62   SQLITE_OPEN_* b
24bb0 69 74 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65  its].** then the
24bc0 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
24bd0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  efined..**.** ^I
24be0 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  f the [SQLITE_OP
24bf0 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67  EN_NOMUTEX] flag
24c00 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68   is set, then th
24c10 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
24c20 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69  ction.** opens i
24c30 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65  n the multi-thre
24c40 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ad [threading mo
24c50 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  de] as long as t
24c60 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  he single-thread
24c70 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74  .** mode has not
24c80 20 62 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d   been set at com
24c90 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61  pile-time or sta
24ca0 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74 68  rt-time.  ^If th
24cb0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  e.** [SQLITE_OPE
24cc0 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61  N_FULLMUTEX] fla
24cd0 67 20 69 73 20 73 65 74 20 74 68 65 6e 20 74 68  g is set then th
24ce0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
24cf0 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69  ction opens.** i
24d00 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64  n the serialized
24d10 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
24d20 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d  ] unless single-
24d30 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72  thread was.** pr
24d40 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65  eviously selecte
24d50 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  d at compile-tim
24d60 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e  e or start-time.
24d70 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
24d80 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
24d90 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74  E] flag causes t
24da0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
24db0 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20  ection to be.** 
24dc0 65 6c 69 67 69 62 6c 65 20 74 6f 20 75 73 65 20  eligible to use 
24dd0 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f  [shared cache mo
24de0 64 65 5d 2c 20 72 65 67 61 72 64 6c 65 73 73 20  de], regardless 
24df0 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
24e00 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68  t shared.** cach
24e10 65 20 69 73 20 65 6e 61 62 6c 65 64 20 75 73 69  e is enabled usi
24e20 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62  ng [sqlite3_enab
24e30 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28  le_shared_cache(
24e40 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51  )].  ^The.** [SQ
24e50 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
24e60 45 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75  ECACHE] flag cau
24e70 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ses the database
24e80 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e   connection to n
24e90 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69 70 61 74  ot.** participat
24ea0 65 20 69 6e 20 5b 73 68 61 72 65 64 20 63 61 63  e in [shared cac
24eb0 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66  he mode] even if
24ec0 20 69 74 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a   it is enabled..
24ed0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74  **.** ^The fourt
24ee0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
24ef0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
24f00 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
24f10 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
24f20 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74  vfs] object that
24f30 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65   defines the ope
24f40 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e  rating system in
24f50 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20  terface that.** 
24f60 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65  the new database
24f70 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75   connection shou
24f80 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 74 68 65  ld use.  ^If the
24f90 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
24fa0 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70  r is.** a NULL p
24fb0 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20  ointer then the 
24fc0 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
24fd0 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 20  _vfs] object is 
24fe0 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  used..**.** ^If 
24ff0 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20  the filename is 
25000 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e  ":memory:", then
25010 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70   a private, temp
25020 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20  orary in-memory 
25030 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63  database.** is c
25040 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 20 63  reated for the c
25050 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69  onnection.  ^Thi
25060 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61  s in-memory data
25070 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68  base will vanish
25080 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74   when.** the dat
25090 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
250a0 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74   is closed.  Fut
250b0 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
250c0 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20  SQLite might.** 
250d0 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69  make use of addi
250e0 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66  tional special f
250f0 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65  ilenames that be
25100 67 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22  gin with the ":"
25110 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49   character..** I
25120 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
25130 20 74 68 61 74 20 77 68 65 6e 20 61 20 64 61 74   that when a dat
25140 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61  abase filename a
25150 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67  ctually does beg
25160 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22  in with.** a ":"
25170 20 63 68 61 72 61 63 74 65 72 20 79 6f 75 20 73   character you s
25180 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68 65  hould prefix the
25190 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61   filename with a
251a0 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61   pathname such a
251b0 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f  s.** "./" to avo
251c0 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a  id ambiguity..**
251d0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65  .** ^If the file
251e0 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79  name is an empty
251f0 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20   string, then a 
25200 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61  private, tempora
25210 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61  ry.** on-disk da
25220 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63  tabase will be c
25230 72 65 61 74 65 64 2e 20 20 5e 54 68 69 73 20 70  reated.  ^This p
25240 72 69 76 61 74 65 20 64 61 74 61 62 61 73 65 20  rivate database 
25250 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d  will be.** autom
25260 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64  atically deleted
25270 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20   as soon as the 
25280 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
25290 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a  ion is closed..*
252a0 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e  *.** [[URI filen
252b0 61 6d 65 73 20 69 6e 20 73 71 6c 69 74 65 33 5f  ames in sqlite3_
252c0 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 52 49  open()]] <h3>URI
252d0 20 46 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a   Filenames</h3>.
252e0 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 20 66  **.** ^If [URI f
252f0 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 65 72 70 72  ilename] interpr
25300 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c  etation is enabl
25310 65 64 2c 20 61 6e 64 20 74 68 65 20 66 69 6c 65  ed, and the file
25320 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  name argument.**
25330 20 62 65 67 69 6e 73 20 77 69 74 68 20 22 66 69   begins with "fi
25340 6c 65 3a 22 2c 20 74 68 65 6e 20 74 68 65 20 66  le:", then the f
25350 69 6c 65 6e 61 6d 65 20 69 73 20 69 6e 74 65 72  ilename is inter
25360 70 72 65 74 65 64 20 61 73 20 61 20 55 52 49 2e  preted as a URI.
25370 20 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d   ^URI.** filenam
25380 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e  e interpretation
25390 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74   is enabled if t
253a0 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
253b0 55 52 49 5d 20 66 6c 61 67 20 69 73 0a 2a 2a 20  URI] flag is.** 
253c0 73 65 74 20 69 6e 20 74 68 65 20 66 6f 75 72 74  set in the fourt
253d0 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  h argument to sq
253e0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2c  lite3_open_v2(),
253f0 20 6f 72 20 69 66 20 69 74 20 68 61 73 0a 2a 2a   or if it has.**
25400 20 62 65 65 6e 20 65 6e 61 62 6c 65 64 20 67 6c   been enabled gl
25410 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20 74 68 65  obally using the
25420 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
25430 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74 68  URI] option with
25440 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
25450 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68 6f  _config()] metho
25460 64 20 6f 72 20 62 79 20 74 68 65 20 5b 53 51 4c  d or by the [SQL
25470 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f 6d  ITE_USE_URI] com
25480 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
25490 2e 0a 2a 2a 20 41 73 20 6f 66 20 53 51 4c 69 74  ..** As of SQLit
254a0 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c  e version 3.7.7,
254b0 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e   URI filename in
254c0 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20  terpretation is 
254d0 74 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79  turned off.** by
254e0 20 64 65 66 61 75 6c 74 2c 20 62 75 74 20 66 75   default, but fu
254f0 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
25500 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 65 6e   SQLite might en
25510 61 62 6c 65 20 55 52 49 20 66 69 6c 65 6e 61 6d  able URI filenam
25520 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 61 74  e.** interpretat
25530 69 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 20  ion by default. 
25540 20 53 65 65 20 22 5b 55 52 49 20 66 69 6c 65 6e   See "[URI filen
25550 61 6d 65 73 5d 22 20 66 6f 72 20 61 64 64 69 74  ames]" for addit
25560 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61  ional.** informa
25570 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20  tion..**.** URI 
25580 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 20 70 61  filenames are pa
25590 72 73 65 64 20 61 63 63 6f 72 64 69 6e 67 20 74  rsed according t
255a0 6f 20 52 46 43 20 33 39 38 36 2e 20 5e 49 66 20  o RFC 3986. ^If 
255b0 74 68 65 20 55 52 49 20 63 6f 6e 74 61 69 6e 73  the URI contains
255c0 20 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79   an.** authority
255d0 2c 20 74 68 65 6e 20 69 74 20 6d 75 73 74 20 62  , then it must b
255e0 65 20 65 69 74 68 65 72 20 61 6e 20 65 6d 70 74  e either an empt
255f0 79 20 73 74 72 69 6e 67 20 6f 72 20 74 68 65 20  y string or the 
25600 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61  string .** "loca
25610 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74 68 65 20  lhost". ^If the 
25620 61 75 74 68 6f 72 69 74 79 20 69 73 20 6e 6f 74  authority is not
25630 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
25640 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c   or "localhost",
25650 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73   an .** error is
25660 20 72 65 74 75 72 6e 65 64 20 74 6f 20 74 68 65   returned to the
25670 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72   caller. ^The fr
25680 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74  agment component
25690 20 6f 66 20 61 20 55 52 49 2c 20 69 66 20 0a 2a   of a URI, if .*
256a0 2a 20 70 72 65 73 65 6e 74 2c 20 69 73 20 69 67  * present, is ig
256b0 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51  nored..**.** ^SQ
256c0 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 70 61  Lite uses the pa
256d0 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  th component of 
256e0 74 68 65 20 55 52 49 20 61 73 20 74 68 65 20 6e  the URI as the n
256f0 61 6d 65 20 6f 66 20 74 68 65 20 64 69 73 6b 20  ame of the disk 
25700 66 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f  file.** which co
25710 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74 61 62  ntains the datab
25720 61 73 65 2e 20 5e 49 66 20 74 68 65 20 70 61 74  ase. ^If the pat
25730 68 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20  h begins with a 
25740 27 2f 27 20 63 68 61 72 61 63 74 65 72 2c 20 0a  '/' character, .
25750 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e  ** then it is in
25760 74 65 72 70 72 65 74 65 64 20 61 73 20 61 6e 20  terpreted as an 
25770 61 62 73 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e  absolute path. ^
25780 49 66 20 74 68 65 20 70 61 74 68 20 64 6f 65 73  If the path does
25790 20 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77   not begin .** w
257a0 69 74 68 20 61 20 27 2f 27 20 28 6d 65 61 6e 69  ith a '/' (meani
257b0 6e 67 20 74 68 61 74 20 74 68 65 20 61 75 74 68  ng that the auth
257c0 6f 72 69 74 79 20 73 65 63 74 69 6f 6e 20 69 73  ority section is
257d0 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
257e0 65 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74  e URI).** then t
257f0 68 65 20 70 61 74 68 20 69 73 20 69 6e 74 65 72  he path is inter
25800 70 72 65 74 65 64 20 61 73 20 61 20 72 65 6c 61  preted as a rela
25810 74 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e  tive path. .** ^
25820 28 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68 65  (On windows, the
25830 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74   first component
25840 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74 65 20   of an absolute 
25850 70 61 74 68 20 0a 2a 2a 20 69 73 20 61 20 64 72  path .** is a dr
25860 69 76 65 20 73 70 65 63 69 66 69 63 61 74 69 6f  ive specificatio
25870 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e 29 5e  n (e.g. "C:").)^
25880 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55 52  .**.** [[core UR
25890 49 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  I query paramete
258a0 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65 72  rs]].** The quer
258b0 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61  y component of a
258c0 20 55 52 49 20 6d 61 79 20 63 6f 6e 74 61 69 6e   URI may contain
258d0 20 70 61 72 61 6d 65 74 65 72 73 20 74 68 61 74   parameters that
258e0 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
258f0 0a 2a 2a 20 65 69 74 68 65 72 20 62 79 20 53 51  .** either by SQ
25900 4c 69 74 65 20 69 74 73 65 6c 66 2c 20 6f 72 20  Lite itself, or 
25910 62 79 20 61 20 5b 56 46 53 20 7c 20 63 75 73 74  by a [VFS | cust
25920 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  om VFS implement
25930 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74  ation]..** SQLit
25940 65 20 61 6e 64 20 69 74 73 20 62 75 69 6c 74 2d  e and its built-
25950 69 6e 20 5b 56 46 53 65 73 5d 20 69 6e 74 65 72  in [VFSes] inter
25960 70 72 65 74 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c  pret the.** foll
25970 6f 77 69 6e 67 20 71 75 65 72 79 20 70 61 72 61  owing query para
25980 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  meters:.**.** <u
25990 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e  l>.**   <li> <b>
259a0 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76  vfs</b>: ^The "v
259b0 66 73 22 20 70 61 72 61 6d 65 74 65 72 20 6d 61  fs" parameter ma
259c0 79 20 62 65 20 75 73 65 64 20 74 6f 20 73 70 65  y be used to spe
259d0 63 69 66 79 20 74 68 65 20 6e 61 6d 65 20 6f 66  cify the name of
259e0 0a 2a 2a 20 20 20 20 20 61 20 56 46 53 20 6f 62  .**     a VFS ob
259f0 6a 65 63 74 20 74 68 61 74 20 70 72 6f 76 69 64  ject that provid
25a00 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  es the operating
25a10 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63   system interfac
25a20 65 20 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a  e that should.**
25a30 20 20 20 20 20 62 65 20 75 73 65 64 20 74 6f 20       be used to 
25a40 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62  access the datab
25a50 61 73 65 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b  ase file on disk
25a60 2e 20 5e 49 66 20 74 68 69 73 20 6f 70 74 69 6f  . ^If this optio
25a70 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20  n is set to.**  
25a80 20 20 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69     an empty stri
25a90 6e 67 20 74 68 65 20 64 65 66 61 75 6c 74 20 56  ng the default V
25aa0 46 53 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65  FS object is use
25ab0 64 2e 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61  d. ^Specifying a
25ac0 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20  n unknown.**    
25ad0 20 56 46 53 20 69 73 20 61 6e 20 65 72 72 6f 72   VFS is an error
25ae0 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70  . ^If sqlite3_op
25af0 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20  en_v2() is used 
25b00 61 6e 64 20 74 68 65 20 76 66 73 20 6f 70 74 69  and the vfs opti
25b10 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70 72 65  on is.**     pre
25b20 73 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 56  sent, then the V
25b30 46 53 20 73 70 65 63 69 66 69 65 64 20 62 79 20  FS specified by 
25b40 74 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  the option takes
25b50 20 70 72 65 63 65 64 65 6e 63 65 20 6f 76 65 72   precedence over
25b60 0a 2a 2a 20 20 20 20 20 74 68 65 20 76 61 6c 75  .**     the valu
25b70 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
25b80 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
25b90 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
25ba0 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c  _v2()..**.**   <
25bb0 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a  li> <b>mode</b>:
25bc0 20 5e 28 54 68 65 20 6d 6f 64 65 20 70 61 72 61   ^(The mode para
25bd0 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74  meter may be set
25be0 20 74 6f 20 65 69 74 68 65 72 20 22 72 6f 22 2c   to either "ro",
25bf0 20 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72   "rw",.**     "r
25c00 77 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22  wc", or "memory"
25c10 2e 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20  . Attempting to 
25c20 73 65 74 20 69 74 20 74 6f 20 61 6e 79 20 6f 74  set it to any ot
25c30 68 65 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20  her value is.** 
25c40 20 20 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20      an error)^. 
25c50 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22  .**     ^If "ro"
25c60 20 69 73 20 73 70 65 63 69 66 69 65 64 2c 20 74   is specified, t
25c70 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
25c80 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
25c90 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20  ead-only .**    
25ca0 20 61 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73   access, just as
25cb0 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   if the [SQLITE_
25cc0 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66  OPEN_READONLY] f
25cd0 6c 61 67 20 68 61 64 20 62 65 65 6e 20 73 65 74  lag had been set
25ce0 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20   in the .**     
25cf0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74  third argument t
25d00 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
25d10 32 28 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64  2(). ^If the mod
25d20 65 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20  e option is set 
25d30 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c  to .**     "rw",
25d40 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
25d50 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
25d60 20 72 65 61 64 2d 77 72 69 74 65 20 28 62 75 74   read-write (but
25d70 20 6e 6f 74 20 63 72 65 61 74 65 29 20 0a 2a 2a   not create) .**
25d80 20 20 20 20 20 61 63 63 65 73 73 2c 20 61 73 20       access, as 
25d90 69 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  if SQLITE_OPEN_R
25da0 45 41 44 57 52 49 54 45 20 28 62 75 74 20 6e 6f  EADWRITE (but no
25db0 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  t SQLITE_OPEN_CR
25dc0 45 41 54 45 29 20 68 61 64 20 0a 2a 2a 20 20 20  EATE) had .**   
25dd0 20 20 62 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c    been set. ^Val
25de0 75 65 20 22 72 77 63 22 20 69 73 20 65 71 75 69  ue "rwc" is equi
25df0 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e  valent to settin
25e00 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53  g both .**     S
25e10 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
25e20 52 49 54 45 20 61 6e 64 20 53 51 4c 49 54 45 5f  RITE and SQLITE_
25e30 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49  OPEN_CREATE.  ^I
25e40 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f  f the mode optio
25e50 6e 20 69 73 0a 2a 2a 20 20 20 20 20 73 65 74 20  n is.**     set 
25e60 74 6f 20 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e  to "memory" then
25e70 20 61 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f   a pure [in-memo
25e80 72 79 20 64 61 74 61 62 61 73 65 5d 20 74 68 61  ry database] tha
25e90 74 20 6e 65 76 65 72 20 72 65 61 64 73 0a 2a 2a  t never reads.**
25ea0 20 20 20 20 20 6f 72 20 77 72 69 74 65 73 20 66       or writes f
25eb0 72 6f 6d 20 64 69 73 6b 20 69 73 20 75 73 65 64  rom disk is used
25ec0 2e 20 5e 49 74 20 69 73 20 61 6e 20 65 72 72 6f  . ^It is an erro
25ed0 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 20 76  r to specify a v
25ee0 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20  alue for.**     
25ef0 74 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74  the mode paramet
25f00 65 72 20 74 68 61 74 20 69 73 20 6c 65 73 73 20  er that is less 
25f10 72 65 73 74 72 69 63 74 69 76 65 20 74 68 61 6e  restrictive than
25f20 20 74 68 61 74 20 73 70 65 63 69 66 69 65 64 20   that specified 
25f30 62 79 0a 2a 2a 20 20 20 20 20 74 68 65 20 66 6c  by.**     the fl
25f40 61 67 73 20 70 61 73 73 65 64 20 69 6e 20 74 68  ags passed in th
25f50 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
25f60 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
25f70 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20  n_v2()..**.**   
25f80 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62  <li> <b>cache</b
25f90 3e 3a 20 5e 54 68 65 20 63 61 63 68 65 20 70 61  >: ^The cache pa
25fa0 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73  rameter may be s
25fb0 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 73 68  et to either "sh
25fc0 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20  ared" or.**     
25fd0 22 70 72 69 76 61 74 65 22 2e 20 5e 53 65 74 74  "private". ^Sett
25fe0 69 6e 67 20 69 74 20 74 6f 20 22 73 68 61 72 65  ing it to "share
25ff0 64 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74  d" is equivalent
26000 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 0a   to setting the.
26010 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50  **     SQLITE_OP
26020 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 62  EN_SHAREDCACHE b
26030 69 74 20 69 6e 20 74 68 65 20 66 6c 61 67 73 20  it in the flags 
26040 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20  argument passed 
26050 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65  to.**     sqlite
26060 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65  3_open_v2(). ^Se
26070 74 74 69 6e 67 20 74 68 65 20 63 61 63 68 65 20  tting the cache 
26080 70 61 72 61 6d 65 74 65 72 20 74 6f 20 22 70 72  parameter to "pr
26090 69 76 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 20  ivate" is .**   
260a0 20 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20    equivalent to 
260b0 73 65 74 74 69 6e 67 20 74 68 65 20 53 51 4c 49  setting the SQLI
260c0 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
260d0 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20  ACHE bit..**    
260e0 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65   ^If sqlite3_ope
260f0 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61  n_v2() is used a
26100 6e 64 20 74 68 65 20 22 63 61 63 68 65 22 20 70  nd the "cache" p
26110 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 65 73  arameter is pres
26120 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20  ent in.**     a 
26130 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74  URI filename, it
26140 73 20 76 61 6c 75 65 20 6f 76 65 72 72 69 64 65  s value override
26150 73 20 61 6e 79 20 62 65 68 61 76 69 6f 72 20 72  s any behavior r
26160 65 71 75 65 73 74 65 64 20 62 79 20 73 65 74 74  equested by sett
26170 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54  ing.**     SQLIT
26180 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
26190 43 48 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50  CHE or SQLITE_OP
261a0 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 66  EN_SHAREDCACHE f
261b0 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e  lag..**.**  <li>
261c0 20 3c 62 3e 70 73 6f 77 3c 2f 62 3e 3a 20 5e 54   <b>psow</b>: ^T
261d0 68 65 20 70 73 6f 77 20 70 61 72 61 6d 65 74 65  he psow paramete
261e0 72 20 69 6e 64 69 63 61 74 65 73 20 77 68 65 74  r indicates whet
261f0 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 0a 2a  her or not the.*
26200 2a 20 20 20 20 20 5b 70 6f 77 65 72 73 61 66 65  *     [powersafe
26210 20 6f 76 65 72 77 72 69 74 65 5d 20 70 72 6f 70   overwrite] prop
26220 65 72 74 79 20 64 6f 65 73 20 6f 72 20 64 6f 65  erty does or doe
26230 73 20 6e 6f 74 20 61 70 70 6c 79 20 74 6f 20 74  s not apply to t
26240 68 65 0a 2a 2a 20 20 20 20 20 73 74 6f 72 61 67  he.**     storag
26250 65 20 6d 65 64 69 61 20 6f 6e 20 77 68 69 63 68  e media on which
26260 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
26270 6c 65 20 72 65 73 69 64 65 73 2e 0a 2a 2a 0a 2a  le resides..**.*
26280 2a 20 20 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f 63  *  <li> <b>noloc
26290 6b 3c 2f 62 3e 3a 20 5e 54 68 65 20 6e 6f 6c 6f  k</b>: ^The nolo
262a0 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ck parameter is 
262b0 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 20  a boolean query 
262c0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20  parameter.**    
262d0 20 77 68 69 63 68 20 69 66 20 73 65 74 20 64 69   which if set di
262e0 73 61 62 6c 65 73 20 66 69 6c 65 20 6c 6f 63 6b  sables file lock
262f0 69 6e 67 20 69 6e 20 72 6f 6c 6c 62 61 63 6b 20  ing in rollback 
26300 6a 6f 75 72 6e 61 6c 20 6d 6f 64 65 73 2e 20 20  journal modes.  
26310 54 68 69 73 0a 2a 2a 20 20 20 20 20 69 73 20 75  This.**     is u
26320 73 65 66 75 6c 20 66 6f 72 20 61 63 63 65 73 73  seful for access
26330 69 6e 67 20 61 20 64 61 74 61 62 61 73 65 20 6f  ing a database o
26340 6e 20 61 20 66 69 6c 65 73 79 73 74 65 6d 20 74  n a filesystem t
26350 68 61 74 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  hat does not.** 
26360 20 20 20 20 73 75 70 70 6f 72 74 20 6c 6f 63 6b      support lock
26370 69 6e 67 2e 20 20 43 61 75 74 69 6f 6e 3a 20 20  ing.  Caution:  
26380 44 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74  Database corrupt
26390 69 6f 6e 20 6d 69 67 68 74 20 72 65 73 75 6c 74  ion might result
263a0 20 69 66 20 74 77 6f 0a 2a 2a 20 20 20 20 20 6f   if two.**     o
263b0 72 20 6d 6f 72 65 20 70 72 6f 63 65 73 73 65 73  r more processes
263c0 20 77 72 69 74 65 20 74 6f 20 74 68 65 20 73 61   write to the sa
263d0 6d 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  me database and 
263e0 61 6e 79 20 6f 6e 65 20 6f 66 20 74 68 6f 73 65  any one of those
263f0 0a 2a 2a 20 20 20 20 20 70 72 6f 63 65 73 73 65  .**     processe
26400 73 20 75 73 65 73 20 6e 6f 6c 6f 63 6b 3d 31 2e  s uses nolock=1.
26410 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e  .**.**  <li> <b>
26420 69 6d 6d 75 74 61 62 6c 65 3c 2f 62 3e 3a 20 5e  immutable</b>: ^
26430 54 68 65 20 69 6d 6d 75 74 61 62 6c 65 20 70 61  The immutable pa
26440 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f  rameter is a boo
26450 6c 65 61 6e 20 71 75 65 72 79 0a 2a 2a 20 20 20  lean query.**   
26460 20 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74    parameter that
26470 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20   indicates that 
26480 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
26490 65 20 69 73 20 73 74 6f 72 65 64 20 6f 6e 0a 2a  e is stored on.*
264a0 2a 20 20 20 20 20 72 65 61 64 2d 6f 6e 6c 79 20  *     read-only 
264b0 6d 65 64 69 61 2e 20 20 5e 57 68 65 6e 20 69 6d  media.  ^When im
264c0 6d 75 74 61 62 6c 65 20 69 73 20 73 65 74 2c 20  mutable is set, 
264d0 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74  SQLite assumes t
264e0 68 61 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 64  hat the.**     d
264f0 61 74 61 62 61 73 65 20 66 69 6c 65 20 63 61 6e  atabase file can
26500 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 2c 20  not be changed, 
26510 65 76 65 6e 20 62 79 20 61 20 70 72 6f 63 65 73  even by a proces
26520 73 20 77 69 74 68 20 68 69 67 68 65 72 0a 2a 2a  s with higher.**
26530 20 20 20 20 20 70 72 69 76 69 6c 65 67 65 2c 20       privilege, 
26540 61 6e 64 20 73 6f 20 74 68 65 20 64 61 74 61 62  and so the datab
26550 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 72 65  ase is opened re
26560 61 64 2d 6f 6e 6c 79 20 61 6e 64 20 61 6c 6c 20  ad-only and all 
26570 6c 6f 63 6b 69 6e 67 0a 2a 2a 20 20 20 20 20 61  locking.**     a
26580 6e 64 20 63 68 61 6e 67 65 20 64 65 74 65 63 74  nd change detect
26590 69 6f 6e 20 69 73 20 64 69 73 61 62 6c 65 64 2e  ion is disabled.
265a0 20 20 43 61 75 74 69 6f 6e 3a 20 53 65 74 74 69    Caution: Setti
265b0 6e 67 20 74 68 65 20 69 6d 6d 75 74 61 62 6c 65  ng the immutable
265c0 0a 2a 2a 20 20 20 20 20 70 72 6f 70 65 72 74 79  .**     property
265d0 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 66   on a database f
265e0 69 6c 65 20 74 68 61 74 20 64 6f 65 73 20 69 6e  ile that does in
265f0 20 66 61 63 74 20 63 68 61 6e 67 65 20 63 61 6e   fact change can
26600 20 72 65 73 75 6c 74 0a 2a 2a 20 20 20 20 20 69   result.**     i
26610 6e 20 69 6e 63 6f 72 72 65 63 74 20 71 75 65 72  n incorrect quer
26620 79 20 72 65 73 75 6c 74 73 20 61 6e 64 2f 6f 72  y results and/or
26630 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54   [SQLITE_CORRUPT
26640 5d 20 65 72 72 6f 72 73 2e 0a 2a 2a 20 20 20 20  ] errors..**    
26650 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49   See also: [SQLI
26660 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42  TE_IOCAP_IMMUTAB
26670 4c 45 5d 2e 0a 2a 2a 20 20 20 20 20 20 20 0a 2a  LE]..**       .*
26680 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53  * </ul>.**.** ^S
26690 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b  pecifying an unk
266a0 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 20 69  nown parameter i
266b0 6e 20 74 68 65 20 71 75 65 72 79 20 63 6f 6d 70  n the query comp
266c0 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 69  onent of a URI i
266d0 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f  s not an.** erro
266e0 72 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  r.  Future versi
266f0 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ons of SQLite mi
26700 67 68 74 20 75 6e 64 65 72 73 74 61 6e 64 20 61  ght understand a
26710 64 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a  dditional query.
26720 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ** parameters.  
26730 53 65 65 20 22 5b 71 75 65 72 79 20 70 61 72 61  See "[query para
26740 6d 65 74 65 72 73 20 77 69 74 68 20 73 70 65 63  meters with spec
26750 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53  ial meaning to S
26760 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61  QLite]" for.** a
26770 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
26780 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55  ation..**.** [[U
26790 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d  RI filename exam
267a0 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66  ples]] <h3>URI f
267b0 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73  ilename examples
267c0 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62  </h3>.**.** <tab
267d0 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 20 61 6c  le border="1" al
267e0 69 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70  ign=center cellp
267f0 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72  adding=5>.** <tr
26800 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 6e 61  ><th> URI filena
26810 6d 65 73 20 3c 74 68 3e 20 52 65 73 75 6c 74 73  mes <th> Results
26820 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
26830 65 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a  e:data.db <td> .
26840 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
26850 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e   the file "data.
26860 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65  db" in the curre
26870 6e 74 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a  nt directory..**
26880 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f   <tr><td> file:/
26890 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
268a0 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20  b<br>.**        
268b0 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66    file:///home/f
268c0 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e  red/data.db <br>
268d0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69   .**          fi
268e0 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68  le://localhost/h
268f0 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
26900 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20   <br> <td> .**  
26910 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65          Open the
26920 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 22   database file "
26930 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
26940 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  db"..** <tr><td>
26950 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72   file://darkstar
26960 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
26970 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  db <td> .**     
26980 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22       An error. "
26990 64 61 72 6b 73 74 61 72 22 20 69 73 20 6e 6f 74  darkstar" is not
269a0 20 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 61 75   a recognized au
269b0 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e  thority..** <tr>
269c0 3c 74 64 20 73 74 79 6c 65 3d 22 77 68 69 74 65  <td style="white
269d0 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20  -space:nowrap"> 
269e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c  .**          fil
269f0 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74  e:///C:/Document
26a00 73 25 32 30 61 6e 64 25 32 30 53 65 74 74 69 6e  s%20and%20Settin
26a10 67 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f  gs/fred/Desktop/
26a20 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c  data.db.**     <
26a30 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79  td> Windows only
26a40 3a 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20  : Open the file 
26a50 22 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 72 65  "data.db" on fre
26a60 64 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64  d's desktop on d
26a70 72 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  rive.**         
26a80 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20 74   C:. Note that t
26a90 68 65 20 25 32 30 20 65 73 63 61 70 69 6e 67 20  he %20 escaping 
26aa0 69 6e 20 74 68 69 73 20 65 78 61 6d 70 6c 65 20  in this example 
26ab0 69 73 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20  is not strictly 
26ac0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65 63  .**          nec
26ad0 65 73 73 61 72 79 20 2d 20 73 70 61 63 65 20 63  essary - space c
26ae0 68 61 72 61 63 74 65 72 73 20 63 61 6e 20 62 65  haracters can be
26af0 20 75 73 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a   used literally.
26b00 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 55  **          in U
26b10 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a  RI filenames..**
26b20 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64   <tr><td> file:d
26b30 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63  ata.db?mode=ro&c
26b40 61 63 68 65 3d 70 72 69 76 61 74 65 20 3c 74 64  ache=private <td
26b50 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f  > .**          O
26b60 70 65 6e 20 66 69 6c 65 20 22 64 61 74 61 2e 64  pen file "data.d
26b70 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  b" in the curren
26b80 74 20 64 69 72 65 63 74 6f 72 79 20 66 6f 72 20  t directory for 
26b90 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73  read-only access
26ba0 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 52 65  ..**          Re
26bb0 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
26bc0 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65  her or not share
26bd0 64 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 73 20  d-cache mode is 
26be0 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20  enabled by.**   
26bf0 20 20 20 20 20 20 20 64 65 66 61 75 6c 74 2c 20         default, 
26c00 75 73 65 20 61 20 70 72 69 76 61 74 65 20 63 61  use a private ca
26c10 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  che..** <tr><td>
26c20 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64   file:/home/fred
26c30 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69  /data.db?vfs=uni
26c40 78 2d 64 6f 74 66 69 6c 65 20 3c 74 64 3e 0a 2a  x-dotfile <td>.*
26c50 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20  *          Open 
26c60 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64  file "/home/fred
26c70 2f 64 61 74 61 2e 64 62 22 2e 20 55 73 65 20 74  /data.db". Use t
26c80 68 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 22  he special VFS "
26c90 75 6e 69 78 2d 64 6f 74 66 69 6c 65 22 0a 2a 2a  unix-dotfile".**
26ca0 20 20 20 20 20 20 20 20 20 20 74 68 61 74 20 75            that u
26cb0 73 65 73 20 64 6f 74 2d 66 69 6c 65 73 20 69 6e  ses dot-files in
26cc0 20 70 6c 61 63 65 20 6f 66 20 70 6f 73 69 78 20   place of posix 
26cd0 61 64 76 69 73 6f 72 79 20 6c 6f 63 6b 69 6e 67  advisory locking
26ce0 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
26cf0 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d  le:data.db?mode=
26d00 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a  readonly <td> .*
26d10 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72  *          An er
26d20 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20  ror. "readonly" 
26d30 69 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f  is not a valid o
26d40 70 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d  ption for the "m
26d50 6f 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e 0a  ode" parameter..
26d60 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a  ** </table>.**.*
26d70 2a 20 5e 55 52 49 20 68 65 78 61 64 65 63 69 6d  * ^URI hexadecim
26d80 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e  al escape sequen
26d90 63 65 73 20 28 25 48 48 29 20 61 72 65 20 73 75  ces (%HH) are su
26da0 70 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20 74  pported within t
26db0 68 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71  he path and.** q
26dc0 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20  uery components 
26dd0 6f 66 20 61 20 55 52 49 2e 20 41 20 68 65 78 61  of a URI. A hexa
26de0 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73  decimal escape s
26df0 65 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74 73  equence consists
26e00 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74   of a.** percent
26e10 20 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f   sign - "%" - fo
26e20 6c 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74 6c  llowed by exactl
26e30 79 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d 61  y two hexadecima
26e40 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70 65  l digits .** spe
26e50 63 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65 74  cifying an octet
26e60 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20   value. ^Before 
26e70 74 68 65 20 70 61 74 68 20 6f 72 20 71 75 65 72  the path or quer
26e80 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20  y components of 
26e90 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d  a.** URI filenam
26ea0 65 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  e are interprete
26eb0 64 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63 6f  d, they are enco
26ec0 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 20  ded using UTF-8 
26ed0 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61  and all .** hexa
26ee0 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73  decimal escape s
26ef0 65 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63 65  equences replace
26f00 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62 79  d by a single by
26f10 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  te containing th
26f20 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69  e.** correspondi
26f30 6e 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68 69  ng octet. If thi
26f40 73 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72 61  s process genera
26f50 74 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20 55  tes an invalid U
26f60 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a  TF-8 encoding,.*
26f70 2a 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  * the results ar
26f80 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  e undefined..**.
26f90 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69  ** <b>Note to Wi
26fa0 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e  ndows users:</b>
26fb0 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75    The encoding u
26fc0 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65  sed for the file
26fd0 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  name argument.**
26fe0 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   of sqlite3_open
26ff0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
27000 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65  pen_v2() must be
27010 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74   UTF-8, not what
27020 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65  ever.** codepage
27030 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65   is currently de
27040 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65  fined.  Filename
27050 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74  s containing int
27060 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68  ernational.** ch
27070 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 65  aracters must be
27080 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54   converted to UT
27090 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73  F-8 prior to pas
270a0 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a  sing them into.*
270b0 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
270c0 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   or sqlite3_open
270d0 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  _v2()..**.** <b>
270e0 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20  Note to Windows 
270f0 52 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f  Runtime users:</
27100 62 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61 72  b>  The temporar
27110 79 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73 74  y directory must
27120 20 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72   be set.** prior
27130 20 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69   to calling sqli
27140 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71  te3_open() or sq
27150 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
27160 20 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61 72    Otherwise, var
27170 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65 73  ious.** features
27180 20 74 68 61 74 20 72 65 71 75 69 72 65 20 74 68   that require th
27190 65 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72 61  e use of tempora
271a0 72 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61 69  ry files may fai
271b0 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  l..**.** See als
271c0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70  o: [sqlite3_temp
271d0 5f 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 69  _directory].*/.i
271e0 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  nt sqlite3_open(
271f0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66  .  const char *f
27200 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
27210 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
27220 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c  (UTF-8) */.  sql
27230 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20  ite3 **ppDb     
27240 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
27250 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
27260 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
27270 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20  open16(.  const 
27280 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  void *filename, 
27290 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
272a0 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20  lename (UTF-16) 
272b0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
272c0 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb          /* 
272d0 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
272e0 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20  andle */.);.int 
272f0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
27300 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66  .  const char *f
27310 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
27320 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
27330 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c  (UTF-8) */.  sql
27340 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20  ite3 **ppDb,    
27350 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
27360 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
27370 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20  .  int flags,   
27380 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c             /* Fl
27390 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ags */.  const c
273a0 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20  har *zVfs       
273b0 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20   /* Name of VFS 
273c0 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f  module to use */
273d0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
273e0 52 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75  REF: Obtain Valu
273f0 65 73 20 46 6f 72 20 55 52 49 20 50 61 72 61 6d  es For URI Param
27400 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  eters.**.** Thes
27410 65 20 61 72 65 20 75 74 69 6c 69 74 79 20 72 6f  e are utility ro
27420 75 74 69 6e 65 73 2c 20 75 73 65 66 75 6c 20 74  utines, useful t
27430 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  o VFS implementa
27440 74 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65 63  tions, that chec
27450 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20 61  k.** to see if a
27460 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
27470 61 73 20 61 20 55 52 49 20 74 68 61 74 20 63 6f  as a URI that co
27480 6e 74 61 69 6e 65 64 20 61 20 73 70 65 63 69 66  ntained a specif
27490 69 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 61 72  ic query .** par
274a0 61 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 20 73  ameter, and if s
274b0 6f 20 6f 62 74 61 69 6e 73 20 74 68 65 20 76 61  o obtains the va
274c0 6c 75 65 20 6f 66 20 74 68 61 74 20 71 75 65 72  lue of that quer
274d0 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  y parameter..**.
274e0 2a 2a 20 49 66 20 46 20 69 73 20 74 68 65 20 64  ** If F is the d
274f0 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
27500 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20   pointer passed 
27510 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29  into the xOpen()
27520 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61   method of .** a
27530 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
27540 69 6f 6e 20 77 68 65 6e 20 74 68 65 20 66 6c 61  ion when the fla
27550 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  gs parameter to 
27560 78 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e 65 20  xOpen() has one 
27570 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74  or .** more of t
27580 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
27590 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  URI] or [SQLITE_
275a0 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69  OPEN_MAIN_DB] bi
275b0 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20  ts set and.** P 
275c0 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
275d0 68 65 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  he query paramet
275e0 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69  er, then.** sqli
275f0 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65  te3_uri_paramete
27600 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 74  r(F,P) returns t
27610 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
27620 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69  P.** parameter i
27630 66 20 69 74 20 65 78 69 73 74 73 20 6f 72 20 61  f it exists or a
27640 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66   NULL pointer if
27650 20 50 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65   P does not appe
27660 61 72 20 61 73 20 61 20 0a 2a 2a 20 71 75 65 72  ar as a .** quer
27670 79 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46  y parameter on F
27680 2e 20 20 49 66 20 50 20 69 73 20 61 20 71 75 65  .  If P is a que
27690 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  ry parameter of 
276a0 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c  F.** has no expl
276b0 69 63 69 74 20 76 61 6c 75 65 2c 20 74 68 65 6e  icit value, then
276c0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72   sqlite3_uri_par
276d0 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75  ameter(F,P) retu
276e0 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72  rns.** a pointer
276f0 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72   to an empty str
27700 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ing..**.** The s
27710 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
27720 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e  an(F,P,B) routin
27730 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 50  e assumes that P
27740 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a   is a boolean.**
27750 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72   parameter and r
27760 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20  eturns true (1) 
27770 6f 72 20 66 61 6c 73 65 20 28 30 29 20 61 63 63  or false (0) acc
27780 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 20 76 61  ording to the va
27790 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68  lue.** of P.  Th
277a0 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  e sqlite3_uri_bo
277b0 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75  olean(F,P,B) rou
277c0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 72 75  tine returns tru
277d0 65 20 28 31 29 20 69 66 20 74 68 65 0a 2a 2a 20  e (1) if the.** 
277e0 76 61 6c 75 65 20 6f 66 20 71 75 65 72 79 20 70  value of query p
277f0 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e  arameter P is on
27800 65 20 6f 66 20 22 79 65 73 22 2c 20 22 74 72 75  e of "yes", "tru
27810 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20 61  e", or "on" in a
27820 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69 66  ny.** case or if
27830 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e   the value begin
27840 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72  s with a non-zer
27850 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 0a  o number.  The .
27860 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  ** sqlite3_uri_b
27870 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f  oolean(F,P,B) ro
27880 75 74 69 6e 65 73 20 72 65 74 75 72 6e 73 20 66  utines returns f
27890 61 6c 73 65 20 28 30 29 20 69 66 20 74 68 65 20  alse (0) if the 
278a0 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65 72  value of.** quer
278b0 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73  y parameter P is
278c0 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22 66   one of "no", "f
278d0 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66 22 20  alse", or "off" 
278e0 69 6e 20 61 6e 79 20 63 61 73 65 20 6f 72 0a 2a  in any case or.*
278f0 2a 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62  * if the value b
27900 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 75 6d  egins with a num
27910 65 72 69 63 20 7a 65 72 6f 2e 20 20 49 66 20 50  eric zero.  If P
27920 20 69 73 20 6e 6f 74 20 61 20 71 75 65 72 79 0a   is not a query.
27930 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20  ** parameter on 
27940 46 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75  F or if the valu
27950 65 20 6f 66 20 50 20 69 73 20 64 6f 65 73 20 6e  e of P is does n
27960 6f 74 20 6d 61 74 63 68 20 61 6e 79 20 6f 66 20  ot match any of 
27970 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 68  the.** above, th
27980 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  en sqlite3_uri_b
27990 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65  oolean(F,P,B) re
279a0 74 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a  turns (B!=0)..**
279b0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
279c0 75 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29  uri_int64(F,P,D)
279d0 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72 74   routine convert
279e0 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50  s the value of P
279f0 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69   into a.** 64-bi
27a00 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
27a10 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 68 61   and returns tha
27a20 74 20 69 6e 74 65 67 65 72 2c 20 6f 72 20 44 20  t integer, or D 
27a30 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a  if P does not.**
27a40 20 65 78 69 73 74 2e 20 20 49 66 20 74 68 65 20   exist.  If the 
27a50 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 73 6f  value of P is so
27a60 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68  mething other th
27a70 61 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74  an an integer, t
27a80 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72  hen.** zero is r
27a90 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20  eturned..** .** 
27aa0 49 66 20 46 20 69 73 20 61 20 4e 55 4c 4c 20 70  If F is a NULL p
27ab0 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 73 71 6c  ointer, then sql
27ac0 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
27ad0 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20  er(F,P) returns 
27ae0 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69  NULL and.** sqli
27af0 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
27b00 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 42  F,P,B) returns B
27b10 2e 20 20 49 66 20 46 20 69 73 20 6e 6f 74 20 61  .  If F is not a
27b20 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e   NULL pointer an
27b30 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64 61  d.** is not a da
27b40 74 61 62 61 73 65 20 66 69 6c 65 20 70 61 74 68  tabase file path
27b50 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 74 68 61  name pointer tha
27b60 74 20 53 51 4c 69 74 65 20 70 61 73 73 65 64 20  t SQLite passed 
27b70 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a  into the xOpen.*
27b80 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 74 68  * VFS method, th
27b90 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
27ba0 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  of this routine 
27bb0 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  is undefined and
27bc0 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64   probably.** und
27bd0 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e  esirable..*/.con
27be0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
27bf0 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63  _uri_parameter(c
27c00 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
27c10 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72  name, const char
27c20 20 2a 7a 50 61 72 61 6d 29 3b 0a 69 6e 74 20 73   *zParam);.int s
27c30 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
27c40 61 6e 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  an(const char *z
27c50 46 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61 72  File, const char
27c60 20 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62 44   *zParam, int bD
27c70 65 66 61 75 6c 74 29 3b 0a 73 71 6c 69 74 65 33  efault);.sqlite3
27c80 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75  _int64 sqlite3_u
27c90 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20 63  ri_int64(const c
27ca0 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  har*, const char
27cb0 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
27cc0 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  );.../*.** CAPI3
27cd0 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73  REF: Error Codes
27ce0 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a   And Messages.**
27cf0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
27d00 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d  .**.** ^If the m
27d10 6f 73 74 20 72 65 63 65 6e 74 20 73 71 6c 69 74  ost recent sqlit
27d20 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 20 61 73  e3_* API call as
27d30 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 0a 2a  sociated with .*
27d40 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
27d50 65 63 74 69 6f 6e 5d 20 44 20 66 61 69 6c 65 64  ection] D failed
27d60 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74  , then the sqlit
27d70 65 33 5f 65 72 72 63 6f 64 65 28 44 29 20 69 6e  e3_errcode(D) in
27d80 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 74 75 72  terface.** retur
27d90 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b  ns the numeric [
27da0 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20  result code] or 
27db0 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
27dc0 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 61 74 0a   code] for that.
27dd0 2a 2a 20 41 50 49 20 63 61 6c 6c 2e 0a 2a 2a 20  ** API call..** 
27de0 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
27df0 6e 74 20 41 50 49 20 63 61 6c 6c 20 77 61 73 20  nt API call was 
27e00 73 75 63 63 65 73 73 66 75 6c 2c 0a 2a 2a 20 74  successful,.** t
27e10 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76  hen the return v
27e20 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
27e30 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20 75  3_errcode() is u
27e40 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 54 68  ndefined..** ^Th
27e50 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  e sqlite3_extend
27e60 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20  ed_errcode().** 
27e70 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 65  interface is the
27e80 20 73 61 6d 65 20 65 78 63 65 70 74 20 74 68 61   same except tha
27e90 74 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75  t it always retu
27ea0 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74  rns the .** [ext
27eb0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
27ec0 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74  e] even when ext
27ed0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
27ee0 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c  es are.** disabl
27ef0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
27f00 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20  qlite3_errmsg() 
27f10 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d  and sqlite3_errm
27f20 73 67 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e  sg16() return En
27f30 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a  glish-language.*
27f40 2a 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63  * text that desc
27f50 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c  ribes the error,
27f60 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38   as either UTF-8
27f70 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70 65   or UTF-16 respe
27f80 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65  ctively..** ^(Me
27f90 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
27fa0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
27fb0 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64  tring is managed
27fc0 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20   internally..** 
27fd0 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
27fe0 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
27ff0 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65   worry about fre
28000 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e  eing the result.
28010 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65  .** However, the
28020 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69   error string mi
28030 67 68 74 20 62 65 20 6f 76 65 72 77 72 69 74 74  ght be overwritt
28040 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65  en or deallocate
28050 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65  d by.** subseque
28060 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65  nt calls to othe
28070 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
28080 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a  ce functions.)^.
28090 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
280a0 65 33 5f 65 72 72 73 74 72 28 29 20 69 6e 74 65  e3_errstr() inte
280b0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
280c0 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61  e English-langua
280d0 67 65 20 74 65 78 74 0a 2a 2a 20 74 68 61 74 20  ge text.** that 
280e0 64 65 73 63 72 69 62 65 73 20 74 68 65 20 5b 72  describes the [r
280f0 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61 73 20  esult code], as 
28100 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f  UTF-8..** ^(Memo
28110 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65  ry to hold the e
28120 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
28130 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69  ing is managed i
28140 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64  nternally.** and
28150 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 66 72 65   must not be fre
28160 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ed by the applic
28170 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57  ation)^..**.** W
28180 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a  hen the serializ
28190 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ed [threading mo
281a0 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69  de] is in use, i
281b0 74 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a  t might be the.*
281c0 2a 20 63 61 73 65 20 74 68 61 74 20 61 20 73 65  * case that a se
281d0 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72  cond error occur
281e0 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20  s on a separate 
281f0 74 68 72 65 61 64 20 69 6e 20 62 65 74 77 65 65  thread in betwee
28200 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66  n.** the time of
28210 20 74 68 65 20 66 69 72 73 74 20 65 72 72 6f 72   the first error
28220 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f   and the call to
28230 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
28240 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20  s..** When that 
28250 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63  happens, the sec
28260 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62  ond error will b
28270 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65  e reported since
28280 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66   these.** interf
28290 61 63 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f  aces always repo
282a0 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  rt the most rece
282b0 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61  nt result.  To a
282c0 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61  void.** this, ea
282d0 63 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62  ch thread can ob
282e0 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75  tain exclusive u
282f0 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62  se of the [datab
28300 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
28310 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67  D.** by invoking
28320 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
28330 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f  enter]([sqlite3_
28340 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65  db_mutex](D)) be
28350 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a  fore beginning.*
28360 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69  * to use D and i
28370 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33  nvoking [sqlite3
28380 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73  _mutex_leave]([s
28390 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d  qlite3_db_mutex]
283a0 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c  (D)) after.** al
283b0 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69  l calls to the i
283c0 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74 65 64  nterfaces listed
283d0 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65   here are comple
283e0 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e  ted..**.** If an
283f0 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73   interface fails
28400 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53   with SQLITE_MIS
28410 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20  USE, that means 
28420 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  the interface.**
28430 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63   was invoked inc
28440 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68 65 20  orrectly by the 
28450 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e  application.  In
28460 20 74 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a   that case, the.
28470 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e  ** error code an
28480 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72  d message may or
28490 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e   may not be set.
284a0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
284b0 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20  errcode(sqlite3 
284c0 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *db);.int sqlite
284d0 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f  3_extended_errco
284e0 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b  de(sqlite3 *db);
284f0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
28500 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69  ite3_errmsg(sqli
28510 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  te3*);.const voi
28520 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  d *sqlite3_errms
28530 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63  g16(sqlite3*);.c
28540 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
28550 65 33 5f 65 72 72 73 74 72 28 69 6e 74 29 3b 0a  e3_errstr(int);.
28560 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
28570 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
28580 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45  ent Object.** KE
28590 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65  YWORDS: {prepare
285a0 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72  d statement} {pr
285b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
285c0 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  s}.**.** An inst
285d0 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
285e0 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61  ect represents a
285f0 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74   single SQL stat
28600 65 6d 65 6e 74 20 74 68 61 74 0a 2a 2a 20 68 61  ement that.** ha
28610 73 20 62 65 65 6e 20 63 6f 6d 70 69 6c 65 64 20  s been compiled 
28620 69 6e 74 6f 20 62 69 6e 61 72 79 20 66 6f 72 6d  into binary form
28630 20 61 6e 64 20 69 73 20 72 65 61 64 79 20 74 6f   and is ready to
28640 20 62 65 20 65 76 61 6c 75 61 74 65 64 2e 0a 2a   be evaluated..*
28650 2a 0a 2a 2a 20 54 68 69 6e 6b 20 6f 66 20 65 61  *.** Think of ea
28660 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ch SQL statement
28670 20 61 73 20 61 20 73 65 70 61 72 61 74 65 20 63   as a separate c
28680 6f 6d 70 75 74 65 72 20 70 72 6f 67 72 61 6d 2e  omputer program.
28690 20 20 54 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61    The.** origina
286a0 6c 20 53 51 4c 20 74 65 78 74 20 69 73 20 73 6f  l SQL text is so
286b0 75 72 63 65 20 63 6f 64 65 2e 20 20 41 20 70 72  urce code.  A pr
286c0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
286d0 20 6f 62 6a 65 63 74 20 0a 2a 2a 20 69 73 20 74   object .** is t
286e0 68 65 20 63 6f 6d 70 69 6c 65 64 20 6f 62 6a 65  he compiled obje
286f0 63 74 20 63 6f 64 65 2e 20 20 41 6c 6c 20 53 51  ct code.  All SQ
28700 4c 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  L must be conver
28710 74 65 64 20 69 6e 74 6f 20 61 0a 2a 2a 20 70 72  ted into a.** pr
28720 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
28730 20 62 65 66 6f 72 65 20 69 74 20 63 61 6e 20 62   before it can b
28740 65 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  e run..**.** The
28750 20 6c 69 66 65 2d 63 79 63 6c 65 20 6f 66 20 61   life-cycle of a
28760 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
28770 65 6e 74 20 6f 62 6a 65 63 74 20 75 73 75 61 6c  ent object usual
28780 6c 79 20 67 6f 65 73 20 6c 69 6b 65 20 74 68 69  ly goes like thi
28790 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a  s:.**.** <ol>.**
287a0 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65   <li> Create the
287b0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
287c0 65 6e 74 20 6f 62 6a 65 63 74 20 75 73 69 6e 67  ent object using
287d0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
287e0 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 3c 6c 69 3e  e_v2()]..** <li>
287f0 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20   Bind values to 
28800 5b 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69  [parameters] usi
28810 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ng the sqlite3_b
28820 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20  ind_*().**      
28830 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c  interfaces..** <
28840 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20  li> Run the SQL 
28850 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
28860 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20  te3_step()] one 
28870 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a  or more times..*
28880 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65  * <li> Reset the
28890 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
288a0 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ent using [sqlit
288b0 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e  e3_reset()] then
288c0 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20   go back.**     
288d0 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20   to step 2.  Do 
288e0 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72  this zero or mor
288f0 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e  e times..** <li>
28900 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a   Destroy the obj
28910 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ect using [sqlit
28920 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a  e3_finalize()]..
28930 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 74 79 70 65  ** </ol>.*/.type
28940 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
28950 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f  e3_stmt sqlite3_
28960 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  stmt;../*.** CAP
28970 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20  I3REF: Run-time 
28980 4c 69 6d 69 74 73 0a 2a 2a 20 4d 45 54 48 4f 44  Limits.** METHOD
28990 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
289a0 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  ^(This interface
289b0 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65   allows the size
289c0 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73   of various cons
289d0 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d  tructs to be lim
289e0 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e  ited.** on a con
289f0 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65  nection by conne
28a00 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68  ction basis.  Th
28a10 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
28a20 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74  r is the.** [dat
28a30 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
28a40 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73  ] whose limit is
28a50 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75   to be set or qu
28a60 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73  eried.  The.** s
28a70 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
28a80 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c  is one of the [l
28a90 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d  imit categories]
28aa0 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a   that define a.*
28ab0 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74  * class of const
28ac0 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65  ructs to be size
28ad0 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74   limited.  The t
28ae0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69  hird parameter i
28af0 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d  s the.** new lim
28b00 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73  it for that cons
28b10 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  truct.)^.**.** ^
28b20 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74  If the new limit
28b30 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e   is a negative n
28b40 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74  umber, the limit
28b50 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a   is unchanged..*
28b60 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69 6d  * ^(For each lim
28b70 69 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c 49  it category SQLI
28b80 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45  TE_LIMIT_<i>NAME
28b90 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61 20  </i> there is a 
28ba0 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61  .** [limits | ha
28bb0 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a  rd upper bound].
28bc0 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c  ** set at compil
28bd0 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70 72  e-time by a C pr
28be0 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
28bf0 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69   called.** [limi
28c00 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f  ts | SQLITE_MAX_
28c10 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a  <i>NAME</i>]..**
28c20 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20   (The "_LIMIT_" 
28c30 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63  in the name is c
28c40 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f  hanged to "_MAX_
28c50 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70  ".))^.** ^Attemp
28c60 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61  ts to increase a
28c70 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73   limit above its
28c80 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e   hard upper boun
28c90 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c  d are.** silentl
28ca0 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74  y truncated to t
28cb0 68 65 20 68 61 72 64 20 75 70 70 65 72 20 62 6f  he hard upper bo
28cc0 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61  und..**.** ^Rega
28cd0 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
28ce0 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d  r or not the lim
28cf0 69 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c 20  it was changed, 
28d00 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  the .** [sqlite3
28d10 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72 66  _limit()] interf
28d20 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
28d30 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74  prior value of t
28d40 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65  he limit..** ^He
28d50 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68 65  nce, to find the
28d60 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f   current value o
28d70 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f 75  f a limit withou
28d80 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a  t changing it,.*
28d90 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20  * simply invoke 
28da0 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 77  this interface w
28db0 69 74 68 20 74 68 65 20 74 68 69 72 64 20 70 61  ith the third pa
28dc0 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20 2d  rameter set to -
28dd0 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d  1..**.** Run-tim
28de0 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74  e limits are int
28df0 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e  ended for use in
28e00 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   applications th
28e10 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74  at manage.** bot
28e20 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65  h their own inte
28e30 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e  rnal database an
28e40 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73  d also databases
28e50 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f   that are contro
28e60 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75  lled.** by untru
28e70 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f  sted external so
28e80 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70  urces.  An examp
28e90 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  le application m
28ea0 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62  ight be a.** web
28eb0 20 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 61   browser that ha
28ec0 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61  s its own databa
28ed0 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20  ses for storing 
28ee0 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73  history and.** s
28ef0 65 70 61 72 61 74 65 20 64 61 74 61 62 61 73 65  eparate database
28f00 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20  s controlled by 
28f10 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 6c 69  JavaScript appli
28f20 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64  cations download
28f30 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e  ed.** off the In
28f40 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74  ternet.  The int
28f50 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20  ernal databases 
28f60 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65  can be given the
28f70 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75  .** large, defau
28f80 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61  lt limits.  Data
28f90 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79  bases managed by
28fa0 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65   external source
28fb0 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65  s can.** be give
28fc0 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c  n much smaller l
28fd0 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 74  imits designed t
28fe0 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69  o prevent a deni
28ff0 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a  al of service.**
29000 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f   attack.  Develo
29010 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20  pers might also 
29020 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20  want to use the 
29030 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
29040 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e  horizer()].** in
29050 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 68  terface to furth
29060 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75  er control untru
29070 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73  sted SQL.  The s
29080 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ize of the datab
29090 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62  ase.** created b
290a0 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73  y an untrusted s
290b0 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e  cript can be con
290c0 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65  tained using the
290d0 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f  .** [max_page_co
290e0 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a  unt] [PRAGMA]..*
290f0 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d  *.** New run-tim
29100 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69  e limit categori
29110 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  es may be added 
29120 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
29130 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  es..*/.int sqlit
29140 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33  e3_limit(sqlite3
29150 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e  *, int id, int n
29160 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ewVal);../*.** C
29170 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
29180 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69  e Limit Categori
29190 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
291a0 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d  {limit category}
291b0 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72   {*limit categor
291c0 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ies}.**.** These
291d0 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e   constants defin
291e0 65 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72  e various perfor
291f0 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20  mance limits.** 
29200 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65  that can be lowe
29210 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20  red at run-time 
29220 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c  using [sqlite3_l
29230 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  imit()]..** The 
29240 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20  synopsis of the 
29250 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20  meanings of the 
29260 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69  various limits i
29270 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a  s shown below..*
29280 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  * Additional inf
29290 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69  ormation is avai
292a0 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73  lable at [limits
292b0 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c   | Limits in SQL
292c0 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  ite]..**.** <dl>
292d0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
292e0 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64  IT_LENGTH]] ^(<d
292f0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  t>SQLITE_LIMIT_L
29300 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
29310 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69  d>The maximum si
29320 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67  ze of any string
29330 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c   or BLOB or tabl
29340 65 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e  e row, in bytes.
29350 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  <dd>)^.**.** [[S
29360 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f  QLITE_LIMIT_SQL_
29370 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  LENGTH]] ^(<dt>S
29380 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f  QLITE_LIMIT_SQL_
29390 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
293a0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c  dd>The maximum l
293b0 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20  ength of an SQL 
293c0 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79  statement, in by
293d0 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  tes.</dd>)^.**.*
293e0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
293f0 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e  _COLUMN]] ^(<dt>
29400 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
29410 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  UMN</dt>.** <dd>
29420 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
29430 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
29440 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74   a table definit
29450 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a  ion or in the.**
29460 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61   result set of a
29470 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65   [SELECT] or the
29480 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
29490 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e  of columns in an
294a0 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20   index.** or in 
294b0 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47  an ORDER BY or G
294c0 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c  ROUP BY clause.<
294d0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
294e0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
294f0 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  _DEPTH]] ^(<dt>S
29500 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
29510 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  _DEPTH</dt>.** <
29520 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64  dd>The maximum d
29530 65 70 74 68 20 6f 66 20 74 68 65 20 70 61 72 73  epth of the pars
29540 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78  e tree on any ex
29550 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e  pression.</dd>)^
29560 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
29570 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53  LIMIT_COMPOUND_S
29580 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51  ELECT]] ^(<dt>SQ
29590 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f  LITE_LIMIT_COMPO
295a0 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a  UND_SELECT</dt>.
295b0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
295c0 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72  um number of ter
295d0 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64  ms in a compound
295e0 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e   SELECT statemen
295f0 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  t.</dd>)^.**.** 
29600 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  [[SQLITE_LIMIT_V
29610 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53  DBE_OP]] ^(<dt>S
29620 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
29630 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  _OP</dt>.** <dd>
29640 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
29650 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f  er of instructio
29660 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20  ns in a virtual 
29670 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a  machine program.
29680 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65  ** used to imple
29690 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74  ment an SQL stat
296a0 65 6d 65 6e 74 2e 20 20 49 66 20 5b 73 71 6c 69  ement.  If [sqli
296b0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
296c0 5d 20 6f 72 0a 2a 2a 20 74 68 65 20 65 71 75 69  ] or.** the equi
296d0 76 61 6c 65 6e 74 20 74 72 69 65 73 20 74 6f 20  valent tries to 
296e0 61 6c 6c 6f 63 61 74 65 20 73 70 61 63 65 20 66  allocate space f
296f0 6f 72 20 6d 6f 72 65 20 74 68 61 6e 20 74 68 69  or more than thi
29700 73 20 6d 61 6e 79 20 6f 70 63 6f 64 65 73 0a 2a  s many opcodes.*
29710 2a 20 69 6e 20 61 20 73 69 6e 67 6c 65 20 70 72  * in a single pr
29720 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
29730 2c 20 61 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45  , an SQLITE_NOME
29740 4d 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  M error is retur
29750 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ned.</dd>)^.**.*
29760 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
29770 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d 20  _FUNCTION_ARG]] 
29780 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
29790 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c  IT_FUNCTION_ARG<
297a0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
297b0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
297c0 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61  f arguments on a
297d0 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29   function.</dd>)
297e0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
297f0 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 5d  _LIMIT_ATTACHED]
29800 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
29810 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64  IMIT_ATTACHED</d
29820 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
29830 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
29840 5b 41 54 54 41 43 48 20 7c 20 61 74 74 61 63 68  [ATTACH | attach
29850 65 64 20 64 61 74 61 62 61 73 65 73 5d 2e 29 5e  ed databases].)^
29860 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
29870 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f  LITE_LIMIT_LIKE_
29880 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d  PATTERN_LENGTH]]
29890 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
298a0 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
298b0 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  ERN_LENGTH</dt>.
298c0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
298d0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  um length of the
298e0 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e   pattern argumen
298f0 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20  t to the [LIKE] 
29900 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65  or.** [GLOB] ope
29910 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a  rators.</dd>)^.*
29920 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
29930 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
29940 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53  BER]].** ^(<dt>S
29950 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
29960 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e  ABLE_NUMBER</dt>
29970 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
29980 6d 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65 72  mum index number
29990 20 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d 65 74   of any [paramet
299a0 65 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73 74  er] in an SQL st
299b0 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a  atement.)^.**.**
299c0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
299d0 54 52 49 47 47 45 52 5f 44 45 50 54 48 5d 5d 20  TRIGGER_DEPTH]] 
299e0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
299f0 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48  IT_TRIGGER_DEPTH
29a00 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
29a10 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f   maximum depth o
29a20 66 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72 20  f recursion for 
29a30 74 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e  triggers.</dd>)^
29a40 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
29a50 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52  LIMIT_WORKER_THR
29a60 45 41 44 53 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  EADS]] ^(<dt>SQL
29a70 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52  ITE_LIMIT_WORKER
29a80 5f 54 48 52 45 41 44 53 3c 2f 64 74 3e 0a 2a 2a  _THREADS</dt>.**
29a90 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
29aa0 20 6e 75 6d 62 65 72 20 6f 66 20 61 75 78 69 6c   number of auxil
29ab0 69 61 72 79 20 77 6f 72 6b 65 72 20 74 68 72 65  iary worker thre
29ac0 61 64 73 20 74 68 61 74 20 61 20 73 69 6e 67 6c  ads that a singl
29ad0 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
29ae0 74 61 74 65 6d 65 6e 74 5d 20 6d 61 79 20 73 74  tatement] may st
29af0 61 72 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c  art.</dd>)^.** <
29b00 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
29b10 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
29b20 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  GTH             
29b30 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65         0.#define
29b40 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51   SQLITE_LIMIT_SQ
29b50 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20  L_LENGTH        
29b60 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
29b70 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  e SQLITE_LIMIT_C
29b80 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20  OLUMN           
29b90 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69           2.#defi
29ba0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
29bb0 45 58 50 52 5f 44 45 50 54 48 20 20 20 20 20 20  EXPR_DEPTH      
29bc0 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66            3.#def
29bd0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
29be0 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54  _COMPOUND_SELECT
29bf0 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65             4.#de
29c00 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
29c10 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20  T_VDBE_OP       
29c20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64              5.#d
29c30 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
29c40 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20  IT_FUNCTION_ARG 
29c50 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23               6.#
29c60 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
29c70 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20 20 20  MIT_ATTACHED    
29c80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 37 0a                7.
29c90 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
29ca0 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52  IMIT_LIKE_PATTER
29cb0 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38  N_LENGTH       8
29cc0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
29cd0 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
29ce0 55 4d 42 45 52 20 20 20 20 20 20 20 20 20 20 20  UMBER           
29cf0 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  9.#define SQLITE
29d00 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44  _LIMIT_TRIGGER_D
29d10 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20  EPTH            
29d20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  10.#define SQLIT
29d30 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54  E_LIMIT_WORKER_T
29d40 48 52 45 41 44 53 20 20 20 20 20 20 20 20 20 20  HREADS          
29d50 20 31 31 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   11.../*.** CAPI
29d60 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20  3REF: Compiling 
29d70 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
29d80 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53  .** KEYWORDS: {S
29d90 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d  QL statement com
29da0 70 69 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44  piler}.** METHOD
29db0 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 20 43 4f 4e  : sqlite3.** CON
29dc0 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65  STRUCTOR: sqlite
29dd0 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 6f 20  3_stmt.**.** To 
29de0 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71  execute an SQL q
29df0 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69  uery, it must fi
29e00 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20  rst be compiled 
29e10 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65  into a byte-code
29e20 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e  .** program usin
29e30 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72  g one of these r
29e40 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  outines..**.** T
29e50 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
29e60 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64  t, "db", is a [d
29e70 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
29e80 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  on] obtained fro
29e90 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63  m a.** prior suc
29ea0 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
29eb0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
29ec0 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  , [sqlite3_open_
29ed0 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  v2()] or.** [sql
29ee0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20  ite3_open16()]. 
29ef0 20 54 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   The database co
29f00 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  nnection must no
29f10 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73  t have been clos
29f20 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  ed..**.** The se
29f30 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22  cond argument, "
29f40 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74  zSql", is the st
29f50 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f  atement to be co
29f60 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a  mpiled, encoded.
29f70 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 46  ** as either UTF
29f80 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54  -8 or UTF-16.  T
29f90 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
29fa0 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  re() and sqlite3
29fb0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a  _prepare_v2().**
29fc0 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 65 20   interfaces use 
29fd0 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74  UTF-8, and sqlit
29fe0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 20 61  e3_prepare16() a
29ff0 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
2a000 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65  re16_v2().** use
2a010 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e   UTF-16..**.** ^
2a020 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67  If the nByte arg
2a030 75 6d 65 6e 74 20 69 73 20 6e 65 67 61 74 69 76  ument is negativ
2a040 65 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20  e, then zSql is 
2a050 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a  read up to the.*
2a060 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72  * first zero ter
2a070 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79  minator. ^If nBy
2a080 74 65 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20  te is positive, 
2a090 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 0a 2a  then it is the.*
2a0a0 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  * number of byte
2a0b0 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c  s read from zSql
2a0c0 2e 20 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20  .  ^If nByte is 
2a0d0 7a 65 72 6f 2c 20 74 68 65 6e 20 6e 6f 20 70 72  zero, then no pr
2a0e0 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d  epared.** statem
2a0f0 65 6e 74 20 69 73 20 67 65 6e 65 72 61 74 65 64  ent is generated
2a100 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 61 6c 6c  ..** If the call
2a110 65 72 20 6b 6e 6f 77 73 20 74 68 61 74 20 74 68  er knows that th
2a120 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e  e supplied strin
2a130 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61  g is nul-termina
2a140 74 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65  ted, then.** the
2a150 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 20 70 65  re is a small pe
2a160 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74  rformance advant
2a170 61 67 65 20 74 6f 20 70 61 73 73 69 6e 67 20 61  age to passing a
2a180 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65  n nByte paramete
2a190 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 74 68 65  r that.** is the
2a1a0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2a1b0 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74   in the input st
2a1c0 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e  ring <i>includin
2a1d0 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c  g</i>.** the nul
2a1e0 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a  -terminator..**.
2a1f0 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 73  ** ^If pzTail is
2a200 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a   not NULL then *
2a210 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74  pzTail is made t
2a220 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66  o point to the f
2a230 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73  irst byte.** pas
2a240 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65  t the end of the
2a250 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65   first SQL state
2a260 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54  ment in zSql.  T
2a270 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e  hese routines on
2a280 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68  ly.** compile th
2a290 65 20 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e  e first statemen
2a2a0 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70  t in zSql, so *p
2a2b0 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f  zTail is left po
2a2c0 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61  inting to.** wha
2a2d0 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70  t remains uncomp
2a2e0 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70  iled..**.** ^*pp
2a2f0 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69  Stmt is left poi
2a300 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69  nting to a compi
2a310 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  led [prepared st
2a320 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61  atement] that ca
2a330 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64  n be.** executed
2a340 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
2a350 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 68  step()].  ^If th
2a360 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c  ere is an error,
2a370 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a   *ppStmt is set.
2a380 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66  ** to NULL.  ^If
2a390 20 74 68 65 20 69 6e 70 75 74 20 74 65 78 74 20   the input text 
2a3a0 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20  contains no SQL 
2a3b0 28 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73  (if the input is
2a3c0 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72   an empty.** str
2a3d0 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74  ing or a comment
2a3e0 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69  ) then *ppStmt i
2a3f0 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a  s set to NULL..*
2a400 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72  * The calling pr
2a410 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 70 6f  ocedure is respo
2a420 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74  nsible for delet
2a430 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64  ing the compiled
2a440 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
2a450 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
2a460 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74  _finalize()] aft
2a470 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68  er it has finish
2a480 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70  ed with it..** p
2a490 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65  pStmt may not be
2a4a0 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e   NULL..**.** ^On
2a4b0 20 73 75 63 63 65 73 73 2c 20 74 68 65 20 73 71   success, the sq
2a4c0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20  lite3_prepare() 
2a4d0 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e  family of routin
2a4e0 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  es return [SQLIT
2a4f0 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77  E_OK];.** otherw
2a500 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  ise an [error co
2a510 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
2a520 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
2a530 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20  e3_prepare_v2() 
2a540 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
2a550 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72  are16_v2() inter
2a560 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63  faces are.** rec
2a570 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c  ommended for all
2a580 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54   new programs. T
2a590 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74  he two older int
2a5a0 65 72 66 61 63 65 73 20 61 72 65 20 72 65 74 61  erfaces are reta
2a5b0 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b  ined.** for back
2a5c0 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
2a5d0 69 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 75  ity, but their u
2a5e0 73 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 65  se is discourage
2a5f0 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76  d..** ^In the "v
2a600 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74  2" interfaces, t
2a610 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
2a620 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73  ement.** that is
2a630 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b   returned (the [
2a640 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62  sqlite3_stmt] ob
2a650 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61  ject) contains a
2a660 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
2a670 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78  original SQL tex
2a680 74 2e 20 54 68 69 73 20 63 61 75 73 65 73 20 74  t. This causes t
2a690 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  he [sqlite3_step
2a6a0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f  ()] interface to
2a6b0 0a 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66 65  .** behave diffe
2a6c0 72 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20  rently in three 
2a6d0 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e  ways:.**.** <ol>
2a6e0 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20  .** <li>.** ^If 
2a6f0 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68  the database sch
2a700 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73  ema changes, ins
2a710 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e  tead of returnin
2a720 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  g [SQLITE_SCHEMA
2a730 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79  ] as it.** alway
2a740 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73  s used to do, [s
2a750 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
2a760 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ill automaticall
2a770 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20  y recompile the 
2a780 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  SQL.** statement
2a790 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20   and try to run 
2a7a0 69 74 20 61 67 61 69 6e 2e 20 41 73 20 6d 61 6e  it again. As man
2a7b0 79 20 61 73 20 5b 53 51 4c 49 54 45 5f 4d 41 58  y as [SQLITE_MAX
2a7c0 5f 53 43 48 45 4d 41 5f 52 45 54 52 59 5d 0a 2a  _SCHEMA_RETRY].*
2a7d0 2a 20 72 65 74 72 69 65 73 20 77 69 6c 6c 20 6f  * retries will o
2a7e0 63 63 75 72 20 62 65 66 6f 72 65 20 73 71 6c 69  ccur before sqli
2a7f0 74 65 33 5f 73 74 65 70 28 29 20 67 69 76 65 73  te3_step() gives
2a800 20 75 70 20 61 6e 64 20 72 65 74 75 72 6e 73 20   up and returns 
2a810 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c  an error..** </l
2a820 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a  i>.**.** <li>.**
2a830 20 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20   ^When an error 
2a840 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33  occurs, [sqlite3
2a850 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65  _step()] will re
2a860 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20  turn one of the 
2a870 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72  detailed.** [err
2a880 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78  or codes] or [ex
2a890 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64  tended error cod
2a8a0 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63  es].  ^The legac
2a8b0 79 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 74  y behavior was t
2a8c0 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  hat.** [sqlite3_
2a8d0 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e  step()] would on
2a8e0 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65  ly return a gene
2a8f0 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ric [SQLITE_ERRO
2a900 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a  R] result code.*
2a910 2a 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63  * and the applic
2a920 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65  ation would have
2a930 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e   to make a secon
2a940 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  d call to [sqlit
2a950 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69  e3_reset()].** i
2a960 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20  n order to find 
2a970 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63  the underlying c
2a980 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62  ause of the prob
2a990 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76  lem. With the "v
2a9a0 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e  2" prepare.** in
2a9b0 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e  terfaces, the un
2a9c0 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20  derlying reason 
2a9d0 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73  for the error is
2a9e0 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69   returned immedi
2a9f0 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a  ately..** </li>.
2aa00 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49  **.** <li>.** ^I
2aa10 66 20 74 68 65 20 73 70 65 63 69 66 69 63 20 76  f the specific v
2aa20 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70  alue bound to [p
2aa30 61 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20  arameter | host 
2aa40 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68  parameter] in th
2aa50 65 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75  e .** WHERE clau
2aa60 73 65 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e  se might influen
2aa70 63 65 20 74 68 65 20 63 68 6f 69 63 65 20 6f 66  ce the choice of
2aa80 20 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 20   query plan for 
2aa90 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20  a statement,.** 
2aaa0 74 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65  then the stateme
2aab0 6e 74 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d  nt will be autom
2aac0 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69  atically recompi
2aad0 6c 65 64 2c 20 61 73 20 69 66 20 74 68 65 72 65  led, as if there
2aae0 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20   had been .** a 
2aaf0 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f  schema change, o
2ab00 6e 20 74 68 65 20 66 69 72 73 74 20 20 5b 73 71  n the first  [sq
2ab10 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61  lite3_step()] ca
2ab20 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79  ll following any
2ab30 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68   change.** to th
2ab40 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
2ab50 74 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d  text | bindings]
2ab60 20 6f 66 20 74 68 61 74 20 5b 70 61 72 61 6d 65   of that [parame
2ab70 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73  ter]. .** ^The s
2ab80 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 6f 66  pecific value of
2ab90 20 57 48 45 52 45 2d 63 6c 61 75 73 65 20 5b 70   WHERE-clause [p
2aba0 61 72 61 6d 65 74 65 72 5d 20 6d 69 67 68 74 20  arameter] might 
2abb0 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a  influence the .*
2abc0 2a 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72  * choice of quer
2abd0 79 20 70 6c 61 6e 20 69 66 20 74 68 65 20 70 61  y plan if the pa
2abe0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6c  rameter is the l
2abf0 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66  eft-hand side of
2ac00 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20   a [LIKE].** or 
2ac10 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20  [GLOB] operator 
2ac20 6f 72 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  or if the parame
2ac30 74 65 72 20 69 73 20 63 6f 6d 70 61 72 65 64 20  ter is compared 
2ac40 74 6f 20 61 6e 20 69 6e 64 65 78 65 64 20 63 6f  to an indexed co
2ac50 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20  lumn.** and the 
2ac60 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53  [SQLITE_ENABLE_S
2ac70 54 41 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  TAT3] compile-ti
2ac80 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61  me option is ena
2ac90 62 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a  bled..** </li>.*
2aca0 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73  * </ol>.*/.int s
2acb0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a  qlite3_prepare(.
2acc0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
2acd0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
2ace0 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
2acf0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
2ad00 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
2ad10 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
2ad20 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  8 encoded */.  i
2ad30 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
2ad40 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
2ad50 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
2ad60 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
2ad70 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
2ad80 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
2ad90 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
2ada0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
2adb0 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
2adc0 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
2add0 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
2ade0 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e  of zSql */.);.in
2adf0 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
2ae00 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  e_v2(.  sqlite3 
2ae10 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
2ae20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
2ae30 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
2ae40 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  ar *zSql,       
2ae50 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
2ae60 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20  , UTF-8 encoded 
2ae70 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
2ae80 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
2ae90 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
2aea0 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
2aeb0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
2aec0 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
2aed0 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
2aee0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
2aef0 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20  t char **pzTail 
2af00 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
2af10 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
2af20 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
2af30 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
2af40 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c  prepare16(.  sql
2af50 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
2af60 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
2af70 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2af80 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20  st void *zSql,  
2af90 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
2afa0 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e  ement, UTF-16 en
2afb0 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
2afc0 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
2afd0 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
2afe0 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
2aff0 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
2b000 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
2b010 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
2b020 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
2b030 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70    const void **p
2b040 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
2b050 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
2b060 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
2b070 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  Sql */.);.int sq
2b080 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2b090 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  sqlite3 *d
2b0a0 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
2b0b0 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
2b0c0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
2b0d0 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
2b0e0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
2b0f0 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a  UTF-16 encoded *
2b100 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
2b110 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
2b120 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
2b130 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
2b140 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
2b150 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
2b160 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
2b170 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
2b180 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20   void **pzTail  
2b190 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
2b1a0 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
2b1b0 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
2b1c0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2b1d0 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53  EF: Retrieving S
2b1e0 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 20  tatement SQL.** 
2b1f0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
2b200 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  stmt.**.** ^The 
2b210 73 71 6c 69 74 65 33 5f 73 71 6c 28 50 29 20 69  sqlite3_sql(P) i
2b220 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2b230 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
2b240 63 6f 70 79 20 6f 66 20 74 68 65 20 55 54 46 2d  copy of the UTF-
2b250 38 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73  8.** SQL text us
2b260 65 64 20 74 6f 20 63 72 65 61 74 65 20 5b 70 72  ed to create [pr
2b270 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2b280 5d 20 50 20 69 66 20 50 20 77 61 73 0a 2a 2a 20  ] P if P was.** 
2b290 63 72 65 61 74 65 64 20 62 79 20 65 69 74 68 65  created by eithe
2b2a0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
2b2b0 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  re_v2()] or [sql
2b2c0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
2b2d0 32 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  2()]..** ^The sq
2b2e0 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73  lite3_expanded_s
2b2f0 71 6c 28 50 29 20 69 6e 74 65 72 66 61 63 65 20  ql(P) interface 
2b300 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
2b310 72 20 74 6f 20 61 20 55 54 46 2d 38 0a 2a 2a 20  r to a UTF-8.** 
2b320 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e  string containin
2b330 67 20 74 68 65 20 53 51 4c 20 74 65 78 74 20 6f  g the SQL text o
2b340 66 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  f prepared state
2b350 6d 65 6e 74 20 50 20 77 69 74 68 0a 2a 2a 20 5b  ment P with.** [
2b360 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73  bound parameters
2b370 5d 20 65 78 70 61 6e 64 65 64 2e 0a 2a 2a 0a 2a  ] expanded..**.*
2b380 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c  * ^(For example,
2b390 20 69 66 20 61 20 70 72 65 70 61 72 65 64 20 73   if a prepared s
2b3a0 74 61 74 65 6d 65 6e 74 20 69 73 20 63 72 65 61  tatement is crea
2b3b0 74 65 64 20 75 73 69 6e 67 20 74 68 65 20 53 51  ted using the SQ
2b3c0 4c 0a 2a 2a 20 74 65 78 74 20 22 53 45 4c 45 43  L.** text "SELEC
2b3d0 54 20 24 61 62 63 2c 3a 78 79 7a 22 20 61 6e 64  T $abc,:xyz" and
2b3e0 20 69 66 20 70 61 72 61 6d 65 74 65 72 20 24 61   if parameter $a
2b3f0 62 63 20 69 73 20 62 6f 75 6e 64 20 74 6f 20 69  bc is bound to i
2b400 6e 74 65 67 65 72 20 32 33 34 35 0a 2a 2a 20 61  nteger 2345.** a
2b410 6e 64 20 70 61 72 61 6d 65 74 65 72 20 3a 78 79  nd parameter :xy
2b420 7a 20 69 73 20 75 6e 62 6f 75 6e 64 2c 20 74 68  z is unbound, th
2b430 65 6e 20 73 71 6c 69 74 65 33 5f 73 71 6c 28 29  en sqlite3_sql()
2b440 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20   will return.** 
2b450 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 72  the original str
2b460 69 6e 67 2c 20 22 53 45 4c 45 43 54 20 24 61 62  ing, "SELECT $ab
2b470 63 2c 3a 78 79 7a 22 20 62 75 74 20 73 71 6c 69  c,:xyz" but sqli
2b480 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c  te3_expanded_sql
2b490 28 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72  ().** will retur
2b4a0 6e 20 22 53 45 4c 45 43 54 20 32 33 34 35 2c 4e  n "SELECT 2345,N
2b4b0 55 4c 4c 22 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  ULL".)^.**.** ^T
2b4c0 68 65 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e  he sqlite3_expan
2b4d0 64 65 64 5f 73 71 6c 28 29 20 69 6e 74 65 72 66  ded_sql() interf
2b4e0 61 63 65 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c  ace returns NULL
2b4f0 20 69 66 20 69 6e 73 75 66 66 69 63 69 65 6e 74   if insufficient
2b500 20 6d 65 6d 6f 72 79 0a 2a 2a 20 69 73 20 61 76   memory.** is av
2b510 61 69 6c 61 62 6c 65 20 74 6f 20 68 6f 6c 64 20  ailable to hold 
2b520 74 68 65 20 72 65 73 75 6c 74 2c 20 6f 72 20 69  the result, or i
2b530 66 20 74 68 65 20 72 65 73 75 6c 74 20 77 6f 75  f the result wou
2b540 6c 64 20 65 78 63 65 65 64 20 74 68 65 0a 2a 2a  ld exceed the.**
2b550 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 73 74 72   the maximum str
2b560 69 6e 67 20 6c 65 6e 67 74 68 20 64 65 74 65 72  ing length deter
2b570 6d 69 6e 65 64 20 62 79 20 74 68 65 20 5b 53 51  mined by the [SQ
2b580 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
2b590 48 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  H]..**.** ^The [
2b5a0 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 49 5a  SQLITE_TRACE_SIZ
2b5b0 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65  E_LIMIT] compile
2b5c0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 6c 69 6d  -time option lim
2b5d0 69 74 73 20 74 68 65 20 73 69 7a 65 20 6f 66 0a  its the size of.
2b5e0 2a 2a 20 62 6f 75 6e 64 20 70 61 72 61 6d 65 74  ** bound paramet
2b5f0 65 72 20 65 78 70 61 6e 73 69 6f 6e 73 2e 20 20  er expansions.  
2b600 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49  ^The [SQLITE_OMI
2b610 54 5f 54 52 41 43 45 5d 20 63 6f 6d 70 69 6c 65  T_TRACE] compile
2b620 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20  -time.** option 
2b630 63 61 75 73 65 73 20 73 71 6c 69 74 65 33 5f 65  causes sqlite3_e
2b640 78 70 61 6e 64 65 64 5f 73 71 6c 28 29 20 74 6f  xpanded_sql() to
2b650 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 4e   always return N
2b660 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ULL..**.** ^The 
2b670 73 74 72 69 6e 67 20 72 65 74 75 72 6e 65 64 20  string returned 
2b680 62 79 20 73 71 6c 69 74 65 33 5f 73 71 6c 28 50  by sqlite3_sql(P
2b690 29 20 69 73 20 6d 61 6e 61 67 65 64 20 62 79 20  ) is managed by 
2b6a0 53 51 4c 69 74 65 20 61 6e 64 20 69 73 0a 2a 2a  SQLite and is.**
2b6b0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66   automatically f
2b6c0 72 65 65 64 20 77 68 65 6e 20 74 68 65 20 70 72  reed when the pr
2b6d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2b6e0 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a   is finalized..*
2b6f0 2a 20 5e 54 68 65 20 73 74 72 69 6e 67 20 72 65  * ^The string re
2b700 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
2b710 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 50  3_expanded_sql(P
2b720 29 2c 20 6f 6e 20 74 68 65 20 6f 74 68 65 72 20  ), on the other 
2b730 68 61 6e 64 2c 0a 2a 2a 20 69 73 20 6f 62 74 61  hand,.** is obta
2b740 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
2b750 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64  e3_malloc()] and
2b760 20 6d 75 73 74 20 62 65 20 66 72 65 65 20 62 79   must be free by
2b770 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2b780 0a 2a 2a 20 62 79 20 70 61 73 73 69 6e 67 20 69  .** by passing i
2b790 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72  t to [sqlite3_fr
2b7a0 65 65 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  ee()]..*/.const 
2b7b0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71  char *sqlite3_sq
2b7c0 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  l(sqlite3_stmt *
2b7d0 70 53 74 6d 74 29 3b 0a 63 68 61 72 20 2a 73 71  pStmt);.char *sq
2b7e0 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73  lite3_expanded_s
2b7f0 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ql(sqlite3_stmt 
2b800 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
2b810 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d  CAPI3REF: Determ
2b820 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74  ine If An SQL St
2b830 61 74 65 6d 65 6e 74 20 57 72 69 74 65 73 20 54  atement Writes T
2b840 68 65 20 44 61 74 61 62 61 73 65 0a 2a 2a 20 4d  he Database.** M
2b850 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
2b860 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  tmt.**.** ^The s
2b870 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
2b880 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 66 61 63  only(X) interfac
2b890 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28  e returns true (
2b8a0 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20  non-zero) if.** 
2b8b0 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20  and only if the 
2b8c0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2b8d0 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20  ent] X makes no 
2b8e0 64 69 72 65 63 74 20 63 68 61 6e 67 65 73 20 74  direct changes t
2b8f0 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74  o.** the content
2b900 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
2b910 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74   file..**.** Not
2b920 65 20 74 68 61 74 20 5b 61 70 70 6c 69 63 61 74  e that [applicat
2b930 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
2b940 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a  functions] or.**
2b950 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73   [virtual tables
2b960 5d 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 74  ] might change t
2b970 68 65 20 64 61 74 61 62 61 73 65 20 69 6e 64 69  he database indi
2b980 72 65 63 74 6c 79 20 61 73 20 61 20 73 69 64 65  rectly as a side
2b990 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28   effect.  .** ^(
2b9a0 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20  For example, if 
2b9b0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  an application d
2b9c0 65 66 69 6e 65 73 20 61 20 66 75 6e 63 74 69 6f  efines a functio
2b9d0 6e 20 22 65 76 61 6c 28 29 22 20 74 68 61 74 20  n "eval()" that 
2b9e0 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74  .** calls [sqlit
2b9f0 65 33 5f 65 78 65 63 28 29 5d 2c 20 74 68 65 6e  e3_exec()], then
2ba00 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53   the following S
2ba10 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 6f 75  QL statement wou
2ba20 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65  ld.** change the
2ba30 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74   database file t
2ba40 68 72 6f 75 67 68 20 73 69 64 65 2d 65 66 66 65  hrough side-effe
2ba50 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  cts:.**.** <bloc
2ba60 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
2ba70 20 20 20 53 45 4c 45 43 54 20 65 76 61 6c 28 27     SELECT eval('
2ba80 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 31 27 29  DELETE FROM t1')
2ba90 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70   FROM t2;.** </p
2baa0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
2bab0 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61 75  .**.** But becau
2bac0 73 65 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20  se the [SELECT] 
2bad0 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e  statement does n
2bae0 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61  ot change the da
2baf0 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64  tabase file.** d
2bb00 69 72 65 63 74 6c 79 2c 20 73 71 6c 69 74 65 33  irectly, sqlite3
2bb10 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29  _stmt_readonly()
2bb20 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65 74   would still ret
2bb30 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a  urn true.)^.**.*
2bb40 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20 63  * ^Transaction c
2bb50 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74  ontrol statement
2bb60 73 20 73 75 63 68 20 61 73 20 5b 42 45 47 49 4e  s such as [BEGIN
2bb70 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f  ], [COMMIT], [RO
2bb80 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56  LLBACK],.** [SAV
2bb90 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45  EPOINT], and [RE
2bba0 4c 45 41 53 45 5d 20 63 61 75 73 65 20 73 71 6c  LEASE] cause sql
2bbb0 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
2bbc0 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74  ly() to return t
2bbd0 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68  rue,.** since th
2bbe0 65 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 65  e statements the
2bbf0 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61  mselves do not a
2bc00 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74  ctually modify t
2bc10 68 65 20 64 61 74 61 62 61 73 65 20 62 75 74 0a  he database but.
2bc20 2a 2a 20 72 61 74 68 65 72 20 74 68 65 79 20 63  ** rather they c
2bc30 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e  ontrol the timin
2bc40 67 20 6f 66 20 77 68 65 6e 20 6f 74 68 65 72 20  g of when other 
2bc50 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66  statements modif
2bc60 79 20 74 68 65 20 0a 2a 2a 20 64 61 74 61 62 61  y the .** databa
2bc70 73 65 2e 20 20 5e 54 68 65 20 5b 41 54 54 41 43  se.  ^The [ATTAC
2bc80 48 5d 20 61 6e 64 20 5b 44 45 54 41 43 48 5d 20  H] and [DETACH] 
2bc90 73 74 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20  statements also 
2bca0 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33  cause.** sqlite3
2bcb0 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29  _stmt_readonly()
2bcc0 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 20   to return true 
2bcd0 73 69 6e 63 65 2c 20 77 68 69 6c 65 20 74 68 6f  since, while tho
2bce0 73 65 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  se statements.**
2bcf0 20 63 68 61 6e 67 65 20 74 68 65 20 63 6f 6e 66   change the conf
2bd00 69 67 75 72 61 74 69 6f 6e 20 6f 66 20 61 20 64  iguration of a d
2bd10 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2bd20 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74 20  on, they do not 
2bd30 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73  make .** changes
2bd40 20 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74 20   to the content 
2bd50 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
2bd60 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a  files on disk..*
2bd70 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73  * ^The sqlite3_s
2bd80 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 69  tmt_readonly() i
2bd90 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2bda0 20 74 72 75 65 20 66 6f 72 20 5b 42 45 47 49 4e   true for [BEGIN
2bdb0 5d 20 73 69 6e 63 65 0a 2a 2a 20 5b 42 45 47 49  ] since.** [BEGI
2bdc0 4e 5d 20 6d 65 72 65 6c 79 20 73 65 74 73 20 69  N] merely sets i
2bdd0 6e 74 65 72 6e 61 6c 20 66 6c 61 67 73 2c 20 62  nternal flags, b
2bde0 75 74 20 74 68 65 20 5b 42 45 47 49 4e 7c 42 45  ut the [BEGIN|BE
2bdf0 47 49 4e 20 49 4d 4d 45 44 49 41 54 45 5d 20 61  GIN IMMEDIATE] a
2be00 6e 64 0a 2a 2a 20 5b 42 45 47 49 4e 7c 42 45 47  nd.** [BEGIN|BEG
2be10 49 4e 20 45 58 43 4c 55 53 49 56 45 5d 20 63 6f  IN EXCLUSIVE] co
2be20 6d 6d 61 6e 64 73 20 64 6f 20 74 6f 75 63 68 20  mmands do touch 
2be30 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64  the database and
2be40 20 73 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73   so.** sqlite3_s
2be50 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 72  tmt_readonly() r
2be60 65 74 75 72 6e 73 20 66 61 6c 73 65 20 66 6f 72  eturns false for
2be70 20 74 68 6f 73 65 20 63 6f 6d 6d 61 6e 64 73 2e   those commands.
2be80 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2be90 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71  stmt_readonly(sq
2bea0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
2beb0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2bec0 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49  REF: Determine I
2bed0 66 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  f A Prepared Sta
2bee0 74 65 6d 65 6e 74 20 48 61 73 20 42 65 65 6e 20  tement Has Been 
2bef0 52 65 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  Reset.** METHOD:
2bf00 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2bf10 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2bf20 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 20 69 6e  _stmt_busy(S) in
2bf30 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2bf40 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20  true (non-zero) 
2bf50 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  if the.** [prepa
2bf60 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
2bf70 20 68 61 73 20 62 65 65 6e 20 73 74 65 70 70 65   has been steppe
2bf80 64 20 61 74 20 6c 65 61 73 74 20 6f 6e 63 65 20  d at least once 
2bf90 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74  using .** [sqlit
2bfa0 65 33 5f 73 74 65 70 28 53 29 5d 20 62 75 74 20  e3_step(S)] but 
2bfb0 68 61 73 20 6e 65 69 74 68 65 72 20 72 75 6e 20  has neither run 
2bfc0 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 28 72  to completion (r
2bfd0 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49  eturned.** [SQLI
2bfe0 54 45 5f 44 4f 4e 45 5d 20 66 72 6f 6d 20 5b 73  TE_DONE] from [s
2bff0 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 29  qlite3_step(S)])
2c000 20 6e 6f 72 0a 2a 2a 20 62 65 65 6e 20 72 65 73   nor.** been res
2c010 65 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  et using [sqlite
2c020 33 5f 72 65 73 65 74 28 53 29 5d 2e 20 20 5e 54  3_reset(S)].  ^T
2c030 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  he sqlite3_stmt_
2c040 62 75 73 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72  busy(S).** inter
2c050 66 61 63 65 20 72 65 74 75 72 6e 73 20 66 61 6c  face returns fal
2c060 73 65 20 69 66 20 53 20 69 73 20 61 20 4e 55 4c  se if S is a NUL
2c070 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 53  L pointer.  If S
2c080 20 69 73 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55   is not a .** NU
2c090 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 69  LL pointer and i
2c0a0 73 20 6e 6f 74 20 61 20 70 6f 69 6e 74 65 72 20  s not a pointer 
2c0b0 74 6f 20 61 20 76 61 6c 69 64 20 5b 70 72 65 70  to a valid [prep
2c0c0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
2c0d0 2a 2a 20 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20  ** object, then 
2c0e0 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
2c0f0 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72  undefined and pr
2c100 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62  obably undesirab
2c110 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  le..**.** This i
2c120 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20  nterface can be 
2c130 75 73 65 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74  used in combinat
2c140 69 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78  ion [sqlite3_nex
2c150 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20  t_stmt()].** to 
2c160 6c 6f 63 61 74 65 20 61 6c 6c 20 70 72 65 70 61  locate all prepa
2c170 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 20 61  red statements a
2c180 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61  ssociated with a
2c190 20 64 61 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f   database .** co
2c1a0 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 61 72  nnection that ar
2c1b0 65 20 69 6e 20 6e 65 65 64 20 6f 66 20 62 65 69  e in need of bei
2c1c0 6e 67 20 72 65 73 65 74 2e 20 20 54 68 69 73 20  ng reset.  This 
2c1d0 63 61 6e 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20  can be used,.** 
2c1e0 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20  for example, in 
2c1f0 64 69 61 67 6e 6f 73 74 69 63 20 72 6f 75 74 69  diagnostic routi
2c200 6e 65 73 20 74 6f 20 73 65 61 72 63 68 20 66 6f  nes to search fo
2c210 72 20 70 72 65 70 61 72 65 64 20 0a 2a 2a 20 73  r prepared .** s
2c220 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 61  tatements that a
2c230 72 65 20 68 6f 6c 64 69 6e 67 20 61 20 74 72 61  re holding a tra
2c240 6e 73 61 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a  nsaction open..*
2c250 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74  /.int sqlite3_st
2c260 6d 74 5f 62 75 73 79 28 73 71 6c 69 74 65 33 5f  mt_busy(sqlite3_
2c270 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
2c280 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63  API3REF: Dynamic
2c290 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65  ally Typed Value
2c2a0 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f   Object.** KEYWO
2c2b0 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20  RDS: {protected 
2c2c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b  sqlite3_value} {
2c2d0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2c2e0 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a  te3_value}.**.**
2c2f0 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65   SQLite uses the
2c300 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2c310 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73 65  bject to represe
2c320 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a  nt all values.**
2c330 20 74 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f   that can be sto
2c340 72 65 64 20 69 6e 20 61 20 64 61 74 61 62 61 73  red in a databas
2c350 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20  e table. SQLite 
2c360 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70  uses dynamic typ
2c370 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76  ing.** for the v
2c380 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e  alues it stores.
2c390 20 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 65 64    ^Values stored
2c3a0 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75   in sqlite3_valu
2c3b0 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e  e objects.** can
2c3c0 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c   be integers, fl
2c3d0 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
2c3e0 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c  ues, strings, BL
2c3f0 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a  OBs, or NULL..**
2c400 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76  .** An sqlite3_v
2c410 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20  alue object may 
2c420 62 65 20 65 69 74 68 65 72 20 22 70 72 6f 74 65  be either "prote
2c430 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74  cted" or "unprot
2c440 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20  ected"..** Some 
2c450 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69  interfaces requi
2c460 72 65 20 61 20 70 72 6f 74 65 63 74 65 64 20 73  re a protected s
2c470 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f  qlite3_value.  O
2c480 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a  ther interfaces.
2c490 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65  ** will accept e
2c4a0 69 74 68 65 72 20 61 20 70 72 6f 74 65 63 74 65  ither a protecte
2c4b0 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63  d or an unprotec
2c4c0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2c4d0 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65  e..** Every inte
2c4e0 72 66 61 63 65 20 74 68 61 74 20 61 63 63 65 70  rface that accep
2c4f0 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ts sqlite3_value
2c500 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69   arguments speci
2c510 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20  fies.** whether 
2c520 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72  or not it requir
2c530 65 73 20 61 20 70 72 6f 74 65 63 74 65 64 20 73  es a protected s
2c540 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 54  qlite3_value.  T
2c550 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  he.** [sqlite3_v
2c560 61 6c 75 65 5f 64 75 70 28 29 5d 20 69 6e 74 65  alue_dup()] inte
2c570 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65  rface can be use
2c580 64 20 74 6f 20 63 6f 6e 73 74 72 75 63 74 20 61  d to construct a
2c590 20 6e 65 77 20 0a 2a 2a 20 70 72 6f 74 65 63 74   new .** protect
2c5a0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2c5b0 20 66 72 6f 6d 20 61 6e 20 75 6e 70 72 6f 74 65   from an unprote
2c5c0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2c5d0 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65  ue..**.** The te
2c5e0 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22 20  rms "protected" 
2c5f0 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64  and "unprotected
2c600 22 20 72 65 66 65 72 20 74 6f 20 77 68 65 74 68  " refer to wheth
2c610 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d  er or not.** a m
2c620 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41  utex is held.  A
2c630 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78  n internal mutex
2c640 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70   is held for a p
2c650 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
2c660 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2c670 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73   but no mutex is
2c680 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70   held for an unp
2c690 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
2c6a0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2c6b0 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20  .  If SQLite is 
2c6c0 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73  compiled to be s
2c6d0 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a  ingle-threaded.*
2c6e0 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  * (with [SQLITE_
2c6f0 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e  THREADSAFE=0] an
2c700 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f  d with [sqlite3_
2c710 74 68 72 65 61 64 73 61 66 65 28 29 5d 20 72 65  threadsafe()] re
2c720 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72  turning 0).** or
2c730 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 72 75   if SQLite is ru
2c740 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75  n in one of redu
2c750 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20  ced mutex modes 
2c760 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
2c770 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d  IG_SINGLETHREAD]
2c780 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   or [SQLITE_CONF
2c790 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a  IG_MULTITHREAD].
2c7a0 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69 73  ** then there is
2c7b0 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20   no distinction 
2c7c0 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65  between protecte
2c7d0 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65  d and unprotecte
2c7e0 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
2c7f0 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74  ue objects and t
2c800 68 65 79 20 63 61 6e 20 62 65 20 75 73 65 64 20  hey can be used 
2c810 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e  interchangeably.
2c820 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f    However,.** fo
2c830 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70  r maximum code p
2c840 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20 69 73  ortability it is
2c850 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61   recommended tha
2c860 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  t applications.*
2c870 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65  * still make the
2c880 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74   distinction bet
2c890 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61  ween protected a
2c8a0 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a  nd unprotected.*
2c8b0 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
2c8c0 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65  objects even whe
2c8d0 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72  n not strictly r
2c8e0 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  equired..**.** ^
2c8f0 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
2c900 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61  e objects that a
2c910 72 65 20 70 61 73 73 65 64 20 61 73 20 70 61 72  re passed as par
2c920 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65  ameters into the
2c930 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
2c940 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69  on of [applicati
2c950 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
2c960 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72  unctions] are pr
2c970 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65  otected..** ^The
2c980 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2c990 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
2c9a0 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  y.** [sqlite3_co
2c9b0 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73  lumn_value()] is
2c9c0 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a   unprotected..**
2c9d0 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   Unprotected sql
2c9e0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2c9f0 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75  ts may only be u
2ca00 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c  sed with.** [sql
2ca10 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
2ca20 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
2ca30 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e  3_bind_value()].
2ca40 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
2ca50 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71  _value_blob | sq
2ca60 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65  lite3_value_type
2ca70 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a  ()] family of.**
2ca80 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75   interfaces requ
2ca90 69 72 65 20 70 72 6f 74 65 63 74 65 64 20 73 71  ire protected sq
2caa0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2cab0 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  cts..*/.typedef 
2cac0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
2cad0 61 6c 75 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  alue sqlite3_val
2cae0 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ue;../*.** CAPI3
2caf0 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f  REF: SQL Functio
2cb00 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74  n Context Object
2cb10 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65  .**.** The conte
2cb20 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53  xt in which an S
2cb30 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63  QL function exec
2cb40 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 69  utes is stored i
2cb50 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  n an.** sqlite3_
2cb60 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20  context object. 
2cb70 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61   ^A pointer to a
2cb80 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  n sqlite3_contex
2cb90 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61  t object.** is a
2cba0 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 72 61  lways first para
2cbb0 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63  meter to [applic
2cbc0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
2cbd0 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a  L functions]..**
2cbe0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
2cbf0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
2cc00 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
2cc10 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74  tion will pass t
2cc20 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  his.** pointer t
2cc30 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c  hrough into call
2cc40 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  s to [sqlite3_re
2cc50 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74  sult_int | sqlit
2cc60 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a  e3_result()],.**
2cc70 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   [sqlite3_aggreg
2cc80 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20  ate_context()], 
2cc90 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  [sqlite3_user_da
2cca0 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  ta()],.** [sqlit
2ccb0 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
2ccc0 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65  ndle()], [sqlite
2ccd0 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d  3_get_auxdata()]
2cce0 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c  ,.** and/or [sql
2ccf0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
2cd00 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ()]..*/.typedef 
2cd10 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63  struct sqlite3_c
2cd20 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63  ontext sqlite3_c
2cd30 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ontext;../*.** C
2cd40 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67  API3REF: Binding
2cd50 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61   Values To Prepa
2cd60 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a  red Statements.*
2cd70 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73  * KEYWORDS: {hos
2cd80 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f  t parameter} {ho
2cd90 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b  st parameters} {
2cda0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e  host parameter n
2cdb0 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ame}.** KEYWORDS
2cdc0 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  : {SQL parameter
2cdd0 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  } {SQL parameter
2cde0 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69  s} {parameter bi
2cdf0 6e 64 69 6e 67 7d 0a 2a 2a 20 4d 45 54 48 4f 44  nding}.** METHOD
2ce00 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2ce10 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 51  *.** ^(In the SQ
2ce20 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  L statement text
2ce30 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
2ce40 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2ce50 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74   and its variant
2ce60 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d  s,.** literals m
2ce70 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 62  ay be replaced b
2ce80 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20  y a [parameter] 
2ce90 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65  that matches one
2cea0 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a   of following.**
2ceb0 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a   templates:.**.*
2cec0 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
2ced0 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a  ?.** <li>  ?NNN.
2cee0 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a  ** <li>  :VVV.**
2cef0 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c   <li>  @VVV.** <
2cf00 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75  li>  $VVV.** </u
2cf10 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20  l>.**.** In the 
2cf20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c  templates above,
2cf30 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20   NNN represents 
2cf40 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72  an integer liter
2cf50 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72  al,.** and VVV r
2cf60 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70  epresents an alp
2cf70 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69  hanumeric identi
2cf80 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61  fier.)^  ^The va
2cf90 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a  lues of these.**
2cfa0 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73   parameters (als
2cfb0 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70  o called "host p
2cfc0 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20  arameter names" 
2cfd0 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65  or "SQL paramete
2cfe0 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73  rs").** can be s
2cff0 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  et using the sql
2d000 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
2d010 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68  utines defined h
2d020 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ere..**.** ^The 
2d030 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
2d040 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  o the sqlite3_bi
2d050 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
2d060 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70  is always.** a p
2d070 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
2d080 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a  qlite3_stmt] obj
2d090 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f  ect returned fro
2d0a0 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  m.** [sqlite3_pr
2d0b0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69  epare_v2()] or i
2d0c0 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a  ts variants..**.
2d0d0 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  ** ^The second a
2d0e0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69  rgument is the i
2d0f0 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20  ndex of the SQL 
2d100 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20  parameter to be 
2d110 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66  set..** ^The lef
2d120 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65  tmost SQL parame
2d130 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78  ter has an index
2d140 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68   of 1.  ^When th
2d150 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20  e same named.** 
2d160 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73  SQL parameter is
2d170 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20   used more than 
2d180 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64  once, second and
2d190 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f   subsequent.** o
2d1a0 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20  ccurrences have 
2d1b0 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61  the same index a
2d1c0 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75  s the first occu
2d1d0 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20  rrence..** ^The 
2d1e0 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20  index for named 
2d1f0 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62  parameters can b
2d200 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e  e looked up usin
2d210 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
2d220 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2d230 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66  _index()] API if
2d240 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20   desired.  ^The 
2d250 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e  index.** for "?N
2d260 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69  NN" parameters i
2d270 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e  s the value of N
2d280 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20  NN..** ^The NNN 
2d290 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65  value must be be
2d2a0 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20  tween 1 and the 
2d2b0 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
2d2c0 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b  ].** parameter [
2d2d0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
2d2e0 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64  IABLE_NUMBER] (d
2d2f0 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39  efault value: 99
2d300 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74  9)..**.** ^The t
2d310 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
2d320 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69   the value to bi
2d330 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65  nd to the parame
2d340 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ter..** ^If the 
2d350 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
2d360 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
2d370 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65  text() or sqlite
2d380 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a  3_bind_text16().
2d390 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  ** or sqlite3_bi
2d3a0 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 61 20 4e  nd_blob() is a N
2d3b0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
2d3c0 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
2d3d0 6d 65 74 65 72 0a 2a 2a 20 69 73 20 69 67 6e 6f  meter.** is igno
2d3e0 72 65 64 20 61 6e 64 20 74 68 65 20 65 6e 64 20  red and the end 
2d3f0 72 65 73 75 6c 74 20 69 73 20 74 68 65 20 73 61  result is the sa
2d400 6d 65 20 61 73 20 73 71 6c 69 74 65 33 5f 62 69  me as sqlite3_bi
2d410 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a  nd_null()..**.**
2d420 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f 75 74   ^(In those rout
2d430 69 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 61  ines that have a
2d440 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
2d450 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 74  , its value is t
2d460 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
2d470 62 79 74 65 73 20 69 6e 20 74 68 65 20 70 61 72  bytes in the par
2d480 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63  ameter.  To be c
2d490 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20  lear: the value 
2d4a0 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
2d4b0 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e   of <u>bytes</u>
2d4c0 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e   in the value, n
2d4d0 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ot the number of
2d4e0 20 63 68 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a   characters.)^.*
2d4f0 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68  * ^If the fourth
2d500 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
2d510 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
2d520 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  ) or sqlite3_bin
2d530 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 69 73  d_text16().** is
2d540 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
2d550 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  the length of th
2d560 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74  e string is.** t
2d570 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
2d580 65 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 72  es up to the fir
2d590 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  st zero terminat
2d5a0 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f  or..** If the fo
2d5b0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
2d5c0 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  o sqlite3_bind_b
2d5d0 6c 6f 62 28 29 20 69 73 20 6e 65 67 61 74 69 76  lob() is negativ
2d5e0 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 62  e, then.** the b
2d5f0 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
2d600 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f  ined..** If a no
2d610 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f 75 72 74  n-negative fourt
2d620 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70  h parameter is p
2d630 72 6f 76 69 64 65 64 20 74 6f 20 73 71 6c 69 74  rovided to sqlit
2d640 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a  e3_bind_text().*
2d650 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  * or sqlite3_bin
2d660 64 5f 74 65 78 74 31 36 28 29 20 6f 72 20 73 71  d_text16() or sq
2d670 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36  lite3_bind_text6
2d680 34 28 29 20 74 68 65 6e 0a 2a 2a 20 74 68 61 74  4() then.** that
2d690 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20   parameter must 
2d6a0 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73  be the byte offs
2d6b0 65 74 0a 2a 2a 20 77 68 65 72 65 20 74 68 65 20  et.** where the 
2d6c0 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77  NUL terminator w
2d6d0 6f 75 6c 64 20 6f 63 63 75 72 20 61 73 73 75 6d  ould occur assum
2d6e0 69 6e 67 20 74 68 65 20 73 74 72 69 6e 67 20 77  ing the string w
2d6f0 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69  ere NUL.** termi
2d700 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e  nated.  If any N
2d710 55 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63  UL characters oc
2d720 63 75 72 20 61 74 20 62 79 74 65 20 6f 66 66 73  cur at byte offs
2d730 65 74 73 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a  ets less than .*
2d740 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  * the value of t
2d750 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
2d760 74 65 72 20 74 68 65 6e 20 74 68 65 20 72 65 73  ter then the res
2d770 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 76 61  ulting string va
2d780 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74  lue will.** cont
2d790 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c  ain embedded NUL
2d7a0 73 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 6f  s.  The result o
2d7b0 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69 6e  f expressions in
2d7c0 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67 73 0a  volving strings.
2d7d0 2a 2a 20 77 69 74 68 20 65 6d 62 65 64 64 65 64  ** with embedded
2d7e0 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e   NULs is undefin
2d7f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ed..**.** ^The f
2d800 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  ifth argument to
2d810 20 74 68 65 20 42 4c 4f 42 20 61 6e 64 20 73 74   the BLOB and st
2d820 72 69 6e 67 20 62 69 6e 64 69 6e 67 20 69 6e 74  ring binding int
2d830 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 61 20  erfaces.** is a 
2d840 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20  destructor used 
2d850 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68  to dispose of th
2d860 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72  e BLOB or.** str
2d870 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65  ing after SQLite
2d880 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
2d890 74 68 20 69 74 2e 20 20 5e 54 68 65 20 64 65 73  th it.  ^The des
2d8a0 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65  tructor is calle
2d8b0 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 20  d.** to dispose 
2d8c0 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73  of the BLOB or s
2d8d0 74 72 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68  tring even if th
2d8e0 65 20 63 61 6c 6c 20 74 6f 20 62 69 6e 64 20 41  e call to bind A
2d8f0 50 49 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 49 66  PI fails..** ^If
2d900 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d   the fifth argum
2d910 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70  ent is.** the sp
2d920 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c  ecial value [SQL
2d930 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65  ITE_STATIC], the
2d940 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73  n SQLite assumes
2d950 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66   that the.** inf
2d960 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73  ormation is in s
2d970 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64  tatic, unmanaged
2d980 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20   space and does 
2d990 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66  not need to be f
2d9a0 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  reed..** ^If the
2d9b0 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
2d9c0 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53  has the value [S
2d9d0 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d  QLITE_TRANSIENT]
2d9e0 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65  , then.** SQLite
2d9f0 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70   makes its own p
2da00 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
2da10 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74  he data immediat
2da20 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74  ely, before.** t
2da30 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
2da40 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  *() routine retu
2da50 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rns..**.** ^The 
2da60 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74  sixth argument t
2da70 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
2da80 65 78 74 36 34 28 29 20 6d 75 73 74 20 62 65 20  ext64() must be 
2da90 6f 6e 65 20 6f 66 0a 2a 2a 20 5b 53 51 4c 49 54  one of.** [SQLIT
2daa0 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45  E_UTF8], [SQLITE
2dab0 5f 55 54 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45  _UTF16], [SQLITE
2dac0 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53  _UTF16BE], or [S
2dad0 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 0a 2a  QLITE_UTF16LE].*
2dae0 2a 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65  * to specify the
2daf0 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 74 68 65   encoding of the
2db00 20 74 65 78 74 20 69 6e 20 74 68 65 20 74 68 69   text in the thi
2db10 72 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49  rd parameter.  I
2db20 66 0a 2a 2a 20 74 68 65 20 73 69 78 74 68 20 61  f.** the sixth a
2db30 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
2db40 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29  e3_bind_text64()
2db50 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74   is not one of t
2db60 68 65 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 76 61  he.** allowed va
2db70 6c 75 65 73 20 73 68 6f 77 6e 20 61 62 6f 76 65  lues shown above
2db80 2c 20 6f 72 20 69 66 20 74 68 65 20 74 65 78 74  , or if the text
2db90 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66   encoding is dif
2dba0 66 65 72 65 6e 74 0a 2a 2a 20 66 72 6f 6d 20 74  ferent.** from t
2dbb0 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63  he encoding spec
2dbc0 69 66 69 65 64 20 62 79 20 74 68 65 20 73 69 78  ified by the six
2dbd0 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68  th parameter, th
2dbe0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a  en the behavior.
2dbf0 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  ** is undefined.
2dc00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2dc10 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f  te3_bind_zeroblo
2dc20 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64  b() routine bind
2dc30 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67  s a BLOB of leng
2dc40 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20  th N that.** is 
2dc50 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f  filled with zero
2dc60 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62  es.  ^A zeroblob
2dc70 20 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d   uses a fixed am
2dc80 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a  ount of memory.*
2dc90 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67  * (just an integ
2dca0 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73  er to hold its s
2dcb0 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73  ize) while it is
2dcc0 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64   being processed
2dcd0 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61  ..** Zeroblobs a
2dce0 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73  re intended to s
2dcf0 65 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c  erve as placehol
2dd00 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77  ders for BLOBs w
2dd10 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20  hose.** content 
2dd20 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e  is later written
2dd30 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
2dd40 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69  e3_blob_open | i
2dd50 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20  ncremental BLOB 
2dd60 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  I/O] routines..*
2dd70 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61  * ^A negative va
2dd80 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f  lue for the zero
2dd90 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20  blob results in 
2dda0 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c  a zero-length BL
2ddb0 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  OB..**.** ^If an
2ddc0 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  y of the sqlite3
2ddd0 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
2dde0 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69  es are called wi
2ddf0 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
2de00 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72  r.** for the [pr
2de10 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2de20 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72 65 70  ] or with a prep
2de30 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66  ared statement f
2de40 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c  or which.** [sql
2de50 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
2de60 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72   been called mor
2de70 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20  e recently than 
2de80 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2de90 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63  ],.** then the c
2dea0 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  all will return 
2deb0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
2dec0 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33    If any sqlite3
2ded0 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74  _bind_().** rout
2dee0 69 6e 65 20 69 73 20 70 61 73 73 65 64 20 61 20  ine is passed a 
2def0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2df00 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62 65  ent] that has be
2df10 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68  en finalized, th
2df20 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75  e.** result is u
2df30 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f  ndefined and pro
2df40 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a  bably harmful..*
2df50 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61  *.** ^Bindings a
2df60 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62  re not cleared b
2df70 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  y the [sqlite3_r
2df80 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e  eset()] routine.
2df90 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72  .** ^Unbound par
2dfa0 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 65  ameters are inte
2dfb0 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e  rpreted as NULL.
2dfc0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2dfd0 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69  te3_bind_* routi
2dfe0 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  nes return [SQLI
2dff0 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
2e000 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f  s or an.** [erro
2e010 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68  r code] if anyth
2e020 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a  ing goes wrong..
2e030 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f 42  ** ^[SQLITE_TOOB
2e040 49 47 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74  IG] might be ret
2e050 75 72 6e 65 64 20 69 66 20 74 68 65 20 73 69 7a  urned if the siz
2e060 65 20 6f 66 20 61 20 73 74 72 69 6e 67 20 6f 72  e of a string or
2e070 20 42 4c 4f 42 0a 2a 2a 20 65 78 63 65 65 64 73   BLOB.** exceeds
2e080 20 6c 69 6d 69 74 73 20 69 6d 70 6f 73 65 64 20   limits imposed 
2e090 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  by [sqlite3_limi
2e0a0 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  t]([SQLITE_LIMIT
2e0b0 5f 4c 45 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a 20  _LENGTH]) or.** 
2e0c0 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47  [SQLITE_MAX_LENG
2e0d0 54 48 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  TH]..** ^[SQLITE
2e0e0 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72  _RANGE] is retur
2e0f0 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61 6d  ned if the param
2e100 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73  eter.** index is
2e110 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20   out of range.  
2e120 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20  ^[SQLITE_NOMEM] 
2e130 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d  is returned if m
2e140 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a  alloc() fails..*
2e150 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
2e160 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2e170 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
2e180 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
2e190 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
2e1a0 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
2e1b0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2e1c0 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e  _index()]..*/.in
2e1d0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  t sqlite3_bind_b
2e1e0 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
2e1f0 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f  *, int, const vo
2e200 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64  id*, int n, void
2e210 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
2e220 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
2e230 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  ob64(sqlite3_stm
2e240 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76  t*, int, const v
2e250 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69  oid*, sqlite3_ui
2e260 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20  nt64,.          
2e270 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f                vo
2e280 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
2e290 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2e2a0 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73  double(sqlite3_s
2e2b0 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c  tmt*, int, doubl
2e2c0 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  e);.int sqlite3_
2e2d0 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33  bind_int(sqlite3
2e2e0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74  _stmt*, int, int
2e2f0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
2e300 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  ind_int64(sqlite
2e310 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71  3_stmt*, int, sq
2e320 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e  lite3_int64);.in
2e330 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e  t sqlite3_bind_n
2e340 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ull(sqlite3_stmt
2e350 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c  *, int);.int sql
2e360 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73  ite3_bind_text(s
2e370 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2e380 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 69 6e 74  ,const char*,int
2e390 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29  ,void(*)(void*))
2e3a0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
2e3b0 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  nd_text16(sqlite
2e3c0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
2e3d0 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20  nst void*, int, 
2e3e0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
2e3f0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
2e400 64 5f 74 65 78 74 36 34 28 73 71 6c 69 74 65 33  d_text64(sqlite3
2e410 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
2e420 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65  st char*, sqlite
2e430 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20  3_uint64,.      
2e440 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2e450 20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a     void(*)(void*
2e460 29 2c 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72  ), unsigned char
2e470 20 65 6e 63 6f 64 69 6e 67 29 3b 0a 69 6e 74 20   encoding);.int 
2e480 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c  sqlite3_bind_val
2e490 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ue(sqlite3_stmt*
2e4a0 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c  , int, const sql
2e4b0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
2e4c0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a  t sqlite3_bind_z
2e4d0 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  eroblob(sqlite3_
2e4e0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20  stmt*, int, int 
2e4f0 6e 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  n);.int sqlite3_
2e500 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 36 34 28  bind_zeroblob64(
2e510 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2e520 6e 74 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74  nt, sqlite3_uint
2e530 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  64);../*.** CAPI
2e540 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20  3REF: Number Of 
2e550 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73 0a 2a  SQL Parameters.*
2e560 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2e570 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  3_stmt.**.** ^Th
2e580 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62  is routine can b
2e590 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74  e used to find t
2e5a0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51  he number of [SQ
2e5b0 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a  L parameters].**
2e5c0 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   in a [prepared 
2e5d0 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c  statement].  SQL
2e5e0 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
2e5f0 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a  tokens of the.**
2e600 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e   form "?", "?NNN
2e610 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41  ", ":AAA", "$AAA
2e620 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68 61  ", or "@AAA" tha
2e630 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c  t serve as.** pl
2e640 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76  aceholders for v
2e650 61 6c 75 65 73 20 74 68 61 74 20 61 72 65 20 5b  alues that are [
2e660 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2e670 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f  b | bound].** to
2e680 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 20   the parameters 
2e690 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e  at a later time.
2e6a0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f  .**.** ^(This ro
2e6b0 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72  utine actually r
2e6c0 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78  eturns the index
2e6d0 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20   of the largest 
2e6e0 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70  (rightmost).** p
2e6f0 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c  arameter. For al
2e700 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f  l forms except ?
2e710 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63  NNN, this will c
2e720 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65  orrespond to the
2e730 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e  .** number of un
2e740 69 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e  ique parameters.
2e750 20 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20    If parameters 
2e760 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d  of the ?NNN form
2e770 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68   are used,.** th
2e780 65 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20  ere may be gaps 
2e790 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a  in the list.)^.*
2e7a0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
2e7b0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2e7c0 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
2e7d0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
2e7e0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
2e7f0 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  me()], and.** [s
2e800 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2e810 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
2e820 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
2e830 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
2e840 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
2e850 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
2e860 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48  REF: Name Of A H
2e870 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a  ost Parameter.**
2e880 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2e890 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _stmt.**.** ^The
2e8a0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
2e8b0 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e  rameter_name(P,N
2e8c0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2e8d0 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20  rns.** the name 
2e8e0 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c  of the N-th [SQL
2e8f0 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74   parameter] in t
2e900 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2e910 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28  tement] P..** ^(
2e920 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f  SQL parameters o
2e930 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e  f the form "?NNN
2e940 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22  " or ":AAA" or "
2e950 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a  @AAA" or "$AAA".
2e960 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77  ** have a name w
2e970 68 69 63 68 20 69 73 20 74 68 65 20 73 74 72 69  hich is the stri
2e980 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41  ng "?NNN" or ":A
2e990 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72  AA" or "@AAA" or
2e9a0 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65   "$AAA".** respe
2e9b0 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f  ctively..** In o
2e9c0 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
2e9d0 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22  initial ":" or "
2e9e0 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22  $" or "@" or "?"
2e9f0 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20  .** is included 
2ea00 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e  as part of the n
2ea10 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d  ame.)^.** ^Param
2ea20 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72  eters of the for
2ea30 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20  m "?" without a 
2ea40 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65  following intege
2ea50 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a  r have no name.*
2ea60 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65 72 72  * and are referr
2ea70 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65  ed to as "namele
2ea80 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75  ss" or "anonymou
2ea90 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a  s parameters"..*
2eaa0 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
2eab0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 68  host parameter h
2eac0 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31  as an index of 1
2ead0 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e  , not 0..**.** ^
2eae0 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69  If the value N i
2eaf0 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f  s out of range o
2eb00 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61  r if the N-th pa
2eb10 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61  rameter is.** na
2eb20 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c  meless, then NUL
2eb30 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  L is returned.  
2eb40 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
2eb50 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79  ring is.** alway
2eb60 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64  s in UTF-8 encod
2eb70 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20  ing even if the 
2eb80 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20  named parameter 
2eb90 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c  was.** originall
2eba0 79 20 73 70 65 63 69 66 69 65 64 20 61 73 20 55  y specified as U
2ebb0 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65  TF-16 in [sqlite
2ebc0 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f  3_prepare16()] o
2ebd0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  r.** [sqlite3_pr
2ebe0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a  epare16_v2()]..*
2ebf0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
2ec00 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2ec10 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
2ec20 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
2ec30 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
2ec40 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  unt()], and.** [
2ec50 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2ec60 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
2ec70 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
2ec80 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2ec90 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69  ameter_name(sqli
2eca0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b  te3_stmt*, int);
2ecb0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2ecc0 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72  : Index Of A Par
2ecd0 61 6d 65 74 65 72 20 57 69 74 68 20 41 20 47 69  ameter With A Gi
2ece0 76 65 6e 20 4e 61 6d 65 0a 2a 2a 20 4d 45 54 48  ven Name.** METH
2ecf0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2ed00 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74  .**.** ^Return t
2ed10 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53  he index of an S
2ed20 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 76  QL parameter giv
2ed30 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54  en its name.  ^T
2ed40 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75  he.** index valu
2ed50 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 75  e returned is su
2ed60 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61  itable for use a
2ed70 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20  s the second.** 
2ed80 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
2ed90 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
2eda0 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e  sqlite3_bind()].
2edb0 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20    ^A zero.** is 
2edc0 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d  returned if no m
2edd0 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65  atching paramete
2ede0 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68  r is found.  ^Th
2edf0 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e  e parameter.** n
2ee00 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 65  ame must be give
2ee10 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20  n in UTF-8 even 
2ee20 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  if the original 
2ee30 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73  statement.** was
2ee40 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55   prepared from U
2ee50 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67  TF-16 text using
2ee60 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2ee70 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  e16_v2()]..**.**
2ee80 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
2ee90 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
2eea0 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
2eeb0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2eec0 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
2eed0 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
2eee0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2eef0 65 72 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2f 0a 69  er_name()]..*/.i
2ef00 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2ef10 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
2ef20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63  sqlite3_stmt*, c
2ef30 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
2ef40 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2ef50 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69  EF: Reset All Bi
2ef60 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70  ndings On A Prep
2ef70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a  ared Statement.*
2ef80 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2ef90 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f  3_stmt.**.** ^Co
2efa0 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e  ntrary to the in
2efb0 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c  tuition of many,
2efc0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2efd0 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65  )] does not rese
2efe0 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  t.** the [sqlite
2eff0 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69  3_bind_blob | bi
2f000 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72  ndings] on a [pr
2f010 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2f020 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73 20  ]..** ^Use this 
2f030 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74  routine to reset
2f040 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65   all host parame
2f050 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f  ters to NULL..*/
2f060 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65  .int sqlite3_cle
2f070 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69  ar_bindings(sqli
2f080 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
2f090 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
2f0a0 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49  ber Of Columns I
2f0b0 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a  n A Result Set.*
2f0c0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2f0d0 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65  3_stmt.**.** ^Re
2f0e0 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20  turn the number 
2f0f0 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
2f100 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 74  e result set ret
2f110 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  urned by the.** 
2f120 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2f130 65 6e 74 5d 2e 20 5e 49 66 20 74 68 69 73 20 72  ent]. ^If this r
2f140 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30  outine returns 0
2f150 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65  , that means the
2f160 20 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73   .** [prepared s
2f170 74 61 74 65 6d 65 6e 74 5d 20 72 65 74 75 72 6e  tatement] return
2f180 73 20 6e 6f 20 64 61 74 61 20 28 66 6f 72 20 65  s no data (for e
2f190 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54  xample an [UPDAT
2f1a0 45 5d 29 2e 0a 2a 2a 20 5e 48 6f 77 65 76 65 72  E])..** ^However
2f1b0 2c 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 74  , just because t
2f1c0 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
2f1d0 72 6e 73 20 61 20 70 6f 73 69 74 69 76 65 20 6e  rns a positive n
2f1e0 75 6d 62 65 72 20 64 6f 65 73 20 6e 6f 74 0a 2a  umber does not.*
2f1f0 2a 20 6d 65 61 6e 20 74 68 61 74 20 6f 6e 65 20  * mean that one 
2f200 6f 72 20 6d 6f 72 65 20 72 6f 77 73 20 6f 66 20  or more rows of 
2f210 64 61 74 61 20 77 69 6c 6c 20 62 65 20 72 65 74  data will be ret
2f220 75 72 6e 65 64 2e 20 20 5e 41 20 53 45 4c 45 43  urned.  ^A SELEC
2f230 54 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77  T statement.** w
2f240 69 6c 6c 20 61 6c 77 61 79 73 20 68 61 76 65 20  ill always have 
2f250 61 20 70 6f 73 69 74 69 76 65 20 73 71 6c 69 74  a positive sqlit
2f260 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
2f270 29 20 62 75 74 20 64 65 70 65 6e 64 69 6e 67 20  ) but depending 
2f280 6f 6e 20 74 68 65 0a 2a 2a 20 57 48 45 52 45 20  on the.** WHERE 
2f290 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e  clause constrain
2f2a0 74 73 20 61 6e 64 20 74 68 65 20 74 61 62 6c 65  ts and the table
2f2b0 20 63 6f 6e 74 65 6e 74 2c 20 69 74 20 6d 69 67   content, it mig
2f2c0 68 74 20 72 65 74 75 72 6e 20 6e 6f 20 72 6f 77  ht return no row
2f2d0 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  s..**.** See als
2f2e0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61  o: [sqlite3_data
2f2f0 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74  _count()].*/.int
2f300 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2f310 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
2f320 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
2f330 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c  ** CAPI3REF: Col
2f340 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52  umn Names In A R
2f350 65 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 54  esult Set.** MET
2f360 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
2f370 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  t.**.** ^These r
2f380 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
2f390 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64  he name assigned
2f3a0 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72   to a particular
2f3b0 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68   column.** in th
2f3c0 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  e result set of 
2f3d0 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  a [SELECT] state
2f3e0 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c 69  ment.  ^The sqli
2f3f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
2f400 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72  ).** interface r
2f410 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
2f420 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   to a zero-termi
2f430 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
2f440 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65  ng.** and sqlite
2f450 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
2f460 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  ) returns a poin
2f470 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65  ter to a zero-te
2f480 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d  rminated.** UTF-
2f490 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65  16 string.  ^The
2f4a0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
2f4b0 20 69 73 20 74 68 65 20 5b 70 72 65 70 61 72 65   is the [prepare
2f4c0 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
2f4d0 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20  that implements 
2f4e0 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  the [SELECT] sta
2f4f0 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 63  tement. ^The sec
2f500 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
2f510 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e   the.** column n
2f520 75 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 66  umber.  ^The lef
2f530 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20  tmost column is 
2f540 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20  number 0..**.** 
2f550 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
2f560 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20  ring pointer is 
2f570 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68  valid until eith
2f580 65 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  er the [prepared
2f590 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69   statement].** i
2f5a0 73 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b  s destroyed by [
2f5b0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2f5c0 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  ()] or until the
2f5d0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75   statement is au
2f5e0 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72  tomatically.** r
2f5f0 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65  eprepared by the
2f600 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b   first call to [
2f610 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2f620 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
2f630 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c   run.** or until
2f640 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74   the next call t
2f650 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  o.** sqlite3_col
2f660 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71  umn_name() or sq
2f670 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
2f680 65 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d  e16() on the sam
2f690 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20  e column..**.** 
2f6a0 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ^If sqlite3_mall
2f6b0 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e  oc() fails durin
2f6c0 67 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67  g the processing
2f6d0 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74 69   of either routi
2f6e0 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70  ne.** (for examp
2f6f0 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76  le during a conv
2f700 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d  ersion from UTF-
2f710 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65  8 to UTF-16) the
2f720 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e  n a.** NULL poin
2f730 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ter is returned.
2f740 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65  .**.** ^The name
2f750 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c   of a result col
2f760 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65  umn is the value
2f770 20 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c 61   of the "AS" cla
2f780 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20  use for.** that 
2f790 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65  column, if there
2f7a0 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65   is an AS clause
2f7b0 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e  .  If there is n
2f7c0 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74  o AS clause.** t
2f7d0 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  hen the name of 
2f7e0 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e  the column is un
2f7f0 73 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61  specified and ma
2f800 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a  y change from.**
2f810 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20   one release of 
2f820 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65  SQLite to the ne
2f830 78 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  xt..*/.const cha
2f840 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
2f850 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  n_name(sqlite3_s
2f860 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f  tmt*, int N);.co
2f870 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2f880 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
2f890 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2f8a0 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt N);../*.** CA
2f8b0 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f  PI3REF: Source O
2f8c0 66 20 44 61 74 61 20 49 6e 20 41 20 51 75 65 72  f Data In A Quer
2f8d0 79 20 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48  y Result.** METH
2f8e0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2f8f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
2f900 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61  utines provide a
2f910 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d   means to determ
2f920 69 6e 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ine the database
2f930 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20  , table, and.** 
2f940 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61  table column tha
2f950 74 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20  t is the origin 
2f960 6f 66 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  of a particular 
2f970 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e  result column in
2f980 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  .** [SELECT] sta
2f990 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20  tement..** ^The 
2f9a0 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
2f9b0 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72  base or table or
2f9c0 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72   column can be r
2f9d0 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69  eturned as.** ei
2f9e0 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20  ther a UTF-8 or 
2f9f0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20  UTF-16 string.  
2fa00 5e 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20  ^The _database_ 
2fa10 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a  routines return.
2fa20 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
2fa30 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65  name, the _table
2fa40 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  _ routines retur
2fa50 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65  n the table name
2fa60 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69  , and.** the ori
2fa70 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  gin_ routines re
2fa80 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20  turn the column 
2fa90 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65  name..** ^The re
2faa0 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
2fab0 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65   valid until the
2fac0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2fad0 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79  ment] is destroy
2fae0 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c  ed.** using [sql
2faf0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2fb00 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74   or until the st
2fb10 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d  atement is autom
2fb20 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72  atically.** repr
2fb30 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69  epared by the fi
2fb40 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  rst call to [sql
2fb50 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72  ite3_step()] for
2fb60 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75   a particular ru
2fb70 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68  n.** or until th
2fb80 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69  e same informati
2fb90 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 0a  on is requested.
2fba0 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69  ** again in a di
2fbb0 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67  fferent encoding
2fbc0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d  ..**.** ^The nam
2fbd0 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20  es returned are 
2fbe0 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d  the original un-
2fbf0 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66  aliased names of
2fc00 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
2fc10 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c  , table, and col
2fc20 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  umn..**.** ^The 
2fc30 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
2fc40 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  o these interfac
2fc50 65 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 65  es is a [prepare
2fc60 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
2fc70 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e   ^These function
2fc80 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61  s return informa
2fc90 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e  tion about the N
2fca0 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  th result column
2fcb0 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
2fcc0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77  the statement, w
2fcd0 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65  here N is the se
2fce0 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72  cond function ar
2fcf0 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20  gument..** ^The 
2fd00 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e  left-most column
2fd10 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72   is column 0 for
2fd20 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
2fd30 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e  .**.** ^If the N
2fd40 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e  th column return
2fd50 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d  ed by the statem
2fd60 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73  ent is an expres
2fd70 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75  sion or.** subqu
2fd80 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ery and is not a
2fd90 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74   column value, t
2fda0 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65  hen all of these
2fdb0 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
2fdc0 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65  n.** NULL.  ^The
2fdd0 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74  se routine might
2fde0 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c   also return NUL
2fdf0 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  L if a memory al
2fe00 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a  location error.*
2fe10 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65  * occurs.  ^Othe
2fe20 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 75  rwise, they retu
2fe30 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  rn the name of t
2fe40 68 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61  he attached data
2fe50 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20  base, table,.** 
2fe60 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71  or column that q
2fe70 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75  uery result colu
2fe80 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 64  mn was extracted
2fe90 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73   from..**.** ^As
2fea0 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20   with all other 
2feb0 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f  SQLite APIs, tho
2fec0 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65  se whose names e
2fed0 6e 64 20 77 69 74 68 20 22 31 36 22 20 72 65 74  nd with "16" ret
2fee0 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e  urn.** UTF-16 en
2fef0 63 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e  coded strings an
2ff00 64 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63  d the other func
2ff10 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46  tions return UTF
2ff20 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  -8..**.** ^These
2ff30 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61   APIs are only a
2ff40 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20  vailable if the 
2ff50 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70  library was comp
2ff60 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  iled with the.**
2ff70 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
2ff80 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d  COLUMN_METADATA]
2ff90 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C-preprocessor 
2ffa0 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66  symbol..**.** If
2ffb0 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72   two or more thr
2ffc0 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72  eads call one or
2ffd0 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72   more of these r
2ffe0 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20  outines against 
2fff0 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70  the same.** prep
30000 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61  ared statement a
30010 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65  nd column at the
30020 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20   same time then 
30030 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a  the results are.
30040 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  ** undefined..**
30050 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f  .** If two or mo
30060 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20  re threads call 
30070 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b  one or more.** [
30080 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
30090 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63  atabase_name | c
300a0 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69  olumn metadata i
300b0 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f  nterfaces].** fo
300c0 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70  r the same [prep
300d0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
300e0 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  and result colum
300f0 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65  n.** at the same
30100 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72   time then the r
30110 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
30120 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  ined..*/.const c
30130 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
30140 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
30150 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
30160 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
30170 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
30180 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36  _database_name16
30190 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
301a0 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  nt);.const char 
301b0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
301c0 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74  table_name(sqlit
301d0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
301e0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
301f0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f  e3_column_table_
30200 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
30210 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
30220 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
30230 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d  olumn_origin_nam
30240 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
30250 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
30260 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
30270 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73  _origin_name16(s
30280 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
30290 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
302a0 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74  EF: Declared Dat
302b0 61 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 79  atype Of A Query
302c0 20 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f   Result.** METHO
302d0 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
302e0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72 73  **.** ^(The firs
302f0 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  t parameter is a
30300 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
30310 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69  ment]..** If thi
30320 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  s statement is a
30330 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
30340 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20  ent and the Nth 
30350 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a  column of the.**
30360 20 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74   returned result
30370 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45   set of that [SE
30380 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65  LECT] is a table
30390 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a   column (not an.
303a0 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  ** expression or
303b0 20 73 75 62 71 75 65 72 79 29 20 74 68 65 6e 20   subquery) then 
303c0 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70  the declared typ
303d0 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a  e of the table.*
303e0 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75  * column is retu
303f0 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74 68 65  rned.)^  ^If the
30400 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74   Nth column of t
30410 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 69 73  he result set is
30420 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f   an.** expressio
30430 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74  n or subquery, t
30440 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  hen a NULL point
30450 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  er is returned..
30460 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  ** ^The returned
30470 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79   string is alway
30480 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e  s UTF-8 encoded.
30490 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61  .**.** ^(For exa
304a0 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20  mple, given the 
304b0 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a  database schema:
304c0 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41  .**.** CREATE TA
304d0 42 4c 45 20 74 31 28 63 31 20 56 41 52 49 41 4e  BLE t1(c1 VARIAN
304e0 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68  T);.**.** and th
304f0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74  e following stat
30500 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70  ement to be comp
30510 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45  iled:.**.** SELE
30520 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52  CT c1 + 1, c1 FR
30530 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69  OM t1;.**.** thi
30540 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20  s routine would 
30550 72 65 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e  return the strin
30560 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20  g "VARIANT" for 
30570 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c  the second resul
30580 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d  t.** column (i==
30590 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70  1), and a NULL p
305a0 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66  ointer for the f
305b0 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75  irst result colu
305c0 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a  mn (i==0).)^.**.
305d0 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20  ** ^SQLite uses 
305e0 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65  dynamic run-time
305f0 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75   typing.  ^So ju
30600 73 74 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c  st because a col
30610 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72  umn.** is declar
30620 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20  ed to contain a 
30630 70 61 72 74 69 63 75 6c 61 72 20 74 79 70 65 20  particular type 
30640 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68  does not mean th
30650 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73  at the.** data s
30660 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f  tored in that co
30670 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64  lumn is of the d
30680 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53  eclared type.  S
30690 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f  QLite is.** stro
306a0 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20  ngly typed, but 
306b0 74 68 65 20 74 79 70 69 6e 67 20 69 73 20 64 79  the typing is dy
306c0 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63  namic not static
306d0 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61  .  ^Type.** is a
306e0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 69  ssociated with i
306f0 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73  ndividual values
30700 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63  , not with the c
30710 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65  ontainers.** use
30720 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20  d to hold those 
30730 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74  values..*/.const
30740 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
30750 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73  olumn_decltype(s
30760 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
30770 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
30780 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
30790 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33  cltype16(sqlite3
307a0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a  _stmt*,int);../*
307b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76  .** CAPI3REF: Ev
307c0 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74  aluate An SQL St
307d0 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f  atement.** METHO
307e0 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
307f0 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70  **.** After a [p
30800 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
30810 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 70  t] has been prep
30820 61 72 65 64 20 75 73 69 6e 67 20 65 69 74 68 65  ared using eithe
30830 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  r.** [sqlite3_pr
30840 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
30850 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
30860 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f  6_v2()] or one o
30870 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20  f the legacy.** 
30880 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69  interfaces [sqli
30890 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
308a0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
308b0 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75  re16()], this fu
308c0 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62  nction.** must b
308d0 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20  e called one or 
308e0 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76  more times to ev
308f0 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 65  aluate the state
30900 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ment..**.** The 
30910 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62  details of the b
30920 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73  ehavior of the s
30930 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e  qlite3_step() in
30940 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a  terface depend.*
30950 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65  * on whether the
30960 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70   statement was p
30970 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68  repared using th
30980 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74  e newer "v2" int
30990 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74  erface.** [sqlit
309a0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
309b0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
309c0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72  epare16_v2()] or
309d0 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63   the older legac
309e0 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b  y.** interface [
309f0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
30a00 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
30a10 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54  prepare16()].  T
30a20 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a  he use of the.**
30a30 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72 66   new "v2" interf
30a40 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ace is recommend
30a50 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69  ed for new appli
30a60 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20  cations but the 
30a70 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
30a80 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75  ace will continu
30a90 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  e to be supporte
30aa0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65  d..**.** ^In the
30ab0 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
30ac0 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  e, the return va
30ad0 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68  lue will be eith
30ae0 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  er [SQLITE_BUSY]
30af0 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ,.** [SQLITE_DON
30b00 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  E], [SQLITE_ROW]
30b10 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  , [SQLITE_ERROR]
30b20 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53  , or [SQLITE_MIS
30b30 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74  USE]..** ^With t
30b40 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
30b50 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74  e, any of the ot
30b60 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  her [result code
30b70 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64  s] or.** [extend
30b80 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
30b90 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e   might be return
30ba0 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a  ed as well..**.*
30bb0 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  * ^[SQLITE_BUSY]
30bc0 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
30bd0 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20  database engine 
30be0 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63  was unable to ac
30bf0 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74  quire the.** dat
30c00 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e  abase locks it n
30c10 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a  eeds to do its j
30c20 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61  ob.  ^If the sta
30c30 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d  tement is a [COM
30c40 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72  MIT].** or occur
30c50 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20  s outside of an 
30c60 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
30c70 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63  tion, then you c
30c80 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20  an retry the.** 
30c90 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74  statement.  If t
30ca0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
30cb0 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61  not a [COMMIT] a
30cc0 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e  nd occurs within
30cd0 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20   an.** explicit 
30ce0 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e  transaction then
30cf0 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c   you should roll
30d00 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63  back the transac
30d10 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63  tion before.** c
30d20 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ontinuing..**.**
30d30 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20   ^[SQLITE_DONE] 
30d40 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73  means that the s
30d50 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e  tatement has fin
30d60 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a  ished executing.
30d70 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e  ** successfully.
30d80 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29    sqlite3_step()
30d90 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63   should not be c
30da0 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74  alled again on t
30db0 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d  his virtual.** m
30dc0 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66  achine without f
30dd0 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71  irst calling [sq
30de0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74  lite3_reset()] t
30df0 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74  o reset the virt
30e00 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62  ual.** machine b
30e10 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69  ack to its initi
30e20 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20  al state..**.** 
30e30 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74  ^If the SQL stat
30e40 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63  ement being exec
30e50 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79  uted returns any
30e60 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c   data, then [SQL
30e70 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72  ITE_ROW].** is r
30e80 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d  eturned each tim
30e90 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64  e a new row of d
30ea0 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f 72  ata is ready for
30eb0 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74   processing by t
30ec0 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68  he.** caller. Th
30ed0 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20  e values may be 
30ee0 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 74  accessed using t
30ef0 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73  he [column acces
30f00 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a  s functions]..**
30f10 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
30f20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  is called again 
30f30 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20  to retrieve the 
30f40 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61  next row of data
30f50 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ..**.** ^[SQLITE
30f60 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68  _ERROR] means th
30f70 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72  at a run-time er
30f80 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63  ror (such as a c
30f90 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f  onstraint.** vio
30fa0 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75  lation) has occu
30fb0 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73  rred.  sqlite3_s
30fc0 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74  tep() should not
30fd0 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   be called again
30fe0 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d   on.** the VM. M
30ff0 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ore information 
31000 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20  may be found by 
31010 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
31020 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e  _errmsg()]..** ^
31030 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20  With the legacy 
31040 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72  interface, a mor
31050 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
31060 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70   code (for examp
31070 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  le,.** [SQLITE_I
31080 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49  NTERRUPT], [SQLI
31090 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c  TE_SCHEMA], [SQL
310a0 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e  ITE_CORRUPT], an
310b0 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63  d so forth).** c
310c0 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62  an be obtained b
310d0 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
310e0 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74  e3_reset()] on t
310f0 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
31100 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e  statement].  ^In
31110 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
31120 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65  ace,.** the more
31130 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20   specific error 
31140 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64  code is returned
31150 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c   directly by sql
31160 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a  ite3_step()..**.
31170 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  ** [SQLITE_MISUS
31180 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  E] means that th
31190 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  e this routine w
311a0 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72  as called inappr
311b0 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65  opriately..** Pe
311c0 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c  rhaps it was cal
311d0 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72  led on a [prepar
311e0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
311f0 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64  at has.** alread
31200 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f  y been [sqlite3_
31210 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c  finalize | final
31220 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20  ized] or on one 
31230 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76  that had.** prev
31240 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20  iously returned 
31250 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f  [SQLITE_ERROR] o
31260 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e  r [SQLITE_DONE].
31270 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a    Or it could.**
31280 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61   be the case tha
31290 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  t the same datab
312a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
312b0 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20  s being used by 
312c0 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74  two or.** more t
312d0 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61  hreads at the sa
312e0 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d  me moment in tim
312f0 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c  e..**.** For all
31300 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
31310 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e  ite up to and in
31320 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31  cluding 3.6.23.1
31330 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  , a call to.** [
31340 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
31350 20 77 61 73 20 72 65 71 75 69 72 65 64 20 61 66   was required af
31360 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70  ter sqlite3_step
31370 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74  () returned anyt
31380 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68  hing.** other th
31390 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  an [SQLITE_ROW] 
313a0 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65  before any subse
313b0 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e  quent invocation
313c0 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73   of.** sqlite3_s
313d0 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20  tep().  Failure 
313e0 74 6f 20 72 65 73 65 74 20 74 68 65 20 70 72 65  to reset the pre
313f0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
31400 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74  using .** [sqlit
31410 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 6c  e3_reset()] woul
31420 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b  d result in an [
31430 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72  SQLITE_MISUSE] r
31440 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71  eturn from.** sq
31450 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42  lite3_step().  B
31460 75 74 20 61 66 74 65 72 20 5b 76 65 72 73 69 6f  ut after [versio
31470 6e 20 33 2e 36 2e 32 33 2e 31 5d 20 28 5b 64 61  n 3.6.23.1] ([da
31480 74 65 6f 66 3a 33 2e 36 2e 32 33 2e 31 5d 2c 0a  teof:3.6.23.1],.
31490 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
314a0 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69  ) began.** calli
314b0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
314c0 74 28 29 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c  t()] automatical
314d0 6c 79 20 69 6e 20 74 68 69 73 20 63 69 72 63 75  ly in this circu
314e0 6d 73 74 61 6e 63 65 20 72 61 74 68 65 72 0a 2a  mstance rather.*
314f0 2a 20 74 68 61 6e 20 72 65 74 75 72 6e 69 6e 67  * than returning
31500 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
31510 2e 20 20 54 68 69 73 20 69 73 20 6e 6f 74 20 63  .  This is not c
31520 6f 6e 73 69 64 65 72 65 64 20 61 20 63 6f 6d 70  onsidered a comp
31530 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65  atibility.** bre
31540 61 6b 20 62 65 63 61 75 73 65 20 61 6e 79 20 61  ak because any a
31550 70 70 6c 69 63 61 74 69 6f 6e 20 74 68 61 74 20  pplication that 
31560 65 76 65 72 20 72 65 63 65 69 76 65 73 20 61 6e  ever receives an
31570 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 65   SQLITE_MISUSE e
31580 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65  rror.** is broke
31590 6e 20 62 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e  n by definition.
315a0 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d    The [SQLITE_OM
315b0 49 54 5f 41 55 54 4f 52 45 53 45 54 5d 20 63 6f  IT_AUTORESET] co
315c0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
315d0 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64  n.** can be used
315e0 20 74 6f 20 72 65 73 74 6f 72 65 20 74 68 65 20   to restore the 
315f0 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 2e  legacy behavior.
31600 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20  .**.** <b>Goofy 
31610 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a  Interface Alert:
31620 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61  </b> In the lega
31630 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  cy interface, th
31640 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  e sqlite3_step()
31650 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72  .** API always r
31660 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63  eturns a generic
31670 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51   error code, [SQ
31680 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c  LITE_ERROR], fol
31690 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72  lowing any.** er
316a0 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  ror other than [
316b0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64  SQLITE_BUSY] and
316c0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
316d0 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c  .  You must call
316e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
316f0 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  et()] or [sqlite
31700 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e  3_finalize()] in
31710 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f   order to find o
31720 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65  ne of the.** spe
31730 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64  cific [error cod
31740 65 73 5d 20 74 68 61 74 20 62 65 74 74 65 72 20  es] that better 
31750 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72  describes the er
31760 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74  ror..** We admit
31770 20 74 68 61 74 20 74 68 69 73 20 69 73 20 61 20   that this is a 
31780 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54  goofy design.  T
31790 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62  he problem has b
317a0 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74  een fixed.** wit
317b0 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  h the "v2" inter
317c0 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72  face.  If you pr
317d0 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75  epare all of you
317e0 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  r SQL statements
317f0 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72  .** using either
31800 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
31810 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  e_v2()] or [sqli
31820 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
31830 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f  ()] instead.** o
31840 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71  f the legacy [sq
31850 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
31860 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
31870 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72  epare16()] inter
31880 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74  faces,.** then t
31890 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63  he more specific
318a0 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61   [error codes] a
318b0 72 65 20 72 65 74 75 72 6e 65 64 20 64 69 72 65  re returned dire
318c0 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74  ctly.** by sqlit
318d0 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20  e3_step().  The 
318e0 75 73 65 20 6f 66 20 74 68 65 20 22 76 32 22 20  use of the "v2" 
318f0 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63  interface is rec
31900 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74  ommended..*/.int
31910 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71   sqlite3_step(sq
31920 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
31930 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
31940 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
31950 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74   in a result set
31960 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
31970 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
31980 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
31990 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72 66  _count(P) interf
319a0 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
319b0 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
319c0 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72  s in the.** curr
319d0 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72  ent row of the r
319e0 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72  esult set of [pr
319f0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
31a00 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70  ] P..** ^If prep
31a10 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50  ared statement P
31a20 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 72   does not have r
31a30 65 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f 20  esults ready to 
31a40 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63  return.** (via c
31a50 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71 6c  alls to the [sql
31a60 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20  ite3_column_int 
31a70 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  | sqlite3_column
31a80 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65  _*()] of.** inte
31a90 72 66 61 63 65 73 29 20 74 68 65 6e 20 73 71 6c  rfaces) then sql
31aa0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
31ab0 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a  P) returns 0..**
31ac0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
31ad0 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74  ta_count(P) rout
31ae0 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e 73  ine also returns
31af0 20 30 20 69 66 20 50 20 69 73 20 61 20 4e 55 4c   0 if P is a NUL
31b00 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54  L pointer..** ^T
31b10 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  he sqlite3_data_
31b20 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65  count(P) routine
31b30 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 74 68   returns 0 if th
31b40 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  e previous call 
31b50 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  to.** [sqlite3_s
31b60 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64  tep](P) returned
31b70 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20   [SQLITE_DONE]. 
31b80 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
31b90 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77  ta_count(P).** w
31ba0 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a  ill return non-z
31bb0 65 72 6f 20 69 66 20 70 72 65 76 69 6f 75 73 20  ero if previous 
31bc0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
31bd0 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e  _step](P) return
31be0 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f  ed.** [SQLITE_RO
31bf0 57 5d 2c 20 65 78 63 65 70 74 20 69 6e 20 74 68  W], except in th
31c00 65 20 63 61 73 65 20 6f 66 20 74 68 65 20 5b 50  e case of the [P
31c10 52 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61  RAGMA incrementa
31c20 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65  l_vacuum].** whe
31c30 72 65 20 69 74 20 61 6c 77 61 79 73 20 72 65 74  re it always ret
31c40 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65 20  urns zero since 
31c50 65 61 63 68 20 73 74 65 70 20 6f 66 20 74 68 61  each step of tha
31c60 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20  t multi-step.** 
31c70 70 72 61 67 6d 61 20 72 65 74 75 72 6e 73 20 30  pragma returns 0
31c80 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61   columns of data
31c90 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
31ca0 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  : [sqlite3_colum
31cb0 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e  n_count()].*/.in
31cc0 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  t sqlite3_data_c
31cd0 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  ount(sqlite3_stm
31ce0 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
31cf0 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64  * CAPI3REF: Fund
31d00 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65  amental Datatype
31d10 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53  s.** KEYWORDS: S
31d20 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a  QLITE_TEXT.**.**
31d30 20 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20 69   ^(Every value i
31d40 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65  n SQLite has one
31d50 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65   of five fundame
31d60 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a  ntal datatypes:.
31d70 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
31d80 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  i> 64-bit signed
31d90 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e   integer.** <li>
31da0 20 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f   64-bit IEEE flo
31db0 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62  ating point numb
31dc0 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e  er.** <li> strin
31dd0 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a  g.** <li> BLOB.*
31de0 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c  * <li> NULL.** <
31df0 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  /ul>)^.**.** The
31e00 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  se constants are
31e10 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20   codes for each 
31e20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a  of those types..
31e30 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
31e40 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20  the SQLITE_TEXT 
31e50 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73  constant was als
31e60 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65  o used in SQLite
31e70 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f   version 2.** fo
31e80 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64  r a completely d
31e90 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67  ifferent meaning
31ea0 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74  .  Software that
31eb0 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62   links against b
31ec0 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65  oth.** SQLite ve
31ed0 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69  rsion 2 and SQLi
31ee0 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f  te version 3 sho
31ef0 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f  uld use SQLITE3_
31f00 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c  TEXT, not.** SQL
31f10 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65  ITE_TEXT..*/.#de
31f20 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
31f30 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53  GER  1.#define S
31f40 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32  QLITE_FLOAT    2
31f50 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
31f60 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69  BLOB     4.#defi
31f70 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20  ne SQLITE_NULL  
31f80 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49     5.#ifdef SQLI
31f90 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20  TE_TEXT.# undef 
31fa0 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73  SQLITE_TEXT.#els
31fb0 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  e.# define SQLIT
31fc0 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e  E_TEXT     3.#en
31fd0 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  dif.#define SQLI
31fe0 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a  TE3_TEXT     3..
31ff0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
32000 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72  Result Values Fr
32010 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45  om A Query.** KE
32020 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20  YWORDS: {column 
32030 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73  access functions
32040 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  }.** METHOD: sql
32050 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
32060 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
32070 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69  return informati
32080 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c  on about a singl
32090 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  e column of the 
320a0 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c  current.** resul
320b0 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79  t row of a query
320c0 2e 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61 73  .  ^In every cas
320d0 65 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  e the first argu
320e0 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
320f0 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65  r.** to the [pre
32100 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
32110 20 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 65   that is being e
32120 76 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73  valuated (the [s
32130 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a  qlite3_stmt*].**
32140 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e   that was return
32150 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
32160 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
32170 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72  r one of its var
32180 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68  iants).** and th
32190 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
321a0 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f  t is the index o
321b0 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72  f the column for
321c0 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69   which informati
321d0 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20  on.** should be 
321e0 72 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c  returned. ^The l
321f0 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f  eftmost column o
32200 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
32210 20 68 61 73 20 74 68 65 20 69 6e 64 65 78 20 30   has the index 0
32220 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72  ..** ^The number
32230 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
32240 68 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62 65  he result can be
32250 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e   determined usin
32260 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  g.** [sqlite3_co
32270 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a  lumn_count()]..*
32280 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20  *.** If the SQL 
32290 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e  statement does n
322a0 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69  ot currently poi
322b0 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f  nt to a valid ro
322c0 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20  w, or if the.** 
322d0 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20  column index is 
322e0 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68  out of range, th
322f0 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65  e result is unde
32300 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20  fined..** These 
32310 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c  routines may onl
32320 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e  y be called when
32330 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
32340 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
32350 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
32360 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
32370 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68  E_ROW] and neith
32380 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  er.** [sqlite3_r
32390 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c  eset()] nor [sql
323a0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
323b0 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65   have been calle
323c0 64 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a  d subsequently..
323d0 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65  ** If any of the
323e0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
323f0 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71  called after [sq
32400 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
32410 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  r.** [sqlite3_fi
32420 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74  nalize()] or aft
32430 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  er [sqlite3_step
32440 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64  ()] has returned
32450 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74  .** something ot
32460 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
32470 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c  _ROW], the resul
32480 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
32490 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33  ..** If [sqlite3
324a0 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c  _step()] or [sql
324b0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
324c0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
324d0 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c  ze()].** are cal
324e0 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65  led from a diffe
324f0 72 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c  rent thread whil
32500 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72  e any of these r
32510 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70  outines.** are p
32520 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65  ending, then the
32530 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
32540 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
32550 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
32560 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65  n_type() routine
32570 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20   returns the.** 
32580 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20  [SQLITE_INTEGER 
32590 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d  | datatype code]
325a0 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c   for the initial
325b0 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66   data type.** of
325c0 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75   the result colu
325d0 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e  mn.  ^The return
325e0 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20  ed value is one 
325f0 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  of [SQLITE_INTEG
32600 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ER],.** [SQLITE_
32610 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  FLOAT], [SQLITE_
32620 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42  TEXT], [SQLITE_B
32630 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  LOB], or [SQLITE
32640 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c  _NULL].  The val
32650 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  ue.** returned b
32660 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
32670 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20  _type() is only 
32680 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f  meaningful if no
32690 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73   type.** convers
326a0 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72  ions have occurr
326b0 65 64 20 61 73 20 64 65 73 63 72 69 62 65 64 20  ed as described 
326c0 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20  below.  After a 
326d0 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c  type conversion,
326e0 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65  .** the value re
326f0 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
32700 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
32710 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46  is undefined.  F
32720 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e  uture.** version
32730 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20  s of SQLite may 
32740 63 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 76  change the behav
32750 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63  ior of sqlite3_c
32760 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20  olumn_type().** 
32770 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65  following a type
32780 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a   conversion..**.
32790 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
327a0 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55  t is a BLOB or U
327b0 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e  TF-8 string then
327c0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   the sqlite3_col
327d0 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72  umn_bytes().** r
327e0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
327f0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
32800 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20  es in that BLOB 
32810 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  or string..** ^I
32820 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
32830 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c  a UTF-16 string,
32840 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
32850 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e  lumn_bytes() con
32860 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72  verts.** the str
32870 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64  ing to UTF-8 and
32880 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68   then returns th
32890 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
328a0 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  s..** ^If the re
328b0 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69  sult is a numeri
328c0 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c  c value then sql
328d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
328e0 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c  s() uses.** [sql
328f0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
32900 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74   to convert that
32910 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d   value to a UTF-
32920 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74  8 string and ret
32930 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  urns.** the numb
32940 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
32950 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e  hat string..** ^
32960 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
32970 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69   NULL, then sqli
32980 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
32990 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e  () returns zero.
329a0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  .**.** ^If the r
329b0 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20  esult is a BLOB 
329c0 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  or UTF-16 string
329d0 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
329e0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
329f0 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65  ().** routine re
32a00 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
32a10 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
32a20 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  t BLOB or string
32a30 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
32a40 75 6c 74 20 69 73 20 61 20 55 54 46 2d 38 20 73  ult is a UTF-8 s
32a50 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69  tring, then sqli
32a60 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
32a70 31 36 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a  16() converts.**
32a80 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55   the string to U
32a90 54 46 2d 31 36 20 61 6e 64 20 74 68 65 6e 20 72  TF-16 and then r
32aa0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
32ab0 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e  r of bytes..** ^
32ac0 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
32ad0 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65   a numeric value
32ae0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
32af0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 75  lumn_bytes16() u
32b00 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ses.** [sqlite3_
32b10 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63  snprintf()] to c
32b20 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75  onvert that valu
32b30 65 20 74 6f 20 61 20 55 54 46 2d 31 36 20 73 74  e to a UTF-16 st
32b40 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73  ring and returns
32b50 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
32b60 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
32b70 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74  string..** ^If t
32b80 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c  he result is NUL
32b90 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  L, then sqlite3_
32ba0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
32bb0 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a   returns zero..*
32bc0 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 73  *.** ^The values
32bd0 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
32be0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
32bf0 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73  es()] and .** [s
32c00 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
32c10 74 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20  tes16()] do not 
32c20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f  include the zero
32c30 20 74 65 72 6d 69 6e 61 74 6f 72 73 20 61 74 20   terminators at 
32c40 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68  the end.** of th
32c50 65 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20  e string.  ^For 
32c60 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c  clarity: the val
32c70 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ues returned by.
32c80 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
32c90 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20  mn_bytes()] and 
32ca0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
32cb0 62 79 74 65 73 31 36 28 29 5d 20 61 72 65 20 74  bytes16()] are t
32cc0 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
32cd0 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72  bytes in the str
32ce0 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d  ing, not the num
32cf0 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
32d00 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67  s..**.** ^String
32d10 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  s returned by sq
32d20 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
32d30 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
32d40 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c  column_text16(),
32d50 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73  .** even empty s
32d60 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61  trings, are alwa
32d70 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  ys zero-terminat
32d80 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e  ed.  ^The return
32d90 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  .** value from s
32da0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
32db0 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d  ob() for a zero-
32dc0 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61  length BLOB is a
32dd0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
32de0 2a 0a 2a 2a 20 3c 62 3e 57 61 72 6e 69 6e 67 3a  *.** <b>Warning:
32df0 3c 2f 62 3e 20 5e 54 68 65 20 6f 62 6a 65 63 74  </b> ^The object
32e00 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
32e10 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
32e20 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b  ue()] is an.** [
32e30 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
32e40 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
32e50 74 2e 20 20 49 6e 20 61 20 6d 75 6c 74 69 74 68  t.  In a multith
32e60 72 65 61 64 65 64 20 65 6e 76 69 72 6f 6e 6d 65  readed environme
32e70 6e 74 2c 0a 2a 2a 20 61 6e 20 75 6e 70 72 6f 74  nt,.** an unprot
32e80 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
32e90 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 6f  lue object may o
32ea0 6e 6c 79 20 62 65 20 75 73 65 64 20 73 61 66 65  nly be used safe
32eb0 6c 79 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69  ly with.** [sqli
32ec0 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29  te3_bind_value()
32ed0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  ] and [sqlite3_r
32ee0 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a  esult_value()]..
32ef0 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f  ** If the [unpro
32f00 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
32f10 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74  alue] object ret
32f20 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
32f30 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
32f40 65 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20  e()] is used in 
32f50 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69  any other way, i
32f60 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a  ncluding calls.*
32f70 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69  * to routines li
32f80 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ke [sqlite3_valu
32f90 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74  e_int()], [sqlit
32fa0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d  e3_value_text()]
32fb0 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ,.** or [sqlite3
32fc0 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c  _value_bytes()],
32fd0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
32fe0 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e   not threadsafe.
32ff0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
33000 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74 6f  tines attempt to
33010 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c   convert the val
33020 75 65 20 77 68 65 72 65 20 61 70 70 72 6f 70 72  ue where appropr
33030 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65  iate.  ^For.** e
33040 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69  xample, if the i
33050 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e  nternal represen
33060 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20  tation is FLOAT 
33070 61 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 6c  and a text resul
33080 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65  t.** is requeste
33090 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  d, [sqlite3_snpr
330a0 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64 20  intf()] is used 
330b0 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65  internally to pe
330c0 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e  rform the.** con
330d0 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69  version automati
330e0 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f  cally.  ^(The fo
330f0 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65  llowing table de
33100 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72  tails the conver
33110 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72  sions.** that ar
33120 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a  e applied:.**.**
33130 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a   <blockquote>.**
33140 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22   <table border="
33150 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20  1">.** <tr><th> 
33160 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65  Internal<br>Type
33170 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c   <th> Requested<
33180 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f  br>Type <th>  Co
33190 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c  nversion.**.** <
331a0 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
331b0 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
331c0 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30  <td> Result is 0
331d0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
331e0 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  LL    <td>  FLOA
331f0 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  T    <td> Result
33200 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c   is 0.0.** <tr><
33210 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
33220 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
33230 20 52 65 73 75 6c 74 20 69 73 20 61 20 4e 55 4c   Result is a NUL
33240 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72  L pointer.** <tr
33250 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
33260 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
33270 64 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20 4e  d> Result is a N
33280 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c  ULL pointer.** <
33290 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
332a0 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
332b0 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f  <td> Convert fro
332c0 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f  m integer to flo
332d0 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49  at.** <tr><td> I
332e0 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54  NTEGER  <td>   T
332f0 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49  EXT    <td> ASCI
33300 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  I rendering of t
33310 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74  he integer.** <t
33320 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20  r><td> INTEGER  
33330 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
33340 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45  td> Same as INTE
33350 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72  GER->TEXT.** <tr
33360 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
33370 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
33380 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54  d> [CAST] to INT
33390 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  EGER.** <tr><td>
333a0 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20    FLOAT   <td>  
333b0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53   TEXT    <td> AS
333c0 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  CII rendering of
333d0 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74   the float.** <t
333e0 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20  r><td>  FLOAT   
333f0 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
33400 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 42 4c  td> [CAST] to BL
33410 4f 42 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  OB.** <tr><td>  
33420 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54  TEXT    <td> INT
33430 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53  EGER   <td> [CAS
33440 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a  T] to INTEGER.**
33450 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
33460 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
33470 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f    <td> [CAST] to
33480 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64   REAL.** <tr><td
33490 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
334a0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e    BLOB    <td> N
334b0 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e  o change.** <tr>
334c0 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
334d0 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
334e0 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45  > [CAST] to INTE
334f0 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  GER.** <tr><td> 
33500 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46   BLOB    <td>  F
33510 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 41  LOAT    <td> [CA
33520 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c  ST] to REAL.** <
33530 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
33540 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
33550 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20  <td> Add a zero 
33560 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65  terminator if ne
33570 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e  eded.** </table>
33580 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  .** </blockquote
33590 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  >)^.**.** Note t
335a0 68 61 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f  hat when type co
335b0 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c  nversions occur,
335c0 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
335d0 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63  ed by prior.** c
335e0 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
335f0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73  column_blob(), s
33600 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
33610 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20  xt(), and/or.** 
33620 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
33630 65 78 74 31 36 28 29 20 6d 61 79 20 62 65 20 69  ext16() may be i
33640 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54  nvalidated..** T
33650 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20  ype conversions 
33660 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61  and pointer inva
33670 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20  lidations might 
33680 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20  occur.** in the 
33690 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a  following cases:
336a0 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
336b0 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20  li> The initial 
336c0 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f  content is a BLO
336d0 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  B and sqlite3_co
336e0 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a  lumn_text() or.*
336f0 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63  *      sqlite3_c
33700 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69  olumn_text16() i
33710 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72  s called.  A zer
33720 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67  o-terminator mig
33730 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20  ht.**      need 
33740 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20 74  to be added to t
33750 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a  he string.</li>.
33760 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
33770 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55  ial content is U
33780 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71  TF-8 text and sq
33790 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
337a0 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20  es16() or.**    
337b0 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
337c0 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c  _text16() is cal
337d0 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e  led.  The conten
337e0 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  t must be conver
337f0 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55  ted.**      to U
33800 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c  TF-16.</li>.** <
33810 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20  li> The initial 
33820 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31  content is UTF-1
33830 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74  6 text and sqlit
33840 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
33850 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c  ) or.**      sql
33860 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
33870 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54  () is called.  T
33880 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20  he content must 
33890 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20  be converted.** 
338a0 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f       to UTF-8.</
338b0 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  li>.** </ul>.**.
338c0 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20  ** ^Conversions 
338d0 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65  between UTF-16be
338e0 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72   and UTF-16le ar
338f0 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e  e always done in
33900 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a   place and do.**
33910 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20   not invalidate 
33920 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c  a prior pointer,
33930 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73   though of cours
33940 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  e the content of
33950 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74   the buffer.** t
33960 68 61 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f  hat the prior po
33970 69 6e 74 65 72 20 72 65 66 65 72 65 6e 63 65 73  inter references
33980 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20   will have been 
33990 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72  modified.  Other
339a0 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e   kinds.** of con
339b0 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65  version are done
339c0 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69   in place when i
339d0 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62  t is possible, b
339e0 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65  ut sometimes the
339f0 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73  y.** are not pos
33a00 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f  sible and in tho
33a10 73 65 20 63 61 73 65 73 20 70 72 69 6f 72 20 70  se cases prior p
33a20 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61  ointers are inva
33a30 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  lidated..**.** T
33a40 68 65 20 73 61 66 65 73 74 20 70 6f 6c 69 63 79  he safest policy
33a50 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68   is to invoke th
33a60 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  ese routines.** 
33a70 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  in one of the fo
33a80 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a  llowing ways:.**
33a90 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69  .** <ul>.**  <li
33aa0 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
33ab0 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20  text() followed 
33ac0 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
33ad0 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a  n_bytes()</li>.*
33ae0 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
33af0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c  olumn_blob() fol
33b00 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
33b10 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c  _column_bytes()<
33b20 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  /li>.**  <li>sql
33b30 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
33b40 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  16() followed by
33b50 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
33b60 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a  bytes16()</li>.*
33b70 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e  * </ul>.**.** In
33b80 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f   other words, yo
33b90 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71  u should call sq
33ba0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
33bb0 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  t(),.** sqlite3_
33bc0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f  column_blob(), o
33bd0 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
33be0 5f 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20  _text16() first 
33bf0 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73  to force the res
33c00 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20  ult.** into the 
33c10 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20  desired format, 
33c20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69  then invoke sqli
33c30 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
33c40 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  () or.** sqlite3
33c50 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
33c60 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69  ) to find the si
33c70 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ze of the result
33c80 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61  .  Do not mix ca
33c90 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  lls.** to sqlite
33ca0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
33cb0 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
33cc0 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61  n_blob() with ca
33cd0 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  lls to.** sqlite
33ce0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
33cf0 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d  (), and do not m
33d00 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ix calls to sqli
33d10 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
33d20 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c  6().** with call
33d30 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
33d40 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a  umn_bytes()..**.
33d50 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73  ** ^The pointers
33d60 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 61   returned are va
33d70 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65  lid until a type
33d80 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75   conversion occu
33d90 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62  rs as.** describ
33da0 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74  ed above, or unt
33db0 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  il [sqlite3_step
33dc0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
33dd0 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b  reset()] or.** [
33de0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
33df0 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  ()] is called.  
33e00 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63  ^The memory spac
33e10 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73  e used to hold s
33e20 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c  trings.** and BL
33e30 4f 42 73 20 69 73 20 66 72 65 65 64 20 61 75 74  OBs is freed aut
33e40 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20  omatically.  Do 
33e50 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20 70 61 73  <em>not</em> pas
33e60 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72  s the pointers r
33e70 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  eturned.** from 
33e80 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
33e90 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65  blob()], [sqlite
33ea0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d  3_column_text()]
33eb0 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b  , etc. into.** [
33ec0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
33ed0 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65  .**.** ^(If a me
33ee0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
33ef0 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72  error occurs dur
33f00 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74 69  ing the evaluati
33f10 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20  on of any.** of 
33f20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20  these routines, 
33f30 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20  a default value 
33f40 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  is returned.  Th
33f50 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a  e default value.
33f60 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74 68 65  ** is either the
33f70 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20   integer 0, the 
33f80 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e  floating point n
33f90 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20  umber 0.0, or a 
33fa0 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e  NULL.** pointer.
33fb0 20 20 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c    Subsequent cal
33fc0 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  ls to [sqlite3_e
33fd0 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72  rrcode()] will r
33fe0 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  eturn.** [SQLITE
33ff0 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f  _NOMEM].)^.*/.co
34000 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
34010 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71  3_column_blob(sq
34020 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
34030 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
34040 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
34050 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
34060 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
34070 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
34080 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74  tes16(sqlite3_st
34090 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
340a0 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63  double sqlite3_c
340b0 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c  olumn_double(sql
340c0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
340d0 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
340e0 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71  e3_column_int(sq
340f0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
34100 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f   iCol);.sqlite3_
34110 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f  int64 sqlite3_co
34120 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74  lumn_int64(sqlit
34130 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
34140 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67  ol);.const unsig
34150 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65  ned char *sqlite
34160 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71  3_column_text(sq
34170 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
34180 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f   iCol);.const vo
34190 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
341a0 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  mn_text16(sqlite
341b0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
341c0 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
341d0 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69  column_type(sqli
341e0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
341f0 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61  Col);.sqlite3_va
34200 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  lue *sqlite3_col
34210 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65  umn_value(sqlite
34220 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
34230 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
34240 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50  REF: Destroy A P
34250 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
34260 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 44 45 53 54  t Object.** DEST
34270 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 5f  RUCTOR: sqlite3_
34280 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  stmt.**.** ^The 
34290 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
342a0 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  () function is c
342b0 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20  alled to delete 
342c0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
342d0 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74  ement]..** ^If t
342e0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65  he most recent e
342f0 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68 65  valuation of the
34300 20 73 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75   statement encou
34310 6e 74 65 72 65 64 20 6e 6f 20 65 72 72 6f 72 73  ntered no errors
34320 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65 20 73 74  .** or if the st
34330 61 74 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 72  atement is never
34340 20 62 65 65 6e 20 65 76 61 6c 75 61 74 65 64 2c   been evaluated,
34350 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 69   then sqlite3_fi
34360 6e 61 6c 69 7a 65 28 29 20 72 65 74 75 72 6e 73  nalize() returns
34370 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20  .** SQLITE_OK.  
34380 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
34390 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f  ent evaluation o
343a0 66 20 73 74 61 74 65 6d 65 6e 74 20 53 20 66 61  f statement S fa
343b0 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71  iled, then.** sq
343c0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53  lite3_finalize(S
343d0 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 61 70  ) returns the ap
343e0 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72  propriate [error
343f0 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78   code] or.** [ex
34400 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64  tended error cod
34410 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  e]..**.** ^The s
34420 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
34430 53 29 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62  S) routine can b
34440 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20  e called at any 
34450 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20  point during.** 
34460 74 68 65 20 6c 69 66 65 20 63 79 63 6c 65 20 6f  the life cycle o
34470 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  f [prepared stat
34480 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66  ement] S:.** bef
34490 6f 72 65 20 73 74 61 74 65 6d 65 6e 74 20 53 20  ore statement S 
344a0 69 73 20 65 76 65 72 20 65 76 61 6c 75 61 74 65  is ever evaluate
344b0 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20  d, after.** one 
344c0 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f  or more calls to
344d0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
344e0 29 5d 2c 20 6f 72 20 61 66 74 65 72 20 61 6e 79  )], or after any
344f0 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c   call.** to [sql
34500 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 67  ite3_step()] reg
34510 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
34520 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 74  er or not the st
34530 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63  atement has.** c
34540 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 69  ompleted executi
34550 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b  on..**.** ^Invok
34560 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  ing sqlite3_fina
34570 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c  lize() on a NULL
34580 20 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61   pointer is a ha
34590 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a  rmless no-op..**
345a0 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
345b0 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a  ion must finaliz
345c0 65 20 65 76 65 72 79 20 5b 70 72 65 70 61 72 65  e every [prepare
345d0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20  d statement] in 
345e0 6f 72 64 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a  order to avoid.*
345f0 2a 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 73  * resource leaks
34600 2e 20 20 49 74 20 69 73 20 61 20 67 72 69 65 76  .  It is a griev
34610 6f 75 73 20 65 72 72 6f 72 20 66 6f 72 20 74 68  ous error for th
34620 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f  e application to
34630 20 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61   try to use.** a
34640 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
34650 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73  ent after it has
34660 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e   been finalized.
34670 20 20 41 6e 79 20 75 73 65 20 6f 66 20 61 20 70    Any use of a p
34680 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65  repared.** state
34690 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61  ment after it ha
346a0 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64  s been finalized
346b0 20 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 75   can result in u
346c0 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20  ndefined and.** 
346d0 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 61  undesirable beha
346e0 76 69 6f 72 20 73 75 63 68 20 61 73 20 73 65 67  vior such as seg
346f0 66 61 75 6c 74 73 20 61 6e 64 20 68 65 61 70 20  faults and heap 
34700 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 69  corruption..*/.i
34710 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  nt sqlite3_final
34720 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ize(sqlite3_stmt
34730 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
34740 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74   CAPI3REF: Reset
34750 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
34760 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20  ement Object.** 
34770 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
34780 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  stmt.**.** The s
34790 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20 66  qlite3_reset() f
347a0 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65  unction is calle
347b0 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b 70 72  d to reset a [pr
347c0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
347d0 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b  ].** object back
347e0 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20   to its initial 
347f0 73 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20  state, ready to 
34800 62 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a  be re-executed..
34810 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74 61 74  ** ^Any SQL stat
34820 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20  ement variables 
34830 74 68 61 74 20 68 61 64 20 76 61 6c 75 65 73 20  that had values 
34840 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73  bound to them us
34850 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  ing.** the [sqli
34860 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
34870 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
34880 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65   API] retain the
34890 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73  ir values..** Us
348a0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72  e [sqlite3_clear
348b0 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20  _bindings()] to 
348c0 72 65 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e  reset the bindin
348d0 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  gs..**.** ^The [
348e0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
348f0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 65  ] interface rese
34900 74 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  ts the [prepared
34910 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a   statement] S.**
34920 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62 65 67   back to the beg
34930 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 72  inning of its pr
34940 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  ogram..**.** ^If
34950 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
34960 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
34970 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74  3_step(S)] for t
34980 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
34990 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74  statement] S ret
349a0 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f  urned [SQLITE_RO
349b0 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f  W] or [SQLITE_DO
349c0 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b 73  NE],.** or if [s
349d0 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
349e0 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65  has never before
349f0 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20   been called on 
34a00 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69  S,.** then [sqli
34a10 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65  te3_reset(S)] re
34a20 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
34a30 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  ]..**.** ^If the
34a40 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
34a50 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
34a60 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a  ep(S)] for the.*
34a70 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
34a80 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63 61 74  ement] S indicat
34a90 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65  ed an error, the
34aa0 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  n.** [sqlite3_re
34ab0 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20  set(S)] returns 
34ac0 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b  an appropriate [
34ad0 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a  error code]..**.
34ae0 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
34af0 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72  _reset(S)] inter
34b00 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68  face does not ch
34b10 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a  ange the values.
34b20 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74  ** of any [sqlit
34b30 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e  e3_bind_blob|bin
34b40 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70  dings] on the [p
34b50 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
34b60 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  t] S..*/.int sql
34b70 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74  ite3_reset(sqlit
34b80 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
34b90 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
34ba0 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65 64 65  : Create Or Rede
34bb0 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f  fine SQL Functio
34bc0 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ns.** KEYWORDS: 
34bd0 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69  {function creati
34be0 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20  on routines}.** 
34bf0 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69  KEYWORDS: {appli
34c00 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
34c10 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20  QL function}.** 
34c20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69  KEYWORDS: {appli
34c30 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
34c40 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a  QL functions}.**
34c50 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
34c60 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75  .**.** ^These fu
34c70 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74  nctions (collect
34c80 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22  ively known as "
34c90 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f  function creatio
34ca0 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20  n routines").** 
34cb0 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20  are used to add 
34cc0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  SQL functions or
34cd0 20 61 67 67 72 65 67 61 74 65 73 20 6f 72 20 74   aggregates or t
34ce0 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65 20 62  o redefine the b
34cf0 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78  ehavior.** of ex
34d00 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74  isting SQL funct
34d10 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74  ions or aggregat
34d20 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69  es.  The only di
34d30 66 66 65 72 65 6e 63 65 73 20 62 65 74 77 65 65  fferences betwee
34d40 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69  n.** these routi
34d50 6e 65 73 20 61 72 65 20 74 68 65 20 74 65 78 74  nes are the text
34d60 20 65 6e 63 6f 64 69 6e 67 20 65 78 70 65 63 74   encoding expect
34d70 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73 65  ed for.** the se
34d80 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28  cond parameter (
34d90 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
34da0 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 63  function being c
34db0 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74  reated).** and t
34dc0 68 65 20 70 72 65 73 65 6e 63 65 20 6f 72 20 61  he presence or a
34dd0 62 73 65 6e 63 65 20 6f 66 20 61 20 64 65 73 74  bsence of a dest
34de0 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20  ructor callback 
34df0 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69  for.** the appli
34e00 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e  cation data poin
34e10 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
34e20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
34e30 69 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  is the [database
34e40 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20   connection] to 
34e50 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a  which the SQL.**
34e60 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20   function is to 
34e70 62 65 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61  be added.  ^If a
34e80 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73  n application us
34e90 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65  es more than one
34ea0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
34eb0 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70  nection then app
34ec0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
34ed0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d   SQL functions m
34ee0 75 73 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20  ust be added.** 
34ef0 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65  to each database
34f00 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61   connection sepa
34f10 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54  rately..**.** ^T
34f20 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
34f30 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20  ter is the name 
34f40 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  of the SQL funct
34f50 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65  ion to be create
34f60 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65  d or.** redefine
34f70 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20  d.  ^The length 
34f80 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c  of the name is l
34f90 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 79  imited to 255 by
34fa0 74 65 73 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a  tes in a UTF-8.*
34fb0 2a 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  * representation
34fc0 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74  , exclusive of t
34fd0 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  he zero-terminat
34fe0 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20  or.  ^Note that 
34ff0 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67  the name.** leng
35000 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 55  th limit is in U
35010 54 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74 20  TF-8 bytes, not 
35020 63 68 61 72 61 63 74 65 72 73 20 6e 6f 72 20 55  characters nor U
35030 54 46 2d 31 36 20 62 79 74 65 73 2e 20 20 0a 2a  TF-16 bytes.  .*
35040 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70 74 20 74  * ^Any attempt t
35050 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e 63 74  o create a funct
35060 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65  ion with a longe
35070 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72  r name.** will r
35080 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45  esult in [SQLITE
35090 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e 67 20 72  _MISUSE] being r
350a0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
350b0 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
350c0 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73  ter (nArg).** is
350d0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61   the number of a
350e0 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68  rguments that th
350f0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
35100 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74  r.** aggregate t
35110 61 6b 65 73 2e 20 5e 49 66 20 74 68 69 73 20 70  akes. ^If this p
35120 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20  arameter is -1, 
35130 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e  then the SQL fun
35140 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
35150 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61  egate may take a
35160 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  ny number of arg
35170 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30  uments between 0
35180 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a   and the limit.*
35190 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65  * set by [sqlite
351a0 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45  3_limit]([SQLITE
351b0 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
351c0 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74  ARG]).  If the t
351d0 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65  hird.** paramete
351e0 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d  r is less than -
351f0 31 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61  1 or greater tha
35200 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65 20 62  n 127 then the b
35210 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e  ehavior is.** un
35220 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
35230 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
35240 65 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20  eter, eTextRep, 
35250 73 70 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a  specifies what.*
35260 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c  * [SQLITE_UTF8 |
35270 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20   text encoding] 
35280 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f  this SQL functio
35290 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a  n prefers for.**
352a0 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e   its parameters.
352b0 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f    The applicatio
352c0 6e 20 73 68 6f 75 6c 64 20 73 65 74 20 74 68 69  n should set thi
352d0 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  s parameter to.*
352e0 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  * [SQLITE_UTF16L
352f0 45 5d 20 69 66 20 74 68 65 20 66 75 6e 63 74 69  E] if the functi
35300 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
35310 6e 20 69 6e 76 6f 6b 65 73 20 0a 2a 2a 20 5b 73  n invokes .** [s
35320 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
35330 74 31 36 6c 65 28 29 5d 20 6f 6e 20 61 6e 20 69  t16le()] on an i
35340 6e 70 75 74 2c 20 6f 72 20 5b 53 51 4c 49 54 45  nput, or [SQLITE
35350 5f 55 54 46 31 36 42 45 5d 20 69 66 20 74 68 65  _UTF16BE] if the
35360 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
35370 6f 6e 20 69 6e 76 6f 6b 65 73 20 5b 73 71 6c 69  on invokes [sqli
35380 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
35390 62 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70 75  be()] on an inpu
353a0 74 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  t, or.** [SQLITE
353b0 5f 55 54 46 31 36 5d 20 69 66 20 5b 73 71 6c 69  _UTF16] if [sqli
353c0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
353d0 28 29 5d 20 69 73 20 75 73 65 64 2c 20 6f 72 20  ()] is used, or 
353e0 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 0a 2a 2a  [SQLITE_UTF8].**
353f0 20 6f 74 68 65 72 77 69 73 65 2e 20 20 5e 54 68   otherwise.  ^Th
35400 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74  e same SQL funct
35410 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73  ion may be regis
35420 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 20 74  tered multiple t
35430 69 6d 65 73 20 75 73 69 6e 67 0a 2a 2a 20 64 69  imes using.** di
35440 66 66 65 72 65 6e 74 20 70 72 65 66 65 72 72 65  fferent preferre
35450 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73  d text encodings
35460 2c 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74  , with different
35470 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
35480 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 65 6e 63   for.** each enc
35490 6f 64 69 6e 67 2e 0a 2a 2a 20 5e 57 68 65 6e 20  oding..** ^When 
354a0 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65  multiple impleme
354b0 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ntations of the 
354c0 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72  same function ar
354d0 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c  e available, SQL
354e0 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b  ite.** will pick
354f0 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e   the one that in
35500 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74  volves the least
35510 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20   amount of data 
35520 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a  conversion..**.*
35530 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61  * ^The fourth pa
35540 72 61 6d 65 74 65 72 20 6d 61 79 20 6f 70 74 69  rameter may opti
35550 6f 6e 61 6c 6c 79 20 62 65 20 4f 52 65 64 20 77  onally be ORed w
35560 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 54 45  ith [SQLITE_DETE
35570 52 4d 49 4e 49 53 54 49 43 5d 0a 2a 2a 20 74 6f  RMINISTIC].** to
35580 20 73 69 67 6e 61 6c 20 74 68 61 74 20 74 68 65   signal that the
35590 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 61   function will a
355a0 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74 68 65  lways return the
355b0 20 73 61 6d 65 20 72 65 73 75 6c 74 20 67 69 76   same result giv
355c0 65 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 69  en.** the same i
355d0 6e 70 75 74 73 20 77 69 74 68 69 6e 20 61 20 73  nputs within a s
355e0 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d  ingle SQL statem
355f0 65 6e 74 2e 20 20 4d 6f 73 74 20 53 51 4c 20 66  ent.  Most SQL f
35600 75 6e 63 74 69 6f 6e 73 20 61 72 65 0a 2a 2a 20  unctions are.** 
35610 64 65 74 65 72 6d 69 6e 69 73 74 69 63 2e 20 20  deterministic.  
35620 54 68 65 20 62 75 69 6c 74 2d 69 6e 20 5b 72 61  The built-in [ra
35630 6e 64 6f 6d 28 29 5d 20 53 51 4c 20 66 75 6e 63  ndom()] SQL func
35640 74 69 6f 6e 20 69 73 20 61 6e 20 65 78 61 6d 70  tion is an examp
35650 6c 65 20 6f 66 20 61 0a 2a 2a 20 66 75 6e 63 74  le of a.** funct
35660 69 6f 6e 20 74 68 61 74 20 69 73 20 6e 6f 74 20  ion that is not 
35670 64 65 74 65 72 6d 69 6e 69 73 74 69 63 2e 20 20  deterministic.  
35680 54 68 65 20 53 51 4c 69 74 65 20 71 75 65 72 79  The SQLite query
35690 20 70 6c 61 6e 6e 65 72 20 69 73 20 61 62 6c 65   planner is able
356a0 20 74 6f 0a 2a 2a 20 70 65 72 66 6f 72 6d 20 61   to.** perform a
356b0 64 64 69 74 69 6f 6e 61 6c 20 6f 70 74 69 6d 69  dditional optimi
356c0 7a 61 74 69 6f 6e 73 20 6f 6e 20 64 65 74 65 72  zations on deter
356d0 6d 69 6e 69 73 74 69 63 20 66 75 6e 63 74 69 6f  ministic functio
356e0 6e 73 2c 20 73 6f 20 75 73 65 0a 2a 2a 20 6f 66  ns, so use.** of
356f0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 44 45 54   the [SQLITE_DET
35700 45 52 4d 49 4e 49 53 54 49 43 5d 20 66 6c 61 67  ERMINISTIC] flag
35710 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
35720 77 68 65 72 65 20 70 6f 73 73 69 62 6c 65 2e 0a  where possible..
35730 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66 74  **.** ^(The fift
35740 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  h parameter is a
35750 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e  n arbitrary poin
35760 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d  ter.  The implem
35770 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a  entation of the.
35780 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20  ** function can 
35790 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74  gain access to t
357a0 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e  his pointer usin
357b0 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  g [sqlite3_user_
357c0 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a  data()].)^.**.**
357d0 20 5e 54 68 65 20 73 69 78 74 68 2c 20 73 65 76   ^The sixth, sev
357e0 65 6e 74 68 20 61 6e 64 20 65 69 67 68 74 68 20  enth and eighth 
357f0 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e  parameters, xFun
35800 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46 69  c, xStep and xFi
35810 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e  nal, are.** poin
35820 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61  ters to C-langua
35830 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61  ge functions tha
35840 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20  t implement the 
35850 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
35860 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20 5e 41  ** aggregate. ^A
35870 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63   scalar SQL func
35880 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e  tion requires an
35890 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
358a0 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20  of the xFunc.** 
358b0 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e  callback only; N
358c0 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75 73  ULL pointers mus
358d0 74 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  t be passed as t
358e0 68 65 20 78 53 74 65 70 20 61 6e 64 20 78 46 69  he xStep and xFi
358f0 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  nal.** parameter
35900 73 2e 20 5e 41 6e 20 61 67 67 72 65 67 61 74 65  s. ^An aggregate
35910 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65   SQL function re
35920 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d  quires an implem
35930 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65  entation of xSte
35940 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20  p.** and xFinal 
35950 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  and NULL pointer
35960 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20   must be passed 
35970 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64  for xFunc. ^To d
35980 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e  elete an existin
35990 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f  g.** SQL functio
359a0 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20  n or aggregate, 
359b0 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  pass NULL pointe
359c0 72 73 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65  rs for all three
359d0 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c   function.** cal
359e0 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  lbacks..**.** ^(
359f0 49 66 20 74 68 65 20 6e 69 6e 74 68 20 70 61 72  If the ninth par
35a00 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
35a10 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
35a20 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 4e 55  n_v2() is not NU
35a30 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69  LL,.** then it i
35a40 73 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72  s destructor for
35a50 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
35a60 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a   data pointer. .
35a70 2a 2a 20 54 68 65 20 64 65 73 74 72 75 63 74 6f  ** The destructo
35a80 72 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65  r is invoked whe
35a90 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  n the function i
35aa0 73 20 64 65 6c 65 74 65 64 2c 20 65 69 74 68 65  s deleted, eithe
35ab0 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76  r by being.** ov
35ac0 65 72 6c 6f 61 64 65 64 20 6f 72 20 77 68 65 6e  erloaded or when
35ad0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
35ae0 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e  nnection closes.
35af0 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74 72  )^.** ^The destr
35b00 75 63 74 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e  uctor is also in
35b10 76 6f 6b 65 64 20 69 66 20 74 68 65 20 63 61 6c  voked if the cal
35b20 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  l to.** sqlite3_
35b30 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f  create_function_
35b40 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e  v2() fails..** ^
35b50 57 68 65 6e 20 74 68 65 20 64 65 73 74 72 75 63  When the destruc
35b60 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20  tor callback of 
35b70 74 68 65 20 74 65 6e 74 68 20 70 61 72 61 6d 65  the tenth parame
35b80 74 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20  ter is invoked, 
35b90 69 74 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20  it.** is passed 
35ba0 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
35bb0 74 20 77 68 69 63 68 20 69 73 20 61 20 63 6f 70  t which is a cop
35bc0 79 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  y of the applica
35bd0 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f  tion data .** po
35be0 69 6e 74 65 72 20 77 68 69 63 68 20 77 61 73 20  inter which was 
35bf0 74 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65  the fifth parame
35c00 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ter to sqlite3_c
35c10 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76  reate_function_v
35c20 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69  2()..**.** ^It i
35c30 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72  s permitted to r
35c40 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65  egister multiple
35c50 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
35c60 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20   of the same.** 
35c70 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74  functions with t
35c80 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74  he same name but
35c90 20 77 69 74 68 20 65 69 74 68 65 72 20 64 69 66   with either dif
35ca0 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f  fering numbers o
35cb0 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f  f.** arguments o
35cc0 72 20 64 69 66 66 65 72 69 6e 67 20 70 72 65 66  r differing pref
35cd0 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
35ce0 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65 20 77  ings.  ^SQLite w
35cf0 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69  ill use.** the i
35d00 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68  mplementation th
35d10 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20  at most closely 
35d20 6d 61 74 63 68 65 73 20 74 68 65 20 77 61 79 20  matches the way 
35d30 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20  in which the.** 
35d40 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
35d50 75 73 65 64 2e 20 20 5e 41 20 66 75 6e 63 74 69  used.  ^A functi
35d60 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
35d70 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67  n with a non-neg
35d80 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61  ative.** nArg pa
35d90 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 65 74  rameter is a bet
35da0 74 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61  ter match than a
35db0 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
35dc0 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a  entation with.**
35dd0 20 61 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67   a negative nArg
35de0 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77  .  ^A function w
35df0 68 65 72 65 20 74 68 65 20 70 72 65 66 65 72 72  here the preferr
35e00 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ed text encoding
35e10 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20  .** matches the 
35e20 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e  database encodin
35e30 67 20 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a  g is a better.**
35e40 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75   match than a fu
35e50 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
35e60 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66   encoding is dif
35e70 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20  ferent.  .** ^A 
35e80 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
35e90 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66  he encoding diff
35ea0 65 72 65 6e 63 65 20 69 73 20 62 65 74 77 65 65  erence is betwee
35eb0 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54  n UTF16le and UT
35ec0 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c  F16be.** is a cl
35ed0 6f 73 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20  oser match than 
35ee0 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  a function where
35ef0 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69   the encoding di
35f00 66 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62  fference is.** b
35f10 65 74 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20  etween UTF8 and 
35f20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75  UTF16..**.** ^Bu
35f30 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73  ilt-in functions
35f40 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64   may be overload
35f50 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63  ed by new applic
35f60 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
35f70 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  nctions..**.** ^
35f80 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  An application-d
35f90 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
35fa0 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20  is permitted to 
35fb0 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51  call other.** SQ
35fc0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e  Lite interfaces.
35fd0 20 20 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20    However, such 
35fe0 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a  calls must not.*
35ff0 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61  * close the data
36000 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
36010 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20  nor finalize or 
36020 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72  reset the prepar
36030 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  ed.** statement 
36040 69 6e 20 77 68 69 63 68 20 74 68 65 20 66 75 6e  in which the fun
36050 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
36060 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
36070 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
36080 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
36090 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
360a0 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20  FunctionName,.  
360b0 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20  int nArg,.  int 
360c0 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64  eTextRep,.  void
360d0 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28   *pApp,.  void (
360e0 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xFunc)(sqlite3_
360f0 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
36100 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
36110 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73   void (*xStep)(s
36120 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
36130 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
36140 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
36150 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63  Final)(sqlite3_c
36160 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20  ontext*).);.int 
36170 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
36180 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c  unction16(.  sql
36190 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73  ite3 *db,.  cons
361a0 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f  t void *zFunctio
361b0 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72  nName,.  int nAr
361c0 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  g,.  int eTextRe
361d0 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c  p,.  void *pApp,
361e0 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29  .  void (*xFunc)
361f0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
36200 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
36210 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
36220 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f  *xStep)(sqlite3_
36230 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
36240 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
36250 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28   void (*xFinal)(
36260 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
36270 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ).);.int sqlite3
36280 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
36290 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
362a0 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  db,.  const char
362b0 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c   *zFunctionName,
362c0 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69  .  int nArg,.  i
362d0 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76  nt eTextRep,.  v
362e0 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69  oid *pApp,.  voi
362f0 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74  d (*xFunc)(sqlit
36300 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
36310 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
36320 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70  ,.  void (*xStep
36330 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
36340 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
36350 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
36360 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65  (*xFinal)(sqlite
36370 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76  3_context*),.  v
36380 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76  oid(*xDestroy)(v
36390 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  oid*).);../*.** 
363a0 43 41 50 49 33 52 45 46 3a 20 54 65 78 74 20 45  CAPI3REF: Text E
363b0 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54  ncodings.**.** T
363c0 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65  hese constant de
363d0 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64  fine integer cod
363e0 65 73 20 74 68 61 74 20 72 65 70 72 65 73 65 6e  es that represen
363f0 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a  t the various.**
36400 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20   text encodings 
36410 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c  supported by SQL
36420 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ite..*/.#define 
36430 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20  SQLITE_UTF8     
36440 20 20 20 20 20 20 31 20 20 20 20 2f 2a 20 49 4d        1    /* IM
36450 50 3a 20 52 2d 33 37 35 31 34 2d 33 35 35 36 36  P: R-37514-35566
36460 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
36470 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20  TE_UTF16LE      
36480 20 20 32 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52    2    /* IMP: R
36490 2d 30 33 33 37 31 2d 33 37 36 33 37 20 2a 2f 0a  -03371-37637 */.
364a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
364b0 54 46 31 36 42 45 20 20 20 20 20 20 20 20 33 20  TF16BE        3 
364c0 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 35 31 39     /* IMP: R-519
364d0 37 31 2d 33 34 31 35 34 20 2a 2f 0a 23 64 65 66  71-34154 */.#def
364e0 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
364f0 20 20 20 20 20 20 20 20 20 20 34 20 20 20 20 2f            4    /
36500 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62 79 74  * Use native byt
36510 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69  e order */.#defi
36520 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20  ne SQLITE_ANY   
36530 20 20 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a           5    /*
36540 20 44 65 70 72 65 63 61 74 65 64 20 2a 2f 0a 23   Deprecated */.#
36550 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
36560 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20  F16_ALIGNED  8  
36570 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65    /* sqlite3_cre
36580 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e  ate_collation on
36590 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ly */../*.** CAP
365a0 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20  I3REF: Function 
365b0 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  Flags.**.** Thes
365c0 65 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61 79 20  e constants may 
365d0 62 65 20 4f 52 65 64 20 74 6f 67 65 74 68 65 72  be ORed together
365e0 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53   with the .** [S
365f0 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 70 72 65  QLITE_UTF8 | pre
36600 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f  ferred text enco
36610 64 69 6e 67 5d 20 61 73 20 74 68 65 20 66 6f 75  ding] as the fou
36620 72 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  rth argument.** 
36630 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  to [sqlite3_crea
36640 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20  te_function()], 
36650 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
36660 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 2c 20 6f  function16()], o
36670 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72  r.** [sqlite3_cr
36680 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
36690 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ()]..*/.#define 
366a0 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49  SQLITE_DETERMINI
366b0 53 54 49 43 20 20 20 20 30 78 38 30 30 0a 0a 2f  STIC    0x800../
366c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
366d0 65 70 72 65 63 61 74 65 64 20 46 75 6e 63 74 69  eprecated Functi
366e0 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41 54 45  ons.** DEPRECATE
366f0 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75  D.**.** These fu
36700 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b 64 65 70  nctions are [dep
36710 72 65 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72  recated].  In or
36720 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a  der to maintain.
36730 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  ** backwards com
36740 70 61 74 69 62 69 6c 69 74 79 20 77 69 74 68 20  patibility with 
36750 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74 68 65 73  older code, thes
36760 65 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74  e functions cont
36770 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73  inue .** to be s
36780 75 70 70 6f 72 74 65 64 2e 20 20 48 6f 77 65 76  upported.  Howev
36790 65 72 2c 20 6e 65 77 20 61 70 70 6c 69 63 61 74  er, new applicat
367a0 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f 69  ions should avoi
367b0 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20  d.** the use of 
367c0 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e  these functions.
367d0 20 20 54 6f 20 65 6e 63 6f 75 72 61 67 65 20 70    To encourage p
367e0 72 6f 67 72 61 6d 6d 65 72 73 20 74 6f 20 61 76  rogrammers to av
367f0 6f 69 64 0a 2a 2a 20 74 68 65 73 65 20 66 75 6e  oid.** these fun
36800 63 74 69 6f 6e 73 2c 20 77 65 20 77 69 6c 6c 20  ctions, we will 
36810 6e 6f 74 20 65 78 70 6c 61 69 6e 20 77 68 61 74  not explain what
36820 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66   they do..*/.#if
36830 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  ndef SQLITE_OMIT
36840 5f 44 45 50 52 45 43 41 54 45 44 0a 53 51 4c 49  _DEPRECATED.SQLI
36850 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
36860 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  t sqlite3_aggreg
36870 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ate_count(sqlite
36880 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c  3_context*);.SQL
36890 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
368a0 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 70 69 72  nt sqlite3_expir
368b0 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ed(sqlite3_stmt*
368c0 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  );.SQLITE_DEPREC
368d0 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
368e0 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e  _transfer_bindin
368f0 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  gs(sqlite3_stmt*
36900 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  , sqlite3_stmt*)
36910 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
36920 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
36930 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 76  global_recover(v
36940 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  oid);.SQLITE_DEP
36950 52 45 43 41 54 45 44 20 76 6f 69 64 20 73 71 6c  RECATED void sql
36960 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 61  ite3_thread_clea
36970 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54  nup(void);.SQLIT
36980 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
36990 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
369a0 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f  alarm(void(*)(vo
369b0 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36  id*,sqlite3_int6
369c0 34 2c 69 6e 74 29 2c 0a 20 20 20 20 20 20 20 20  4,int),.        
369d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f                vo
369e0 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36  id*,sqlite3_int6
369f0 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  4);.#endif../*.*
36a00 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61  * CAPI3REF: Obta
36a10 69 6e 69 6e 67 20 53 51 4c 20 56 61 6c 75 65 73  ining SQL Values
36a20 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
36a30 74 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20  te3_value.**.** 
36a40 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69  The C-language i
36a50 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
36a60 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61   SQL functions a
36a70 6e 64 20 61 67 67 72 65 67 61 74 65 73 20 75 73  nd aggregates us
36a80 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f  es.** this set o
36a90 66 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74  f interface rout
36aa0 69 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20 74  ines to access t
36ab0 68 65 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c  he parameter val
36ac0 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75  ues on.** the fu
36ad0 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67  nction or aggreg
36ae0 61 74 65 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65  ate.  .**.** The
36af0 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61 6c   xFunc (for scal
36b00 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72  ar functions) or
36b10 20 78 53 74 65 70 20 28 66 6f 72 20 61 67 67 72   xStep (for aggr
36b20 65 67 61 74 65 73 29 20 70 61 72 61 6d 65 74 65  egates) paramete
36b30 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65  rs.** to [sqlite
36b40 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
36b50 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
36b60 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
36b70 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65  n16()].** define
36b80 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20   callbacks that 
36b90 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51  implement the SQ
36ba0 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20  L functions and 
36bb0 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54  aggregates..** T
36bc0 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
36bd0 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 61   to these callba
36be0 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79 20  cks is an array 
36bf0 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a  of pointers to.*
36c00 2a 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  * [protected sql
36c10 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
36c20 63 74 73 2e 20 20 54 68 65 72 65 20 69 73 20 6f  cts.  There is o
36c30 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ne [sqlite3_valu
36c40 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a  e] object for.**
36c50 20 65 61 63 68 20 70 61 72 61 6d 65 74 65 72 20   each parameter 
36c60 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  to the SQL funct
36c70 69 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 74  ion.  These rout
36c80 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 74 6f  ines are used to
36c90 0a 2a 2a 20 65 78 74 72 61 63 74 20 76 61 6c 75  .** extract valu
36ca0 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c  es from the [sql
36cb0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
36cc0 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  cts..**.** These
36cd0 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f   routines work o
36ce0 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f 74 65 63  nly with [protec
36cf0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
36d00 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41  e] objects..** A
36d10 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73  ny attempt to us
36d20 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  e these routines
36d30 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63   on an [unprotec
36d40 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
36d50 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73  e].** object res
36d60 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65  ults in undefine
36d70 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a  d behavior..**.*
36d80 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
36d90 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65  s work just like
36da0 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
36db0 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73  ng [column acces
36dc0 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20  s functions].** 
36dd0 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65 73  except that thes
36de0 65 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20  e routines take 
36df0 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63  a single [protec
36e00 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
36e10 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69  e] object.** poi
36e20 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20  nter instead of 
36e30 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  a [sqlite3_stmt*
36e40 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e  ] pointer and an
36e50 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20   integer column 
36e60 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  number..**.** ^T
36e70 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
36e80 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65 72 66  _text16() interf
36e90 61 63 65 20 65 78 74 72 61 63 74 73 20 61 20 55  ace extracts a U
36ea0 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20  TF-16 string.** 
36eb0 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
36ec0 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20  te-order of the 
36ed0 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e  host machine.  ^
36ee0 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  The.** sqlite3_v
36ef0 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29 20  alue_text16be() 
36f00 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  and sqlite3_valu
36f10 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e 74  e_text16le() int
36f20 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 61  erfaces.** extra
36f30 63 74 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  ct UTF-16 string
36f40 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e 20  s as big-endian 
36f50 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61  and little-endia
36f60 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  n respectively..
36f70 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69  **.** ^(The sqli
36f80 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69  te3_value_numeri
36f90 63 5f 74 79 70 65 28 29 20 69 6e 74 65 72 66 61  c_type() interfa
36fa0 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61  ce attempts to a
36fb0 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20  pply.** numeric 
36fc0 61 66 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20  affinity to the 
36fd0 76 61 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61  value.  This mea
36fe0 6e 73 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d  ns that an attem
36ff0 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f  pt is.** made to
37000 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c   convert the val
37010 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  ue to an integer
37020 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69   or floating poi
37030 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20  nt.  If.** such 
37040 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20  a conversion is 
37050 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74  possible without
37060 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61   loss of informa
37070 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a  tion (in other.*
37080 2a 20 77 6f 72 64 73 2c 20 69 66 20 74 68 65 20  * words, if the 
37090 76 61 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e  value is a strin
370a0 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b  g that looks lik
370b0 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74  e a number).** t
370c0 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69  hen the conversi
370d0 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e  on is performed.
370e0 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63    Otherwise no c
370f0 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73  onversion occurs
37100 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ..** The [SQLITE
37110 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74  _INTEGER | datat
37120 79 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65  ype] after conve
37130 72 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65  rsion is returne
37140 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73  d.)^.**.** Pleas
37150 65 20 70 61 79 20 70 61 72 74 69 63 75 6c 61 72  e pay particular
37160 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68   attention to th
37170 65 20 66 61 63 74 20 74 68 61 74 20 74 68 65 20  e fact that the 
37180 70 6f 69 6e 74 65 72 20 72 65 74 75 72 6e 65 64  pointer returned
37190 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
371a0 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c  3_value_blob()],
371b0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
371c0 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b  text()], or.** [
371d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
371e0 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69  xt16()] can be i
371f0 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20 61 20  nvalidated by a 
37200 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20  subsequent call 
37210 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  to.** [sqlite3_v
37220 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b  alue_bytes()], [
37230 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
37240 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74  tes16()], [sqlit
37250 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d  e3_value_text()]
37260 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ,.** or [sqlite3
37270 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d  _value_text16()]
37280 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
37290 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63  utines must be c
372a0 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
372b0 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a  ame thread as.**
372c0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
372d0 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65 64 20  n that supplied 
372e0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
372f0 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 2e  ue*] parameters.
37300 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  .*/.const void *
37310 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
37320 6f 62 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ob(sqlite3_value
37330 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
37340 76 61 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69  value_bytes(sqli
37350 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
37360 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62   sqlite3_value_b
37370 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76  ytes16(sqlite3_v
37380 61 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73  alue*);.double s
37390 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75  qlite3_value_dou
373a0 62 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ble(sqlite3_valu
373b0 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
373c0 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74  _value_int(sqlit
373d0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69  e3_value*);.sqli
373e0 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
373f0 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71  3_value_int64(sq
37400 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63  lite3_value*);.c
37410 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68  onst unsigned ch
37420 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  ar *sqlite3_valu
37430 65 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76  e_text(sqlite3_v
37440 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f  alue*);.const vo
37450 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
37460 65 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  e_text16(sqlite3
37470 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20  _value*);.const 
37480 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
37490 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c  lue_text16le(sql
374a0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f  ite3_value*);.co
374b0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
374c0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65  3_value_text16be
374d0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
374e0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
374f0 6c 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33  lue_type(sqlite3
37500 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
37510 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65  lite3_value_nume
37520 72 69 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33  ric_type(sqlite3
37530 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  _value*);../*.**
37540 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 69   CAPI3REF: Findi
37550 6e 67 20 54 68 65 20 53 75 62 74 79 70 65 20 4f  ng The Subtype O
37560 66 20 53 51 4c 20 56 61 6c 75 65 73 0a 2a 2a 20  f SQL Values.** 
37570 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
37580 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20  value.**.** The 
37590 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 73 75  sqlite3_value_su
375a0 62 74 79 70 65 28 56 29 20 66 75 6e 63 74 69 6f  btype(V) functio
375b0 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 75  n returns the su
375c0 62 74 79 70 65 20 66 6f 72 0a 2a 2a 20 61 6e 20  btype for.** an 
375d0 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
375e0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
375f0 6e 5d 20 61 72 67 75 6d 65 6e 74 20 56 2e 20 20  n] argument V.  
37600 54 68 65 20 73 75 62 74 79 70 65 0a 2a 2a 20 69  The subtype.** i
37610 6e 66 6f 72 6d 61 74 69 6f 6e 20 63 61 6e 20 62  nformation can b
37620 65 20 75 73 65 64 20 74 6f 20 70 61 73 73 20 61  e used to pass a
37630 20 6c 69 6d 69 74 65 64 20 61 6d 6f 75 6e 74 20   limited amount 
37640 6f 66 20 63 6f 6e 74 65 78 74 20 66 72 6f 6d 0a  of context from.
37650 2a 2a 20 6f 6e 65 20 53 51 4c 20 66 75 6e 63 74  ** one SQL funct
37660 69 6f 6e 20 74 6f 20 61 6e 6f 74 68 65 72 2e 20  ion to another. 
37670 20 55 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65   Use the [sqlite
37680 33 5f 72 65 73 75 6c 74 5f 73 75 62 74 79 70 65  3_result_subtype
37690 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74  ()].** routine t
376a0 6f 20 73 65 74 20 74 68 65 20 73 75 62 74 79 70  o set the subtyp
376b0 65 20 66 6f 72 20 74 68 65 20 72 65 74 75 72 6e  e for the return
376c0 20 76 61 6c 75 65 20 6f 66 20 61 6e 20 53 51 4c   value of an SQL
376d0 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
376e0 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 6e 6f   SQLite makes no
376f0 20 75 73 65 20 6f 66 20 73 75 62 74 79 70 65 20   use of subtype 
37700 69 74 73 65 6c 66 2e 20 20 49 74 20 6d 65 72 65  itself.  It mere
37710 6c 79 20 70 61 73 73 65 73 20 74 68 65 20 73 75  ly passes the su
37720 62 74 79 70 65 0a 2a 2a 20 66 72 6f 6d 20 74 68  btype.** from th
37730 65 20 72 65 73 75 6c 74 20 6f 66 20 6f 6e 65 20  e result of one 
37740 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
37750 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
37760 6e 5d 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69  n] into the.** i
37770 6e 70 75 74 20 6f 66 20 61 6e 6f 74 68 65 72 2e  nput of another.
37780 0a 2a 2f 0a 75 6e 73 69 67 6e 65 64 20 69 6e 74  .*/.unsigned int
37790 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 73   sqlite3_value_s
377a0 75 62 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76  ubtype(sqlite3_v
377b0 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  alue*);../*.** C
377c0 41 50 49 33 52 45 46 3a 20 43 6f 70 79 20 41 6e  API3REF: Copy An
377d0 64 20 46 72 65 65 20 53 51 4c 20 56 61 6c 75 65  d Free SQL Value
377e0 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
377f0 69 74 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a  ite3_value.**.**
37800 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61   ^The sqlite3_va
37810 6c 75 65 5f 64 75 70 28 56 29 20 69 6e 74 65 72  lue_dup(V) inter
37820 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  face makes a cop
37830 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  y of the [sqlite
37840 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65  3_value].** obje
37850 63 74 20 44 20 61 6e 64 20 72 65 74 75 72 6e 73  ct D and returns
37860 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
37870 61 74 20 63 6f 70 79 2e 20 20 5e 54 68 65 20 5b  at copy.  ^The [
37880 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 72  sqlite3_value] r
37890 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 61 20  eturned.** is a 
378a0 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
378b0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
378c0 20 65 76 65 6e 20 69 66 20 74 68 65 20 69 6e 70   even if the inp
378d0 75 74 20 69 73 20 6e 6f 74 2e 0a 2a 2a 20 5e 54  ut is not..** ^T
378e0 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
378f0 5f 64 75 70 28 56 29 20 69 6e 74 65 72 66 61 63  _dup(V) interfac
37900 65 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69  e returns NULL i
37910 66 20 56 20 69 73 20 4e 55 4c 4c 20 6f 72 20 69  f V is NULL or i
37920 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  f a.** memory al
37930 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2e 0a  location fails..
37940 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
37950 65 33 5f 76 61 6c 75 65 5f 66 72 65 65 28 56 29  e3_value_free(V)
37960 20 69 6e 74 65 72 66 61 63 65 20 66 72 65 65 73   interface frees
37970 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   an [sqlite3_val
37980 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 72  ue] object.** pr
37990 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65  eviously obtaine
379a0 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
379b0 76 61 6c 75 65 5f 64 75 70 28 29 5d 2e 20 20 5e  value_dup()].  ^
379c0 49 66 20 56 20 69 73 20 61 20 4e 55 4c 4c 20 70  If V is a NULL p
379d0 6f 69 6e 74 65 72 0a 2a 2a 20 74 68 65 6e 20 73  ointer.** then s
379e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 66 72 65  qlite3_value_fre
379f0 65 28 56 29 20 69 73 20 61 20 68 61 72 6d 6c 65  e(V) is a harmle
37a00 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 73 71 6c  ss no-op..*/.sql
37a10 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69  ite3_value *sqli
37a20 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 63 6f  te3_value_dup(co
37a30 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  nst sqlite3_valu
37a40 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  e*);.void sqlite
37a50 33 5f 76 61 6c 75 65 5f 66 72 65 65 28 73 71 6c  3_value_free(sql
37a60 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f  ite3_value*);../
37a70 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
37a80 62 74 61 69 6e 20 41 67 67 72 65 67 61 74 65 20  btain Aggregate 
37a90 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74  Function Context
37aa0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
37ab0 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a  te3_context.**.*
37ac0 2a 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * Implementation
37ad0 73 20 6f 66 20 61 67 67 72 65 67 61 74 65 20 53  s of aggregate S
37ae0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65  QL functions use
37af0 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65   this.** routine
37b00 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d   to allocate mem
37b10 6f 72 79 20 66 6f 72 20 73 74 6f 72 69 6e 67 20  ory for storing 
37b20 74 68 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a  their state..**.
37b30 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74 69  ** ^The first ti
37b40 6d 65 20 74 68 65 20 73 71 6c 69 74 65 33 5f 61  me the sqlite3_a
37b50 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
37b60 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 69 73  (C,N) routine is
37b70 20 63 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20   called .** for 
37b80 61 20 70 61 72 74 69 63 75 6c 61 72 20 61 67 67  a particular agg
37b90 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c  regate function,
37ba0 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63   SQLite.** alloc
37bb0 61 74 65 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79  ates N of memory
37bc0 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 61  , zeroes out tha
37bd0 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65  t memory, and re
37be0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a  turns a pointer.
37bf0 2a 2a 20 74 6f 20 74 68 65 20 6e 65 77 20 6d 65  ** to the new me
37c00 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64  mory. ^On second
37c10 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20   and subsequent 
37c20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69  calls to.** sqli
37c30 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
37c40 6e 74 65 78 74 28 29 20 66 6f 72 20 74 68 65 20  ntext() for the 
37c50 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66  same aggregate f
37c60 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65  unction instance
37c70 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 75  ,.** the same bu
37c80 66 66 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  ffer is returned
37c90 2e 20 20 53 71 6c 69 74 65 33 5f 61 67 67 72 65  .  Sqlite3_aggre
37ca0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 69  gate_context() i
37cb0 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61  s normally.** ca
37cc0 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61  lled once for ea
37cd0 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  ch invocation of
37ce0 20 74 68 65 20 78 53 74 65 70 20 63 61 6c 6c 62   the xStep callb
37cf0 61 63 6b 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65  ack and then one
37d00 0a 2a 2a 20 6c 61 73 74 20 74 69 6d 65 20 77 68  .** last time wh
37d10 65 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61  en the xFinal ca
37d20 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
37d30 64 2e 20 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f  d.  ^(When no ro
37d40 77 73 20 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61  ws match.** an a
37d50 67 67 72 65 67 61 74 65 20 71 75 65 72 79 2c 20  ggregate query, 
37d60 74 68 65 20 78 53 74 65 70 28 29 20 63 61 6c 6c  the xStep() call
37d70 62 61 63 6b 20 6f 66 20 74 68 65 20 61 67 67 72  back of the aggr
37d80 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a  egate function.*
37d90 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
37da0 20 69 73 20 6e 65 76 65 72 20 63 61 6c 6c 65 64   is never called
37db0 20 61 6e 64 20 78 46 69 6e 61 6c 28 29 20 69 73   and xFinal() is
37dc0 20 63 61 6c 6c 65 64 20 65 78 61 63 74 6c 79 20   called exactly 
37dd0 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73  once..** In thos
37de0 65 20 63 61 73 65 73 2c 20 73 71 6c 69 74 65 33  e cases, sqlite3
37df0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
37e00 78 74 28 29 20 6d 69 67 68 74 20 62 65 20 63 61  xt() might be ca
37e10 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20  lled for the.** 
37e20 66 69 72 73 74 20 74 69 6d 65 20 66 72 6f 6d 20  first time from 
37e30 77 69 74 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e  within xFinal().
37e40 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )^.**.** ^The sq
37e50 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
37e60 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75  context(C,N) rou
37e70 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 4e  tine returns a N
37e80 55 4c 4c 20 70 6f 69 6e 74 65 72 20 0a 2a 2a 20  ULL pointer .** 
37e90 77 68 65 6e 20 66 69 72 73 74 20 63 61 6c 6c 65  when first calle
37ea0 64 20 69 66 20 4e 20 69 73 20 6c 65 73 73 20 74  d if N is less t
37eb0 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20  han or equal to 
37ec0 7a 65 72 6f 20 6f 72 20 69 66 20 61 20 6d 65 6d  zero or if a mem
37ed0 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20  ory.** allocate 
37ee0 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a  error occurs..**
37ef0 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74  .** ^(The amount
37f00 20 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f 63 61   of space alloca
37f10 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 61  ted by sqlite3_a
37f20 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
37f30 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65  (C,N) is.** dete
37f40 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20 4e 20  rmined by the N 
37f50 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 66 69 72  parameter on fir
37f60 73 74 20 73 75 63 63 65 73 73 66 75 6c 20 63 61  st successful ca
37f70 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20 74 68  ll.  Changing th
37f80 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20  e.** value of N 
37f90 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  in subsequent ca
37fa0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67  ll to sqlite3_ag
37fb0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
37fc0 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20  ) within.** the 
37fd0 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66  same aggregate f
37fe0 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65  unction instance
37ff0 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65   will not resize
38000 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61   the memory.** a
38010 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 20 20 57 69  llocation.)^  Wi
38020 74 68 69 6e 20 74 68 65 20 78 46 69 6e 61 6c 20  thin the xFinal 
38030 63 61 6c 6c 62 61 63 6b 2c 20 69 74 20 69 73 20  callback, it is 
38040 63 75 73 74 6f 6d 61 72 79 20 74 6f 20 73 65 74  customary to set
38050 0a 2a 2a 20 4e 3d 30 20 69 6e 20 63 61 6c 6c 73  .** N=0 in calls
38060 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72   to sqlite3_aggr
38070 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
38080 4e 29 20 73 6f 20 74 68 61 74 20 6e 6f 20 0a 2a  N) so that no .*
38090 2a 20 70 6f 69 6e 74 6c 65 73 73 20 6d 65 6d 6f  * pointless memo
380a0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 6f  ry allocations o
380b0 63 63 75 72 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  ccur..**.** ^SQL
380c0 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ite automaticall
380d0 79 20 66 72 65 65 73 20 74 68 65 20 6d 65 6d 6f  y frees the memo
380e0 72 79 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  ry allocated by 
380f0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72  .** sqlite3_aggr
38100 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
38110 77 68 65 6e 20 74 68 65 20 61 67 67 72 65 67 61  when the aggrega
38120 74 65 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64  te query conclud
38130 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  es..**.** The fi
38140 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75  rst parameter mu
38150 73 74 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20  st be a copy of 
38160 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
38170 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75  context | SQL fu
38180 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20  nction context] 
38190 74 68 61 74 20 69 73 20 74 68 65 20 66 69 72 73  that is the firs
381a0 74 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74  t parameter.** t
381b0 6f 20 74 68 65 20 78 53 74 65 70 20 6f 72 20 78  o the xStep or x
381c0 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72  Final callback r
381d0 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c  outine that impl
381e0 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67 72 65  ements the aggre
381f0 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  gate.** function
38200 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ..**.** This rou
38210 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c  tine must be cal
38220 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
38230 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63  e thread in whic
38240 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61  h.** the aggrega
38250 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  te SQL function 
38260 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76  is running..*/.v
38270 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67  oid *sqlite3_agg
38280 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73  regate_context(s
38290 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
382a0 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f   int nBytes);../
382b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55  *.** CAPI3REF: U
382c0 73 65 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e  ser Data For Fun
382d0 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44  ctions.** METHOD
382e0 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  : sqlite3_contex
382f0 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
38300 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29  ite3_user_data()
38310 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
38320 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  ns a copy of.** 
38330 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74  the pointer that
38340 20 77 61 73 20 74 68 65 20 70 55 73 65 72 44 61   was the pUserDa
38350 74 61 20 70 61 72 61 6d 65 74 65 72 20 28 74 68  ta parameter (th
38360 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 29  e 5th parameter)
38370 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
38380 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
38390 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ion()].** and [s
383a0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
383b0 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74  nction16()] rout
383c0 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e  ines that origin
383d0 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72  ally.** register
383e0 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ed the applicati
383f0 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on defined funct
38400 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ion..**.** This 
38410 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20  routine must be 
38420 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
38430 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
38440 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c  hich.** the appl
38450 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
38460 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
38470 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ing..*/.void *sq
38480 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
38490 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
384a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
384b0 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
384c0 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63  nection For Func
384d0 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  tions.** METHOD:
384e0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
384f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
38500 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
38510 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63  andle() interfac
38520 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79  e returns a copy
38530 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74   of.** the point
38540 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62  er to the [datab
38550 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
38560 28 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74  (the 1st paramet
38570 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  er).** of the [s
38580 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
38590 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64  nction()].** and
385a0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
385b0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72  _function16()] r
385c0 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69  outines that ori
385d0 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73  ginally.** regis
385e0 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63  tered the applic
385f0 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75  ation defined fu
38600 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c 69 74  nction..*/.sqlit
38610 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74  e3 *sqlite3_cont
38620 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71  ext_db_handle(sq
38630 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
38640 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
38650 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c  : Function Auxil
38660 69 61 72 79 20 44 61 74 61 0a 2a 2a 20 4d 45 54  iary Data.** MET
38670 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e  HOD: sqlite3_con
38680 74 65 78 74 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  text.**.** These
38690 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62   functions may b
386a0 65 20 75 73 65 64 20 62 79 20 28 6e 6f 6e 2d 61  e used by (non-a
386b0 67 67 72 65 67 61 74 65 29 20 53 51 4c 20 66 75  ggregate) SQL fu
386c0 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73  nctions to.** as
386d0 73 6f 63 69 61 74 65 20 6d 65 74 61 64 61 74 61  sociate metadata
386e0 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76   with argument v
386f0 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73 61  alues. If the sa
38700 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61 73 73  me value is pass
38710 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c  ed to.** multipl
38720 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66  e invocations of
38730 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75   the same SQL fu
38740 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75  nction during qu
38750 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75  ery execution, u
38760 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72  nder.** some cir
38770 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61  cumstances the a
38780 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61  ssociated metada
38790 74 61 20 6d 61 79 20 62 65 20 70 72 65 73 65 72  ta may be preser
387a0 76 65 64 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65  ved.  An example
387b0 0a 2a 2a 20 6f 66 20 77 68 65 72 65 20 74 68 69  .** of where thi
387c0 73 20 6d 69 67 68 74 20 62 65 20 75 73 65 66 75  s might be usefu
387d0 6c 20 69 73 20 69 6e 20 61 20 72 65 67 75 6c 61  l is in a regula
387e0 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74  r-expression mat
387f0 63 68 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f  ching.** functio
38800 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20  n. The compiled 
38810 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72  version of the r
38820 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f  egular expressio
38830 6e 20 63 61 6e 20