/ Hex Artifact Content
Login
SQLite training in Houston TX on 2019-11-05 (details)
Part of the 2019 Tcl Conference

Artifact ab77e511620eebbd4ed7e4f52fae697b6870dda66c945acd2d3066f99c98e17e:


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 43 41  define SQLITE_CA
5820: 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52  NTOPEN_NOTEMPDIR
5830: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
5840: 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29  NTOPEN | (1<<8))
5850: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5860: 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20  CANTOPEN_ISDIR  
5870: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5880: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38  CANTOPEN | (2<<8
5890: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
58a0: 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50  E_CANTOPEN_FULLP
58b0: 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54  ATH       (SQLIT
58c0: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c  E_CANTOPEN | (3<
58d0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
58e0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e  ITE_CANTOPEN_CON
58f0: 56 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c  VPATH       (SQL
5900: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
5910: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
5920: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54  QLITE_CORRUPT_VT
5930: 41 42 20 20 20 20 20 20 20 20 20 20 20 20 28 53  AB            (S
5940: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20  QLITE_CORRUPT | 
5950: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
5960: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f  SQLITE_READONLY_
5970: 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 28  RECOVERY       (
5980: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
5990: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
59a0: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
59b0: 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20  Y_CANTLOCK      
59c0: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   (SQLITE_READONL
59d0: 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  Y | (2<<8)).#def
59e0: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
59f0: 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20  NLY_ROLLBACK    
5a00: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f     (SQLITE_READO
5a10: 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64  NLY | (3<<8)).#d
5a20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
5a30: 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20 20 20  DONLY_DBMOVED   
5a40: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
5a50: 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29 29 0a  DONLY | (4<<8)).
5a60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
5a70: 42 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20  BORT_ROLLBACK   
5a80: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41         (SQLITE_A
5a90: 42 4f 52 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23  BORT | (2<<8)).#
5aa0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5ab0: 4e 53 54 52 41 49 4e 54 5f 43 48 45 43 4b 20 20  NSTRAINT_CHECK  
5ac0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5ad0: 4e 53 54 52 41 49 4e 54 20 7c 20 28 31 3c 3c 38  NSTRAINT | (1<<8
5ae0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5af0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 4f 4d  E_CONSTRAINT_COM
5b00: 4d 49 54 48 4f 4f 4b 20 20 20 28 53 51 4c 49 54  MITHOOK   (SQLIT
5b10: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5b20: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
5b30: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5b40: 5f 46 4f 52 45 49 47 4e 4b 45 59 20 20 20 28 53  _FOREIGNKEY   (S
5b50: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5b60: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69   | (3<<8)).#defi
5b70: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5b80: 41 49 4e 54 5f 46 55 4e 43 54 49 4f 4e 20 20 20  AINT_FUNCTION   
5b90: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5ba0: 41 49 4e 54 20 7c 20 28 34 3c 3c 38 29 29 0a 23  AINT | (4<<8)).#
5bb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5bc0: 4e 53 54 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c  NSTRAINT_NOTNULL
5bd0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5be0: 4e 53 54 52 41 49 4e 54 20 7c 20 28 35 3c 3c 38  NSTRAINT | (5<<8
5bf0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5c00: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 50 52 49  E_CONSTRAINT_PRI
5c10: 4d 41 52 59 4b 45 59 20 20 20 28 53 51 4c 49 54  MARYKEY   (SQLIT
5c20: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5c30: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
5c40: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5c50: 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 28 53  _TRIGGER      (S
5c60: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5c70: 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69   | (7<<8)).#defi
5c80: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5c90: 41 49 4e 54 5f 55 4e 49 51 55 45 20 20 20 20 20  AINT_UNIQUE     
5ca0: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5cb0: 41 49 4e 54 20 7c 20 28 38 3c 3c 38 29 29 0a 23  AINT | (8<<8)).#
5cc0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5cd0: 4e 53 54 52 41 49 4e 54 5f 56 54 41 42 20 20 20  NSTRAINT_VTAB   
5ce0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5cf0: 4e 53 54 52 41 49 4e 54 20 7c 20 28 39 3c 3c 38  NSTRAINT | (9<<8
5d00: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5d10: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 52 4f 57  E_CONSTRAINT_ROW
5d20: 49 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  ID        (SQLIT
5d30: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 28 31  E_CONSTRAINT |(1
5d40: 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  0<<8)).#define S
5d50: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43  QLITE_NOTICE_REC
5d60: 4f 56 45 52 5f 57 41 4c 20 20 20 20 20 20 28 53  OVER_WAL      (S
5d70: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28  QLITE_NOTICE | (
5d80: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5d90: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43  QLITE_NOTICE_REC
5da0: 4f 56 45 52 5f 52 4f 4c 4c 42 41 43 4b 20 28 53  OVER_ROLLBACK (S
5db0: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28  QLITE_NOTICE | (
5dc0: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
5dd0: 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 5f 41 55  QLITE_WARNING_AU
5de0: 54 4f 49 4e 44 45 58 20 20 20 20 20 20 20 28 53  TOINDEX       (S
5df0: 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 7c 20  QLITE_WARNING | 
5e00: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
5e10: 53 51 4c 49 54 45 5f 41 55 54 48 5f 55 53 45 52  SQLITE_AUTH_USER
5e20: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28                 (
5e30: 53 51 4c 49 54 45 5f 41 55 54 48 20 7c 20 28 31  SQLITE_AUTH | (1
5e40: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5e50: 4c 49 54 45 5f 4f 4b 5f 4c 4f 41 44 5f 50 45 52  LITE_OK_LOAD_PER
5e60: 4d 41 4e 45 4e 54 4c 59 20 20 20 20 20 28 53 51  MANENTLY     (SQ
5e70: 4c 49 54 45 5f 4f 4b 20 7c 20 28 31 3c 3c 38 29  LITE_OK | (1<<8)
5e80: 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  )../*.** CAPI3RE
5e90: 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69 6c  F: Flags For Fil
5ea0: 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e  e Open Operation
5eb0: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69  s.**.** These bi
5ec0: 74 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 74  t values are int
5ed0: 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e  ended for use in
5ee0: 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72 61   the.** 3rd para
5ef0: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  meter to the [sq
5f00: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
5f10: 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a 2a   interface and.*
5f20: 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70 61 72  * in the 4th 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 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
5f50: 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23 64 65  ] method..*/.#de
5f60: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5f70: 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20  _READONLY       
5f80: 20 20 30 78 30 30 30 30 30 30 30 31 20 20 2f 2a    0x00000001  /*
5f90: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
5fa0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
5fb0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5fc0: 5f 52 45 41 44 57 52 49 54 45 20 20 20 20 20 20  _READWRITE      
5fd0: 20 20 30 78 30 30 30 30 30 30 30 32 20 20 2f 2a    0x00000002  /*
5fe0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
5ff0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
6000: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6010: 5f 43 52 45 41 54 45 20 20 20 20 20 20 20 20 20  _CREATE         
6020: 20 20 30 78 30 30 30 30 30 30 30 34 20 20 2f 2a    0x00000004  /*
6030: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
6040: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
6050: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6060: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20  _DELETEONCLOSE  
6070: 20 20 30 78 30 30 30 30 30 30 30 38 20 20 2f 2a    0x00000008  /*
6080: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6090: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
60a0: 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 20  _EXCLUSIVE      
60b0: 20 20 30 78 30 30 30 30 30 30 31 30 20 20 2f 2a    0x00000010  /*
60c0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
60d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
60e0: 5f 41 55 54 4f 50 52 4f 58 59 20 20 20 20 20 20  _AUTOPROXY      
60f0: 20 20 30 78 30 30 30 30 30 30 32 30 20 20 2f 2a    0x00000020  /*
6100: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6110: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6120: 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 20 20  _URI            
6130: 20 20 30 78 30 30 30 30 30 30 34 30 20 20 2f 2a    0x00000040  /*
6140: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
6150: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
6160: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6170: 5f 4d 45 4d 4f 52 59 20 20 20 20 20 20 20 20 20  _MEMORY         
6180: 20 20 30 78 30 30 30 30 30 30 38 30 20 20 2f 2a    0x00000080  /*
6190: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
61a0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
61b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
61c0: 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20  _MAIN_DB        
61d0: 20 20 30 78 30 30 30 30 30 31 30 30 20 20 2f 2a    0x00000100  /*
61e0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
61f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6200: 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20  _TEMP_DB        
6210: 20 20 30 78 30 30 30 30 30 32 30 30 20 20 2f 2a    0x00000200  /*
6220: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6230: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6240: 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20  _TRANSIENT_DB   
6250: 20 20 30 78 30 30 30 30 30 34 30 30 20 20 2f 2a    0x00000400  /*
6260: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6270: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6280: 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20  _MAIN_JOURNAL   
6290: 20 20 30 78 30 30 30 30 30 38 30 30 20 20 2f 2a    0x00000800  /*
62a0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
62b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
62c0: 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20  _TEMP_JOURNAL   
62d0: 20 20 30 78 30 30 30 30 31 30 30 30 20 20 2f 2a    0x00001000  /*
62e0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
62f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6300: 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20  _SUBJOURNAL     
6310: 20 20 30 78 30 30 30 30 32 30 30 30 20 20 2f 2a    0x00002000  /*
6320: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6330: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6340: 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20  _MASTER_JOURNAL 
6350: 20 20 30 78 30 30 30 30 34 30 30 30 20 20 2f 2a    0x00004000  /*
6360: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6370: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6380: 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20  _NOMUTEX        
6390: 20 20 30 78 30 30 30 30 38 30 30 30 20 20 2f 2a    0x00008000  /*
63a0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
63b0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
63c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
63d0: 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20  _FULLMUTEX      
63e0: 20 20 30 78 30 30 30 31 30 30 30 30 20 20 2f 2a    0x00010000  /*
63f0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
6400: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
6410: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6420: 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20  _SHAREDCACHE    
6430: 20 20 30 78 30 30 30 32 30 30 30 30 20 20 2f 2a    0x00020000  /*
6440: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
6450: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
6460: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6470: 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 20 20  _PRIVATECACHE   
6480: 20 20 30 78 30 30 30 34 30 30 30 30 20 20 2f 2a    0x00040000  /*
6490: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
64a0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
64b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
64c0: 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20  _WAL            
64d0: 20 20 30 78 30 30 30 38 30 30 30 30 20 20 2f 2a    0x00080000  /*
64e0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a   VFS only */../*
64f0: 20 52 65 73 65 72 76 65 64 3a 20 20 20 20 20 20   Reserved:      
6500: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6510: 20 20 20 30 78 30 30 46 30 30 30 30 30 20 2a 2f     0x00F00000 */
6520: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
6530: 3a 20 44 65 76 69 63 65 20 43 68 61 72 61 63 74  : Device Charact
6540: 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54  eristics.**.** T
6550: 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63  he xDeviceCharac
6560: 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64  teristics method
6570: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
6580: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  _io_methods].** 
6590: 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73 20 61  object returns a
65a0: 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
65b0: 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66 20 74  is a vector of t
65c0: 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75  hese.** bit valu
65d0: 65 73 20 65 78 70 72 65 73 73 69 6e 67 20 49 2f  es expressing I/
65e0: 4f 20 63 68 61 72 61 63 74 65 72 69 73 74 69 63  O characteristic
65f0: 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73 74  s of the mass st
6600: 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 20  orage.** device 
6610: 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20 66  that holds the f
6620: 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73 71  ile that the [sq
6630: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
6640: 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a  ].** refers to..
6650: 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  **.** The SQLITE
6660: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72  _IOCAP_ATOMIC pr
6670: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
6680: 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a  t all writes of.
6690: 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20  ** any size are 
66a0: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
66b0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
66c0: 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65  nnn values.** me
66d0: 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f  an that writes o
66e0: 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72  f blocks that ar
66f0: 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73  e nnn bytes in s
6700: 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61  ize and.** are a
6710: 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64  ligned to an add
6720: 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e  ress which is an
6730: 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c   integer multipl
6740: 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20  e of.** nnn are 
6750: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
6760: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
6770: 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e  PPEND value mean
6780: 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64  s.** that when d
6790: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20  ata is appended 
67a0: 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64  to a file, the d
67b0: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a  ata is appended.
67c0: 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68  ** first then th
67d0: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69  e size of the fi
67e0: 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20  le is extended, 
67f0: 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a  never the other.
6800: 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20  ** way around.  
6810: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
6820: 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70  _SEQUENTIAL prop
6830: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a  erty means that.
6840: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ** information i
6850: 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73  s written to dis
6860: 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72  k in the same or
6870: 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20  der as calls.** 
6880: 74 6f 20 78 57 72 69 74 65 28 29 2e 20 20 54 68  to xWrite().  Th
6890: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50  e SQLITE_IOCAP_P
68a0: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
68b0: 54 45 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  TE property mean
68c0: 73 20 74 68 61 74 0a 2a 2a 20 61 66 74 65 72 20  s that.** after 
68d0: 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77 69 6e 67  reboot following
68e0: 20 61 20 63 72 61 73 68 20 6f 72 20 70 6f 77 65   a crash or powe
68f0: 72 20 6c 6f 73 73 2c 20 74 68 65 20 6f 6e 6c 79  r loss, the only
6900: 20 62 79 74 65 73 20 69 6e 20 61 0a 2a 2a 20 66   bytes in a.** f
6910: 69 6c 65 20 74 68 61 74 20 77 65 72 65 20 77 72  ile that were wr
6920: 69 74 74 65 6e 20 61 74 20 74 68 65 20 61 70 70  itten at the app
6930: 6c 69 63 61 74 69 6f 6e 20 6c 65 76 65 6c 20 6d  lication level m
6940: 69 67 68 74 20 68 61 76 65 20 63 68 61 6e 67 65  ight have change
6950: 64 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 61 64  d.** and that ad
6960: 6a 61 63 65 6e 74 20 62 79 74 65 73 2c 20 65 76  jacent bytes, ev
6970: 65 6e 20 62 79 74 65 73 20 77 69 74 68 69 6e 20  en bytes within 
6980: 74 68 65 20 73 61 6d 65 20 73 65 63 74 6f 72 20  the same sector 
6990: 61 72 65 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65  are.** guarantee
69a0: 64 20 74 6f 20 62 65 20 75 6e 63 68 61 6e 67 65  d to be unchange
69b0: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  d.  The SQLITE_I
69c0: 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45  OCAP_UNDELETABLE
69d0: 5f 57 48 45 4e 5f 4f 50 45 4e 0a 2a 2a 20 66 6c  _WHEN_OPEN.** fl
69e0: 61 67 20 69 6e 64 69 63 61 74 65 73 20 74 68 61  ag indicates tha
69f0: 74 20 61 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20  t a file cannot 
6a00: 62 65 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  be deleted when 
6a10: 6f 70 65 6e 2e 20 20 54 68 65 0a 2a 2a 20 53 51  open.  The.** SQ
6a20: 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54  LITE_IOCAP_IMMUT
6a30: 41 42 4c 45 20 66 6c 61 67 20 69 6e 64 69 63 61  ABLE flag indica
6a40: 74 65 73 20 74 68 61 74 20 74 68 65 20 66 69 6c  tes that the fil
6a50: 65 20 69 73 20 6f 6e 0a 2a 2a 20 72 65 61 64 2d  e is on.** read-
6a60: 6f 6e 6c 79 20 6d 65 64 69 61 20 61 6e 64 20 63  only media and c
6a70: 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64  annot be changed
6a80: 20 65 76 65 6e 20 62 79 20 70 72 6f 63 65 73 73   even by process
6a90: 65 73 20 77 69 74 68 0a 2a 2a 20 65 6c 65 76 61  es with.** eleva
6aa0: 74 65 64 20 70 72 69 76 69 6c 65 67 65 73 2e 0a  ted privileges..
6ab0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6ac0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20  E_IOCAP_ATOMIC  
6ad0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
6ae0: 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e  x00000001.#defin
6af0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6b00: 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20 20  TOMIC512        
6b10: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32        0x00000002
6b20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6b30: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20  IOCAP_ATOMIC1K  
6b40: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6b50: 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20  0000004.#define 
6b60: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6b70: 4d 49 43 32 4b 20 20 20 20 20 20 20 20 20 20 20  MIC2K           
6b80: 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0a 23      0x00000008.#
6b90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6ba0: 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20  CAP_ATOMIC4K    
6bb0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6bc0: 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51  00010.#define SQ
6bd0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6be0: 43 38 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  C8K             
6bf0: 20 20 30 78 30 30 30 30 30 30 32 30 0a 23 64 65    0x00000020.#de
6c00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6c10: 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20  P_ATOMIC16K     
6c20: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6c30: 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  040.#define SQLI
6c40: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33  TE_IOCAP_ATOMIC3
6c50: 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  2K              
6c60: 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 69  0x00000080.#defi
6c70: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6c80: 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20  ATOMIC64K       
6c90: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30         0x0000010
6ca0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6cb0: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45  _IOCAP_SAFE_APPE
6cc0: 4e 44 20 20 20 20 20 20 20 20 20 20 20 20 30 78  ND            0x
6cd0: 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65  00000200.#define
6ce0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45   SQLITE_IOCAP_SE
6cf0: 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20 20 20  QUENTIAL        
6d00: 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 0a       0x00000400.
6d10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6d20: 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45  OCAP_UNDELETABLE
6d30: 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30  _WHEN_OPEN  0x00
6d40: 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53  000800.#define S
6d50: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45  QLITE_IOCAP_POWE
6d60: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20  RSAFE_OVERWRITE 
6d70: 20 20 20 30 78 30 30 30 30 31 30 30 30 0a 23 64     0x00001000.#d
6d80: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6d90: 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 20 20 20  AP_IMMUTABLE    
6da0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6db0: 32 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  2000../*.** CAPI
6dc0: 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69  3REF: File Locki
6dd0: 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20  ng Levels.**.** 
6de0: 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20  SQLite uses one 
6df0: 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72  of these integer
6e00: 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73   values as the s
6e10: 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e  econd.** argumen
6e20: 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61  t to calls it ma
6e30: 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b  kes to the xLock
6e40: 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29  () and xUnlock()
6e50: 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61   methods.** of a
6e60: 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  n [sqlite3_io_me
6e70: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a  thods] object..*
6e80: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6e90: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20  _LOCK_NONE      
6ea0: 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
6eb0: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
6ec0: 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
6ed0: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45  e SQLITE_LOCK_RE
6ee0: 53 45 52 56 45 44 20 20 20 20 20 20 32 0a 23 64  SERVED      2.#d
6ef0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
6f00: 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20  K_PENDING       
6f10: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
6f20: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20  _LOCK_EXCLUSIVE 
6f30: 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      4../*.** CAP
6f40: 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69  I3REF: Synchroni
6f50: 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67  zation Type Flag
6f60: 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c  s.**.** When SQL
6f70: 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20  ite invokes the 
6f80: 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f  xSync() method o
6f90: 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  f an.** [sqlite3
6fa0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
6fb0: 65 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f  ect it uses a co
6fc0: 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20  mbination of.** 
6fd0: 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61  these integer va
6fe0: 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f  lues as the seco
6ff0: 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  nd argument..**.
7000: 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49  ** When the SQLI
7010: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
7020: 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69   flag is used, i
7030: 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  t means that the
7040: 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69  .** sync operati
7050: 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f  on only needs to
7060: 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d   flush data to m
7070: 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e  ass storage.  In
7080: 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  ode.** informati
7090: 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66  on need not be f
70a0: 6c 75 73 68 65 64 2e 20 49 66 20 74 68 65 20 6c  lushed. If the l
70b0: 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 6f  ower four bits o
70c0: 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71  f the flag.** eq
70d0: 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ual SQLITE_SYNC_
70e0: 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61  NORMAL, that mea
70f0: 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c  ns to use normal
7100: 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69   fsync() semanti
7110: 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f  cs..** If the lo
7120: 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 65 71  wer four bits eq
7130: 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ual SQLITE_SYNC_
7140: 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73  FULL, that means
7150: 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f  .** to use Mac O
7160: 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79  S X style fullsy
7170: 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73  nc instead of fs
7180: 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20  ync()..**.** Do 
7190: 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74 68 65 20  not confuse the 
71a0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
71b0: 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59  AL and SQLITE_SY
71c0: 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a  NC_FULL flags.**
71d0: 20 77 69 74 68 20 74 68 65 20 5b 50 52 41 47 4d   with the [PRAGM
71e0: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e  A synchronous]=N
71f0: 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47 4d  ORMAL and [PRAGM
7200: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46  A synchronous]=F
7210: 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73 2e  ULL.** settings.
7220: 20 20 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e 6f    The [synchrono
7230: 75 73 20 70 72 61 67 6d 61 5d 20 64 65 74 65 72  us pragma] deter
7240: 6d 69 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c 73  mines when calls
7250: 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e 63   to the.** xSync
7260: 20 56 46 53 20 6d 65 74 68 6f 64 20 6f 63 63 75   VFS method occu
7270: 72 20 61 6e 64 20 61 70 70 6c 69 65 73 20 75 6e  r and applies un
7280: 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20 61  iformly across a
7290: 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a  ll platforms..**
72a0: 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   The SQLITE_SYNC
72b0: 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49  _NORMAL and SQLI
72c0: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61  TE_SYNC_FULL fla
72d0: 67 73 20 64 65 74 65 72 6d 69 6e 65 20 68 6f 77  gs determine how
72e0: 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63 20 6f 72  .** energetic or
72f0: 20 72 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f 72   rigorous or for
7300: 63 65 66 75 6c 20 74 68 65 20 73 79 6e 63 20 6f  ceful the sync o
7310: 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20 61 6e  perations are an
7320: 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 61  d.** only make a
7330: 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 20 4d   difference on M
7340: 61 63 20 4f 53 58 20 66 6f 72 20 74 68 65 20 64  ac OSX for the d
7350: 65 66 61 75 6c 74 20 53 51 4c 69 74 65 20 63 6f  efault SQLite co
7360: 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70 61  de..** (Third-pa
7370: 72 74 79 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  rty VFS implemen
7380: 74 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 61 6c  tations might al
7390: 73 6f 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74  so make the dist
73a0: 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65  inction.** betwe
73b0: 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  en SQLITE_SYNC_N
73c0: 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45  ORMAL and SQLITE
73d0: 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 20  _SYNC_FULL, but 
73e0: 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 65  among the.** ope
73f0: 72 61 74 69 6e 67 20 73 79 73 74 65 6d 73 20 6e  rating systems n
7400: 61 74 69 76 65 6c 79 20 73 75 70 70 6f 72 74 65  atively supporte
7410: 64 20 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e 6c  d by SQLite, onl
7420: 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61 72  y Mac OSX.** car
7430: 65 73 20 61 62 6f 75 74 20 74 68 65 20 64 69 66  es about the dif
7440: 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65  ference.).*/.#de
7450: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43  fine SQLITE_SYNC
7460: 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30  _NORMAL        0
7470: 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53  x00002.#define S
7480: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
7490: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 33           0x00003
74a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
74b0: 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20  SYNC_DATAONLY   
74c0: 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a     0x00010../*.*
74d0: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49  * CAPI3REF: OS I
74e0: 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69  nterface Open Fi
74f0: 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20  le Handle.**.** 
7500: 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  An [sqlite3_file
7510: 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65  ] object represe
7520: 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  nts an open file
7530: 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c   in the .** [sql
7540: 69 74 65 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e  ite3_vfs | OS in
7550: 74 65 72 66 61 63 65 20 6c 61 79 65 72 5d 2e 20  terface layer]. 
7560: 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69   Individual OS i
7570: 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c  nterface.** impl
7580: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c  ementations will
7590: 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63  .** want to subc
75a0: 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74  lass this object
75b0: 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64   by appending ad
75c0: 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a  ditional fields.
75d0: 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e  ** for their own
75e0: 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68   use.  The pMeth
75f0: 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61 20 70  ods entry is a p
7600: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
7610: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
7620: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74  ods] object that
7630: 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73   defines methods
7640: 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a   for performing.
7650: 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e  ** I/O operation
7660: 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69  s on the open fi
7670: 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  le..*/.typedef s
7680: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69  truct sqlite3_fi
7690: 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b  le sqlite3_file;
76a0: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
76b0: 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73  file {.  const s
76c0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
76d0: 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f  _methods *pMetho
76e0: 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  ds;  /* Methods 
76f0: 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  for an open file
7700: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
7710: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
7720: 66 61 63 65 20 46 69 6c 65 20 56 69 72 74 75 61  face File Virtua
7730: 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74  l Methods Object
7740: 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c  .**.** Every fil
7750: 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20  e opened by the 
7760: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
7770: 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c  en] method popul
7780: 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  ates an.** [sqli
7790: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
77a0: 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f   (or, more commo
77b0: 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73 20  nly, a subclass 
77c0: 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
77d0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29  e3_file] object)
77e0: 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20   with a pointer 
77f0: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
7800: 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a  f this object..*
7810: 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65  * This object de
7820: 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f 64  fines the method
7830: 73 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72  s used to perfor
7840: 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74  m various operat
7850: 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20  ions.** against 
7860: 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 65  the open file re
7870: 70 72 65 73 65 6e 74 65 64 20 62 79 20 74 68 65  presented by the
7880: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
7890: 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66  object..**.** If
78a0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
78b0: 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20  s.xOpen] method 
78c0: 73 65 74 73 20 74 68 65 20 73 71 6c 69 74 65 33  sets the sqlite3
78d0: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65  _file.pMethods e
78e0: 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 20  lement .** to a 
78f0: 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  non-NULL pointer
7900: 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74  , then the sqlit
7910: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 43  e3_io_methods.xC
7920: 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d  lose method.** m
7930: 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 76  ay be invoked ev
7940: 65 6e 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74  en if the [sqlit
7950: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 72 65  e3_vfs.xOpen] re
7960: 70 6f 72 74 65 64 20 74 68 61 74 20 69 74 20 66  ported that it f
7970: 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f  ailed.  The.** o
7980: 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 65 76 65  nly way to preve
7990: 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c  nt a call to xCl
79a0: 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  ose following a 
79b0: 66 61 69 6c 65 64 20 5b 73 71 6c 69 74 65 33 5f  failed [sqlite3_
79c0: 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73  vfs.xOpen].** is
79d0: 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65   for the [sqlite
79e0: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74 6f 20  3_vfs.xOpen] to 
79f0: 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f  set the sqlite3_
7a00: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c  file.pMethods el
7a10: 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c  ement.** to NULL
7a20: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67  ..**.** The flag
7a30: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53  s argument to xS
7a40: 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f  ync may be one o
7a50: 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  f [SQLITE_SYNC_N
7a60: 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51  ORMAL] or.** [SQ
7a70: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e  LITE_SYNC_FULL].
7a80: 20 20 54 68 65 20 66 69 72 73 74 20 63 68 6f 69    The first choi
7a90: 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c  ce is the normal
7aa0: 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65   fsync()..** The
7ab0: 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69   second choice i
7ac0: 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73 74 79  s a Mac OS X sty
7ad0: 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68  le fullsync.  Th
7ae0: 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  e [SQLITE_SYNC_D
7af0: 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67  ATAONLY].** flag
7b00: 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20   may be ORed in 
7b10: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  to indicate that
7b20: 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f   only the data o
7b30: 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e  f the file.** an
7b40: 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20  d not its inode 
7b50: 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63  needs to be sync
7b60: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  ed..**.** The in
7b70: 74 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20  teger values to 
7b80: 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c  xLock() and xUnl
7b90: 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66  ock() are one of
7ba0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
7bb0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f   [SQLITE_LOCK_NO
7bc0: 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  NE],.** <li> [SQ
7bd0: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
7be0: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
7bf0: 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44  TE_LOCK_RESERVED
7c00: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
7c10: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d  TE_LOCK_PENDING]
7c20: 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  , or.** <li> [SQ
7c30: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53  LITE_LOCK_EXCLUS
7c40: 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  IVE]..** </ul>.*
7c50: 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61  * xLock() increa
7c60: 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55  ses the lock. xU
7c70: 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65  nlock() decrease
7c80: 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54  s the lock..** T
7c90: 68 65 20 78 43 68 65 63 6b 52 65 73 65 72 76 65  he xCheckReserve
7ca0: 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63  dLock() method c
7cb0: 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e  hecks whether an
7cc0: 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  y database conne
7cd0: 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72  ction,.** either
7ce0: 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73   in this process
7cf0: 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65   or in some othe
7d00: 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f  r process, is ho
7d10: 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56 45 44  lding a RESERVED
7d20: 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72  ,.** PENDING, or
7d30: 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20   EXCLUSIVE lock 
7d40: 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74  on the file.  It
7d50: 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a   returns true.**
7d60: 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20   if such a lock 
7d70: 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65  exists and false
7d80: 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a   otherwise..**.*
7d90: 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  * The xFileContr
7da0: 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61  ol() method is a
7db0: 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61   generic interfa
7dc0: 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63  ce that allows c
7dd0: 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70  ustom.** VFS imp
7de0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20  lementations to 
7df0: 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c  directly control
7e00: 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73   an open file us
7e10: 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ing the.** [sqli
7e20: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
7e30: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ()] interface.  
7e40: 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20  The second "op" 
7e50: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a  argument is an.*
7e60: 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65  * integer opcode
7e70: 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67  .  The third arg
7e80: 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72  ument is a gener
7e90: 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e  ic pointer inten
7ea0: 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20  ded to.** point 
7eb0: 74 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 74  to a structure t
7ec0: 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20  hat may contain 
7ed0: 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61  arguments or spa
7ee0: 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a  ce in which to.*
7ef0: 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 76  * write return v
7f00: 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61  alues.  Potentia
7f10: 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65  l uses for xFile
7f20: 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20  Control() might 
7f30: 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  be.** functions 
7f40: 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69  to enable blocki
7f50: 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69  ng locks with ti
7f60: 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67  meouts, to chang
7f70: 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67  e the.** locking
7f80: 20 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 65   strategy (for e
7f90: 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f  xample to use do
7fa0: 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74  t-file locks), t
7fb0: 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f  o inquire.** abo
7fc0: 75 74 20 74 68 65 20 73 74 61 74 75 73 20 6f 66  ut the status of
7fd0: 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62   a lock, or to b
7fe0: 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73  reak stale locks
7ff0: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a  .  The SQLite.**
8000: 20 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 61   core reserves a
8010: 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20  ll opcodes less 
8020: 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73  than 100 for its
8030: 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b   own use..** A [
8040: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63  file control opc
8050: 6f 64 65 73 20 7c 20 6c 69 73 74 20 6f 66 20 6f  odes | list of o
8060: 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61  pcodes] less tha
8070: 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c 61 62  n 100 is availab
8080: 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  le..** Applicati
8090: 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65 20  ons that define 
80a0: 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f  a custom xFileCo
80b0: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f  ntrol method sho
80c0: 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73 0a  uld use opcodes.
80d0: 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  ** greater than 
80e0: 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e  100 to avoid con
80f0: 66 6c 69 63 74 73 2e 20 20 56 46 53 20 69 6d 70  flicts.  VFS imp
8100: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f  lementations sho
8110: 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  uld.** return [S
8120: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20  QLITE_NOTFOUND] 
8130: 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  for file control
8140: 20 6f 70 63 6f 64 65 73 20 74 68 61 74 20 74 68   opcodes that th
8150: 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63  ey do not.** rec
8160: 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  ognize..**.** Th
8170: 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29 20  e xSectorSize() 
8180: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 74  method returns t
8190: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 6f  he sector size o
81a0: 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 20  f the.** device 
81b0: 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20 74  that underlies t
81c0: 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73 65  he file.  The se
81d0: 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68 65  ctor size is the
81e0: 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74  .** minimum writ
81f0: 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 65  e that can be pe
8200: 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 20  rformed without 
8210: 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74  disturbing.** ot
8220: 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68 65  her bytes in the
8230: 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65 76   file.  The xDev
8240: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
8250: 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72  cs().** method r
8260: 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65 63  eturns a bit vec
8270: 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20 62  tor describing b
8280: 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65 0a  ehaviors of the.
8290: 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 65  ** underlying de
82a0: 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  vice:.**.** <ul>
82b0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
82c0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a  _IOCAP_ATOMIC].*
82d0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
82e0: 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a  OCAP_ATOMIC512].
82f0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8300: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a  IOCAP_ATOMIC1K].
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 32 4b 5d 0a  IOCAP_ATOMIC2K].
8330: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8340: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a  IOCAP_ATOMIC4K].
8350: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8360: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a  IOCAP_ATOMIC8K].
8370: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8380: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d  IOCAP_ATOMIC16K]
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 33 32 4b  _IOCAP_ATOMIC32K
83b0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
83c0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34  E_IOCAP_ATOMIC64
83d0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
83e0: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
83f0: 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  PEND].** <li> [S
8400: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
8410: 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  ENTIAL].** <li> 
8420: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e  [SQLITE_IOCAP_UN
8430: 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f  DELETABLE_WHEN_O
8440: 50 45 4e 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  PEN].** <li> [SQ
8450: 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52  LITE_IOCAP_POWER
8460: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 0a  SAFE_OVERWRITE].
8470: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8480: 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 5d  IOCAP_IMMUTABLE]
8490: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
84a0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
84b0: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79  _ATOMIC property
84c0: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20   means that all 
84d0: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79  writes of.** any
84e0: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63   size are atomic
84f0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
8500: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61  CAP_ATOMICnnn va
8510: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61  lues.** mean tha
8520: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63  t writes of bloc
8530: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20  ks that are nnn 
8540: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
8550: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64  d.** are aligned
8560: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77   to an address w
8570: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67  hich is an integ
8580: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a  er multiple of.*
8590: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63  * nnn are atomic
85a0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
85b0: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
85c0: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74  value means.** t
85d0: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73  hat when data is
85e0: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66   appended to a f
85f0: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73  ile, the data is
8600: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72   appended.** fir
8610: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65  st then the size
8620: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   of the file is 
8630: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20  extended, never 
8640: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79  the other.** way
8650: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51   around.  The SQ
8660: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
8670: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d  NTIAL property m
8680: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66  eans that.** inf
8690: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74  ormation is writ
86a0: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74  ten to disk in t
86b0: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73  he same order as
86c0: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72   calls.** to xWr
86d0: 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ite()..**.** If 
86e0: 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73 20  xRead() returns 
86f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f  SQLITE_IOERR_SHO
8700: 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20  RT_READ it must 
8710: 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20  also fill.** in 
8720: 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69  the unread porti
8730: 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66 65  ons of the buffe
8740: 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41  r with zeros.  A
8750: 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69   VFS that.** fai
8760: 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20  ls to zero-fill 
8770: 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68  short reads migh
8780: 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20  t seem to work. 
8790: 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69   However,.** fai
87a0: 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c  lure to zero-fil
87b0: 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77 69  l short reads wi
87c0: 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65  ll eventually le
87d0: 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73  ad to.** databas
87e0: 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f  e corruption..*/
87f0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
8800: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
8810: 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ds sqlite3_io_me
8820: 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
8830: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
8840: 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
8850: 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73  n;.  int (*xClos
8860: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
8870: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64  );.  int (*xRead
8880: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8890: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74   void*, int iAmt
88a0: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
88b0: 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a  iOfst);.  int (*
88c0: 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f  xWrite)(sqlite3_
88d0: 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  file*, const voi
88e0: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71  d*, int iAmt, sq
88f0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
8900: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75  t);.  int (*xTru
8910: 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66  ncate)(sqlite3_f
8920: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
8930: 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74  t64 size);.  int
8940: 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65   (*xSync)(sqlite
8950: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61  3_file*, int fla
8960: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  gs);.  int (*xFi
8970: 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f  leSize)(sqlite3_
8980: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
8990: 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20  nt64 *pSize);.  
89a0: 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c  int (*xLock)(sql
89b0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29  ite3_file*, int)
89c0: 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63  ;.  int (*xUnloc
89d0: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
89e0: 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a  , int);.  int (*
89f0: 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f  xCheckReservedLo
8a00: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
8a10: 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29  *, int *pResOut)
8a20: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43  ;.  int (*xFileC
8a30: 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f  ontrol)(sqlite3_
8a40: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76  file*, int op, v
8a50: 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e  oid *pArg);.  in
8a60: 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29  t (*xSectorSize)
8a70: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
8a80: 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65  .  int (*xDevice
8a90: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 29  Characteristics)
8aa0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
8ab0: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62  .  /* Methods ab
8ac0: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f  ove are valid fo
8ad0: 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20  r version 1 */. 
8ae0: 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29 28   int (*xShmMap)(
8af0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8b00: 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73 7a  nt iPg, int pgsz
8b10: 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61  , int, void vola
8b20: 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28  tile**);.  int (
8b30: 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74  *xShmLock)(sqlit
8b40: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66  e3_file*, int of
8b50: 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74  fset, int n, int
8b60: 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64 20   flags);.  void 
8b70: 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28 73  (*xShmBarrier)(s
8b80: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
8b90: 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70   int (*xShmUnmap
8ba0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8bb0: 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67 29   int deleteFlag)
8bc0: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
8bd0: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
8be0: 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a  or version 2 */.
8bf0: 20 20 69 6e 74 20 28 2a 78 46 65 74 63 68 29 28    int (*xFetch)(
8c00: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
8c10: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
8c20: 73 74 2c 20 69 6e 74 20 69 41 6d 74 2c 20 76 6f  st, int iAmt, vo
8c30: 69 64 20 2a 2a 70 70 29 3b 0a 20 20 69 6e 74 20  id **pp);.  int 
8c40: 28 2a 78 55 6e 66 65 74 63 68 29 28 73 71 6c 69  (*xUnfetch)(sqli
8c50: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
8c60: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20  e3_int64 iOfst, 
8c70: 76 6f 69 64 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d  void *p);.  /* M
8c80: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
8c90: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69   valid for versi
8ca0: 6f 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20 41 64 64  on 3 */.  /* Add
8cb0: 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20  itional methods 
8cc0: 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
8cd0: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
8ce0: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
8cf0: 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20  I3REF: Standard 
8d00: 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63  File Control Opc
8d10: 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  odes.** KEYWORDS
8d20: 3a 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  : {file control 
8d30: 6f 70 63 6f 64 65 73 7d 20 7b 66 69 6c 65 20 63  opcodes} {file c
8d40: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 7d 0a 2a  ontrol opcode}.*
8d50: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67  *.** These integ
8d60: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  er constants are
8d70: 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65   opcodes for the
8d80: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
8d90: 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  thod.** of the [
8da0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
8db0: 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66  ds] object and f
8dc0: 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  or the [sqlite3_
8dd0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a  file_control()].
8de0: 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  ** interface..**
8df0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
8e00: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c  [[SQLITE_FCNTL_L
8e10: 4f 43 4b 53 54 41 54 45 5d 5d 0a 2a 2a 20 54 68  OCKSTATE]].** Th
8e20: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
8e30: 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64  LOCKSTATE] opcod
8e40: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65  e is used for de
8e50: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a  bugging.  This.*
8e60: 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20  * opcode causes 
8e70: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
8e80: 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65   method to write
8e90: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
8ea0: 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63  te of.** the loc
8eb0: 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  k (one of [SQLIT
8ec0: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53  E_LOCK_NONE], [S
8ed0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
8ee0: 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c  D],.** [SQLITE_L
8ef0: 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b  OCK_RESERVED], [
8f00: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
8f10: 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  ING], or [SQLITE
8f20: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d  _LOCK_EXCLUSIVE]
8f30: 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74  ).** into an int
8f40: 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41  eger that the pA
8f50: 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  rg argument poin
8f60: 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61  ts to. This capa
8f70: 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65  bility.** is use
8f80: 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67  d during testing
8f90: 20 61 6e 64 20 69 73 20 6f 6e 6c 79 20 61 76 61   and is only ava
8fa0: 69 6c 61 62 6c 65 20 77 68 65 6e 20 74 68 65 20  ilable when the 
8fb0: 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 63  SQLITE_TEST.** c
8fc0: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
8fd0: 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  on is used..**.*
8fe0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
8ff0: 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d  CNTL_SIZE_HINT]]
9000: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
9010: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d  FCNTL_SIZE_HINT]
9020: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
9030: 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67 69 76  by SQLite to giv
9040: 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79  e the VFS.** lay
9050: 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68 6f 77  er a hint of how
9060: 20 6c 61 72 67 65 20 74 68 65 20 64 61 74 61 62   large the datab
9070: 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 67 72  ase file will gr
9080: 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e 67 20  ow to be during 
9090: 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74  the.** current t
90a0: 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68 69  ransaction.  Thi
90b0: 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20 67 75  s hint is not gu
90c0: 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 61  aranteed to be a
90d0: 63 63 75 72 61 74 65 20 62 75 74 20 69 74 0a 2a  ccurate but it.*
90e0: 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65  * is often close
90f0: 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e  .  The underlyin
9100: 67 20 56 46 53 20 6d 69 67 68 74 20 63 68 6f 6f  g VFS might choo
9110: 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74  se to preallocat
9120: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  e database.** fi
9130: 6c 65 20 73 70 61 63 65 20 62 61 73 65 64 20 6f  le space based o
9140: 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e 20 6f  n this hint in o
9150: 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77 72 69  rder to help wri
9160: 74 65 73 20 74 6f 20 74 68 65 20 64 61 74 61 62  tes to the datab
9170: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20  ase.** file run 
9180: 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  faster..**.** <l
9190: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
91a0: 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a  _CHUNK_SIZE]].**
91b0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
91c0: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f  TL_CHUNK_SIZE] o
91d0: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
91e0: 20 72 65 71 75 65 73 74 20 74 68 61 74 20 74 68   request that th
91f0: 65 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73  e VFS.** extends
9200: 20 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74   and truncates t
9210: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
9220: 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20   in chunks of a 
9230: 73 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a  size specified.*
9240: 2a 20 62 79 20 74 68 65 20 75 73 65 72 2e 20 54  * by the user. T
9250: 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
9260: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  nt to [sqlite3_f
9270: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73  ile_control()] s
9280: 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20  hould .** point 
9290: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74  to an integer (t
92a0: 79 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e  ype int) contain
92b0: 69 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e  ing the new chun
92c0: 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a  k-size to use.**
92d0: 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74   for the nominat
92e0: 65 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c  ed database. All
92f0: 6f 63 61 74 69 6e 67 20 64 61 74 61 62 61 73 65  ocating database
9300: 20 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c   file space in l
9310: 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28  arge.** chunks (
9320: 73 61 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d  say 1MB at a tim
9330: 65 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66  e), may reduce f
9340: 69 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d  ile-system fragm
9350: 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20  entation and.** 
9360: 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61  improve performa
9370: 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74  nce on some syst
9380: 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ems..**.** <li>[
9390: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49  [SQLITE_FCNTL_FI
93a0: 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20  LE_POINTER]].** 
93b0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
93c0: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20  L_FILE_POINTER] 
93d0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
93e0: 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74  o obtain a point
93f0: 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  er.** to the [sq
9400: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
9410: 63 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ct associated wi
9420: 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  th a particular 
9430: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
9440: 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 61 6c 73  ection.  See als
9450: 6f 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  o [SQLITE_FCNTL_
9460: 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d  JOURNAL_POINTER]
9470: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
9480: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e  LITE_FCNTL_JOURN
9490: 41 4c 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20  AL_POINTER]].** 
94a0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
94b0: 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45  L_JOURNAL_POINTE
94c0: 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  R] opcode is use
94d0: 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f  d to obtain a po
94e0: 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
94f0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
9500: 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 64  bject associated
9510: 20 77 69 74 68 20 74 68 65 20 6a 6f 75 72 6e 61   with the journa
9520: 6c 20 66 69 6c 65 20 28 65 69 74 68 65 72 0a 2a  l file (either.*
9530: 2a 20 74 68 65 20 5b 72 6f 6c 6c 62 61 63 6b 20  * the [rollback 
9540: 6a 6f 75 72 6e 61 6c 5d 20 6f 72 20 74 68 65 20  journal] or the 
9550: 5b 77 72 69 74 65 2d 61 68 65 61 64 20 6c 6f 67  [write-ahead log
9560: 5d 29 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  ]) for a particu
9570: 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  lar database.** 
9580: 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65  connection.  See
9590: 20 61 6c 73 6f 20 5b 53 51 4c 49 54 45 5f 46 43   also [SQLITE_FC
95a0: 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52  NTL_FILE_POINTER
95b0: 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  ]..**.** <li>[[S
95c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
95d0: 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20 4e 6f  _OMITTED]].** No
95e0: 20 6c 6f 6e 67 65 72 20 69 6e 20 75 73 65 2e 0a   longer in use..
95f0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9600: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 5d 0a  TE_FCNTL_SYNC]].
9610: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
9620: 43 4e 54 4c 5f 53 59 4e 43 5d 20 6f 70 63 6f 64  CNTL_SYNC] opcod
9630: 65 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 69  e is generated i
9640: 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c  nternally by SQL
9650: 69 74 65 20 61 6e 64 0a 2a 2a 20 73 65 6e 74 20  ite and.** sent 
9660: 74 6f 20 74 68 65 20 56 46 53 20 69 6d 6d 65 64  to the VFS immed
9670: 69 61 74 65 6c 79 20 62 65 66 6f 72 65 20 74 68  iately before th
9680: 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 69  e xSync method i
9690: 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 0a 2a  s invoked on a.*
96a0: 2a 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  * database file 
96b0: 64 65 73 63 72 69 70 74 6f 72 2e 20 4f 72 2c 20  descriptor. Or, 
96c0: 69 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74  if the xSync met
96d0: 68 6f 64 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b  hod is not invok
96e0: 65 64 20 0a 2a 2a 20 62 65 63 61 75 73 65 20 74  ed .** because t
96f0: 68 65 20 75 73 65 72 20 68 61 73 20 63 6f 6e 66  he user has conf
9700: 69 67 75 72 65 64 20 53 51 4c 69 74 65 20 77 69  igured SQLite wi
9710: 74 68 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 73  th .** [PRAGMA s
9720: 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41  ynchronous | PRA
9730: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d  GMA synchronous=
9740: 4f 46 46 5d 20 69 74 20 69 73 20 69 6e 76 6f 6b  OFF] it is invok
9750: 65 64 20 69 6e 20 70 6c 61 63 65 20 0a 2a 2a 20  ed in place .** 
9760: 6f 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74  of the xSync met
9770: 68 6f 64 2e 20 49 6e 20 6d 6f 73 74 20 63 61 73  hod. In most cas
9780: 65 73 2c 20 74 68 65 20 70 6f 69 6e 74 65 72 20  es, the pointer 
9790: 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20  argument passed 
97a0: 77 69 74 68 0a 2a 2a 20 74 68 69 73 20 66 69 6c  with.** this fil
97b0: 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 4e 55 4c  e-control is NUL
97c0: 4c 2e 20 48 6f 77 65 76 65 72 2c 20 69 66 20 74  L. However, if t
97d0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
97e0: 20 69 73 20 62 65 69 6e 67 20 73 79 6e 63 65 64   is being synced
97f0: 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 61  .** as part of a
9800: 20 6d 75 6c 74 69 2d 64 61 74 61 62 61 73 65 20   multi-database 
9810: 63 6f 6d 6d 69 74 2c 20 74 68 65 20 61 72 67 75  commit, the argu
9820: 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 20 61  ment points to a
9830: 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a   nul-terminated.
9840: 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69  ** string contai
9850: 6e 69 6e 67 20 74 68 65 20 74 72 61 6e 73 61 63  ning the transac
9860: 74 69 6f 6e 73 20 6d 61 73 74 65 72 2d 6a 6f 75  tions master-jou
9870: 72 6e 61 6c 20 66 69 6c 65 20 6e 61 6d 65 2e 20  rnal file name. 
9880: 56 46 53 65 73 20 74 68 61 74 20 0a 2a 2a 20 64  VFSes that .** d
9890: 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20  o not need this 
98a0: 73 69 67 6e 61 6c 20 73 68 6f 75 6c 64 20 73 69  signal should si
98b0: 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68  lently ignore th
98c0: 69 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69  is opcode. Appli
98d0: 63 61 74 69 6f 6e 73 20 0a 2a 2a 20 73 68 6f 75  cations .** shou
98e0: 6c 64 20 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c  ld not call [sql
98f0: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
9900: 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f  l()] with this o
9910: 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73  pcode as doing s
9920: 6f 20 6d 61 79 20 0a 2a 2a 20 64 69 73 72 75 70  o may .** disrup
9930: 74 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20  t the operation 
9940: 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a  of the specializ
9950: 65 64 20 56 46 53 65 73 20 74 68 61 74 20 64 6f  ed VFSes that do
9960: 20 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a   require it.  .*
9970: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9980: 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50  E_FCNTL_COMMIT_P
9990: 48 41 53 45 54 57 4f 5d 5d 0a 2a 2a 20 54 68 65  HASETWO]].** The
99a0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43   [SQLITE_FCNTL_C
99b0: 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 20  OMMIT_PHASETWO] 
99c0: 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61  opcode is genera
99d0: 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62  ted internally b
99e0: 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20  y SQLite.** and 
99f0: 73 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20  sent to the VFS 
9a00: 61 66 74 65 72 20 61 20 74 72 61 6e 73 61 63 74  after a transact
9a10: 69 6f 6e 20 68 61 73 20 62 65 65 6e 20 63 6f 6d  ion has been com
9a20: 6d 69 74 74 65 64 20 69 6d 6d 65 64 69 61 74 65  mitted immediate
9a30: 6c 79 0a 2a 2a 20 62 75 74 20 62 65 66 6f 72 65  ly.** but before
9a40: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
9a50: 20 75 6e 6c 6f 63 6b 65 64 2e 20 56 46 53 65 73   unlocked. VFSes
9a60: 20 74 68 61 74 20 64 6f 20 6e 6f 74 20 6e 65 65   that do not nee
9a70: 64 20 74 68 69 73 20 73 69 67 6e 61 6c 0a 2a 2a  d this signal.**
9a80: 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79   should silently
9a90: 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63   ignore this opc
9aa0: 6f 64 65 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e  ode. Application
9ab0: 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c  s should not cal
9ac0: 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  l.** [sqlite3_fi
9ad0: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69  le_control()] wi
9ae0: 74 68 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61  th this opcode a
9af0: 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64  s doing so may d
9b00: 69 73 72 75 70 74 20 74 68 65 20 0a 2a 2a 20 6f  isrupt the .** o
9b10: 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  peration of the 
9b20: 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65  specialized VFSe
9b30: 73 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72  s that do requir
9b40: 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c  e it.  .**.** <l
9b50: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
9b60: 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d  _WIN32_AV_RETRY]
9b70: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
9b80: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56  E_FCNTL_WIN32_AV
9b90: 5f 52 45 54 52 59 5d 20 6f 70 63 6f 64 65 20 69  _RETRY] opcode i
9ba0: 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67  s used to config
9bb0: 75 72 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a  ure automatic.**
9bc0: 20 72 65 74 72 79 20 63 6f 75 6e 74 73 20 61 6e   retry counts an
9bd0: 64 20 69 6e 74 65 72 76 61 6c 73 20 66 6f 72 20  d intervals for 
9be0: 63 65 72 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f  certain disk I/O
9bf0: 20 6f 70 65 72 61 74 69 6f 6e 73 20 66 6f 72 20   operations for 
9c00: 74 68 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b  the.** windows [
9c10: 56 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f  VFS] in order to
9c20: 20 70 72 6f 76 69 64 65 20 72 6f 62 75 73 74 6e   provide robustn
9c30: 65 73 73 20 69 6e 20 74 68 65 20 70 72 65 73 65  ess in the prese
9c40: 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76  nce of.** anti-v
9c50: 69 72 75 73 20 70 72 6f 67 72 61 6d 73 2e 20 20  irus programs.  
9c60: 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20  By default, the 
9c70: 77 69 6e 64 6f 77 73 20 56 46 53 20 77 69 6c 6c  windows VFS will
9c80: 20 72 65 74 72 79 20 66 69 6c 65 20 72 65 61 64   retry file read
9c90: 2c 0a 2a 2a 20 66 69 6c 65 20 77 72 69 74 65 2c  ,.** file write,
9ca0: 20 61 6e 64 20 66 69 6c 65 20 64 65 6c 65 74 65   and file delete
9cb0: 20 6f 70 65 72 61 74 69 6f 6e 73 20 75 70 20 74   operations up t
9cc0: 6f 20 31 30 20 74 69 6d 65 73 2c 20 77 69 74 68  o 10 times, with
9cd0: 20 61 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32   a delay.** of 2
9ce0: 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62  5 milliseconds b
9cf0: 65 66 6f 72 65 20 74 68 65 20 66 69 72 73 74 20  efore the first 
9d00: 72 65 74 72 79 20 61 6e 64 20 77 69 74 68 20 74  retry and with t
9d10: 68 65 20 64 65 6c 61 79 20 69 6e 63 72 65 61 73  he delay increas
9d20: 69 6e 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64  ing.** by an add
9d30: 69 74 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69  itional 25 milli
9d40: 73 65 63 6f 6e 64 73 20 77 69 74 68 20 65 61 63  seconds with eac
9d50: 68 20 73 75 62 73 65 71 75 65 6e 74 20 72 65 74  h subsequent ret
9d60: 72 79 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63  ry.  This.** opc
9d70: 6f 64 65 20 61 6c 6c 6f 77 73 20 74 68 65 73 65  ode allows these
9d80: 20 74 77 6f 20 76 61 6c 75 65 73 20 28 31 30 20   two values (10 
9d90: 72 65 74 72 69 65 73 20 61 6e 64 20 32 35 20 6d  retries and 25 m
9da0: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 64  illiseconds of d
9db0: 65 6c 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61  elay).** to be a
9dc0: 64 6a 75 73 74 65 64 2e 20 20 54 68 65 20 76 61  djusted.  The va
9dd0: 6c 75 65 73 20 61 72 65 20 63 68 61 6e 67 65 64  lues are changed
9de0: 20 66 6f 72 20 61 6c 6c 20 64 61 74 61 62 61 73   for all databas
9df0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a  e connections.**
9e00: 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65   within the same
9e10: 20 70 72 6f 63 65 73 73 2e 20 20 54 68 65 20 61   process.  The a
9e20: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
9e30: 6e 74 65 72 20 74 6f 20 61 6e 20 61 72 72 61 79  nter to an array
9e40: 20 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67   of two.** integ
9e50: 65 72 73 20 77 68 65 72 65 20 74 68 65 20 66 69  ers where the fi
9e60: 72 73 74 20 69 6e 74 65 67 65 72 20 69 20 74 68  rst integer i th
9e70: 65 20 6e 65 77 20 72 65 74 72 79 20 63 6f 75 6e  e new retry coun
9e80: 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  t and the second
9e90: 0a 2a 2a 20 69 6e 74 65 67 65 72 20 69 73 20 74  .** integer is t
9ea0: 68 65 20 64 65 6c 61 79 2e 20 20 49 66 20 65 69  he delay.  If ei
9eb0: 74 68 65 72 20 69 6e 74 65 67 65 72 20 69 73 20  ther integer is 
9ec0: 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74  negative, then t
9ed0: 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73  he setting.** is
9ee0: 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 62 75 74   not changed but
9ef0: 20 69 6e 73 74 65 61 64 20 74 68 65 20 70 72 69   instead the pri
9f00: 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74  or value of that
9f10: 20 73 65 74 74 69 6e 67 20 69 73 20 77 72 69 74   setting is writ
9f20: 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20  ten.** into the 
9f30: 61 72 72 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c  array entry, all
9f40: 6f 77 69 6e 67 20 74 68 65 20 63 75 72 72 65 6e  owing the curren
9f50: 74 20 72 65 74 72 79 20 73 65 74 74 69 6e 67 73  t retry settings
9f60: 20 74 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72   to be.** interr
9f70: 6f 67 61 74 65 64 2e 20 20 54 68 65 20 7a 44 62  ogated.  The zDb
9f80: 4e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69  Name parameter i
9f90: 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a  s ignored..**.**
9fa0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
9fb0: 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d  NTL_PERSIST_WAL]
9fc0: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
9fd0: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
9fe0: 57 41 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  WAL] opcode is u
9ff0: 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75  sed to set or qu
a000: 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69  ery the.** persi
a010: 73 74 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69  stent [WAL | Wri
a020: 74 65 20 41 68 65 61 64 20 4c 6f 67 5d 20 73 65  te Ahead Log] se
a030: 74 74 69 6e 67 2e 20 20 42 79 20 64 65 66 61 75  tting.  By defau
a040: 6c 74 2c 20 74 68 65 20 61 75 78 69 6c 69 61 72  lt, the auxiliar
a050: 79 0a 2a 2a 20 77 72 69 74 65 20 61 68 65 61 64  y.** write ahead
a060: 20 6c 6f 67 20 61 6e 64 20 73 68 61 72 65 64 20   log and shared 
a070: 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 75 73 65  memory files use
a080: 64 20 66 6f 72 20 74 72 61 6e 73 61 63 74 69 6f  d for transactio
a090: 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65  n control.** are
a0a0: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64   automatically d
a0b0: 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65 20  eleted when the 
a0c0: 6c 61 74 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f  latest connectio
a0d0: 6e 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  n to the databas
a0e0: 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65  e.** closes.  Se
a0f0: 74 74 69 6e 67 20 70 65 72 73 69 73 74 65 6e 74  tting persistent
a100: 20 57 41 4c 20 6d 6f 64 65 20 63 61 75 73 65 73   WAL mode causes
a110: 20 74 68 6f 73 65 20 66 69 6c 65 73 20 74 6f 20   those files to 
a120: 70 65 72 73 69 73 74 20 61 66 74 65 72 0a 2a 2a  persist after.**
a130: 20 63 6c 6f 73 65 2e 20 20 50 65 72 73 69 73 74   close.  Persist
a140: 69 6e 67 20 74 68 65 20 66 69 6c 65 73 20 69 73  ing the files is
a150: 20 75 73 65 66 75 6c 20 77 68 65 6e 20 6f 74 68   useful when oth
a160: 65 72 20 70 72 6f 63 65 73 73 65 73 20 74 68 61  er processes tha
a170: 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65  t do not.** have
a180: 20 77 72 69 74 65 20 70 65 72 6d 69 73 73 69 6f   write permissio
a190: 6e 20 6f 6e 20 74 68 65 20 64 69 72 65 63 74 6f  n on the directo
a1a0: 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  ry containing th
a1b0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
a1c0: 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20  want.** to read 
a1d0: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
a1e0: 65 2c 20 61 73 20 74 68 65 20 57 41 4c 20 61 6e  e, as the WAL an
a1f0: 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20  d shared memory 
a200: 66 69 6c 65 73 20 6d 75 73 74 20 65 78 69 73 74  files must exist
a210: 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f 72  .** in order for
a220: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74 6f   the database to
a230: 20 62 65 20 72 65 61 64 61 62 6c 65 2e 20 20 54   be readable.  T
a240: 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
a250: 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ter to.** [sqlit
a260: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
a270: 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f  )] for this opco
a280: 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70  de should be a p
a290: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
a2a0: 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e  eger..** That in
a2b0: 74 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69  teger is 0 to di
a2c0: 73 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74  sable persistent
a2d0: 20 57 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74   WAL mode or 1 t
a2e0: 6f 20 65 6e 61 62 6c 65 20 70 65 72 73 69 73 74  o enable persist
a2f0: 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e  ent.** WAL mode.
a300: 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72    If the integer
a310: 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20   is -1, then it 
a320: 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77  is overwritten w
a330: 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a  ith the current.
a340: 2a 2a 20 57 41 4c 20 70 65 72 73 69 73 74 65 6e  ** WAL persisten
a350: 63 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a  ce setting..**.*
a360: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
a370: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f  CNTL_POWERSAFE_O
a380: 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54  VERWRITE]].** ^T
a390: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
a3a0: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
a3b0: 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20  RITE] opcode is 
a3c0: 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71  used to set or q
a3d0: 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73  uery the.** pers
a3e0: 69 73 74 65 6e 74 20 22 70 6f 77 65 72 73 61 66  istent "powersaf
a3f0: 65 2d 6f 76 65 72 77 72 69 74 65 22 20 6f 72 20  e-overwrite" or 
a400: 22 50 53 4f 57 22 20 73 65 74 74 69 6e 67 2e 20  "PSOW" setting. 
a410: 20 54 68 65 20 50 53 4f 57 20 73 65 74 74 69 6e   The PSOW settin
a420: 67 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73 20  g.** determines 
a430: 74 68 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  the [SQLITE_IOCA
a440: 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  P_POWERSAFE_OVER
a450: 57 52 49 54 45 5d 20 62 69 74 20 6f 66 20 74 68  WRITE] bit of th
a460: 65 0a 2a 2a 20 78 44 65 76 69 63 65 43 68 61 72  e.** xDeviceChar
a470: 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68  acteristics meth
a480: 6f 64 73 2e 20 54 68 65 20 66 6f 75 72 74 68 20  ods. The fourth 
a490: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
a4a0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
a4b0: 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69  ntrol()] for thi
a4c0: 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20  s opcode should 
a4d0: 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  be a pointer to 
a4e0: 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54  an integer..** T
a4f0: 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30  hat integer is 0
a500: 20 74 6f 20 64 69 73 61 62 6c 65 20 7a 65 72 6f   to disable zero
a510: 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20  -damage mode or 
a520: 31 20 74 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f  1 to enable zero
a530: 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e  -damage.** mode.
a540: 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72    If the integer
a550: 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20   is -1, then it 
a560: 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77  is overwritten w
a570: 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a  ith the current.
a580: 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d  ** zero-damage m
a590: 6f 64 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a  ode setting..**.
a5a0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
a5b0: 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d  FCNTL_OVERWRITE]
a5c0: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
a5d0: 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54  E_FCNTL_OVERWRIT
a5e0: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6e 76  E] opcode is inv
a5f0: 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 61  oked by SQLite a
a600: 66 74 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20  fter opening.** 
a610: 61 20 77 72 69 74 65 20 74 72 61 6e 73 61 63 74  a write transact
a620: 69 6f 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20  ion to indicate 
a630: 74 68 61 74 2c 20 75 6e 6c 65 73 73 20 69 74 20  that, unless it 
a640: 69 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66  is rolled back f
a650: 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f  or some.** reaso
a660: 6e 2c 20 74 68 65 20 65 6e 74 69 72 65 20 64 61  n, the entire da
a670: 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c  tabase file will
a680: 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20   be overwritten 
a690: 62 79 20 74 68 65 20 63 75 72 72 65 6e 74 20 0a  by the current .
a6a0: 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20  ** transaction. 
a6b0: 54 68 69 73 20 69 73 20 75 73 65 64 20 62 79 20  This is used by 
a6c0: 56 41 43 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e  VACUUM operation
a6d0: 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  s..**.** <li>[[S
a6e0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e  QLITE_FCNTL_VFSN
a6f0: 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  AME]].** ^The [S
a700: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e  QLITE_FCNTL_VFSN
a710: 41 4d 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20  AME] opcode can 
a720: 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  be used to obtai
a730: 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a  n the names of.*
a740: 2a 20 61 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e  * all [VFSes] in
a750: 20 74 68 65 20 56 46 53 20 73 74 61 63 6b 2e 20   the VFS stack. 
a760: 20 54 68 65 20 6e 61 6d 65 73 20 61 72 65 20 6f   The names are o
a770: 66 20 61 6c 6c 20 56 46 53 20 73 68 69 6d 73 20  f all VFS shims 
a780: 61 6e 64 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c  and the.** final
a790: 20 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46   bottom-level VF
a7a0: 53 20 61 72 65 20 77 72 69 74 74 65 6e 20 69 6e  S are written in
a7b0: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
a7c0: 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c  ed from .** [sql
a7d0: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61  ite3_malloc()] a
a7e0: 6e 64 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  nd the result is
a7f0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20 63   stored in the c
a800: 68 61 72 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a  har* variable.**
a810: 20 74 68 61 74 20 74 68 65 20 66 6f 75 72 74 68   that the fourth
a820: 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 5b 73   parameter of [s
a830: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
a840: 72 6f 6c 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f  rol()] points to
a850: 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 65 72 20  ..** The caller 
a860: 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
a870: 6f 72 20 66 72 65 65 69 6e 67 20 74 68 65 20 6d  or freeing the m
a880: 65 6d 6f 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e  emory when done.
a890: 20 20 41 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c    As with.** all
a8a0: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63   file-control ac
a8b0: 74 69 6f 6e 73 2c 20 74 68 65 72 65 20 69 73 20  tions, there is 
a8c0: 6e 6f 20 67 75 61 72 61 6e 74 65 65 20 74 68 61  no guarantee tha
a8d0: 74 20 74 68 69 73 20 77 69 6c 6c 20 61 63 74 75  t this will actu
a8e0: 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68  ally.** do anyth
a8f0: 69 6e 67 2e 20 20 43 61 6c 6c 65 72 73 20 73 68  ing.  Callers sh
a900: 6f 75 6c 64 20 69 6e 69 74 69 61 6c 69 7a 65 20  ould initialize 
a910: 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62  the char* variab
a920: 6c 65 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20  le to a NULL.** 
a930: 70 6f 69 6e 74 65 72 20 69 6e 20 63 61 73 65 20  pointer in case 
a940: 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  this file-contro
a950: 6c 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65  l is not impleme
a960: 6e 74 65 64 2e 20 20 54 68 69 73 20 66 69 6c 65  nted.  This file
a970: 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69  -control.** is i
a980: 6e 74 65 6e 64 65 64 20 66 6f 72 20 64 69 61 67  ntended for diag
a990: 6e 6f 73 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e  nostic use only.
a9a0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
a9b0: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f  ITE_FCNTL_VFS_PO
a9c0: 49 4e 54 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20  INTER]].** ^The 
a9d0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46  [SQLITE_FCNTL_VF
a9e0: 53 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64  S_POINTER] opcod
a9f0: 65 20 66 69 6e 64 73 20 61 20 70 6f 69 6e 74 65  e finds a pointe
aa00: 72 20 74 6f 20 74 68 65 20 74 6f 70 2d 6c 65 76  r to the top-lev
aa10: 65 6c 0a 2a 2a 20 5b 56 46 53 65 73 5d 20 63 75  el.** [VFSes] cu
aa20: 72 72 65 6e 74 6c 79 20 69 6e 20 75 73 65 2e 20  rrently in use. 
aa30: 20 5e 28 54 68 65 20 61 72 67 75 6d 65 6e 74 20   ^(The argument 
aa40: 58 20 69 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  X in.** sqlite3_
aa50: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 64 62 2c  file_control(db,
aa60: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53  SQLITE_FCNTL_VFS
aa70: 5f 50 4f 49 4e 54 45 52 2c 58 29 20 6d 75 73 74  _POINTER,X) must
aa80: 20 62 65 0a 2a 2a 20 6f 66 20 74 79 70 65 20 22   be.** of type "
aa90: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 2a 2a  [sqlite3_vfs] **
aaa0: 22 2e 20 20 54 68 69 73 20 6f 70 63 6f 64 65 73  ".  This opcodes
aab0: 20 77 69 6c 6c 20 73 65 74 20 2a 58 0a 2a 2a 20   will set *X.** 
aac0: 74 6f 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  to a pointer to 
aad0: 74 68 65 20 74 6f 70 2d 6c 65 76 65 6c 20 56 46  the top-level VF
aae0: 53 2e 29 5e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68  S.)^.** ^When th
aaf0: 65 72 65 20 61 72 65 20 6d 75 6c 74 69 70 6c 65  ere are multiple
ab00: 20 56 46 53 20 73 68 69 6d 73 20 69 6e 20 74 68   VFS shims in th
ab10: 65 20 73 74 61 63 6b 2c 20 74 68 69 73 20 6f 70  e stack, this op
ab20: 63 6f 64 65 20 66 69 6e 64 73 20 74 68 65 0a 2a  code finds the.*
ab30: 2a 20 75 70 70 65 72 2d 6d 6f 73 74 20 73 68 69  * upper-most shi
ab40: 6d 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  m only..**.** <l
ab50: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
ab60: 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68  _PRAGMA]].** ^Wh
ab70: 65 6e 65 76 65 72 20 61 20 5b 50 52 41 47 4d 41  enever a [PRAGMA
ab80: 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 70  ] statement is p
ab90: 61 72 73 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54  arsed, an [SQLIT
aba0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
abb0: 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  .** file control
abc0: 20 69 73 20 73 65 6e 74 20 74 6f 20 74 68 65 20   is sent to the 
abd0: 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  open [sqlite3_fi
abe0: 6c 65 5d 20 6f 62 6a 65 63 74 20 63 6f 72 72 65  le] object corre
abf0: 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74  sponding.** to t
ac00: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
ac10: 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 70 72   to which the pr
ac20: 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 72  agma statement r
ac30: 65 66 65 72 73 2e 20 5e 54 68 65 20 61 72 67 75  efers. ^The argu
ac40: 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  ment.** to the [
ac50: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
ac60: 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  GMA] file contro
ac70: 6c 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  l is an array of
ac80: 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  .** pointers to 
ac90: 73 74 72 69 6e 67 73 20 28 63 68 61 72 2a 2a 29  strings (char**)
aca0: 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 73 65   in which the se
acb0: 63 6f 6e 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20  cond element of 
acc0: 74 68 65 20 61 72 72 61 79 0a 2a 2a 20 69 73 20  the array.** is 
acd0: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
ace0: 70 72 61 67 6d 61 20 61 6e 64 20 74 68 65 20 74  pragma and the t
acf0: 68 69 72 64 20 65 6c 65 6d 65 6e 74 20 69 73 20  hird element is 
ad00: 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  the argument to 
ad10: 74 68 65 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72  the.** pragma or
ad20: 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 70 72 61   NULL if the pra
ad30: 67 6d 61 20 68 61 73 20 6e 6f 20 61 72 67 75 6d  gma has no argum
ad40: 65 6e 74 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c  ent.  ^The handl
ad50: 65 72 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51  er for an.** [SQ
ad60: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
ad70: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A] file control 
ad80: 63 61 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d  can optionally m
ad90: 61 6b 65 20 74 68 65 20 66 69 72 73 74 20 65 6c  ake the first el
ada0: 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20  ement.** of the 
adb0: 63 68 61 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20  char** argument 
adc0: 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e  point to a strin
add0: 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  g obtained from 
ade0: 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  [sqlite3_mprintf
adf0: 28 29 5d 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71  ()].** or the eq
ae00: 75 69 76 61 6c 65 6e 74 20 61 6e 64 20 74 68 61  uivalent and tha
ae10: 74 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65  t string will be
ae20: 63 6f 6d 65 20 74 68 65 20 72 65 73 75 6c 74 20  come the result 
ae30: 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 6f 72  of the pragma or
ae40: 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 6d 65  .** the error me
ae50: 73 73 61 67 65 20 69 66 20 74 68 65 20 70 72 61  ssage if the pra
ae60: 67 6d 61 20 66 61 69 6c 73 2e 20 5e 49 66 20 74  gma fails. ^If t
ae70: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43  he.** [SQLITE_FC
ae80: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65  NTL_PRAGMA] file
ae90: 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73   control returns
aea0: 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e   [SQLITE_NOTFOUN
aeb0: 44 5d 2c 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20  D], then normal 
aec0: 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f  .** [PRAGMA] pro
aed0: 63 65 73 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65  cessing continue
aee0: 73 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c  s.  ^If the [SQL
aef0: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
af00: 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f  ].** file contro
af10: 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  l returns [SQLIT
af20: 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20  E_OK], then the 
af30: 70 61 72 73 65 72 20 61 73 73 75 6d 65 73 20 74  parser assumes t
af40: 68 61 74 20 74 68 65 0a 2a 2a 20 56 46 53 20 68  hat the.** VFS h
af50: 61 73 20 68 61 6e 64 6c 65 64 20 74 68 65 20 50  as handled the P
af60: 52 41 47 4d 41 20 69 74 73 65 6c 66 20 61 6e 64  RAGMA itself and
af70: 20 74 68 65 20 70 61 72 73 65 72 20 67 65 6e 65   the parser gene
af80: 72 61 74 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a  rates a no-op.**
af90: 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
afa0: 65 6e 74 20 69 66 20 72 65 73 75 6c 74 20 73 74  ent if result st
afb0: 72 69 6e 67 20 69 73 20 4e 55 4c 4c 2c 20 6f 72  ring is NULL, or
afc0: 20 74 68 61 74 20 72 65 74 75 72 6e 73 20 61 20   that returns a 
afd0: 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 72  copy.** of the r
afe0: 65 73 75 6c 74 20 73 74 72 69 6e 67 20 69 66 20  esult string if 
aff0: 74 68 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f  the string is no
b000: 6e 2d 4e 55 4c 4c 2e 0a 2a 2a 20 5e 49 66 20 74  n-NULL..** ^If t
b010: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
b020: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
b030: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 0a 2a 2a  ntrol returns.**
b040: 20 61 6e 79 20 72 65 73 75 6c 74 20 63 6f 64 65   any result code
b050: 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
b060: 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49  ITE_OK] or [SQLI
b070: 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68  TE_NOTFOUND], th
b080: 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  at means.** that
b090: 20 74 68 65 20 56 46 53 20 65 6e 63 6f 75 6e 74   the VFS encount
b0a0: 65 72 65 64 20 61 6e 20 65 72 72 6f 72 20 77 68  ered an error wh
b0b0: 69 6c 65 20 68 61 6e 64 6c 69 6e 67 20 74 68 65  ile handling the
b0c0: 20 5b 50 52 41 47 4d 41 5d 20 61 6e 64 20 74 68   [PRAGMA] and th
b0d0: 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74 69 6f 6e  e.** compilation
b0e0: 20 6f 66 20 74 68 65 20 50 52 41 47 4d 41 20 66   of the PRAGMA f
b0f0: 61 69 6c 73 20 77 69 74 68 20 61 6e 20 65 72 72  ails with an err
b100: 6f 72 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54  or.  ^The [SQLIT
b110: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a  E_FCNTL_PRAGMA].
b120: 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  ** file control 
b130: 6f 63 63 75 72 73 20 61 74 20 74 68 65 20 62 65  occurs at the be
b140: 67 69 6e 6e 69 6e 67 20 6f 66 20 70 72 61 67 6d  ginning of pragm
b150: 61 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 61 6c  a statement anal
b160: 79 73 69 73 20 61 6e 64 20 73 6f 0a 2a 2a 20 69  ysis and so.** i
b170: 74 20 69 73 20 61 62 6c 65 20 74 6f 20 6f 76 65  t is able to ove
b180: 72 72 69 64 65 20 62 75 69 6c 74 2d 69 6e 20 5b  rride built-in [
b190: 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e  PRAGMA] statemen
b1a0: 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ts..**.** <li>[[
b1b0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53  SQLITE_FCNTL_BUS
b1c0: 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54  YHANDLER]].** ^T
b1d0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
b1e0: 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 0a 2a 2a  _BUSYHANDLER].**
b1f0: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61   file-control ma
b200: 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 62 79 20  y be invoked by 
b210: 53 51 4c 69 74 65 20 6f 6e 20 74 68 65 20 64 61  SQLite on the da
b220: 74 61 62 61 73 65 20 66 69 6c 65 20 68 61 6e 64  tabase file hand
b230: 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c 79 20 61 66  le.** shortly af
b240: 74 65 72 20 69 74 20 69 73 20 6f 70 65 6e 65 64  ter it is opened
b250: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f   in order to pro
b260: 76 69 64 65 20 61 20 63 75 73 74 6f 6d 20 56 46  vide a custom VF
b270: 53 20 77 69 74 68 20 61 63 63 65 73 73 0a 2a 2a  S with access.**
b280: 20 74 6f 20 74 68 65 20 63 6f 6e 6e 65 63 74 69   to the connecti
b290: 6f 6e 73 20 62 75 73 79 2d 68 61 6e 64 6c 65 72  ons busy-handler
b2a0: 20 63 61 6c 6c 62 61 63 6b 2e 20 54 68 65 20 61   callback. The a
b2b0: 72 67 75 6d 65 6e 74 20 69 73 20 6f 66 20 74 79  rgument is of ty
b2c0: 70 65 20 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20  pe (void **).** 
b2d0: 2d 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77  - an array of tw
b2e0: 6f 20 28 76 6f 69 64 20 2a 29 20 76 61 6c 75 65  o (void *) value
b2f0: 73 2e 20 54 68 65 20 66 69 72 73 74 20 28 76 6f  s. The first (vo
b300: 69 64 20 2a 29 20 61 63 74 75 61 6c 6c 79 20 70  id *) actually p
b310: 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 61 20 66 75  oints.** to a fu
b320: 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 28  nction of type (
b330: 69 6e 74 20 28 2a 29 28 76 6f 69 64 20 2a 29 29  int (*)(void *))
b340: 2e 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e  . In order to in
b350: 76 6f 6b 65 20 74 68 65 20 63 6f 6e 6e 65 63 74  voke the connect
b360: 69 6f 6e 73 0a 2a 2a 20 62 75 73 79 2d 68 61 6e  ions.** busy-han
b370: 64 6c 65 72 2c 20 74 68 69 73 20 66 75 6e 63 74  dler, this funct
b380: 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 69 6e  ion should be in
b390: 76 6f 6b 65 64 20 77 69 74 68 20 74 68 65 20 73  voked with the s
b3a0: 65 63 6f 6e 64 20 28 76 6f 69 64 20 2a 29 20 69  econd (void *) i
b3b0: 6e 0a 2a 2a 20 74 68 65 20 61 72 72 61 79 20 61  n.** the array a
b3c0: 73 20 74 68 65 20 6f 6e 6c 79 20 61 72 67 75 6d  s the only argum
b3d0: 65 6e 74 2e 20 49 66 20 69 74 20 72 65 74 75 72  ent. If it retur
b3e0: 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
b3f0: 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a  n the operation.
b400: 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74  ** should be ret
b410: 72 69 65 64 2e 20 49 66 20 69 74 20 72 65 74 75  ried. If it retu
b420: 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20 63 75  rns zero, the cu
b430: 73 74 6f 6d 20 56 46 53 20 73 68 6f 75 6c 64 20  stom VFS should 
b440: 61 62 61 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20 63  abandon the.** c
b450: 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e  urrent operation
b460: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
b470: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46  LITE_FCNTL_TEMPF
b480: 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70  ILENAME]].** ^Ap
b490: 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 69 6e  plication can in
b4a0: 76 6f 6b 65 20 74 68 65 20 5b 53 51 4c 49 54 45  voke the [SQLITE
b4b0: 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e  _FCNTL_TEMPFILEN
b4c0: 41 4d 45 5d 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  AME] file-contro
b4d0: 6c 0a 2a 2a 20 74 6f 20 68 61 76 65 20 53 51 4c  l.** to have SQL
b4e0: 69 74 65 20 67 65 6e 65 72 61 74 65 20 61 0a 2a  ite generate a.*
b4f0: 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  * temporary file
b500: 6e 61 6d 65 20 75 73 69 6e 67 20 74 68 65 20 73  name using the s
b510: 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 74 68  ame algorithm th
b520: 61 74 20 69 73 20 66 6f 6c 6c 6f 77 65 64 20 74  at is followed t
b530: 6f 20 67 65 6e 65 72 61 74 65 0a 2a 2a 20 74 65  o generate.** te
b540: 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65  mporary filename
b550: 73 20 66 6f 72 20 54 45 4d 50 20 74 61 62 6c 65  s for TEMP table
b560: 73 20 61 6e 64 20 6f 74 68 65 72 20 69 6e 74 65  s and other inte
b570: 72 6e 61 6c 20 75 73 65 73 2e 20 20 54 68 65 0a  rnal uses.  The.
b580: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  ** argument shou
b590: 6c 64 20 62 65 20 61 20 63 68 61 72 2a 2a 20 77  ld be a char** w
b5a0: 68 69 63 68 20 77 69 6c 6c 20 62 65 20 66 69 6c  hich will be fil
b5b0: 6c 65 64 20 77 69 74 68 20 74 68 65 20 66 69 6c  led with the fil
b5c0: 65 6e 61 6d 65 0a 2a 2a 20 77 72 69 74 74 65 6e  ename.** written
b5d0: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
b5e0: 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
b5f0: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20  te3_malloc()].  
b600: 54 68 65 20 63 61 6c 6c 65 72 20 73 68 6f 75 6c  The caller shoul
b610: 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20 5b 73 71 6c  d.** invoke [sql
b620: 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20  ite3_free()] on 
b630: 74 68 65 20 72 65 73 75 6c 74 20 74 6f 20 61 76  the result to av
b640: 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61  oid a memory lea
b650: 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  k..**.** <li>[[S
b660: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50  QLITE_FCNTL_MMAP
b670: 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  _SIZE]].** The [
b680: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41  SQLITE_FCNTL_MMA
b690: 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e  P_SIZE] file con
b6a0: 74 72 6f 6c 20 69 73 20 75 73 65 64 20 74 6f 20  trol is used to 
b6b0: 71 75 65 72 79 20 6f 72 20 73 65 74 20 74 68 65  query or set the
b6c0: 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  .** maximum numb
b6d0: 65 72 20 6f 66 20 62 79 74 65 73 20 74 68 61 74  er of bytes that
b6e0: 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 66 6f   will be used fo
b6f0: 72 20 6d 65 6d 6f 72 79 2d 6d 61 70 70 65 64 20  r memory-mapped 
b700: 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75  I/O..** The argu
b710: 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
b720: 72 20 74 6f 20 61 20 76 61 6c 75 65 20 6f 66 20  r to a value of 
b730: 74 79 70 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  type sqlite3_int
b740: 36 34 20 74 68 61 74 0a 2a 2a 20 69 73 20 61 6e  64 that.** is an
b750: 20 61 64 76 69 73 6f 72 79 20 6d 61 78 69 6d 75   advisory maximu
b760: 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  m number of byte
b770: 73 20 69 6e 20 74 68 65 20 66 69 6c 65 20 74 6f  s in the file to
b780: 20 6d 65 6d 6f 72 79 20 6d 61 70 2e 20 20 54 68   memory map.  Th
b790: 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 73 20  e.** pointer is 
b7a0: 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68  overwritten with
b7b0: 20 74 68 65 20 6f 6c 64 20 76 61 6c 75 65 2e 20   the old value. 
b7c0: 20 54 68 65 20 6c 69 6d 69 74 20 69 73 20 6e 6f   The limit is no
b7d0: 74 20 63 68 61 6e 67 65 64 20 69 66 0a 2a 2a 20  t changed if.** 
b7e0: 74 68 65 20 76 61 6c 75 65 20 6f 72 69 67 69 6e  the value origin
b7f0: 61 6c 6c 79 20 70 6f 69 6e 74 65 64 20 74 6f 20  ally pointed to 
b800: 69 73 20 6e 65 67 61 74 69 76 65 2c 20 61 6e 64  is negative, and
b810: 20 73 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20   so the current 
b820: 6c 69 6d 69 74 20 0a 2a 2a 20 63 61 6e 20 62 65  limit .** can be
b830: 20 71 75 65 72 69 65 64 20 62 79 20 70 61 73 73   queried by pass
b840: 69 6e 67 20 69 6e 20 61 20 70 6f 69 6e 74 65 72  ing in a pointer
b850: 20 74 6f 20 61 20 6e 65 67 61 74 69 76 65 20 6e   to a negative n
b860: 75 6d 62 65 72 2e 20 20 54 68 69 73 0a 2a 2a 20  umber.  This.** 
b870: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20  file-control is 
b880: 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  used internally 
b890: 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 50 52  to implement [PR
b8a0: 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 2e  AGMA mmap_size].
b8b0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
b8c0: 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d  ITE_FCNTL_TRACE]
b8d0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
b8e0: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 66 69  _FCNTL_TRACE] fi
b8f0: 6c 65 20 63 6f 6e 74 72 6f 6c 20 70 72 6f 76 69  le control provi
b900: 64 65 73 20 61 64 76 69 73 6f 72 79 20 69 6e 66  des advisory inf
b910: 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74  ormation.** to t
b920: 68 65 20 56 46 53 20 61 62 6f 75 74 20 77 68 61  he VFS about wha
b930: 74 20 74 68 65 20 68 69 67 68 65 72 20 6c 61 79  t the higher lay
b940: 65 72 73 20 6f 66 20 74 68 65 20 53 51 4c 69 74  ers of the SQLit
b950: 65 20 73 74 61 63 6b 20 61 72 65 20 64 6f 69 6e  e stack are doin
b960: 67 2e 0a 2a 2a 20 54 68 69 73 20 66 69 6c 65 20  g..** This file 
b970: 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20  control is used 
b980: 62 79 20 73 6f 6d 65 20 56 46 53 20 61 63 74 69  by some VFS acti
b990: 76 69 74 79 20 74 72 61 63 69 6e 67 20 5b 73 68  vity tracing [sh
b9a0: 69 6d 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 72 67  ims]..** The arg
b9b0: 75 6d 65 6e 74 20 69 73 20 61 20 7a 65 72 6f 2d  ument is a zero-
b9c0: 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
b9d0: 67 2e 20 20 48 69 67 68 65 72 20 6c 61 79 65 72  g.  Higher layer
b9e0: 73 20 69 6e 20 74 68 65 0a 2a 2a 20 53 51 4c 69  s in the.** SQLi
b9f0: 74 65 20 73 74 61 63 6b 20 6d 61 79 20 67 65 6e  te stack may gen
ba00: 65 72 61 74 65 20 69 6e 73 74 61 6e 63 65 73 20  erate instances 
ba10: 6f 66 20 74 68 69 73 20 66 69 6c 65 20 63 6f 6e  of this file con
ba20: 74 72 6f 6c 20 69 66 0a 2a 2a 20 74 68 65 20 5b  trol if.** the [
ba30: 53 51 4c 49 54 45 5f 55 53 45 5f 46 43 4e 54 4c  SQLITE_USE_FCNTL
ba40: 5f 54 52 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d  _TRACE] compile-
ba50: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65  time option is e
ba60: 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  nabled..**.** <l
ba70: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
ba80: 5f 48 41 53 5f 4d 4f 56 45 44 5d 5d 0a 2a 2a 20  _HAS_MOVED]].** 
ba90: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
baa0: 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 20 66 69 6c  L_HAS_MOVED] fil
bab0: 65 20 63 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70  e control interp
bac0: 72 65 74 73 20 69 74 73 20 61 72 67 75 6d 65 6e  rets its argumen
bad0: 74 20 61 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65  t as a.** pointe
bae0: 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  r to an integer 
baf0: 61 6e 64 20 69 74 20 77 72 69 74 65 73 20 61 20  and it writes a 
bb00: 62 6f 6f 6c 65 61 6e 20 69 6e 74 6f 20 74 68 61  boolean into tha
bb10: 74 20 69 6e 74 65 67 65 72 20 64 65 70 65 6e 64  t integer depend
bb20: 69 6e 67 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65  ing.** on whethe
bb30: 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 66 69 6c  r or not the fil
bb40: 65 20 68 61 73 20 62 65 65 6e 20 72 65 6e 61 6d  e has been renam
bb50: 65 64 2c 20 6d 6f 76 65 64 2c 20 6f 72 20 64 65  ed, moved, or de
bb60: 6c 65 74 65 64 20 73 69 6e 63 65 20 69 74 0a 2a  leted since it.*
bb70: 2a 20 77 61 73 20 66 69 72 73 74 20 6f 70 65 6e  * was first open
bb80: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ed..**.** <li>[[
bb90: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
bba0: 33 32 5f 47 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a  32_GET_HANDLE]].
bbb0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
bbc0: 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48  CNTL_WIN32_GET_H
bbd0: 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 65 20 63 61  ANDLE] opcode ca
bbe0: 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74  n be used to obt
bbf0: 61 69 6e 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72  ain the.** under
bc00: 6c 79 69 6e 67 20 6e 61 74 69 76 65 20 66 69 6c  lying native fil
bc10: 65 20 68 61 6e 64 6c 65 20 61 73 73 6f 63 69 61  e handle associa
bc20: 74 65 64 20 77 69 74 68 20 61 20 66 69 6c 65 20  ted with a file 
bc30: 68 61 6e 64 6c 65 2e 20 20 54 68 69 73 20 66 69  handle.  This fi
bc40: 6c 65 0a 2a 2a 20 63 6f 6e 74 72 6f 6c 20 69 6e  le.** control in
bc50: 74 65 72 70 72 65 74 73 20 69 74 73 20 61 72 67  terprets its arg
bc60: 75 6d 65 6e 74 20 61 73 20 61 20 70 6f 69 6e 74  ument as a point
bc70: 65 72 20 74 6f 20 61 20 6e 61 74 69 76 65 20 66  er to a native f
bc80: 69 6c 65 20 68 61 6e 64 6c 65 20 61 6e 64 0a 2a  ile handle and.*
bc90: 2a 20 77 72 69 74 65 73 20 74 68 65 20 72 65 73  * writes the res
bca0: 75 6c 74 69 6e 67 20 76 61 6c 75 65 20 74 68 65  ulting value the
bcb0: 72 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  re..**.** <li>[[
bcc0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
bcd0: 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a  32_SET_HANDLE]].
bce0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
bcf0: 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48  CNTL_WIN32_SET_H
bd00: 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 65 20 69 73  ANDLE] opcode is
bd10: 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67 67   used for debugg
bd20: 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70  ing.  This.** op
bd30: 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65 20  code causes the 
bd40: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
bd50: 68 6f 64 20 74 6f 20 73 77 61 70 20 74 68 65 20  hod to swap the 
bd60: 66 69 6c 65 20 68 61 6e 64 6c 65 20 77 69 74 68  file handle with
bd70: 20 74 68 65 20 6f 6e 65 0a 2a 2a 20 70 6f 69 6e   the one.** poin
bd80: 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 70 41  ted to by the pA
bd90: 72 67 20 61 72 67 75 6d 65 6e 74 2e 20 20 54 68  rg argument.  Th
bda0: 69 73 20 63 61 70 61 62 69 6c 69 74 79 20 69 73  is capability is
bdb0: 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73   used during tes
bdc0: 74 69 6e 67 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79  ting.** and only
bdd0: 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75 70   needs to be sup
bde0: 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49  ported when SQLI
bdf0: 54 45 5f 54 45 53 54 20 69 73 20 64 65 66 69 6e  TE_TEST is defin
be00: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ed..**.** <li>[[
be10: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c  SQLITE_FCNTL_WAL
be20: 5f 42 4c 4f 43 4b 5d 5d 0a 2a 2a 20 54 68 65 20  _BLOCK]].** The 
be30: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41  [SQLITE_FCNTL_WA
be40: 4c 5f 42 4c 4f 43 4b 5d 20 69 73 20 61 20 73 69  L_BLOCK] is a si
be50: 67 6e 61 6c 20 74 6f 20 74 68 65 20 56 46 53 20  gnal to the VFS 
be60: 6c 61 79 65 72 20 74 68 61 74 20 69 74 20 6d 69  layer that it mi
be70: 67 68 74 0a 2a 2a 20 62 65 20 61 64 76 61 6e 74  ght.** be advant
be80: 61 67 65 6f 75 73 20 74 6f 20 62 6c 6f 63 6b 20  ageous to block 
be90: 6f 6e 20 74 68 65 20 6e 65 78 74 20 57 41 4c 20  on the next WAL 
bea0: 6c 6f 63 6b 20 69 66 20 74 68 65 20 6c 6f 63 6b  lock if the lock
beb0: 20 69 73 20 6e 6f 74 20 69 6d 6d 65 64 69 61 74   is not immediat
bec0: 65 6c 79 0a 2a 2a 20 61 76 61 69 6c 61 62 6c 65  ely.** available
bed0: 2e 20 20 54 68 65 20 57 41 4c 20 73 75 62 73 79  .  The WAL subsy
bee0: 73 74 65 6d 20 69 73 73 75 65 73 20 74 68 69 73  stem issues this
bef0: 20 73 69 67 6e 61 6c 20 64 75 72 69 6e 67 20 72   signal during r
bf00: 61 72 65 0a 2a 2a 20 63 69 72 63 75 6d 73 74 61  are.** circumsta
bf10: 6e 63 65 73 20 69 6e 20 6f 72 64 65 72 20 74 6f  nces in order to
bf20: 20 66 69 78 20 61 20 70 72 6f 62 6c 65 6d 20 77   fix a problem w
bf30: 69 74 68 20 70 72 69 6f 72 69 74 79 20 69 6e 76  ith priority inv
bf40: 65 72 73 69 6f 6e 2e 0a 2a 2a 20 41 70 70 6c 69  ersion..** Appli
bf50: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 3c  cations should <
bf60: 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20 75 73 65 20  em>not</em> use 
bf70: 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  this file-contro
bf80: 6c 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  l..**.** <li>[[S
bf90: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56  QLITE_FCNTL_ZIPV
bfa0: 46 53 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  FS]].** The [SQL
bfb0: 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53  ITE_FCNTL_ZIPVFS
bfc0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6d 70 6c  ] opcode is impl
bfd0: 65 6d 65 6e 74 65 64 20 62 79 20 7a 69 70 76 66  emented by zipvf
bfe0: 73 20 6f 6e 6c 79 2e 20 41 6c 6c 20 6f 74 68 65  s only. All othe
bff0: 72 0a 2a 2a 20 56 46 53 20 73 68 6f 75 6c 64 20  r.** VFS should 
c000: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f  return SQLITE_NO
c010: 54 46 4f 55 4e 44 20 66 6f 72 20 74 68 69 73 20  TFOUND for this 
c020: 6f 70 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  opcode..**.** <l
c030: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
c040: 5f 52 42 55 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  _RBU]].** The [S
c050: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d  QLITE_FCNTL_RBU]
c060: 20 6f 70 63 6f 64 65 20 69 73 20 69 6d 70 6c 65   opcode is imple
c070: 6d 65 6e 74 65 64 20 62 79 20 74 68 65 20 73 70  mented by the sp
c080: 65 63 69 61 6c 20 56 46 53 20 75 73 65 64 20 62  ecial VFS used b
c090: 79 0a 2a 2a 20 74 68 65 20 52 42 55 20 65 78 74  y.** the RBU ext
c0a0: 65 6e 73 69 6f 6e 20 6f 6e 6c 79 2e 20 20 41 6c  ension only.  Al
c0b0: 6c 20 6f 74 68 65 72 20 56 46 53 20 73 68 6f 75  l other VFS shou
c0c0: 6c 64 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  ld return SQLITE
c0d0: 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f 72 0a 2a 2a  _NOTFOUND for.**
c0e0: 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 20 0a   this opcode.  .
c0f0: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </ul>.*/.#def
c100: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c110: 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20  _LOCKSTATE      
c120: 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69           1.#defi
c130: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c140: 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  GET_LOCKPROXYFIL
c150: 45 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e  E       2.#defin
c160: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  e SQLITE_FCNTL_S
c170: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
c180: 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
c190: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41   SQLITE_FCNTL_LA
c1a0: 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20  ST_ERRNO        
c1b0: 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20        4.#define 
c1c0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
c1d0: 45 5f 48 49 4e 54 20 20 20 20 20 20 20 20 20 20  E_HINT          
c1e0: 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53       5.#define S
c1f0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e  QLITE_FCNTL_CHUN
c200: 4b 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 20  K_SIZE          
c210: 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51      6.#define SQ
c220: 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f  LITE_FCNTL_FILE_
c230: 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 20  POINTER         
c240: 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c     7.#define SQL
c250: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f  ITE_FCNTL_SYNC_O
c260: 4d 49 54 54 45 44 20 20 20 20 20 20 20 20 20 20  MITTED          
c270: 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    8.#define SQLI
c280: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41  TE_FCNTL_WIN32_A
c290: 56 5f 52 45 54 52 59 20 20 20 20 20 20 20 20 20  V_RETRY         
c2a0: 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   9.#define SQLIT
c2b0: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
c2c0: 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 31  WAL            1
c2d0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
c2e0: 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45  _FCNTL_OVERWRITE
c2f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 31                11
c300: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c310: 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20  FCNTL_VFSNAME   
c320: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 32 0a               12.
c330: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c340: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f  CNTL_POWERSAFE_O
c350: 56 45 52 57 52 49 54 45 20 20 20 20 31 33 0a 23  VERWRITE    13.#
c360: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
c370: 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20 20 20 20  NTL_PRAGMA      
c380: 20 20 20 20 20 20 20 20 20 20 20 31 34 0a 23 64             14.#d
c390: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
c3a0: 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 20 20  TL_BUSYHANDLER  
c3b0: 20 20 20 20 20 20 20 20 20 20 31 35 0a 23 64 65            15.#de
c3c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c3d0: 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 20 20  L_TEMPFILENAME  
c3e0: 20 20 20 20 20 20 20 20 20 31 36 0a 23 64 65 66           16.#def
c3f0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c400: 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 20 20  _MMAP_SIZE      
c410: 20 20 20 20 20 20 20 20 31 38 0a 23 64 65 66 69          18.#defi
c420: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c430: 54 52 41 43 45 20 20 20 20 20 20 20 20 20 20 20  TRACE           
c440: 20 20 20 20 20 20 20 31 39 0a 23 64 65 66 69 6e         19.#defin
c450: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48  e SQLITE_FCNTL_H
c460: 41 53 5f 4d 4f 56 45 44 20 20 20 20 20 20 20 20  AS_MOVED        
c470: 20 20 20 20 20 20 32 30 0a 23 64 65 66 69 6e 65        20.#define
c480: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59   SQLITE_FCNTL_SY
c490: 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20  NC              
c4a0: 20 20 20 20 20 32 31 0a 23 64 65 66 69 6e 65 20       21.#define 
c4b0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d  SQLITE_FCNTL_COM
c4c0: 4d 49 54 5f 50 48 41 53 45 54 57 4f 20 20 20 20  MIT_PHASETWO    
c4d0: 20 20 20 20 32 32 0a 23 64 65 66 69 6e 65 20 53      22.#define S
c4e0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
c4f0: 32 5f 53 45 54 5f 48 41 4e 44 4c 45 20 20 20 20  2_SET_HANDLE    
c500: 20 20 20 32 33 0a 23 64 65 66 69 6e 65 20 53 51     23.#define SQ
c510: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42  LITE_FCNTL_WAL_B
c520: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20  LOCK            
c530: 20 20 32 34 0a 23 64 65 66 69 6e 65 20 53 51 4c    24.#define SQL
c540: 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53  ITE_FCNTL_ZIPVFS
c550: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
c560: 20 32 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   25.#define SQLI
c570: 54 45 5f 46 43 4e 54 4c 5f 52 42 55 20 20 20 20  TE_FCNTL_RBU    
c580: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
c590: 32 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  26.#define SQLIT
c5a0: 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e  E_FCNTL_VFS_POIN
c5b0: 54 45 52 20 20 20 20 20 20 20 20 20 20 20 20 32  TER            2
c5c0: 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  7.#define SQLITE
c5d0: 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50  _FCNTL_JOURNAL_P
c5e0: 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 32 38  OINTER        28
c5f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c600: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f  FCNTL_WIN32_GET_
c610: 48 41 4e 44 4c 45 20 20 20 20 20 20 20 32 39 0a  HANDLE       29.
c620: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c630: 43 4e 54 4c 5f 50 44 42 20 20 20 20 20 20 20 20  CNTL_PDB        
c640: 20 20 20 20 20 20 20 20 20 20 20 20 33 30 0a 0a              30..
c650: 2f 2a 20 64 65 70 72 65 63 61 74 65 64 20 6e 61  /* deprecated na
c660: 6d 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  mes */.#define S
c670: 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52  QLITE_GET_LOCKPR
c680: 4f 58 59 46 49 4c 45 20 20 20 20 20 20 53 51 4c  OXYFILE      SQL
c690: 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f  ITE_FCNTL_GET_LO
c6a0: 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 66  CKPROXYFILE.#def
c6b0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c  ine SQLITE_SET_L
c6c0: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20  OCKPROXYFILE    
c6d0: 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53    SQLITE_FCNTL_S
c6e0: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
c6f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c700: 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20  LAST_ERRNO      
c710: 20 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43         SQLITE_FC
c720: 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 0a 0a  NTL_LAST_ERRNO..
c730: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
c740: 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a   Mutex Handle.**
c750: 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f  .** The mutex mo
c760: 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69  dule within SQLi
c770: 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69  te defines [sqli
c780: 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65  te3_mutex] to be
c790: 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20   an.** abstract 
c7a0: 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78  type for a mutex
c7b0: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51   object.  The SQ
c7c0: 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20  Lite core never 
c7d0: 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20  looks.** at the 
c7e0: 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65  internal represe
c7f0: 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73  ntation of an [s
c800: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20  qlite3_mutex].  
c810: 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73  It only.** deals
c820: 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74   with pointers t
c830: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  o the [sqlite3_m
c840: 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  utex] object..**
c850: 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20  .** Mutexes are 
c860: 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73  created using [s
c870: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c  qlite3_mutex_all
c880: 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65  oc()]..*/.typede
c890: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
c8a0: 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d  _mutex sqlite3_m
c8b0: 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  utex;../*.** CAP
c8c0: 49 33 52 45 46 3a 20 4c 6f 61 64 61 62 6c 65 20  I3REF: Loadable 
c8d0: 45 78 74 65 6e 73 69 6f 6e 20 54 68 75 6e 6b 0a  Extension Thunk.
c8e0: 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20  **.** A pointer 
c8f0: 74 6f 20 74 68 65 20 6f 70 61 71 75 65 20 73 71  to the opaque sq
c900: 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e  lite3_api_routin
c910: 65 73 20 73 74 72 75 63 74 75 72 65 20 69 73 20  es structure is 
c920: 70 61 73 73 65 64 20 61 73 0a 2a 2a 20 74 68 65  passed as.** the
c930: 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
c940: 20 74 6f 20 65 6e 74 72 79 20 70 6f 69 6e 74 73   to entry points
c950: 20 6f 66 20 5b 6c 6f 61 64 61 62 6c 65 20 65 78   of [loadable ex
c960: 74 65 6e 73 69 6f 6e 73 5d 2e 20 20 54 68 69 73  tensions].  This
c970: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 6d 75  .** structure mu
c980: 73 74 20 62 65 20 74 79 70 65 64 65 66 65 64 20  st be typedefed 
c990: 69 6e 20 6f 72 64 65 72 20 74 6f 20 77 6f 72 6b  in order to work
c9a0: 20 61 72 6f 75 6e 64 20 63 6f 6d 70 69 6c 65 72   around compiler
c9b0: 20 77 61 72 6e 69 6e 67 73 0a 2a 2a 20 6f 6e 20   warnings.** on 
c9c0: 73 6f 6d 65 20 70 6c 61 74 66 6f 72 6d 73 2e 0a  some platforms..
c9d0: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
c9e0: 74 20 73 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f  t sqlite3_api_ro
c9f0: 75 74 69 6e 65 73 20 73 71 6c 69 74 65 33 5f 61  utines sqlite3_a
ca00: 70 69 5f 72 6f 75 74 69 6e 65 73 3b 0a 0a 2f 2a  pi_routines;../*
ca10: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
ca20: 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63   Interface Objec
ca30: 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  t.**.** An insta
ca40: 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74  nce of the sqlit
ca50: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65  e3_vfs object de
ca60: 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66  fines the interf
ca70: 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74  ace between.** t
ca80: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61  he SQLite core a
ca90: 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  nd the underlyin
caa0: 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  g operating syst
cab0: 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a  em.  The "vfs".*
cac0: 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  * in the name of
cad0: 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e   the object stan
cae0: 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20  ds for "virtual 
caf0: 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 20 20 53  file system".  S
cb00: 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c  ee.** the [VFS |
cb10: 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 61 74 69   VFS documentati
cb20: 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 65 72 20  on] for further 
cb30: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
cb40: 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20  ** The value of 
cb50: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65  the iVersion fie
cb60: 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20  ld is initially 
cb70: 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72  1 but may be lar
cb80: 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65  ger in.** future
cb90: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
cba0: 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c  ite.  Additional
cbb0: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61   fields may be a
cbc0: 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a  ppended to this.
cbd0: 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74  ** object when t
cbe0: 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75  he iVersion valu
cbf0: 65 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e 20  e is increased. 
cc00: 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 73   Note that the s
cc10: 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74  tructure.** of t
cc20: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  he sqlite3_vfs o
cc30: 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69 6e  bject changes in
cc40: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
cc50: 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69   between.** SQLi
cc60: 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39  te version 3.5.9
cc70: 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20 79   and 3.6.0 and y
cc80: 65 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  et the iVersion 
cc90: 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a  field was not.**
cca0: 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a   modified..**.**
ccb0: 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69   The szOsFile fi
ccc0: 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65 20  eld is the size 
ccd0: 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 73 65  of the subclasse
cce0: 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  d [sqlite3_file]
ccf0: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75 73  .** structure us
cd00: 65 64 20 62 79 20 74 68 69 73 20 56 46 53 2e 20  ed by this VFS. 
cd10: 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74   mxPathname is t
cd20: 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
cd30: 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61  h of.** a pathna
cd40: 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a  me in this VFS..
cd50: 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64  **.** Registered
cd60: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a   sqlite3_vfs obj
cd70: 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f 6e  ects are kept on
cd80: 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66   a linked list f
cd90: 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20  ormed by.** the 
cda0: 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20  pNext pointer.  
cdb0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  The [sqlite3_vfs
cdc0: 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20  _register()].** 
cdd0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  and [sqlite3_vfs
cde0: 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69  _unregister()] i
cdf0: 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65  nterfaces manage
ce00: 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e   this list.** in
ce10: 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 20 77   a thread-safe w
ce20: 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  ay.  The [sqlite
ce30: 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e  3_vfs_find()] in
ce40: 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63  terface.** searc
ce50: 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20 4e  hes the list.  N
ce60: 65 69 74 68 65 72 20 74 68 65 20 61 70 70 6c 69  either the appli
ce70: 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20  cation code nor 
ce80: 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65  the VFS.** imple
ce90: 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64  mentation should
cea0: 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 20 70   use the pNext p
ceb0: 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  ointer..**.** Th
cec0: 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73  e pNext field is
ced0: 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20   the only field 
cee0: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  in the sqlite3_v
cef0: 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  fs.** structure 
cf00: 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
cf10: 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53   ever modify.  S
cf20: 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20  QLite will only 
cf30: 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64  access.** or mod
cf40: 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 20 77  ify this field w
cf50: 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70  hile holding a p
cf60: 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 69 63  articular static
cf70: 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61   mutex..** The a
cf80: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
cf90: 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61  d never modify a
cfa0: 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74  nything within t
cfb0: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a  he sqlite3_vfs.*
cfc0: 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68  * object once th
cfd0: 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65  e object has bee
cfe0: 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a  n registered..**
cff0: 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69  .** The zName fi
d000: 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61  eld holds the na
d010: 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f  me of the VFS mo
d020: 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20  dule.  The name 
d030: 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75  must.** be uniqu
d040: 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53  e across all VFS
d050: 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20   modules..**.** 
d060: 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f  [[sqlite3_vfs.xO
d070: 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65  pen]].** ^SQLite
d080: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
d090: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70   the zFilename p
d0a0: 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65  arameter to xOpe
d0b0: 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 61  n.** is either a
d0c0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72   NULL pointer or
d0d0: 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64   string obtained
d0e0: 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61  .** from xFullPa
d0f0: 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20 61 6e  thname() with an
d100: 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66 69 78   optional suffix
d110: 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61   added..** ^If a
d120: 20 73 75 66 66 69 78 20 69 73 20 61 64 64 65 64   suffix is added
d130: 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d   to the zFilenam
d140: 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69 74 20  e parameter, it 
d150: 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20  will.** consist 
d160: 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d 22 20  of a single "-" 
d170: 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77  character follow
d180: 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68  ed by no more th
d190: 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e 75  an.** 11 alphanu
d1a0: 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22  meric and/or "-"
d1b0: 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20   characters..** 
d1c0: 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65 72 20  ^SQLite further 
d1d0: 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a  guarantees that.
d1e0: 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77 69  ** the string wi
d1f0: 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20  ll be valid and 
d200: 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20  unchanged until 
d210: 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63  xClose() is.** c
d220: 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20 6f  alled. Because o
d230: 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73  f the previous s
d240: 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20  entence,.** the 
d250: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63  [sqlite3_file] c
d260: 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65 20  an safely store 
d270: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
d280: 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20  .** filename if 
d290: 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65  it needs to reme
d2a0: 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d  mber the filenam
d2b0: 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f  e for some reaso
d2c0: 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69  n..** If the zFi
d2d0: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
d2e0: 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 20 4e   to xOpen is a N
d2f0: 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
d300: 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69   xOpen.** must i
d310: 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74 65  nvent its own te
d320: 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f 72  mporary name for
d330: 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57 68 65   the file.  ^Whe
d340: 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 46  never the .** xF
d350: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
d360: 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c  r is NULL it wil
d370: 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63 61  l also be the ca
d380: 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 66  se that the.** f
d390: 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 77  lags parameter w
d3a0: 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c  ill include [SQL
d3b0: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
d3c0: 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54  NCLOSE]..**.** T
d3d0: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
d3e0: 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63  t to xOpen() inc
d3f0: 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73  ludes all bits s
d400: 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61  et in.** the fla
d410: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b  gs argument to [
d420: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
d430: 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69  )].  Or if [sqli
d440: 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f  te3_open()].** o
d450: 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  r [sqlite3_open1
d460: 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68  6()] is used, th
d470: 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65  en flags include
d480: 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53  s at least.** [S
d490: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
d4a0: 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f  RITE] | [SQLITE_
d4b0: 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a  OPEN_CREATE]. .*
d4c0: 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65  * If xOpen() ope
d4d0: 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f  ns a file read-o
d4e0: 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74 73  nly then it sets
d4f0: 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a   *pOutFlags to.*
d500: 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54  * include [SQLIT
d510: 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d  E_OPEN_READONLY]
d520: 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e  .  Other bits in
d530: 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20   *pOutFlags may 
d540: 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28  be set..**.** ^(
d550: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f  SQLite will also
d560: 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20   add one of the 
d570: 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20  following flags 
d580: 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a  to the xOpen().*
d590: 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e  * call, dependin
d5a0: 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20  g on the object 
d5b0: 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a  being opened:.**
d5c0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
d5d0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
d5e0: 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  AIN_DB].** <li> 
d5f0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
d600: 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  IN_JOURNAL].** <
d610: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
d620: 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c  N_TEMP_DB].** <l
d630: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
d640: 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  _TEMP_JOURNAL].*
d650: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
d660: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44  OPEN_TRANSIENT_D
d670: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  B].** <li>  [SQL
d680: 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52  ITE_OPEN_SUBJOUR
d690: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
d6a0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45  QLITE_OPEN_MASTE
d6b0: 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  R_JOURNAL].** <l
d6c0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
d6d0: 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e  _WAL].** </ul>)^
d6e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20  .**.** The file 
d6f0: 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  I/O implementati
d700: 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f  on can use the o
d710: 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67 73  bject type flags
d720: 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68   to.** change th
d730: 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20 77  e way it deals w
d740: 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20  ith files.  For 
d750: 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c  example, an appl
d760: 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20  ication.** that 
d770: 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62  does not care ab
d780: 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76 65  out crash recove
d790: 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d  ry or rollback m
d7a0: 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65  ight make.** the
d7b0: 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e   open of a journ
d7c0: 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e  al file a no-op.
d7d0: 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 69 73    Writes to this
d7e0: 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a   journal would.*
d7f0: 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73  * also be no-ops
d800: 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d 70  , and any attemp
d810: 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f  t to read the jo
d820: 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 75  urnal would retu
d830: 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45  rn.** SQLITE_IOE
d840: 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70 6c  RR.  Or the impl
d850: 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74  ementation might
d860: 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74 20   recognize that 
d870: 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  a database.** fi
d880: 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67  le will be doing
d890: 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 65   page-aligned se
d8a0: 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20 77  ctor reads and w
d8b0: 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64 6f  rites in a rando
d8c0: 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20 73  m.** order and s
d8d0: 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73 75  et up its I/O su
d8e0: 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69 6e  bsystem accordin
d8f0: 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  gly..**.** SQLit
d900: 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64  e might also add
d910: 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
d920: 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74  owing flags to t
d930: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a  he xOpen method:
d940: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
d950: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  li> [SQLITE_OPEN
d960: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a  _DELETEONCLOSE].
d970: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
d980: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a  OPEN_EXCLUSIVE].
d990: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54  ** </ul>.**.** T
d9a0: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
d9b0: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66  DELETEONCLOSE] f
d9c0: 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69  lag means the fi
d9d0: 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  le should be.** 
d9e0: 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20  deleted when it 
d9f0: 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65  is closed.  ^The
da00: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
da10: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20  LETEONCLOSE].** 
da20: 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20  will be set for 
da30: 54 45 4d 50 20 64 61 74 61 62 61 73 65 73 20 61  TEMP databases a
da40: 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c  nd their journal
da50: 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20  s, transient.** 
da60: 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64 20 73  databases, and s
da70: 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a  ubjournals..**.*
da80: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  * ^The [SQLITE_O
da90: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66  PEN_EXCLUSIVE] f
daa0: 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20 75 73  lag is always us
dab0: 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f  ed in conjunctio
dac0: 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53  n.** with the [S
dad0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
dae0: 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20 61  E] flag, which a
daf0: 72 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c 79  re both directly
db00: 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f  .** analogous to
db10: 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20   the O_EXCL and 
db20: 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f 66  O_CREAT flags of
db30: 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e 28   the POSIX open(
db40: 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 53  ).** API.  The S
db50: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
db60: 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e 20  SIVE flag, when 
db70: 70 61 69 72 65 64 20 77 69 74 68 20 74 68 65 20  paired with the 
db80: 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  .** SQLITE_OPEN_
db90: 43 52 45 41 54 45 2c 20 69 73 20 75 73 65 64 20  CREATE, is used 
dba0: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  to indicate that
dbb0: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77   file should alw
dbc0: 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 65  ays.** be create
dbd0: 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20 69  d, and that it i
dbe0: 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69 74  s an error if it
dbf0: 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 73 2e   already exists.
dc00: 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74  .** It is <i>not
dc10: 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e 64  </i> used to ind
dc20: 69 63 61 74 65 20 74 68 65 20 66 69 6c 65 20 73  icate the file s
dc30: 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 20  hould be opened 
dc40: 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76  .** for exclusiv
dc50: 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20  e access..**.** 
dc60: 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69  ^At least szOsFi
dc70: 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  le bytes of memo
dc80: 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64  ry are allocated
dc90: 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f   by SQLite.** to
dca0: 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69   hold the  [sqli
dcb0: 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74  te3_file] struct
dcc0: 75 72 65 20 70 61 73 73 65 64 20 61 73 20 74 68  ure passed as th
dcd0: 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d  e third.** argum
dce0: 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54  ent to xOpen.  T
dcf0: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20  he xOpen method 
dd00: 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f  does not have to
dd10: 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65  .** allocate the
dd20: 20 73 74 72 75 63 74 75 72 65 3b 20 69 74 20 73   structure; it s
dd30: 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20  hould just fill 
dd40: 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61  it in.  Note tha
dd50: 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d  t.** the xOpen m
dd60: 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20 74  ethod must set t
dd70: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
dd80: 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74 68  pMethods to eith
dd90: 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73  er.** a valid [s
dda0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
ddb0: 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20  s] object or to 
ddc0: 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73  NULL.  xOpen mus
ddd0: 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65  t do.** this eve
dde0: 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66 61  n if the open fa
ddf0: 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78 70  ils.  SQLite exp
de00: 65 63 74 73 20 74 68 61 74 20 74 68 65 20 73 71  ects that the sq
de10: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
de20: 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77  ods.** element w
de30: 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66 74  ill be valid aft
de40: 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e 73  er xOpen returns
de50: 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74   regardless of t
de60: 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72  he success.** or
de70: 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65 20   failure of the 
de80: 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a  xOpen call..**.*
de90: 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  * [[sqlite3_vfs.
dea0: 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68  xAccess]].** ^Th
deb0: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
dec0: 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61   to xAccess() ma
ded0: 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43  y be [SQLITE_ACC
dee0: 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74  ESS_EXISTS].** t
def0: 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 20 65  o test for the e
df00: 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69  xistence of a fi
df10: 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41  le, or [SQLITE_A
df20: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d  CCESS_READWRITE]
df30: 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74   to.** test whet
df40: 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 72 65  her a file is re
df50: 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61  adable and writa
df60: 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ble, or [SQLITE_
df70: 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20  ACCESS_READ].** 
df80: 74 6f 20 74 65 73 74 20 77 68 65 74 68 65 72 20  to test whether 
df90: 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61  a file is at lea
dfa0: 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20 54  st readable.   T
dfb0: 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20 61  he file can be a
dfc0: 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a  .** directory..*
dfd0: 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  *.** ^SQLite wil
dfe0: 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74  l always allocat
dff0: 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74  e at least mxPat
e000: 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f  hname+1 bytes fo
e010: 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20  r the.** output 
e020: 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68  buffer xFullPath
e030: 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63 74  name.  The exact
e040: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74   size of the out
e050: 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73  put buffer.** is
e060: 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20   also passed as 
e070: 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62  a parameter to b
e080: 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 66  oth  methods. If
e090: 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66   the output buff
e0a0: 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72  er.** is not lar
e0b0: 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49  ge enough, [SQLI
e0c0: 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f  TE_CANTOPEN] sho
e0d0: 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e  uld be returned.
e0e0: 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a   Since this is.*
e0f0: 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66  * handled as a f
e100: 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51  atal error by SQ
e110: 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d  Lite, vfs implem
e120: 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  entations should
e130: 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20   endeavor.** to 
e140: 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 20  prevent this by 
e150: 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61  setting mxPathna
e160: 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 65  me to a sufficie
e170: 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65  ntly large value
e180: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e  ..**.** The xRan
e190: 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65  domness(), xSlee
e1a0: 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69 6d  p(), xCurrentTim
e1b0: 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e  e(), and xCurren
e1c0: 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20  tTimeInt64().** 
e1d0: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 6e  interfaces are n
e1e0: 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20 70 61  ot strictly a pa
e1f0: 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79  rt of the filesy
e200: 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61  stem, but they a
e210: 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69  re.** included i
e220: 6e 20 74 68 65 20 56 46 53 20 73 74 72 75 63 74  n the VFS struct
e230: 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65  ure for complete
e240: 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61  ness..** The xRa
e250: 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74  ndomness() funct
e260: 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ion attempts to 
e270: 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79  return nBytes by
e280: 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71  tes.** of good-q
e290: 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73  uality randomnes
e2a0: 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68  s into zOut.  Th
e2b0: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69  e return value i
e2c0: 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20  s.** the actual 
e2d0: 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
e2e0: 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62  of randomness ob
e2f0: 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78  tained..** The x
e300: 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63  Sleep() method c
e310: 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e  auses the callin
e320: 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65  g thread to slee
e330: 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73  p for at.** leas
e340: 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
e350: 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76  microseconds giv
e360: 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72 65  en.  ^The xCurre
e370: 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68  ntTime().** meth
e380: 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c  od returns a Jul
e390: 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66  ian Day Number f
e3a0: 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  or the current d
e3b0: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73 0a  ate and time as.
e3c0: 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f  ** a floating po
e3d0: 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54  int value..** ^T
e3e0: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  he xCurrentTimeI
e3f0: 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72 65  nt64() method re
e400: 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e 74  turns, as an int
e410: 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61 6e  eger, the Julian
e420: 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20 6d  .** Day Number m
e430: 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38 36 34  ultiplied by 864
e440: 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62 65  00000 (the numbe
e450: 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  r of millisecond
e460: 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f  s in .** a 24-ho
e470: 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53  ur day).  .** ^S
e480: 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74  QLite will use t
e490: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  he xCurrentTimeI
e4a0: 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74 6f  nt64() method to
e4b0: 20 67 65 74 20 74 68 65 20 63 75 72 72 65 6e 74   get the current
e4c0: 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69 6d  .** date and tim
e4d0: 65 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f 64  e if that method
e4e0: 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28 69   is available (i
e4f0: 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32 20  f iVersion is 2 
e500: 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20 61  or .** greater a
e510: 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  nd the function 
e520: 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e  pointer is not N
e530: 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66 61  ULL) and will fa
e540: 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43  ll back.** to xC
e550: 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66 20  urrentTime() if 
e560: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
e570: 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61 62  4() is unavailab
e580: 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78  le..**.** ^The x
e590: 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c  SetSystemCall(),
e5a0: 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 28   xGetSystemCall(
e5b0: 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73 74  ), and xNestSyst
e5c0: 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66 61  emCall() interfa
e5d0: 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 75  ces.** are not u
e5e0: 73 65 64 20 62 79 20 74 68 65 20 53 51 4c 69 74  sed by the SQLit
e5f0: 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20 6f  e core.  These o
e600: 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61 63  ptional interfac
e610: 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 0a  es are provided.
e620: 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65 73  ** by some VFSes
e630: 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20 74   to facilitate t
e640: 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56 46  esting of the VF
e650: 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72 72  S code. By overr
e660: 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65 6d  iding .** system
e670: 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e 63   calls with func
e680: 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73 20  tions under its 
e690: 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74 20  control, a test 
e6a0: 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 73  program can.** s
e6b0: 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20 61  imulate faults a
e6c0: 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74 69  nd error conditi
e6d0: 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20 6f  ons that would o
e6e0: 74 68 65 72 77 69 73 65 20 62 65 20 64 69 66 66  therwise be diff
e6f0: 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f  icult.** or impo
e700: 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63 65  ssible to induce
e710: 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20 73 79  .  The set of sy
e720: 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74 20  stem calls that 
e730: 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65  can be overridde
e740: 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f 6d  n.** varies from
e750: 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f 74   one VFS to anot
e760: 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f 6e  her, and from on
e770: 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65  e version of the
e780: 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68 65   same VFS to the
e790: 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c 69  .** next.  Appli
e7a0: 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65  cations that use
e7b0: 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
e7c0: 73 20 6d 75 73 74 20 62 65 20 70 72 65 70 61 72  s must be prepar
e7d0: 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72  ed for any.** or
e7e0: 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69 6e   all of these in
e7f0: 74 65 72 66 61 63 65 73 20 74 6f 20 62 65 20 4e  terfaces to be N
e800: 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69 72  ULL or for their
e810: 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68 61   behavior to cha
e820: 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20  nge.** from one 
e830: 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20 6e  release to the n
e840: 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ext.  Applicatio
e850: 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74 65  ns must not atte
e860: 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a 2a  mpt to access.**
e870: 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d 65   any of these me
e880: 74 68 6f 64 73 20 69 66 20 74 68 65 20 69 56 65  thods if the iVe
e890: 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46 53  rsion of the VFS
e8a0: 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33 2e   is less than 3.
e8b0: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
e8c0: 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73  ct sqlite3_vfs s
e8d0: 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70 65  qlite3_vfs;.type
e8e0: 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74  def void (*sqlit
e8f0: 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 28  e3_syscall_ptr)(
e900: 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73 71  void);.struct sq
e910: 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e  lite3_vfs {.  in
e920: 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20  t iVersion;     
e930: 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74         /* Struct
e940: 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62  ure version numb
e950: 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33 29  er (currently 3)
e960: 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69   */.  int szOsFi
e970: 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f  le;            /
e980: 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61  * Size of subcla
e990: 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c  ssed sqlite3_fil
e9a0: 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74  e */.  int mxPat
e9b0: 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20  hname;          
e9c0: 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20  /* Maximum file 
e9d0: 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20  pathname length 
e9e0: 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73  */.  sqlite3_vfs
e9f0: 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a   *pNext;      /*
ea00: 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65 64   Next registered
ea10: 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20   VFS */.  const 
ea20: 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20  char *zName;    
ea30: 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68     /* Name of th
ea40: 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20  is virtual file 
ea50: 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64  system */.  void
ea60: 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20   *pAppData;     
ea70: 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20       /* Pointer 
ea80: 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73  to application-s
ea90: 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a  pecific data */.
eaa0: 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73    int (*xOpen)(s
eab0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
eac0: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
ead0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20  sqlite3_file*,. 
eae0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e                in
eaf0: 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f  t flags, int *pO
eb00: 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20  utFlags);.  int 
eb10: 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74  (*xDelete)(sqlit
eb20: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
eb30: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
eb40: 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20  syncDir);.  int 
eb50: 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69 74  (*xAccess)(sqlit
eb60: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
eb70: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
eb80: 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73  flags, int *pRes
eb90: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  Out);.  int (*xF
eba0: 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c  ullPathname)(sql
ebb0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
ebc0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
ebd0: 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f  t nOut, char *zO
ebe0: 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78  ut);.  void *(*x
ebf0: 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f  DlOpen)(sqlite3_
ec00: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
ec10: 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20   *zFilename);.  
ec20: 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29  void (*xDlError)
ec30: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
ec40: 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a  nt nByte, char *
ec50: 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64  zErrMsg);.  void
ec60: 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c   (*(*xDlSym)(sql
ec70: 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c  ite3_vfs*,void*,
ec80: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79   const char *zSy
ec90: 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20  mbol))(void);.  
eca0: 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29  void (*xDlClose)
ecb0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76  (sqlite3_vfs*, v
ecc0: 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  oid*);.  int (*x
ecd0: 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69  Randomness)(sqli
ece0: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42  te3_vfs*, int nB
ecf0: 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29  yte, char *zOut)
ed00: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70  ;.  int (*xSleep
ed10: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
ed20: 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73  int microseconds
ed30: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72  );.  int (*xCurr
ed40: 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33  entTime)(sqlite3
ed50: 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b  _vfs*, double*);
ed60: 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73  .  int (*xGetLas
ed70: 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f  tError)(sqlite3_
ed80: 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20  vfs*, int, char 
ed90: 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68  *);.  /*.  ** Th
eda0: 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  e methods above 
edb0: 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20 31  are in version 1
edc0: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76   of the sqlite_v
edd0: 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64  fs object.  ** d
ede0: 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73  efinition.  Thos
edf0: 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72  e that follow ar
ee00: 65 20 61 64 64 65 64 20 69 6e 20 76 65 72 73 69  e added in versi
ee10: 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20 20  on 2 or later.  
ee20: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72  */.  int (*xCurr
ee30: 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73 71  entTimeInt64)(sq
ee40: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69  lite3_vfs*, sqli
ee50: 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f  te3_int64*);.  /
ee60: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
ee70: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
ee80: 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20 32  versions 1 and 2
ee90: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76   of the sqlite_v
eea0: 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20  fs object..  ** 
eeb0: 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65 20  Those below are 
eec0: 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61 6e  for version 3 an
eed0: 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f 0a  d greater..  */.
eee0: 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73 74    int (*xSetSyst
eef0: 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f  emCall)(sqlite3_
ef00: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
ef10: 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33   *zName, sqlite3
ef20: 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 20  _syscall_ptr);. 
ef30: 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c   sqlite3_syscall
ef40: 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73 74 65  _ptr (*xGetSyste
ef50: 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76  mCall)(sqlite3_v
ef60: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
ef70: 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 74  *zName);.  const
ef80: 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53 79   char *(*xNextSy
ef90: 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
efa0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
efb0: 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a  ar *zName);.  /*
efc0: 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64  .  ** The method
efd0: 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76  s above are in v
efe0: 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75 67  ersions 1 throug
eff0: 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69 74  h 3 of the sqlit
f000: 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20  e_vfs object..  
f010: 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61  ** New fields ma
f020: 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e  y be appended in
f030: 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
f040: 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a  .  The iVersion.
f050: 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20    ** value will 
f060: 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76  increment whenev
f070: 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e  er this happens.
f080: 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a   .  */.};../*.**
f090: 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73   CAPI3REF: Flags
f0a0: 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73   for the xAccess
f0b0: 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a   VFS method.**.*
f0c0: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  * These integer 
f0d0: 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65  constants can be
f0e0: 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68 69   used as the thi
f0f0: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  rd parameter to.
f100: 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  ** the xAccess m
f110: 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c  ethod of an [sql
f120: 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
f130: 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e  .  They determin
f140: 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f  e.** what kind o
f150: 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68  f permissions th
f160: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
f170: 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e   is looking for.
f180: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
f190: 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74  ACCESS_EXISTS, t
f1a0: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
f1b0: 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63  d.** simply chec
f1c0: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66  ks whether the f
f1d0: 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57  ile exists..** W
f1e0: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
f1f0: 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65  S_READWRITE, the
f200: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
f210: 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ** checks whethe
f220: 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72 65  r the named dire
f230: 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72 65  ctory is both re
f240: 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61  adable and writa
f250: 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72  ble.** (in other
f260: 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65 73   words, if files
f270: 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20 72   can be added, r
f280: 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e 61  emoved, and rena
f290: 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68  med within.** th
f2a0: 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a  e directory)..**
f2b0: 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45   The SQLITE_ACCE
f2c0: 53 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f 6e  SS_READWRITE con
f2d0: 73 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e 74  stant is current
f2e0: 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79 20  ly used only by 
f2f0: 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f  the.** [temp_sto
f300: 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61  re_directory pra
f310: 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68 69  gma], though thi
f320: 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20 69  s could change i
f330: 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65  n a future.** re
f340: 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e  lease of SQLite.
f350: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
f360: 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65  ACCESS_READ, the
f370: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
f380: 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ** checks whethe
f390: 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65  r the file is re
f3a0: 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51 4c  adable.  The SQL
f3b0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20  ITE_ACCESS_READ 
f3c0: 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63  constant is.** c
f3d0: 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c  urrently unused,
f3e0: 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68 74   though it might
f3f0: 20 62 65 20 75 73 65 64 20 69 6e 20 61 20 66 75   be used in a fu
f400: 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a  ture release of.
f410: 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64  ** SQLite..*/.#d
f420: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
f430: 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a  ESS_EXISTS    0.
f440: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
f450: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20  CCESS_READWRITE 
f460: 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20 50  1   /* Used by P
f470: 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65  RAGMA temp_store
f480: 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64  _directory */.#d
f490: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
f4a0: 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 20  ESS_READ      2 
f4b0: 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a    /* Unused */..
f4c0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
f4d0: 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 53  Flags for the xS
f4e0: 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f  hmLock VFS metho
f4f0: 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  d.**.** These in
f500: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
f510: 64 65 66 69 6e 65 20 74 68 65 20 76 61 72 69 6f  define the vario
f520: 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61  us locking opera
f530: 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64  tions.** allowed
f540: 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b   by the xShmLock
f550: 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69   method of [sqli
f560: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e  te3_io_methods].
f570: 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69    The.** followi
f580: 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20  ng are the only 
f590: 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f  legal combinatio
f5a0: 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20 74  ns of flags to t
f5b0: 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d  he.** xShmLock m
f5c0: 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  ethod:.**.** <ul
f5d0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  >.** <li>  SQLIT
f5e0: 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c  E_SHM_LOCK | SQL
f5f0: 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a  ITE_SHM_SHARED.*
f600: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
f610: 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45  HM_LOCK | SQLITE
f620: 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a  _SHM_EXCLUSIVE.*
f630: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
f640: 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49  HM_UNLOCK | SQLI
f650: 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a  TE_SHM_SHARED.**
f660: 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
f670: 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  M_UNLOCK | SQLIT
f680: 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a  E_SHM_EXCLUSIVE.
f690: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57  ** </ul>.**.** W
f6a0: 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74  hen unlocking, t
f6b0: 68 65 20 73 61 6d 65 20 53 48 41 52 45 44 20 6f  he same SHARED o
f6c0: 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67  r EXCLUSIVE flag
f6d0: 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69 65   must be supplie
f6e0: 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76 65  d as.** was give
f6f0: 6e 20 6f 6e 20 74 68 65 20 63 6f 72 72 65 73 70  n on the corresp
f700: 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a  onding lock.  .*
f710: 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63  *.** The xShmLoc
f720: 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72 61  k method can tra
f730: 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  nsition between 
f740: 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48 41  unlocked and SHA
f750: 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65  RED or.** betwee
f760: 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45  n unlocked and E
f770: 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63 61  XCLUSIVE.  It ca
f780: 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e 20  nnot transition 
f790: 62 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a 2a  between SHARED.*
f7a0: 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e  * and EXCLUSIVE.
f7b0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
f7c0: 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20  TE_SHM_UNLOCK   
f7d0: 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
f7e0: 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20  LITE_SHM_LOCK   
f7f0: 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
f800: 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45  SQLITE_SHM_SHARE
f810: 44 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e  D       4.#defin
f820: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43  e SQLITE_SHM_EXC
f830: 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a  LUSIVE    8../*.
f840: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61 78  ** CAPI3REF: Max
f850: 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e  imum xShmLock in
f860: 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53  dex.**.** The xS
f870: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e  hmLock method on
f880: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
f890: 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76 61  hods] may use va
f8a0: 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20  lues.** between 
f8b0: 30 20 61 6e 64 20 74 68 69 73 20 75 70 70 65 72  0 and this upper
f8c0: 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22 6f   bound as its "o
f8d0: 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74 2e  ffset" argument.
f8e0: 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63  .** The SQLite c
f8f0: 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 61  ore will never a
f900: 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69 72  ttempt to acquir
f910: 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a 2a  e or release a.*
f920: 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f  * lock outside o
f930: 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a  f this range.*/.
f940: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
f950: 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20  HM_NLOCK        
f960: 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  8.../*.** CAPI3R
f970: 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54  EF: Initialize T
f980: 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72  he SQLite Librar
f990: 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  y.**.** ^The sql
f9a0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
f9b0: 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61  ) routine initia
f9c0: 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c  lizes the.** SQL
f9d0: 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e 54  ite library.  ^T
f9e0: 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  he sqlite3_shutd
f9f0: 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a  own() routine.**
fa00: 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79   deallocates any
fa10: 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 20   resources that 
fa20: 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62  were allocated b
fa30: 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  y sqlite3_initia
fa40: 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65  lize()..** These
fa50: 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65   routines are de
fa60: 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69 6e  signed to aid in
fa70: 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c   process initial
fa80: 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73  ization and.** s
fa90: 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64  hutdown on embed
faa0: 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57 6f  ded systems.  Wo
fab0: 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 63  rkstation applic
fac0: 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20  ations using.** 
fad0: 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20  SQLite normally 
fae0: 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69  do not need to i
faf0: 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 20  nvoke either of 
fb00: 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
fb10: 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20  **.** A call to 
fb20: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
fb30: 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 65  ze() is an "effe
fb40: 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69  ctive" call if i
fb50: 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73  t is.** the firs
fb60: 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69  t time sqlite3_i
fb70: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
fb80: 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68  nvoked during th
fb90: 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a  e lifetime of.**
fba0: 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72   the process, or
fbb0: 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69   if it is the fi
fbc0: 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33  rst time sqlite3
fbd0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
fbe0: 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c   invoked.** foll
fbf0: 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20  owing a call to 
fc00: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
fc10: 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65  ().  ^(Only an e
fc20: 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a  ffective call.**
fc30: 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   of sqlite3_init
fc40: 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e  ialize() does an
fc50: 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  y initialization
fc60: 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c  .  All other cal
fc70: 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65  ls.** are harmle
fc80: 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a  ss no-ops.)^.**.
fc90: 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ** A call to sql
fca0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
fcb0: 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65  is an "effective
fcc0: 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20  " call if it is 
fcd0: 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c  the first.** cal
fce0: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
fcf0: 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68  tdown() since th
fd00: 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69  e last sqlite3_i
fd10: 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28  nitialize().  ^(
fd20: 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63  Only.** an effec
fd30: 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c  tive call to sql
fd40: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
fd50: 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69  does any deiniti
fd60: 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c  alization..** Al
fd70: 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61  l other valid ca
fd80: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  lls to sqlite3_s
fd90: 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61  hutdown() are ha
fda0: 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e  rmless no-ops.)^
fdb0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
fdc0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
fdd0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 72  interface is thr
fde0: 65 61 64 73 61 66 65 2c 20 62 75 74 20 73 71 6c  eadsafe, but sql
fdf0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a  ite3_shutdown().
fe00: 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 20  ** is not.  The 
fe10: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
fe20: 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75 73  () interface mus
fe30: 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64  t only be called
fe40: 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c   from a.** singl
fe50: 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f  e thread.  All o
fe60: 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f  pen [database co
fe70: 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20  nnections] must 
fe80: 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c  be closed and al
fe90: 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74  l.** other SQLit
fea0: 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73 74  e resources must
feb0: 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
fec0: 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e  prior to invokin
fed0: 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 75  g.** sqlite3_shu
fee0: 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41  tdown()..**.** A
fef0: 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67  mong other thing
ff00: 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74  s, ^sqlite3_init
ff10: 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e  ialize() will in
ff20: 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  voke.** sqlite3_
ff30: 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69  os_init().  Simi
ff40: 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f  larly, ^sqlite3_
ff50: 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69  shutdown().** wi
ff60: 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ll invoke sqlite
ff70: 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a  3_os_end()..**.*
ff80: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
ff90: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
ffa0: 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ine returns [SQL
ffb0: 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
ffc0: 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73  ss..** ^If for s
ffd0: 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69  ome reason, sqli
ffe0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
fff0: 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e   is unable to in
10000 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20  itialize.** the 
10010 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 70 73  library (perhaps
10020 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f   it is unable to
10030 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64   allocate a need
10040 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 68  ed resource such
10050 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20  .** as a mutex) 
10060 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65  it returns an [e
10070 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72  rror code] other
10080 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b   than [SQLITE_OK
10090 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ]..**.** ^The sq
100a0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
100b0 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61  () routine is ca
100c0 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  lled internally 
100d0 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a  by many other.**
100e0 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
100f0 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70  es so that an ap
10100 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c  plication usuall
10110 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  y does not need 
10120 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c  to.** invoke sql
10130 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
10140 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72  ) directly.  For
10150 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74   example, [sqlit
10160 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61  e3_open()].** ca
10170 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  lls sqlite3_init
10180 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20  ialize() so the 
10190 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77  SQLite library w
101a0 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63  ill be automatic
101b0 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69  ally.** initiali
101c0 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  zed when [sqlite
101d0 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c  3_open()] is cal
101e0 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f  led if it has no
101f0 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64  t be initialized
10200 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e 48  .** already.  ^H
10210 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74  owever, if SQLit
10220 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
10230 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  th the [SQLITE_O
10240 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a  MIT_AUTOINIT].**
10250 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
10260 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61  tion, then the a
10270 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74  utomatic calls t
10280 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  o sqlite3_initia
10290 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d  lize().** are om
102a0 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 70  itted and the ap
102b0 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63  plication must c
102c0 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  all sqlite3_init
102d0 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c  ialize() directl
102e0 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73  y.** prior to us
102f0 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51  ing any other SQ
10300 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
10310 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72   For maximum por
10320 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20  tability,.** it 
10330 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
10340 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  hat applications
10350 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73   always invoke s
10360 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
10370 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20  e().** directly 
10380 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61  prior to using a
10390 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ny other SQLite 
103a0 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 75  interface.  Futu
103b0 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f  re releases.** o
103c0 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71  f SQLite may req
103d0 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f  uire this.  In o
103e0 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
103f0 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 74  behavior exhibit
10400 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74  ed.** when SQLit
10410 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
10420 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  th [SQLITE_OMIT_
10430 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20  AUTOINIT] might 
10440 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65  become the.** de
10450 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69  fault behavior i
10460 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65  n some future re
10470 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e  lease of SQLite.
10480 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
10490 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75  e3_os_init() rou
104a0 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74  tine does operat
104b0 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69  ing-system speci
104c0 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a  fic.** initializ
104d0 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c  ation of the SQL
104e0 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68  ite library.  Th
104f0 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  e sqlite3_os_end
10500 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e  ().** routine un
10510 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20  does the effect 
10520 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  of sqlite3_os_in
10530 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74  it().  Typical t
10540 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65  asks.** performe
10550 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 69  d by these routi
10560 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f  nes include allo
10570 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f  cation or deallo
10580 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61  cation.** of sta
10590 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69  tic resources, i
105a0 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66  nitialization of
105b0 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65   global variable
105c0 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70  s,.** setting up
105d0 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69   a default [sqli
105e0 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c  te3_vfs] module,
105f0 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a   or setting up.*
10600 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  * a default conf
10610 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20  iguration using 
10620 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
10630 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70  )]..**.** The ap
10640 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
10650 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69   never invoke ei
10660 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  ther sqlite3_os_
10670 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  init().** or sql
10680 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69  ite3_os_end() di
10690 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70  rectly.  The app
106a0 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
106b0 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73  only invoke.** s
106c0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
106d0 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
106e0 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65  shutdown().  The
106f0 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
10700 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
10710 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61  is called automa
10720 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74  tically by sqlit
10730 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
10740 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  and.** sqlite3_o
10750 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65  s_end() is calle
10760 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75  d by sqlite3_shu
10770 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70  tdown().  Approp
10780 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  riate.** impleme
10790 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c  ntations for sql
107a0 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61  ite3_os_init() a
107b0 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nd sqlite3_os_en
107c0 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74  d().** are built
107d0 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65   into SQLite whe
107e0 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64  n it is compiled
107f0 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f   for Unix, Windo
10800 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20  ws, or OS/2..** 
10810 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69  When [custom bui
10820 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 20  lds | built for 
10830 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d  other platforms]
10840 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20 5b  .** (using the [
10850 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d  SQLITE_OS_OTHER=
10860 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a  1] compile-time.
10870 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61  ** option) the a
10880 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
10890 73 75 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c  supply a suitabl
108a0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
108b0 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
108c0 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71  os_init() and sq
108d0 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20  lite3_os_end(). 
108e0 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   An application-
108f0 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c  supplied.** impl
10900 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71  ementation of sq
10910 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
10920 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  or sqlite3_os_en
10930 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75  d().** must retu
10940 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  rn [SQLITE_OK] o
10950 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f  n success and so
10960 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20  me other [error 
10970 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61  code] upon.** fa
10980 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ilure..*/.int sq
10990 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
109a0 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69  (void);.int sqli
109b0 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69  te3_shutdown(voi
109c0 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
109d0 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 69  os_init(void);.i
109e0 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nt sqlite3_os_en
109f0 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20  d(void);../*.** 
10a00 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67  CAPI3REF: Config
10a10 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65  uring The SQLite
10a20 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54   Library.**.** T
10a30 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  he sqlite3_confi
10a40 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  g() interface is
10a50 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c   used to make gl
10a60 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69  obal configurati
10a70 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  on.** changes to
10a80 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72   SQLite in order
10a90 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20   to tune SQLite 
10aa0 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20  to the specific 
10ab0 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20  needs of.** the 
10ac0 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68  application.  Th
10ad0 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67  e default config
10ae0 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d  uration is recom
10af0 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a  mended for most.
10b00 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** applications 
10b10 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74  and so this rout
10b20 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e  ine is usually n
10b30 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49  ot necessary.  I
10b40 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64  t is.** provided
10b50 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65   to support rare
10b60 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69   applications wi
10b70 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73  th unusual needs
10b80 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 54 68 65 20 73  ..**.** <b>The s
10b90 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
10ba0 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74  interface is not
10bb0 20 74 68 72 65 61 64 73 61 66 65 2e 20 54 68 65   threadsafe. The
10bc0 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
10bd0 6d 75 73 74 20 65 6e 73 75 72 65 20 74 68 61 74  must ensure that
10be0 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65   no other SQLite
10bf0 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
10c00 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72  invoked by other
10c10 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c  .** threads whil
10c20 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
10c30 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 3c 2f  () is running.</
10c40 62 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  b>.**.** The sql
10c50 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e  ite3_config() in
10c60 74 65 72 66 61 63 65 0a 2a 2a 20 6d 61 79 20 6f  terface.** may o
10c70 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70  nly be invoked p
10c80 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20  rior to library 
10c90 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75  initialization u
10ca0 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
10cb0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f  _initialize()] o
10cc0 72 20 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e  r after shutdown
10cd0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75   by [sqlite3_shu
10ce0 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66  tdown()]..** ^If
10cf0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
10d00 29 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65  ) is called afte
10d10 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  r [sqlite3_initi
10d20 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66  alize()] and bef
10d30 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ore.** [sqlite3_
10d40 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e  shutdown()] then
10d50 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20   it will return 
10d60 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a  SQLITE_MISUSE..*
10d70 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c  * Note, however,
10d80 20 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63   that ^sqlite3_c
10d90 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 63  onfig() can be c
10da0 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66  alled as part of
10db0 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   the.** implemen
10dc0 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70  tation of an app
10dd0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
10de0 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69   [sqlite3_os_ini
10df0 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  t()]..**.** The 
10e00 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
10e10 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  o sqlite3_config
10e20 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  () is an integer
10e30 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74 69  .** [configurati
10e40 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20  on option] that 
10e50 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68  determines.** wh
10e60 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53  at property of S
10e70 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20 63  QLite is to be c
10e80 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62 73  onfigured.  Subs
10e90 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73  equent arguments
10ea0 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69  .** vary dependi
10eb0 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69  ng on the [confi
10ec0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d  guration option]
10ed0 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74  .** in the first
10ee0 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
10ef0 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75   ^When a configu
10f00 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
10f10 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f   set, sqlite3_co
10f20 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b  nfig() returns [
10f30 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e  SQLITE_OK]..** ^
10f40 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73  If the option is
10f50 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69   unknown or SQLi
10f60 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  te is unable to 
10f70 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a  set the option.*
10f80 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74  * then this rout
10f90 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f  ine returns a no
10fa0 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f  n-zero [error co
10fb0 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  de]..*/.int sqli
10fc0 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20  te3_config(int, 
10fd0 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ...);../*.** CAP
10fe0 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65  I3REF: Configure
10ff0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
11000 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  tions.** METHOD:
11010 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54   sqlite3.**.** T
11020 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  he sqlite3_db_co
11030 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
11040 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65   is used to make
11050 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a   configuration.*
11060 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b  * changes to a [
11070 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
11080 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72  ion].  The inter
11090 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20  face is similar 
110a0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
110b0 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74 20  onfig()] except 
110c0 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65 73  that the changes
110d0 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67   apply to a sing
110e0 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  le.** [database 
110f0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65  connection] (spe
11100 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66 69  cified in the fi
11110 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a 2a  rst argument)..*
11120 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  *.** The second 
11130 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
11140 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c  te3_db_config(D,
11150 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a  V,...)  is the.*
11160 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  * [SQLITE_DBCONF
11170 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 63  IG_LOOKASIDE | c
11180 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72  onfiguration ver
11190 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20  b] - an integer 
111a0 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69 6e  code .** that in
111b0 64 69 63 61 74 65 73 20 77 68 61 74 20 61 73 70  dicates what asp
111c0 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61  ect of the [data
111d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
111e0 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 67   is being config
111f0 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71 75  ured..** Subsequ
11200 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76 61  ent arguments va
11210 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ry depending on 
11220 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
11230 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43  n verb..**.** ^C
11240 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
11250 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75  db_config() retu
11260 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20  rn SQLITE_OK if 
11270 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74  and only if.** t
11280 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69  he call is consi
11290 64 65 72 65 64 20 73 75 63 63 65 73 73 66 75 6c  dered successful
112a0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
112b0 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74  _db_config(sqlit
112c0 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e  e3*, int op, ...
112d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
112e0 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63  EF: Memory Alloc
112f0 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a  ation Routines.*
11300 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
11310 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
11320 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
11330 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53 51  rface between SQ
11340 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d  Lite.** and low-
11350 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  level memory all
11360 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
11370 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a  ..**.** This obj
11380 65 63 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f  ect is used in o
11390 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e  nly one place in
113a0 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65   the SQLite inte
113b0 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e  rface..** A poin
113c0 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
113d0 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
113e0 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e  t is the argumen
113f0 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  t to.** [sqlite3
11400 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20  _config()] when 
11410 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
11420 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b  n option is.** [
11430 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
11440 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45  LLOC] or [SQLITE
11450 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
11460 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65 61  C].  .** By crea
11470 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65  ting an instance
11480 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a   of this object.
11490 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69  ** and passing i
114a0 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
114b0 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f  nfig]([SQLITE_CO
114c0 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a  NFIG_MALLOC]).**
114d0 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72   during configur
114e0 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63  ation, an applic
114f0 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 66  ation can specif
11500 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65  y an alternative
11510 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
11520 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20  ation subsystem 
11530 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75 73  for SQLite to us
11540 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  e for all of its
11550 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f  .** dynamic memo
11560 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20  ry needs..**.** 
11570 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74 65  Note that SQLite
11580 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76 65   comes with seve
11590 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65  ral [built-in me
115a0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d  mory allocators]
115b0 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65 72  .** that are per
115c0 66 65 63 74 6c 79 20 61 64 65 71 75 61 74 65 20  fectly adequate 
115d0 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c  for the overwhel
115e0 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66  ming majority of
115f0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
11600 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f   and that this o
11610 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73  bject is only us
11620 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d  eful to a tiny m
11630 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69  inority of appli
11640 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20  cations.** with 
11650 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f  specialized memo
11660 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65  ry allocation re
11670 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69  quirements.  Thi
11680 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61  s object is.** a
11690 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20  lso used during 
116a0 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74  testing of SQLit
116b0 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70  e in order to sp
116c0 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61  ecify an alterna
116d0 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  tive.** memory a
116e0 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69  llocator that si
116f0 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f  mulates memory o
11700 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e  ut-of-memory con
11710 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72  ditions in.** or
11720 64 65 72 20 74 6f 20 76 65 72 69 66 79 20 74 68  der to verify th
11730 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65  at SQLite recove
11740 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72  rs gracefully fr
11750 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69  om such.** condi
11760 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tions..**.** The
11770 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c   xMalloc, xReall
11780 6f 63 2c 20 61 6e 64 20 78 46 72 65 65 20 6d 65  oc, and xFree me
11790 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20  thods must work 
117a0 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c  like the.** mall
117b0 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20  oc(), realloc() 
117c0 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63 74  and free() funct
117d0 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74  ions from the st
117e0 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
117f0 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61  ..** ^SQLite gua
11800 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65  rantees that the
11810 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
11820 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20   to.** xRealloc 
11830 69 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c 75  is always a valu
11840 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 61 20  e returned by a 
11850 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52  prior call to xR
11860 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53  oundup..**.** xS
11870 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72  ize should retur
11880 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20  n the allocated 
11890 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79  size of a memory
118a0 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70   allocation.** p
118b0 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e  reviously obtain
118c0 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20  ed from xMalloc 
118d0 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68  or xRealloc.  Th
118e0 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65  e allocated size
118f0 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 74  .** is always at
11900 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61 73   least as big as
11910 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 73   the requested s
11920 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20 6c  ize but may be l
11930 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  arger..**.** The
11940 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64   xRoundup method
11950 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 77 6f   returns what wo
11960 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f 63  uld be the alloc
11970 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20  ated size of.** 
11980 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
11990 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72 74  ion given a part
119a0 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 65 64  icular requested
119b0 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d   size.  Most mem
119c0 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72  ory.** allocator
119d0 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72  s round up memor
119e0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74  y allocations at
119f0 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e 65   least to the ne
11a00 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f  xt multiple.** o
11a10 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63  f 8.  Some alloc
11a20 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 74  ators round up t
11a30 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 69  o a larger multi
11a40 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 65  ple or to a powe
11a50 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79  r of 2..** Every
11a60 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
11a70 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69 6e  on request comin
11a80 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73 71  g in through [sq
11a90 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a  lite3_malloc()].
11aa0 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  ** or [sqlite3_r
11ab0 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74 20  ealloc()] first 
11ac0 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20  calls xRoundup. 
11ad0 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65 74   If xRoundup ret
11ae0 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74  urns 0, .** that
11af0 20 63 61 75 73 65 73 20 74 68 65 20 63 6f 72 72   causes the corr
11b00 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79  esponding memory
11b10 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66   allocation to f
11b20 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ail..**.** The x
11b30 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69 74  Init method init
11b40 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f  ializes the memo
11b50 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 46  ry allocator.  F
11b60 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69  or example,.** i
11b70 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 65  t might allocate
11b80 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75 74   any require mut
11b90 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c 69  exes or initiali
11ba0 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  ze internal data
11bb0 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e 20  .** structures. 
11bc0 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20 6d   The xShutdown m
11bd0 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64  ethod is invoked
11be0 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62 79   (indirectly) by
11bf0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  .** [sqlite3_shu
11c00 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f  tdown()] and sho
11c10 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 61  uld deallocate a
11c20 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61 63 71  ny resources acq
11c30 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69  uired.** by xIni
11c40 74 2e 20 20 54 68 65 20 70 41 70 70 44 61 74 61  t.  The pAppData
11c50 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65 64   pointer is used
11c60 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72   as the only par
11c70 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e  ameter to.** xIn
11c80 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e  it and xShutdown
11c90 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68  ..**.** SQLite h
11ca0 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45  olds the [SQLITE
11cb0 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41  _MUTEX_STATIC_MA
11cc0 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68 65 6e  STER] mutex when
11cd0 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74   it invokes.** t
11ce0 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c  he xInit method,
11cf0 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20 6d 65   so the xInit me
11d00 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62 65  thod need not be
11d10 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68   threadsafe.  Th
11d20 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d  e.** xShutdown m
11d30 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61  ethod is only ca
11d40 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  lled from [sqlit
11d50 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 73  e3_shutdown()] s
11d60 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  o it does.** not
11d70 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68 72 65   need to be thre
11d80 61 64 73 61 66 65 20 65 69 74 68 65 72 2e 20 20  adsafe either.  
11d90 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65  For all other me
11da0 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a  thods, SQLite.**
11db0 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49   holds the [SQLI
11dc0 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
11dd0 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f  MEM] mutex as lo
11de0 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51  ng as the.** [SQ
11df0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
11e00 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 72 61  TATUS] configura
11e10 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74  tion option is t
11e20 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 68 0a  urned on (which.
11e30 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65 66 61  ** it is by defa
11e40 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 65 20  ult) and so the 
11e50 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75 74 6f  methods are auto
11e60 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69 61 6c  matically serial
11e70 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72  ized..** However
11e80 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  , if [SQLITE_CON
11e90 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69  FIG_MEMSTATUS] i
11ea0 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 6e  s disabled, then
11eb0 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65   the other.** me
11ec0 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20 74 68  thods must be th
11ed0 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c 73 65  readsafe or else
11ee0 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 6e 20   make their own 
11ef0 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72  arrangements for
11f00 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 69 6f  .** serializatio
11f10 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  n..**.** SQLite 
11f20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b  will never invok
11f30 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 20 74  e xInit() more t
11f40 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75 74  han once without
11f50 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a   an intervening.
11f60 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 75 74  ** call to xShut
11f70 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64  down()..*/.typed
11f80 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
11f90 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71  3_mem_methods sq
11fa0 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
11fb0 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  s;.struct sqlite
11fc0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a  3_mem_methods {.
11fd0 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f    void *(*xMallo
11fe0 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20  c)(int);        
11ff0 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63   /* Memory alloc
12000 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a  ation function *
12010 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65 65  /.  void (*xFree
12020 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20  )(void*);       
12030 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69     /* Free a pri
12040 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f  or allocation */
12050 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c  .  void *(*xReal
12060 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b  loc)(void*,int);
12070 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61    /* Resize an a
12080 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69  llocation */.  i
12090 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 64  nt (*xSize)(void
120a0 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a  *);           /*
120b0 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65   Return the size
120c0 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f   of an allocatio
120d0 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f  n */.  int (*xRo
120e0 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20  undup)(int);    
120f0 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75        /* Round u
12100 70 20 72 65 71 75 65 73 74 20 73 69 7a 65 20 74  p request size t
12110 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  o allocation siz
12120 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e  e */.  int (*xIn
12130 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  it)(void*);     
12140 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c        /* Initial
12150 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ize the memory a
12160 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f  llocator */.  vo
12170 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28  id (*xShutdown)(
12180 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20  void*);      /* 
12190 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65  Deinitialize the
121a0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
121b0 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70  r */.  void *pAp
121c0 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20  pData;          
121d0 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e        /* Argumen
121e0 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64  t to xInit() and
121f0 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a   xShutdown() */.
12200 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
12210 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f  EF: Configuratio
12220 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59  n Options.** KEY
12230 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72  WORDS: {configur
12240 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a  ation option}.**
12250 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
12260 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69  nts are the avai
12270 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f  lable integer co
12280 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
12290 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20  ons that.** can 
122a0 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
122b0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
122c0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
122d0 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
122e0 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63  ace..**.** New c
122f0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
12300 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65  ions may be adde
12310 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
12320 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
12330 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66  ** Existing conf
12340 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
12350 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f  s might be disco
12360 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63  ntinued.  Applic
12370 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64  ations.** should
12380 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72   check the retur
12390 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c  n code from [sql
123a0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74  ite3_config()] t
123b0 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74  o make sure that
123c0 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72  .** the call wor
123d0 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ked.  The [sqlit
123e0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  e3_config()] int
123f0 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75  erface will retu
12400 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f  rn a.** non-zero
12410 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66   [error code] if
12420 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20   a discontinued 
12430 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63  or unsupported c
12440 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
12450 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65  ion.** is invoke
12460 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  d..**.** <dl>.**
12470 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
12480 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20  _SINGLETHREAD]] 
12490 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
124a0 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f  G_SINGLETHREAD</
124b0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65  dt>.** <dd>There
124c0 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74   are no argument
124d0 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
124e0 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  .  ^This option 
124f0 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72  sets the.** [thr
12500 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20  eading mode] to 
12510 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20 20  Single-thread.  
12520 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
12530 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61  it disables.** a
12540 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20  ll mutexing and 
12550 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f  puts SQLite into
12560 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74   a mode where it
12570 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65   can only be use
12580 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65  d.** by a single
12590 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20 53   thread.   ^If S
125a0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
125b0 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
125c0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
125d0 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
125e0 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
125f0 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
12600 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f  .** it is not po
12610 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67 65  ssible to change
12620 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20   the [threading 
12630 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20 64  mode] from its d
12640 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20  efault.** value 
12650 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64  of Single-thread
12660 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65 33   and so [sqlite3
12670 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20  _config()] will 
12680 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49  return .** [SQLI
12690 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c  TE_ERROR] if cal
126a0 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c  led with the SQL
126b0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
126c0 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69  ETHREAD.** confi
126d0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
126e0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
126f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
12700 49 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51  ITHREAD]] <dt>SQ
12710 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
12720 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20  ITHREAD</dt>.** 
12730 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f  <dd>There are no
12740 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
12750 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69  is option.  ^Thi
12760 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68  s option sets th
12770 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20  e.** [threading 
12780 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74  mode] to Multi-t
12790 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72  hread.  In other
127a0 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62   words, it disab
127b0 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20  les.** mutexing 
127c0 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  on [database con
127d0 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72  nection] and [pr
127e0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
127f0 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68  ] objects..** Th
12800 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73  e application is
12810 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
12820 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63   serializing acc
12830 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62  ess to.** [datab
12840 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
12850 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
12860 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74  tatements].  But
12870 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a   other mutexes.*
12880 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f  * are enabled so
12890 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
128a0 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 73 65  l be safe to use
128b0 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65   in a multi-thre
128c0 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d  aded.** environm
128d0 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e  ent as long as n
128e0 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 61 74  o two threads at
128f0 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65  tempt to use the
12900 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61   same.** [databa
12910 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
12920 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e  t the same time.
12930 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20    ^If SQLite is 
12940 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
12950 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
12960 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
12970 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
12980 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
12990 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73  on then.** it is
129a0 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f   not possible to
129b0 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d 74   set the Multi-t
129c0 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67  hread [threading
129d0 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73   mode] and.** [s
129e0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
129f0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
12a00 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
12a10 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  alled with the.*
12a20 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  * SQLITE_CONFIG_
12a30 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e 66  MULTITHREAD conf
12a40 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
12a50 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
12a60 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
12a70 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51  IALIZED]] <dt>SQ
12a80 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
12a90 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  ALIZED</dt>.** <
12aa0 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20  dd>There are no 
12ab0 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
12ac0 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73  s option.  ^This
12ad0 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65   option sets the
12ae0 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  .** [threading m
12af0 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a  ode] to Serializ
12b00 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  ed. In other wor
12b10 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e 20  ds, this option 
12b20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d  enables.** all m
12b30 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e 67  utexes including
12b40 20 74 68 65 20 72 65 63 75 72 73 69 76 65 0a 2a   the recursive.*
12b50 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 61  * mutexes on [da
12b60 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
12b70 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  n] and [prepared
12b80 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65   statement] obje
12b90 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20  cts..** In this 
12ba0 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73 20 74  mode (which is t
12bb0 68 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e 20  he default when 
12bc0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
12bd0 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49  ed with.** [SQLI
12be0 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 5d  TE_THREADSAFE=1]
12bf0 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  ) the SQLite lib
12c00 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66  rary will itself
12c10 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73   serialize acces
12c20 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73  s.** to [databas
12c30 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61  e connections] a
12c40 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  nd [prepared sta
12c50 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74  tements] so that
12c60 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74   the.** applicat
12c70 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75  ion is free to u
12c80 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  se the same [dat
12c90 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
12ca0 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65  ] or the.** same
12cb0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
12cc0 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65  ment] in differe
12cd0 6e 74 20 74 68 72 65 61 64 73 20 61 74 20 74 68  nt threads at th
12ce0 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20  e same time..** 
12cf0 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
12d00 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
12d10 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
12d20 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
12d30 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
12d40 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
12d50 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e   then.** it is n
12d60 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73  ot possible to s
12d70 65 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a 65  et the Serialize
12d80 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
12d90 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  e] and.** [sqlit
12da0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c  e3_config()] wil
12db0 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
12dc0 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65  _ERROR] if calle
12dd0 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51  d with the.** SQ
12de0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
12df0 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72 61  ALIZED configura
12e00 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64  tion option.</dd
12e10 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
12e20 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d  _CONFIG_MALLOC]]
12e30 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
12e40 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a  IG_MALLOC</dt>.*
12e50 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c  * <dd> ^(The SQL
12e60 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
12e70 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  C option takes a
12e80 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
12e90 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 61 20   which is .** a 
12ea0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
12eb0 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
12ec0 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
12ed0 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a  ds] structure..*
12ee0 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73  * The argument s
12ef0 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65  pecifies.** alte
12f00 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65  rnative low-leve
12f10 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
12f20 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ion routines to 
12f30 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65  be used in place
12f40 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72   of.** the memor
12f50 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
12f60 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f  tines built into
12f70 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69   SQLite.)^ ^SQLi
12f80 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20  te makes.** its 
12f90 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79  own private copy
12fa0 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20   of the content 
12fb0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
12fc0 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  mem_methods] str
12fd0 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65  ucture.** before
12fe0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
12ff0 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65 74  nfig()] call ret
13000 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  urns.</dd>.**.**
13010 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
13020 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74  _GETMALLOC]] <dt
13030 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
13040 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a  ETMALLOC</dt>.**
13050 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49   <dd> ^(The SQLI
13060 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
13070 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  LOC option takes
13080 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
13090 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61  nt which.** is a
130a0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
130b0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
130c0 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
130d0 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a  ods] structure..
130e0 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
130f0 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  mem_methods].** 
13100 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c  structure is fil
13110 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72  led with the cur
13120 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d  rently defined m
13130 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
13140 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20   routines.)^.** 
13150 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20  This option can 
13160 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c  be used to overl
13170 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20  oad the default 
13180 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
13190 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69  n.** routines wi
131a0 74 68 20 61 20 77 72 61 70 70 65 72 20 74 68 61  th a wrapper tha
131b0 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65  t simulations me
131c0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
131d0 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72  failure or.** tr
131e0 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67  acks memory usag
131f0 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20  e, for example. 
13200 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
13210 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
13220 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49  TATUS]] <dt>SQLI
13230 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
13240 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TUS</dt>.** <dd>
13250 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e   ^The SQLITE_CON
13260 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 6f 70  FIG_MEMSTATUS op
13270 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c  tion takes singl
13280 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79  e argument of ty
13290 70 65 20 69 6e 74 2c 0a 2a 2a 20 69 6e 74 65 72  pe int,.** inter
132a0 70 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c  preted as a bool
132b0 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c  ean, which enabl
132c0 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74  es or disables t
132d0 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66  he collection of
132e0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
132f0 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73  ation statistics
13300 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20  . ^(When memory 
13310 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
13320 73 74 69 63 73 20 61 72 65 0a 2a 2a 20 64 69 73  stics are.** dis
13330 61 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c 6c 6f  abled, the follo
13340 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65  wing SQLite inte
13350 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f  rfaces become no
13360 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a  n-operational:.*
13370 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  *   <ul>.**   <l
13380 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  i> [sqlite3_memo
13390 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20  ry_used()].**   
133a0 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65  <li> [sqlite3_me
133b0 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
133c0 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
133d0 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
133e0 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c  imit64()].**   <
133f0 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61  li> [sqlite3_sta
13400 74 75 73 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 2f  tus64()].**   </
13410 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79  ul>)^.** ^Memory
13420 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74   allocation stat
13430 69 73 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c  istics are enabl
13440 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e  ed by default un
13450 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a  less SQLite is.*
13460 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  * compiled with 
13470 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f  [SQLITE_DEFAULT_
13480 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20  MEMSTATUS]=0 in 
13490 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72  which case memor
134a0 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  y.** allocation 
134b0 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64  statistics are d
134c0 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
134d0 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a  lt..** </dd>.**.
134e0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
134f0 49 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64 74  IG_SCRATCH]] <dt
13500 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
13510 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  CRATCH</dt>.** <
13520 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  dd> ^The SQLITE_
13530 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 6f  CONFIG_SCRATCH o
13540 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20  ption specifies 
13550 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20  a static memory 
13560 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 53  buffer.** that S
13570 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f  QLite can use fo
13580 72 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79  r scratch memory
13590 2e 20 20 5e 28 54 68 65 72 65 20 61 72 65 20 74  .  ^(There are t
135a0 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 0a 2a  hree arguments.*
135b0 2a 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46  * to SQLITE_CONF
135c0 49 47 5f 53 43 52 41 54 43 48 3a 20 20 41 20 70  IG_SCRATCH:  A p
135d0 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79 74 65  ointer an 8-byte
135e0 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f  .** aligned memo
135f0 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d 20 77  ry buffer from w
13600 68 69 63 68 20 74 68 65 20 73 63 72 61 74 63 68  hich the scratch
13610 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c   allocations wil
13620 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74  l be.** drawn, t
13630 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  he size of each 
13640 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69  scratch allocati
13650 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20  on (sz),.** and 
13660 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  the maximum numb
13670 65 72 20 6f 66 20 73 63 72 61 74 63 68 20 61 6c  er of scratch al
13680 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e 29 5e  locations (N).)^
13690 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
136a0 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61  gument must be a
136b0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38   pointer to an 8
136c0 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75  -byte aligned bu
136d0 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65  ffer.** of at le
136e0 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f  ast sz*N bytes o
136f0 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51  f memory..** ^SQ
13700 4c 69 74 65 20 77 69 6c 6c 20 6e 6f 74 20 75 73  Lite will not us
13710 65 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  e more than one 
13720 73 63 72 61 74 63 68 20 62 75 66 66 65 72 73 20  scratch buffers 
13730 70 65 72 20 74 68 72 65 61 64 2e 0a 2a 2a 20 5e  per thread..** ^
13740 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65  SQLite will neve
13750 72 20 72 65 71 75 65 73 74 20 61 20 73 63 72 61  r request a scra
13760 74 63 68 20 62 75 66 66 65 72 20 74 68 61 74 20  tch buffer that 
13770 69 73 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a  is more than 6.*
13780 2a 20 74 69 6d 65 73 20 74 68 65 20 64 61 74 61  * times the data
13790 62 61 73 65 20 70 61 67 65 20 73 69 7a 65 2e 0a  base page size..
137a0 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 6e 65  ** ^If SQLite ne
137b0 65 64 73 20 6e 65 65 64 73 20 61 64 64 69 74 69  eds needs additi
137c0 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20  onal.** scratch 
137d0 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77 68  memory beyond wh
137e0 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62  at is provided b
137f0 79 20 74 68 69 73 20 63 6f 6e 66 69 67 75 72 61  y this configura
13800 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65  tion option, the
13810 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  n .** [sqlite3_m
13820 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65  alloc()] will be
13830 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20   used to obtain 
13840 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65  the memory neede
13850 64 2e 3c 70 3e 0a 2a 2a 20 5e 57 68 65 6e 20 74  d.<p>.** ^When t
13860 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 70  he application p
13870 72 6f 76 69 64 65 73 20 61 6e 79 20 61 6d 6f 75  rovides any amou
13880 6e 74 20 6f 66 20 73 63 72 61 74 63 68 20 6d 65  nt of scratch me
13890 6d 6f 72 79 20 75 73 69 6e 67 0a 2a 2a 20 53 51  mory using.** SQ
138a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
138b0 54 43 48 2c 20 53 51 4c 69 74 65 20 61 76 6f 69  TCH, SQLite avoi
138c0 64 73 20 75 6e 6e 65 63 65 73 73 61 72 79 20 6c  ds unnecessary l
138d0 61 72 67 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  arge.** [sqlite3
138e0 5f 6d 61 6c 6c 6f 63 7c 68 65 61 70 20 61 6c 6c  _malloc|heap all
138f0 6f 63 61 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68  ocations]..** Th
13900 69 73 20 63 61 6e 20 68 65 6c 70 20 5b 52 6f 62  is can help [Rob
13910 73 6f 6e 20 70 72 6f 6f 66 7c 70 72 65 76 65 6e  son proof|preven
13920 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  t memory allocat
13930 69 6f 6e 20 66 61 69 6c 75 72 65 73 5d 20 64 75  ion failures] du
13940 65 20 74 6f 20 68 65 61 70 0a 2a 2a 20 66 72 61  e to heap.** fra
13950 67 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 20 6c 6f  gmentation in lo
13960 77 2d 6d 65 6d 6f 72 79 20 65 6d 62 65 64 64 65  w-memory embedde
13970 64 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 20 3c 2f  d systems..** </
13980 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
13990 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
139a0 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  CHE]] <dt>SQLITE
139b0 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
139c0 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
139d0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
139e0 47 5f 50 41 47 45 43 41 43 48 45 20 6f 70 74 69  G_PAGECACHE opti
139f0 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 6d  on specifies a m
13a00 65 6d 6f 72 79 20 70 6f 6f 6c 0a 2a 2a 20 74 68  emory pool.** th
13a10 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73  at SQLite can us
13a20 65 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61  e for the databa
13a30 73 65 20 70 61 67 65 20 63 61 63 68 65 20 77 69  se page cache wi
13a40 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 20 70  th the default p
13a50 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70  age.** cache imp
13a60 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a  lementation.  .*
13a70 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61  * This configura
13a80 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 61  tion option is a
13a90 20 6e 6f 2d 6f 70 20 69 66 20 61 6e 20 61 70 70   no-op if an app
13aa0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20  lication-define 
13ab0 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d  page.** cache im
13ac0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20  plementation is 
13ad0 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68 65  loaded using the
13ae0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
13af0 50 43 41 43 48 45 32 5d 2e 0a 2a 2a 20 5e 54 68  PCACHE2]..** ^Th
13b00 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
13b10 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54  guments to SQLIT
13b20 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
13b30 48 45 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  HE: A pointer to
13b40 0a 2a 2a 20 38 2d 62 79 74 65 20 61 6c 69 67 6e  .** 8-byte align
13b50 65 64 20 6d 65 6d 6f 72 79 20 28 70 4d 65 6d 29  ed memory (pMem)
13b60 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61  , the size of ea
13b70 63 68 20 70 61 67 65 20 63 61 63 68 65 20 6c 69  ch page cache li
13b80 6e 65 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20  ne (sz),.** and 
13b90 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 61  the number of ca
13ba0 63 68 65 20 6c 69 6e 65 73 20 28 4e 29 2e 0a 2a  che lines (N)..*
13bb0 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e  * The sz argumen
13bc0 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20  t should be the 
13bd0 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67  size of the larg
13be0 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67  est database pag
13bf0 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66  e.** (a power of
13c00 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32   two between 512
13c10 20 61 6e 64 20 36 35 35 33 36 29 20 70 6c 75 73   and 65536) plus
13c20 20 73 6f 6d 65 20 65 78 74 72 61 20 62 79 74 65   some extra byte
13c30 73 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61  s for each.** pa
13c40 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65  ge header.  ^The
13c50 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61   number of extra
13c60 20 62 79 74 65 73 20 6e 65 65 64 65 64 20 62 79   bytes needed by
13c70 20 74 68 65 20 70 61 67 65 20 68 65 61 64 65 72   the page header
13c80 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65 72  .** can be deter
13c90 6d 69 6e 65 64 20 75 73 69 6e 67 20 5b 53 51 4c  mined using [SQL
13ca0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
13cb0 45 5f 48 44 52 53 5a 5d 2e 0a 2a 2a 20 5e 49 74  E_HDRSZ]..** ^It
13cc0 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70   is harmless, ap
13cd0 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73  art from the was
13ce0 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 66  ted memory,.** f
13cf0 6f 72 20 74 68 65 20 73 7a 20 70 61 72 61 6d 65  or the sz parame
13d00 74 65 72 20 74 6f 20 62 65 20 6c 61 72 67 65 72  ter to be larger
13d10 20 74 68 61 6e 20 6e 65 63 65 73 73 61 72 79 2e   than necessary.
13d20 20 20 54 68 65 20 70 4d 65 6d 0a 2a 2a 20 61 72    The pMem.** ar
13d30 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 65  gument must be e
13d40 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69  ither a NULL poi
13d50 6e 74 65 72 20 6f 72 20 61 20 70 6f 69 6e 74 65  nter or a pointe
13d60 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a  r to an 8-byte.*
13d70 2a 20 61 6c 69 67 6e 65 64 20 62 6c 6f 63 6b 20  * aligned block 
13d80 6f 66 20 6d 65 6d 6f 72 79 20 6f 66 20 61 74 20  of memory of at 
13d90 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73  least sz*N bytes
13da0 2c 20 6f 74 68 65 72 77 69 73 65 0a 2a 2a 20 73  , otherwise.** s
13db0 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69  ubsequent behavi
13dc0 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
13dd0 0a 2a 2a 20 5e 57 68 65 6e 20 70 4d 65 6d 20 69  .** ^When pMem i
13de0 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69  s not NULL, SQLi
13df0 74 65 20 77 69 6c 6c 20 73 74 72 69 76 65 20 74  te will strive t
13e00 6f 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  o use the memory
13e10 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 74 6f 20   provided.** to 
13e20 73 61 74 69 73 66 79 20 70 61 67 65 20 63 61 63  satisfy page cac
13e30 68 65 20 6e 65 65 64 73 2c 20 66 61 6c 6c 69 6e  he needs, fallin
13e40 67 20 62 61 63 6b 20 74 6f 20 5b 73 71 6c 69 74  g back to [sqlit
13e50 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 66 0a  e3_malloc()] if.
13e60 2a 2a 20 61 20 70 61 67 65 20 63 61 63 68 65 20  ** a page cache 
13e70 6c 69 6e 65 20 69 73 20 6c 61 72 67 65 72 20 74  line is larger t
13e80 68 61 6e 20 73 7a 20 62 79 74 65 73 20 6f 72 20  han sz bytes or 
13e90 69 66 20 61 6c 6c 20 6f 66 20 74 68 65 20 70 4d  if all of the pM
13ea0 65 6d 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20  em buffer.** is 
13eb0 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 5e 49  exhausted..** ^I
13ec0 66 20 70 4d 65 6d 20 69 73 20 4e 55 4c 4c 20 61  f pMem is NULL a
13ed0 6e 64 20 4e 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f  nd N is non-zero
13ee0 2c 20 74 68 65 6e 20 65 61 63 68 20 64 61 74 61  , then each data
13ef0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
13f00 2a 2a 20 64 6f 65 73 20 61 6e 20 69 6e 69 74 69  ** does an initi
13f10 61 6c 20 62 75 6c 6b 20 61 6c 6c 6f 63 61 74 69  al bulk allocati
13f20 6f 6e 20 66 6f 72 20 70 61 67 65 20 63 61 63 68  on for page cach
13f30 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 66 72 6f 6d  e memory.** from
13f40 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
13f50 28 29 5d 20 73 75 66 66 69 63 69 65 6e 74 20 66  ()] sufficient f
13f60 6f 72 20 4e 20 63 61 63 68 65 20 6c 69 6e 65 73  or N cache lines
13f70 20 69 66 20 4e 20 69 73 20 70 6f 73 69 74 69 76   if N is positiv
13f80 65 20 6f 72 0a 2a 2a 20 6f 66 20 2d 31 30 32 34  e or.** of -1024
13f90 2a 4e 20 62 79 74 65 73 20 69 66 20 4e 20 69 73  *N bytes if N is
13fa0 20 6e 65 67 61 74 69 76 65 2c 20 2e 20 5e 49 66   negative, . ^If
13fb0 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70   additional.** p
13fc0 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79  age cache memory
13fd0 20 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e   is needed beyon
13fe0 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64  d what is provid
13ff0 65 64 20 62 79 20 74 68 65 20 69 6e 69 74 69 61  ed by the initia
14000 6c 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c  l.** allocation,
14010 20 74 68 65 6e 20 53 51 4c 69 74 65 20 67 6f 65   then SQLite goe
14020 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61  s to [sqlite3_ma
14030 6c 6c 6f 63 28 29 5d 20 73 65 70 61 72 61 74 65  lloc()] separate
14040 6c 79 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 61  ly for each.** a
14050 64 64 69 74 69 6f 6e 61 6c 20 63 61 63 68 65 20  dditional cache 
14060 6c 69 6e 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  line. </dd>.**.*
14070 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
14080 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c  G_HEAP]] <dt>SQL
14090 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c  ITE_CONFIG_HEAP<
140a0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
140b0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
140c0 48 45 41 50 20 6f 70 74 69 6f 6e 20 73 70 65 63  HEAP option spec
140d0 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d  ifies a static m
140e0 65 6d 6f 72 79 20 62 75 66 66 65 72 20 0a 2a 2a  emory buffer .**
140f0 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
14100 6c 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66  l use for all of
14110 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d   its dynamic mem
14120 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
14130 65 65 64 73 0a 2a 2a 20 62 65 79 6f 6e 64 20 74  eeds.** beyond t
14140 68 6f 73 65 20 70 72 6f 76 69 64 65 64 20 66 6f  hose provided fo
14150 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  r by [SQLITE_CON
14160 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64  FIG_SCRATCH] and
14170 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
14180 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a  IG_PAGECACHE]..*
14190 2a 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  * ^The SQLITE_CO
141a0 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e  NFIG_HEAP option
141b0 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62   is only availab
141c0 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  le if SQLite is 
141d0 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68  compiled.** with
141e0 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
141f0 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20  ENABLE_MEMSYS3] 
14200 6f 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  or [SQLITE_ENABL
14210 45 5f 4d 45 4d 53 59 53 35 5d 20 61 6e 64 20 72  E_MEMSYS5] and r
14220 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54  eturns.** [SQLIT
14230 45 5f 45 52 52 4f 52 5d 20 69 66 20 69 6e 76 6f  E_ERROR] if invo
14240 6b 65 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a  ked otherwise..*
14250 2a 20 5e 54 68 65 72 65 20 61 72 65 20 74 68 72  * ^There are thr
14260 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  ee arguments to 
14270 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
14280 41 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79 74 65  AP:.** An 8-byte
14290 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72   aligned pointer
142a0 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a   to the memory,.
142b0 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
142c0 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65   bytes in the me
142d0 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64  mory buffer, and
142e0 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   the minimum all
142f0 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a  ocation size..**
14300 20 5e 49 66 20 74 68 65 20 66 69 72 73 74 20 70   ^If the first p
14310 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f  ointer (the memo
14320 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e  ry pointer) is N
14330 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ULL, then SQLite
14340 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75   reverts.** to u
14350 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74  sing its default
14360 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
14370 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61  r (the system ma
14380 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74  lloc() implement
14390 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69  ation),.** undoi
143a0 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76  ng any prior inv
143b0 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49  ocation of [SQLI
143c0 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
143d0 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d  ].  ^If the.** m
143e0 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73  emory pointer is
143f0 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 74   not NULL then t
14400 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d  he alternative m
14410 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
14420 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f  or is engaged to
14430 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53   handle all of S
14440 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c  QLites memory al
14450 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a  location needs..
14460 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f 69  ** The first poi
14470 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79  nter (the memory
14480 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62   pointer) must b
14490 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
144a0 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61  8-byte.** bounda
144b0 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74  ry or subsequent
144c0 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c   behavior of SQL
144d0 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65  ite will be unde
144e0 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69  fined..** The mi
144f0 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e  nimum allocation
14500 20 73 69 7a 65 20 69 73 20 63 61 70 70 65 64 20   size is capped 
14510 61 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e  at 2**12. Reason
14520 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66  able values.** f
14530 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61  or the minimum a
14540 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61  llocation size a
14550 72 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20  re 2**5 through 
14560 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  2**8.</dd>.**.**
14570 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
14580 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c  _MUTEX]] <dt>SQL
14590 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
145a0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
145b0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
145c0 47 5f 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74  G_MUTEX option t
145d0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
145e0 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
145f0 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20  a.** pointer to 
14600 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
14610 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
14620 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
14630 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67  ture..** The arg
14640 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 20  ument specifies 
14650 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d  alternative low-
14660 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74  level mutex rout
14670 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 0a  ines to be used.
14680 2a 2a 20 69 6e 20 70 6c 61 63 65 20 74 68 65 20  ** in place the 
14690 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62  mutex routines b
146a0 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65  uilt into SQLite
146b0 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b  .)^  ^SQLite mak
146c0 65 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  es a copy of.** 
146d0 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
146e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
146f0 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
14700 74 75 72 65 20 62 65 66 6f 72 65 20 74 68 65 20  ture before the 
14710 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
14720 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65  te3_config()] re
14730 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74  turns. ^If SQLit
14740 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
14750 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
14760 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
14770 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
14780 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
14790 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
147a0 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78  the entire mutex
147b0 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73  ing subsystem is
147c0 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
147d0 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63  e build and henc
147e0 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73  e calls to.** [s
147f0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
14800 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
14810 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f  _CONFIG_MUTEX co
14820 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
14830 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72  on will.** retur
14840 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
14850 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
14860 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
14870 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49  MUTEX]] <dt>SQLI
14880 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
14890 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  EX</dt>.** <dd> 
148a0 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  ^(The SQLITE_CON
148b0 46 49 47 5f 47 45 54 4d 55 54 45 58 20 6f 70 74  FIG_GETMUTEX opt
148c0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
148d0 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
148e0 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65  h.** is a pointe
148f0 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
14900 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
14910 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
14920 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a  structure.  The.
14930 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ** [sqlite3_mute
14940 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74  x_methods].** st
14950 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65  ructure is fille
14960 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  d with the curre
14970 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74  ntly defined mut
14980 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a  ex routines.)^.*
14990 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61  * This option ca
149a0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65  n be used to ove
149b0 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c  rload the defaul
149c0 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69  t mutex allocati
149d0 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77  on.** routines w
149e0 69 74 68 20 61 20 77 72 61 70 70 65 72 20 75 73  ith a wrapper us
149f0 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65  ed to track mute
14a00 78 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 66  x usage for perf
14a10 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69  ormance.** profi
14a20 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c  ling or testing,
14a30 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20   for example.   
14a40 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
14a50 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
14a60 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
14a70 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
14a80 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
14a90 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
14aa0 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74   then.** the ent
14ab0 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62  ire mutexing sub
14ac0 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65  system is omitte
14ad0 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64  d from the build
14ae0 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73   and hence calls
14af0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
14b00 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74  config()] with t
14b10 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
14b20 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67  _GETMUTEX config
14b30 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77  uration option w
14b40 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  ill.** return [S
14b50 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64  QLITE_ERROR].</d
14b60 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
14b70 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
14b80 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  DE]] <dt>SQLITE_
14b90 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
14ba0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
14bb0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
14bc0 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f 70 74 69  G_LOOKASIDE opti
14bd0 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67  on takes two arg
14be0 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65  uments that dete
14bf0 72 6d 69 6e 65 0a 2a 2a 20 74 68 65 20 64 65 66  rmine.** the def
14c00 61 75 6c 74 20 73 69 7a 65 20 6f 66 20 6c 6f 6f  ault size of loo
14c10 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 6f 6e  kaside memory on
14c20 20 65 61 63 68 20 5b 64 61 74 61 62 61 73 65 20   each [database 
14c30 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20  connection]..** 
14c40 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
14c50 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a  nt is the.** siz
14c60 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73  e of each lookas
14c70 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20  ide buffer slot 
14c80 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69  and the second i
14c90 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  s the number of.
14ca0 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74  ** slots allocat
14cb0 65 64 20 74 6f 20 65 61 63 68 20 64 61 74 61 62  ed to each datab
14cc0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29  ase connection.)
14cd0 5e 20 20 5e 28 53 51 4c 49 54 45 5f 43 4f 4e 46  ^  ^(SQLITE_CONF
14ce0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a 2a 20  IG_LOOKASIDE.** 
14cf0 73 65 74 73 20 74 68 65 20 3c 69 3e 64 65 66 61  sets the <i>defa
14d00 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64  ult</i> lookasid
14d10 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c  e size. The [SQL
14d20 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
14d30 4b 41 53 49 44 45 5d 0a 2a 2a 20 6f 70 74 69 6f  KASIDE].** optio
14d40 6e 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62  n to [sqlite3_db
14d50 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62  _config()] can b
14d60 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65  e used to change
14d70 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a   the lookaside.*
14d80 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
14d90 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f  on individual co
14da0 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64  nnections.)^ </d
14db0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
14dc0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32  E_CONFIG_PCACHE2
14dd0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
14de0 4e 46 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 74  NFIG_PCACHE2</dt
14df0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20  >.** <dd> ^(The 
14e00 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
14e10 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b  ACHE2 option tak
14e20 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
14e30 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a  ment which is .*
14e40 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * a pointer to a
14e50 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68  n [sqlite3_pcach
14e60 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65  e_methods2] obje
14e70 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74  ct.  This object
14e80 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68   specifies.** th
14e90 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 61  e interface to a
14ea0 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63   custom page cac
14eb0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
14ec0 6e 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  n.)^.** ^SQLite 
14ed0 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
14ee0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 63 61  the [sqlite3_pca
14ef0 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62  che_methods2] ob
14f00 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ject.</dd>.**.**
14f10 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
14f20 5f 47 45 54 50 43 41 43 48 45 32 5d 5d 20 3c 64  _GETPCACHE2]] <d
14f30 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
14f40 47 45 54 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a  GETPCACHE2</dt>.
14f50 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51  ** <dd> ^(The SQ
14f60 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
14f70 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61  CACHE2 option ta
14f80 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
14f90 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69  ument which.** i
14fa0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
14fb0 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68  n [sqlite3_pcach
14fc0 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65  e_methods2] obje
14fd0 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69  ct.  SQLite copi
14fe0 65 73 20 6f 66 0a 2a 2a 20 74 68 65 20 63 75 72  es of.** the cur
14ff0 72 65 6e 74 20 70 61 67 65 20 63 61 63 68 65 20  rent page cache 
15000 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
15010 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e  nto that object.
15020 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  )^ </dd>.**.** [
15030 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  [SQLITE_CONFIG_L
15040 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  OG]] <dt>SQLITE_
15050 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a  CONFIG_LOG</dt>.
15060 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49  ** <dd> The SQLI
15070 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70  TE_CONFIG_LOG op
15080 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
15090 63 6f 6e 66 69 67 75 72 65 20 74 68 65 20 53 51  configure the SQ
150a0 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b  Lite.** global [
150b0 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28  error log]..** (
150c0 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
150d0 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61  IG_LOG option ta
150e0 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  kes two argument
150f0 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  s: a pointer to 
15100 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69  a.** function wi
15110 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74  th a call signat
15120 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76  ure of void(*)(v
15130 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63  oid*,int,const c
15140 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61  har*), .** and a
15150 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64   pointer to void
15160 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69  . ^If the functi
15170 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f  on pointer is no
15180 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a  t NULL, it is.**
15190 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c   invoked by [sql
151a0 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70  ite3_log()] to p
151b0 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67  rocess each logg
151c0 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20  ing event.  ^If 
151d0 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  the.** function 
151e0 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c  pointer is NULL,
151f0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f   the [sqlite3_lo
15200 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62  g()] interface b
15210 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a  ecomes a no-op..
15220 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69  ** ^The void poi
15230 6e 74 65 72 20 74 68 61 74 20 69 73 20 74 68 65  nter that is the
15240 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
15250 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49   to SQLITE_CONFI
15260 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73  G_LOG is.** pass
15270 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68  ed through as th
15280 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
15290 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  r to the applica
152a0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67  tion-defined log
152b0 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ger.** function 
152c0 77 68 65 6e 65 76 65 72 20 74 68 61 74 20 66 75  whenever that fu
152d0 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65  nction is invoke
152e0 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  d.  ^The second 
152f0 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
15300 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74  the logger funct
15310 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ion is a copy of
15320 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
15330 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72  eter to the corr
15340 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71  esponding.** [sq
15350 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c  lite3_log()] cal
15360 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65  l and is intende
15370 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c  d to be a [resul
15380 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a  t code] or an.**
15390 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
153a0 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74  t code].  ^The t
153b0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 70  hird parameter p
153c0 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67  assed to the log
153d0 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65  ger is.** log me
153e0 73 73 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d  ssage after form
153f0 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69  atting via [sqli
15400 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e  te3_snprintf()].
15410 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c  .** The SQLite l
15420 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65  ogging interface
15430 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e   is not reentran
15440 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75  t; the logger fu
15450 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69  nction.** suppli
15460 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ed by the applic
15470 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69  ation must not i
15480 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65  nvoke any SQLite
15490 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49   interface..** I
154a0 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64  n a multi-thread
154b0 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20  ed application, 
154c0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
154d0 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a  defined logger.*
154e0 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  * function must 
154f0 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c  be threadsafe. <
15500 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
15510 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d  ITE_CONFIG_URI]]
15520 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
15530 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28  IG_URI.** <dd>^(
15540 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
15550 47 5f 55 52 49 20 6f 70 74 69 6f 6e 20 74 61 6b  G_URI option tak
15560 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
15570 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74  ment of type int
15580 2e 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f  ..** If non-zero
15590 2c 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c  , then URI handl
155a0 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20  ing is globally 
155b0 65 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 65 20  enabled. If the 
155c0 70 61 72 61 6d 65 74 65 72 20 69 73 20 7a 65 72  parameter is zer
155d0 6f 2c 0a 2a 2a 20 74 68 65 6e 20 55 52 49 20 68  o,.** then URI h
155e0 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61  andling is globa
155f0 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e 29 5e 20  lly disabled.)^ 
15600 5e 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e 67  ^If URI handling
15610 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20   is globally.** 
15620 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c  enabled, all fil
15630 65 6e 61 6d 65 73 20 70 61 73 73 65 64 20 74 6f  enames passed to
15640 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
15650 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
15660 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  _v2()],.** [sqli
15670 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72  te3_open16()] or
15680 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20 61 73  .** specified as
15690 20 70 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48   part of [ATTACH
156a0 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69  ] commands are i
156b0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52  nterpreted as UR
156c0 49 73 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a  Is, regardless.*
156d0 2a 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  * of whether or 
156e0 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  not the [SQLITE_
156f0 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69  OPEN_URI] flag i
15700 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 64  s set when the d
15710 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
15720 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e  ction is opened.
15730 20 5e 49 66 20 69 74 20 69 73 20 67 6c 6f 62 61   ^If it is globa
15740 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 66 69  lly disabled, fi
15750 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f  lenames are.** o
15760 6e 6c 79 20 69 6e 74 65 72 70 72 65 74 65 64 20  nly interpreted 
15770 61 73 20 55 52 49 73 20 69 66 20 74 68 65 20 53  as URIs if the S
15780 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66  QLITE_OPEN_URI f
15790 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20  lag is set when 
157a0 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
157b0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70  connection is op
157c0 65 6e 65 64 2e 20 5e 28 42 79 20 64 65 66 61 75  ened. ^(By defau
157d0 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67  lt, URI handling
157e0 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20   is globally.** 
157f0 64 69 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65  disabled. The de
15800 66 61 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20  fault value may 
15810 62 65 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f  be changed by co
15820 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65  mpiling with the
15830 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f  .** [SQLITE_USE_
15840 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69  URI] symbol defi
15850 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  ned.)^.**.** [[S
15860 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56  QLITE_CONFIG_COV
15870 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e  ERING_INDEX_SCAN
15880 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
15890 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e  NFIG_COVERING_IN
158a0 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e  DEX_SCAN.** <dd>
158b0 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
158c0 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45  IG_COVERING_INDE
158d0 58 5f 53 43 41 4e 20 6f 70 74 69 6f 6e 20 74 61  X_SCAN option ta
158e0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 69 6e 74  kes a single int
158f0 65 67 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  eger.** argument
15900 20 77 68 69 63 68 20 69 73 20 69 6e 74 65 72 70   which is interp
15910 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65  reted as a boole
15920 61 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65  an in order to e
15930 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65  nable or disable
15940 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 63  .** the use of c
15950 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20  overing indices 
15960 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73  for full table s
15970 63 61 6e 73 20 69 6e 20 74 68 65 20 71 75 65 72  cans in the quer
15980 79 20 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a 2a 20  y optimizer..** 
15990 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74  ^The default set
159a0 74 69 6e 67 20 69 73 20 64 65 74 65 72 6d 69 6e  ting is determin
159b0 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53 51  ed.** by the [SQ
159c0 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52  LITE_ALLOW_COVER
159d0 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20  ING_INDEX_SCAN] 
159e0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
159f0 69 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a  ion, or is "on".
15a00 2a 2a 20 69 66 20 74 68 61 74 20 63 6f 6d 70 69  ** if that compi
15a10 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69  le-time option i
15a20 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68  s omitted..** Th
15a30 65 20 61 62 69 6c 69 74 79 20 74 6f 20 64 69 73  e ability to dis
15a40 61 62 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20  able the use of 
15a50 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73  covering indices
15a60 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20   for full table 
15a70 73 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61  scans.** is beca
15a80 75 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65  use some incorre
15a90 63 74 6c 79 20 63 6f 64 65 64 20 6c 65 67 61 63  ctly coded legac
15aa0 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d  y applications m
15ab0 69 67 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e  ight malfunction
15ac0 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 6f 70 74  .** when the opt
15ad0 69 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e 61  imization is ena
15ae0 62 6c 65 64 2e 20 20 50 72 6f 76 69 64 69 6e 67  bled.  Providing
15af0 20 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 0a   the ability to.
15b00 2a 2a 20 64 69 73 61 62 6c 65 20 74 68 65 20 6f  ** disable the o
15b10 70 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f  ptimization allo
15b20 77 73 20 74 68 65 20 6f 6c 64 65 72 2c 20 62 75  ws the older, bu
15b30 67 67 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  ggy application 
15b40 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20  code to work.** 
15b50 77 69 74 68 6f 75 74 20 63 68 61 6e 67 65 20 65  without change e
15b60 76 65 6e 20 77 69 74 68 20 6e 65 77 65 72 20 76  ven with newer v
15b70 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
15b80 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  e..**.** [[SQLIT
15b90 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d  E_CONFIG_PCACHE]
15ba0 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ] [[SQLITE_CONFI
15bb0 47 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a  G_GETPCACHE]].**
15bc0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
15bd0 49 47 5f 50 43 41 43 48 45 20 61 6e 64 20 53 51  IG_PCACHE and SQ
15be0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
15bf0 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68  CACHE.** <dd> Th
15c00 65 73 65 20 6f 70 74 69 6f 6e 73 20 61 72 65 20  ese options are 
15c10 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f  obsolete and sho
15c20 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20  uld not be used 
15c30 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20  by new code..** 
15c40 54 68 65 79 20 61 72 65 20 72 65 74 61 69 6e 65  They are retaine
15c50 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20  d for backwards 
15c60 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 62 75  compatibility bu
15c70 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73  t are now no-ops
15c80 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
15c90 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
15ca0 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74  _SQLLOG]].** <dt
15cb0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
15cc0 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 69  QLLOG.** <dd>Thi
15cd0 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79  s option is only
15ce0 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 73 71   available if sq
15cf0 6c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  lite is compiled
15d00 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51   with the.** [SQ
15d10 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c  LITE_ENABLE_SQLL
15d20 4f 47 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f  OG] pre-processo
15d30 72 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 2e  r macro defined.
15d40 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
15d50 65 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65  ent should.** be
15d60 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
15d70 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65  function of type
15d80 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73   void(*)(void*,s
15d90 71 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68  qlite3*,const ch
15da0 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68  ar*, int)..** Th
15db0 65 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20  e second should 
15dc0 62 65 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64  be of type (void
15dd0 2a 29 2e 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  *). The callback
15de0 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 74   is invoked by t
15df0 68 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e  he library.** in
15e00 20 74 68 72 65 65 20 73 65 70 61 72 61 74 65 20   three separate 
15e10 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 69  circumstances, i
15e20 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65  dentified by the
15e30 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73   value passed as
15e40 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70   the.** fourth p
15e50 61 72 61 6d 65 74 65 72 2e 20 49 66 20 74 68 65  arameter. If the
15e60 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
15e70 72 20 69 73 20 30 2c 20 74 68 65 6e 20 74 68 65  r is 0, then the
15e80 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
15e90 74 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61  tion.** passed a
15ea0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
15eb0 75 6d 65 6e 74 20 68 61 73 20 6a 75 73 74 20 62  ument has just b
15ec0 65 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65 20  een opened. The 
15ed0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a  third argument.*
15ee0 2a 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 62 75  * points to a bu
15ef0 66 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ffer containing 
15f00 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
15f10 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 69  main database fi
15f20 6c 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f  le. If the.** fo
15f30 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
15f40 73 20 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51  s 1, then the SQ
15f50 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  L statement that
15f60 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
15f70 65 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74  eter.** points t
15f80 6f 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20  o has just been 
15f90 65 78 65 63 75 74 65 64 2e 20 4f 72 2c 20 69 66  executed. Or, if
15fa0 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
15fb0 6d 65 74 65 72 20 69 73 20 32 2c 20 74 68 65 6e  meter is 2, then
15fc0 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74 69  .** the connecti
15fd0 6f 6e 20 62 65 69 6e 67 20 70 61 73 73 65 64 20  on being passed 
15fe0 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
15ff0 72 61 6d 65 74 65 72 20 69 73 20 62 65 69 6e 67  rameter is being
16000 20 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20   closed. The.** 
16010 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
16020 69 73 20 70 61 73 73 65 64 20 4e 55 4c 4c 20 49  is passed NULL I
16030 6e 20 74 68 69 73 20 63 61 73 65 2e 20 20 41 6e  n this case.  An
16040 20 65 78 61 6d 70 6c 65 20 6f 66 20 75 73 69 6e   example of usin
16050 67 20 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 67  g this.** config
16060 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 63  uration option c
16070 61 6e 20 62 65 20 73 65 65 6e 20 69 6e 20 74 68  an be seen in th
16080 65 20 22 74 65 73 74 5f 73 71 6c 6c 6f 67 2e 63  e "test_sqllog.c
16090 22 20 73 6f 75 72 63 65 20 66 69 6c 65 20 69 6e  " source file in
160a0 0a 2a 2a 20 74 68 65 20 63 61 6e 6f 6e 69 63 61  .** the canonica
160b0 6c 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20  l SQLite source 
160c0 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tree.</dd>.**.**
160d0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
160e0 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20  _MMAP_SIZE]].** 
160f0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
16100 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c  G_MMAP_SIZE.** <
16110 64 64 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  dd>^SQLITE_CONFI
16120 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 74 61 6b 65  G_MMAP_SIZE take
16130 73 20 74 77 6f 20 36 34 2d 62 69 74 20 69 6e 74  s two 64-bit int
16140 65 67 65 72 20 28 73 71 6c 69 74 65 33 5f 69 6e  eger (sqlite3_in
16150 74 36 34 29 20 76 61 6c 75 65 73 0a 2a 2a 20 74  t64) values.** t
16160 68 61 74 20 61 72 65 20 74 68 65 20 64 65 66 61  hat are the defa
16170 75 6c 74 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69  ult mmap size li
16180 6d 69 74 20 28 74 68 65 20 64 65 66 61 75 6c 74  mit (the default
16190 20 73 65 74 74 69 6e 67 20 66 6f 72 0a 2a 2a 20   setting for.** 
161a0 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a  [PRAGMA mmap_siz
161b0 65 5d 29 20 61 6e 64 20 74 68 65 20 6d 61 78 69  e]) and the maxi
161c0 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70  mum allowed mmap
161d0 20 73 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20   size limit..** 
161e0 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74  ^The default set
161f0 74 69 6e 67 20 63 61 6e 20 62 65 20 6f 76 65 72  ting can be over
16200 72 69 64 64 65 6e 20 62 79 20 65 61 63 68 20 64  ridden by each d
16210 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
16220 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 65 69 74 68  on using.** eith
16230 65 72 20 74 68 65 20 5b 50 52 41 47 4d 41 20 6d  er the [PRAGMA m
16240 6d 61 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e  map_size] comman
16250 64 2c 20 6f 72 20 62 79 20 75 73 69 6e 67 20 74  d, or by using t
16260 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43  he.** [SQLITE_FC
16270 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66  NTL_MMAP_SIZE] f
16280 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e 28  ile control.  ^(
16290 54 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f  The maximum allo
162a0 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a  wed mmap size.**
162b0 20 77 69 6c 6c 20 62 65 20 73 69 6c 65 6e 74 6c   will be silentl
162c0 79 20 74 72 75 6e 63 61 74 65 64 20 69 66 20 6e  y truncated if n
162d0 65 63 65 73 73 61 72 79 20 73 6f 20 74 68 61 74  ecessary so that
162e0 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 65 78 63   it does not exc
162f0 65 65 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69  eed the.** compi
16300 6c 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20  le-time maximum 
16310 6d 6d 61 70 20 73 69 7a 65 20 73 65 74 20 62 79  mmap size set by
16320 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
16330 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63  MAX_MMAP_SIZE] c
16340 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
16350 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74  on.)^.** ^If eit
16360 68 65 72 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  her argument to 
16370 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e  this option is n
16380 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68  egative, then th
16390 61 74 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a  at argument is.*
163a0 2a 20 63 68 61 6e 67 65 64 20 74 6f 20 69 74 73  * changed to its
163b0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65   compile-time de
163c0 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  fault..**.** [[S
163d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e  QLITE_CONFIG_WIN
163e0 33 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a  32_HEAPSIZE]].**
163f0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
16400 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a  IG_WIN32_HEAPSIZ
16410 45 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51  E.** <dd>^The SQ
16420 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33  LITE_CONFIG_WIN3
16430 32 5f 48 45 41 50 53 49 5a 45 20 6f 70 74 69 6f  2_HEAPSIZE optio
16440 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61  n is only availa
16450 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 73  ble if SQLite is
16460 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72  .** compiled for
16470 20 57 69 6e 64 6f 77 73 20 77 69 74 68 20 74 68   Windows with th
16480 65 20 5b 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f  e [SQLITE_WIN32_
16490 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d 70 72 6f 63  MALLOC] pre-proc
164a0 65 73 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a 20 64  essor macro.** d
164b0 65 66 69 6e 65 64 2e 20 5e 53 51 4c 49 54 45 5f  efined. ^SQLITE_
164c0 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41  CONFIG_WIN32_HEA
164d0 50 53 49 5a 45 20 74 61 6b 65 73 20 61 20 33 32  PSIZE takes a 32
164e0 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e  -bit unsigned in
164f0 74 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a 20 74  teger value.** t
16500 68 61 74 20 73 70 65 63 69 66 69 65 73 20 74 68  hat specifies th
16510 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f  e maximum size o
16520 66 20 74 68 65 20 63 72 65 61 74 65 64 20 68 65  f the created he
16530 61 70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  ap..**.** [[SQLI
16540 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
16550 5f 48 44 52 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e  _HDRSZ]].** <dt>
16560 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
16570 41 43 48 45 5f 48 44 52 53 5a 0a 2a 2a 20 3c 64  ACHE_HDRSZ.** <d
16580 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  d>^The SQLITE_CO
16590 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53  NFIG_PCACHE_HDRS
165a0 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  Z option takes a
165b0 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65   single paramete
165c0 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20  r which.** is a 
165d0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
165e0 74 65 67 65 72 20 61 6e 64 20 77 72 69 74 65 73  teger and writes
165f0 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67   into that integ
16600 65 72 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  er the number of
16610 20 65 78 74 72 61 0a 2a 2a 20 62 79 74 65 73 20   extra.** bytes 
16620 70 65 72 20 70 61 67 65 20 72 65 71 75 69 72 65  per page require
16630 64 20 66 6f 72 20 65 61 63 68 20 70 61 67 65 20  d for each page 
16640 69 6e 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  in [SQLITE_CONFI
16650 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a  G_PAGECACHE]..**
16660 20 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 65   The amount of e
16670 78 74 72 61 20 73 70 61 63 65 20 72 65 71 75 69  xtra space requi
16680 72 65 64 20 63 61 6e 20 63 68 61 6e 67 65 20 64  red can change d
16690 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
166a0 63 6f 6d 70 69 6c 65 72 2c 0a 2a 2a 20 74 61 72  compiler,.** tar
166b0 67 65 74 20 70 6c 61 74 66 6f 72 6d 2c 20 61 6e  get platform, an
166c0 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  d SQLite version
166d0 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
166e0 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 5d 5d 0a  _CONFIG_PMASZ]].
166f0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
16700 4e 46 49 47 5f 50 4d 41 53 5a 0a 2a 2a 20 3c 64  NFIG_PMASZ.** <d
16710 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  d>^The SQLITE_CO
16720 4e 46 49 47 5f 50 4d 41 53 5a 20 6f 70 74 69 6f  NFIG_PMASZ optio
16730 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
16740 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68   parameter which
16750 0a 2a 2a 20 69 73 20 61 6e 20 75 6e 73 69 67 6e  .** is an unsign
16760 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 73  ed integer and s
16770 65 74 73 20 74 68 65 20 22 4d 69 6e 69 6d 75 6d  ets the "Minimum
16780 20 50 4d 41 20 53 69 7a 65 22 20 66 6f 72 20 74   PMA Size" for t
16790 68 65 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64  he multithreaded
167a0 0a 2a 2a 20 73 6f 72 74 65 72 20 74 6f 20 74 68  .** sorter to th
167b0 61 74 20 69 6e 74 65 67 65 72 2e 20 20 54 68 65  at integer.  The
167c0 20 64 65 66 61 75 6c 74 20 6d 69 6e 69 6d 75 6d   default minimum
167d0 20 50 4d 41 20 53 69 7a 65 20 69 73 20 73 65 74   PMA Size is set
167e0 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49   by the.** [SQLI
167f0 54 45 5f 53 4f 52 54 45 52 5f 50 4d 41 53 5a 5d  TE_SORTER_PMASZ]
16800 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
16810 74 69 6f 6e 2e 20 20 4e 65 77 20 74 68 72 65 61  tion.  New threa
16820 64 73 20 61 72 65 20 6c 61 75 6e 63 68 65 64 0a  ds are launched.
16830 2a 2a 20 74 6f 20 68 65 6c 70 20 77 69 74 68 20  ** to help with 
16840 73 6f 72 74 20 6f 70 65 72 61 74 69 6f 6e 73 20  sort operations 
16850 77 68 65 6e 20 6d 75 6c 74 69 74 68 72 65 61 64  when multithread
16860 65 64 20 73 6f 72 74 69 6e 67 0a 2a 2a 20 69 73  ed sorting.** is
16870 20 65 6e 61 62 6c 65 64 20 28 75 73 69 6e 67 20   enabled (using 
16880 74 68 65 20 5b 50 52 41 47 4d 41 20 74 68 72 65  the [PRAGMA thre
16890 61 64 73 5d 20 63 6f 6d 6d 61 6e 64 29 20 61 6e  ads] command) an
168a0 64 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20  d the amount of 
168b0 63 6f 6e 74 65 6e 74 0a 2a 2a 20 74 6f 20 62 65  content.** to be
168c0 20 73 6f 72 74 65 64 20 65 78 63 65 65 64 73 20   sorted exceeds 
168d0 74 68 65 20 70 61 67 65 20 73 69 7a 65 20 74 69  the page size ti
168e0 6d 65 73 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20  mes the minimum 
168f0 6f 66 20 74 68 65 0a 2a 2a 20 5b 50 52 41 47 4d  of the.** [PRAGM
16900 41 20 63 61 63 68 65 5f 73 69 7a 65 5d 20 73 65  A cache_size] se
16910 74 74 69 6e 67 20 61 6e 64 20 74 68 69 73 20 76  tting and this v
16920 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  alue..**.** [[SQ
16930 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54  LITE_CONFIG_STMT
16940 4a 52 4e 4c 5f 53 50 49 4c 4c 5d 5d 0a 2a 2a 20  JRNL_SPILL]].** 
16950 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
16960 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c  G_STMTJRNL_SPILL
16970 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c  .** <dd>^The SQL
16980 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a  ITE_CONFIG_STMTJ
16990 52 4e 4c 5f 53 50 49 4c 4c 20 6f 70 74 69 6f 6e  RNL_SPILL option
169a0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
169b0 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a  parameter which.
169c0 2a 2a 20 62 65 63 6f 6d 65 73 20 74 68 65 20 5b  ** becomes the [
169d0 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61  statement journa
169e0 6c 5d 20 73 70 69 6c 6c 2d 74 6f 2d 64 69 73 6b  l] spill-to-disk
169f0 20 74 68 72 65 73 68 6f 6c 64 2e 20 20 0a 2a 2a   threshold.  .**
16a00 20 5b 53 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72   [Statement jour
16a10 6e 61 6c 73 5d 20 61 72 65 20 68 65 6c 64 20 69  nals] are held i
16a20 6e 20 6d 65 6d 6f 72 79 20 75 6e 74 69 6c 20 74  n memory until t
16a30 68 65 69 72 20 73 69 7a 65 20 28 69 6e 20 62 79  heir size (in by
16a40 74 65 73 29 0a 2a 2a 20 65 78 63 65 65 64 73 20  tes).** exceeds 
16a50 74 68 69 73 20 74 68 72 65 73 68 6f 6c 64 2c 20  this threshold, 
16a60 61 74 20 77 68 69 63 68 20 70 6f 69 6e 74 20 74  at which point t
16a70 68 65 79 20 61 72 65 20 77 72 69 74 74 65 6e 20  hey are written 
16a80 74 6f 20 64 69 73 6b 2e 0a 2a 2a 20 4f 72 20 69  to disk..** Or i
16a90 66 20 74 68 65 20 74 68 72 65 73 68 6f 6c 64 20  f the threshold 
16aa0 69 73 20 2d 31 2c 20 73 74 61 74 65 6d 65 6e 74  is -1, statement
16ab0 20 6a 6f 75 72 6e 61 6c 73 20 61 72 65 20 61 6c   journals are al
16ac0 77 61 79 73 20 68 65 6c 64 0a 2a 2a 20 65 78 63  ways held.** exc
16ad0 6c 75 73 69 76 65 6c 79 20 69 6e 20 6d 65 6d 6f  lusively in memo
16ae0 72 79 2e 0a 2a 2a 20 53 69 6e 63 65 20 6d 61 6e  ry..** Since man
16af0 79 20 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72  y statement jour
16b00 6e 61 6c 73 20 6e 65 76 65 72 20 62 65 63 6f 6d  nals never becom
16b10 65 20 6c 61 72 67 65 2c 20 73 65 74 74 69 6e 67  e large, setting
16b20 20 74 68 65 20 73 70 69 6c 6c 0a 2a 2a 20 74 68   the spill.** th
16b30 72 65 73 68 6f 6c 64 20 74 6f 20 61 20 76 61 6c  reshold to a val
16b40 75 65 20 73 75 63 68 20 61 73 20 36 34 4b 69 42  ue such as 64KiB
16b50 20 63 61 6e 20 67 72 65 61 74 6c 79 20 72 65 64   can greatly red
16b60 75 63 65 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f  uce the amount o
16b70 66 0a 2a 2a 20 49 2f 4f 20 72 65 71 75 69 72 65  f.** I/O require
16b80 64 20 74 6f 20 73 75 70 70 6f 72 74 20 73 74 61  d to support sta
16b90 74 65 6d 65 6e 74 20 72 6f 6c 6c 62 61 63 6b 2e  tement rollback.
16ba0 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20  .** The default 
16bb0 76 61 6c 75 65 20 66 6f 72 20 74 68 69 73 20 73  value for this s
16bc0 65 74 74 69 6e 67 20 69 73 20 63 6f 6e 74 72 6f  etting is contro
16bd0 6c 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b  lled by the.** [
16be0 53 51 4c 49 54 45 5f 53 54 4d 54 4a 52 4e 4c 5f  SQLITE_STMTJRNL_
16bf0 53 50 49 4c 4c 5d 20 63 6f 6d 70 69 6c 65 2d 74  SPILL] compile-t
16c00 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 3c  ime option..** <
16c10 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
16c20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
16c30 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f  NGLETHREAD  1  /
16c40 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
16c50 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
16c60 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 20  ULTITHREAD   2  
16c70 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
16c80 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16c90 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20  SERIALIZED    3 
16ca0 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
16cb0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
16cc0 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34  _MALLOC        4
16cd0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d    /* sqlite3_mem
16ce0 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#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 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20  IG_GETMALLOC    
16d10 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d   5  /* 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 53 43 52 41 54 43 48 20 20 20 20  NFIG_SCRATCH    
16d50 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20     6  /* void*, 
16d60 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f  int sz, int N */
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 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
16d90 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a       7  /* 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 48 45 41 50 20 20 20  E_CONFIG_HEAP   
16dd0 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69         8  /* voi
16de0 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69  d*, int nByte, i
16df0 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e  nt min */.#defin
16e00 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16e10 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 39 20  MEMSTATUS     9 
16e20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23   /* boolean */.#
16e30 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
16e40 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20  NFIG_MUTEX      
16e50 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33    10  /* sqlite3
16e60 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20  _mutex_methods* 
16e70 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16e80 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
16e90 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c  X     11  /* sql
16ea0 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
16eb0 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f  ds* */./* previo
16ec0 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46  usly SQLITE_CONF
16ed0 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32  IG_CHUNKALLOC 12
16ee0 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e   which is now un
16ef0 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e  used. */ .#defin
16f00 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16f10 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20  LOOKASIDE    13 
16f20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23   /* int int */.#
16f30 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
16f40 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20 20 20  NFIG_PCACHE     
16f50 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a    14  /* no-op *
16f60 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16f70 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
16f80 45 20 20 20 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f  E    15  /* no-o
16f90 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  p */.#define SQL
16fa0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20  ITE_CONFIG_LOG  
16fb0 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a 20 78          16  /* x
16fc0 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23  Func, void* */.#
16fd0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
16fe0 4e 46 49 47 5f 55 52 49 20 20 20 20 20 20 20 20  NFIG_URI        
16ff0 20 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a    17  /* int */.
17000 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
17010 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 20 20  ONFIG_PCACHE2   
17020 20 20 20 31 38 20 20 2f 2a 20 73 71 6c 69 74 65     18  /* sqlite
17030 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
17040 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  2* */.#define SQ
17050 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
17060 43 41 43 48 45 32 20 20 20 31 39 20 20 2f 2a 20  CACHE2   19  /* 
17070 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
17080 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66  ethods2* */.#def
17090 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
170a0 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58  G_COVERING_INDEX
170b0 5f 53 43 41 4e 20 32 30 20 20 2f 2a 20 69 6e 74  _SCAN 20  /* int
170c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
170d0 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47  TE_CONFIG_SQLLOG
170e0 20 20 20 20 20 20 20 32 31 20 20 2f 2a 20 78 53         21  /* xS
170f0 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20 2a 2f 0a  qllog, void* */.
17100 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
17110 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20  ONFIG_MMAP_SIZE 
17120 20 20 20 32 32 20 20 2f 2a 20 73 71 6c 69 74 65     22  /* sqlite
17130 33 5f 69 6e 74 36 34 2c 20 73 71 6c 69 74 65 33  3_int64, sqlite3
17140 5f 69 6e 74 36 34 20 2a 2f 0a 23 64 65 66 69 6e  _int64 */.#defin
17150 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
17160 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 20  WIN32_HEAPSIZE  
17170 20 20 20 20 32 33 20 20 2f 2a 20 69 6e 74 20 6e      23  /* int n
17180 42 79 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  Byte */.#define 
17190 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
171a0 41 43 48 45 5f 48 44 52 53 5a 20 20 20 20 20 20  ACHE_HDRSZ      
171b0 20 20 32 34 20 20 2f 2a 20 69 6e 74 20 2a 70 73    24  /* int *ps
171c0 7a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  z */.#define SQL
171d0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a  ITE_CONFIG_PMASZ
171e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
171f0 35 20 20 2f 2a 20 75 6e 73 69 67 6e 65 64 20 69  5  /* unsigned i
17200 6e 74 20 73 7a 50 6d 61 20 2a 2f 0a 23 64 65 66  nt szPma */.#def
17210 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
17220 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c  G_STMTJRNL_SPILL
17230 20 20 20 20 20 20 32 36 20 20 2f 2a 20 69 6e 74        26  /* int
17240 20 6e 42 79 74 65 20 2a 2f 0a 0a 2f 2a 0a 2a 2a   nByte */../*.**
17250 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62   CAPI3REF: Datab
17260 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43  ase Connection C
17270 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74  onfiguration Opt
17280 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
17290 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74   constants are t
172a0 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74  he available int
172b0 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69  eger configurati
172c0 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a  on options that.
172d0 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64  ** can be passed
172e0 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   as the second a
172f0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b  rgument to the [
17300 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
17310 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  g()] interface..
17320 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67  **.** New config
17330 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
17340 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
17350 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
17360 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78  of SQLite..** Ex
17370 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61  isting configura
17380 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67  tion options mig
17390 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75  ht be discontinu
173a0 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  ed.  Application
173b0 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63  s.** should chec
173c0 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64  k the return cod
173d0 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  e from [sqlite3_
173e0 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20  db_config()] to 
173f0 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a  make sure that.*
17400 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65  * the call worke
17410 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  d.  ^The [sqlite
17420 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69  3_db_config()] i
17430 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65  nterface will re
17440 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65  turn a.** non-ze
17450 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ro [error code] 
17460 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65  if a discontinue
17470 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64  d or unsupported
17480 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
17490 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f  ption.** is invo
174a0 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  ked..**.** <dl>.
174b0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
174c0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
174d0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
174e0 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
174f0 20 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61   three additiona
17500 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  l arguments that
17510 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a   determine the .
17520 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  ** [lookaside me
17530 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20  mory allocator] 
17540 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f  configuration fo
17550 72 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  r the [database 
17560 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20  connection]..** 
17570 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
17580 65 6e 74 20 28 74 68 65 20 74 68 69 72 64 20 70  ent (the third p
17590 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
175a0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
175b0 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65  ] is a.** pointe
175c0 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75  r to a memory bu
175d0 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72 20  ffer to use for 
175e0 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
175f0 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  ..** ^The first 
17600 61 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20 74  argument after t
17610 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  he SQLITE_DBCONF
17620 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72  IG_LOOKASIDE ver
17630 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c  b.** may be NULL
17640 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 53   in which case S
17650 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63  QLite will alloc
17660 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61  ate the.** looka
17670 73 69 64 65 20 62 75 66 66 65 72 20 69 74 73 65  side buffer itse
17680 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  lf using [sqlite
17690 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68  3_malloc()]. ^Th
176a0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
176b0 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65  t is the.** size
176c0 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69   of each lookasi
176d0 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e 20  de buffer slot. 
176e0 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75   ^The third argu
176f0 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62  ment is the numb
17700 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20  er of.** slots. 
17710 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   The size of the
17720 20 62 75 66 66 65 72 20 69 6e 20 74 68 65 20 66   buffer in the f
17730 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75  irst argument mu
17740 73 74 20 62 65 20 67 72 65 61 74 65 72 20 74 68  st be greater th
17750 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74  an.** or equal t
17760 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66  o the product of
17770 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20   the second and 
17780 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e  third arguments.
17790 20 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a 20    The buffer.** 
177a0 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20  must be aligned 
177b0 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75  to an 8-byte bou
177c0 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65 20  ndary.  ^If the 
177d0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
177e0 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43  to.** SQLITE_DBC
177f0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
17800 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c  is not a multipl
17810 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69 6e  e of 8, it is in
17820 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e  ternally.** roun
17830 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65 20  ded down to the 
17840 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75 6c  next smaller mul
17850 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28 54  tiple of 8.  ^(T
17860 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  he lookaside mem
17870 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  ory.** configura
17880 74 69 6f 6e 20 66 6f 72 20 61 20 64 61 74 61 62  tion for a datab
17890 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63  ase connection c
178a0 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e 67  an only be chang
178b0 65 64 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a 20  ed when that.** 
178c0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e 6f  connection is no
178d0 74 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69 6e  t currently usin
178e0 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  g lookaside memo
178f0 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72 20  ry, or in other 
17900 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74 68  words.** when th
17910 65 20 22 63 75 72 72 65 6e 74 20 76 61 6c 75 65  e "current value
17920 22 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  " returned by.**
17930 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 61   [sqlite3_db_sta
17940 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 43  tus](D,[SQLITE_C
17950 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d  ONFIG_LOOKASIDE]
17960 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a 2a  ,...) is zero..*
17970 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f  * Any attempt to
17980 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b   change the look
17990 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f 6e  aside memory con
179a0 66 69 67 75 72 61 74 69 6f 6e 20 77 68 65 6e 20  figuration when 
179b0 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65 6d  lookaside.** mem
179c0 6f 72 79 20 69 73 20 69 6e 20 75 73 65 20 6c 65  ory is in use le
179d0 61 76 65 73 20 74 68 65 20 63 6f 6e 66 69 67 75  aves the configu
179e0 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65 64  ration unchanged
179f0 20 61 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a 2a   and returns .**
17a00 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 29   [SQLITE_BUSY].)
17a10 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  ^</dd>.**.** <dt
17a20 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
17a30 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64 74  _ENABLE_FKEY</dt
17a40 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
17a50 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  option is used t
17a60 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61  o enable or disa
17a70 62 6c 65 20 74 68 65 20 65 6e 66 6f 72 63 65 6d  ble the enforcem
17a80 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69  ent of.** [forei
17a90 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e  gn key constrain
17aa0 74 73 5d 2e 20 20 54 68 65 72 65 20 73 68 6f 75  ts].  There shou
17ab0 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69  ld be two additi
17ac0 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a  onal arguments..
17ad0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
17ae0 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65  ument is an inte
17af0 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74  ger which is 0 t
17b00 6f 20 64 69 73 61 62 6c 65 20 46 4b 20 65 6e 66  o disable FK enf
17b10 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73  orcement,.** pos
17b20 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20  itive to enable 
17b30 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f  FK enforcement o
17b40 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65  r negative to le
17b50 61 76 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  ave FK enforceme
17b60 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e  nt.** unchanged.
17b70 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72    The second par
17b80 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
17b90 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
17ba0 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20  r into which.** 
17bb0 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20  is written 0 or 
17bc0 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  1 to indicate wh
17bd0 65 74 68 65 72 20 46 4b 20 65 6e 66 6f 72 63 65  ether FK enforce
17be0 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f 72 20 6f  ment is off or o
17bf0 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74  n.** following t
17c00 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73  his call.  The s
17c10 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
17c20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f  may be a NULL po
17c30 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69  inter, in.** whi
17c40 63 68 20 63 61 73 65 20 74 68 65 20 46 4b 20 65  ch case the FK e
17c50 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65 74 74 69  nforcement setti
17c60 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74  ng is not report
17c70 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a  ed back. </dd>.*
17c80 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
17c90 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
17ca0 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20  TRIGGER</dt>.** 
17cb0 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
17cc0 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61  n is used to ena
17cd0 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 5b  ble or disable [
17ce0 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c  CREATE TRIGGER |
17cf0 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 54   triggers]..** T
17d00 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74  here should be t
17d10 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72  wo additional ar
17d20 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20  guments..** The 
17d30 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
17d40 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
17d50 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  ch is 0 to disab
17d60 6c 65 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a 20  le triggers,.** 
17d70 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62  positive to enab
17d80 6c 65 20 74 72 69 67 67 65 72 73 20 6f 72 20 6e  le triggers or n
17d90 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65  egative to leave
17da0 20 74 68 65 20 73 65 74 74 69 6e 67 20 75 6e 63   the setting unc
17db0 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73  hanged..** The s
17dc0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
17dd0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
17de0 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20  an integer into 
17df0 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74  which.** is writ
17e00 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e  ten 0 or 1 to in
17e10 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 74  dicate whether t
17e20 72 69 67 67 65 72 73 20 61 72 65 20 64 69 73 61  riggers are disa
17e30 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a  bled or enabled.
17e40 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69  ** following thi
17e50 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63  s call.  The sec
17e60 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61  ond parameter ma
17e70 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  y be a NULL poin
17e80 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68  ter, in.** which
17e90 20 63 61 73 65 20 74 68 65 20 74 72 69 67 67 65   case the trigge
17ea0 72 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74  r setting is not
17eb0 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20   reported back. 
17ec0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
17ed0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
17ee0 45 4e 41 42 4c 45 5f 46 54 53 33 5f 54 4f 4b 45  ENABLE_FTS3_TOKE
17ef0 4e 49 5a 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  NIZER</dt>.** <d
17f00 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
17f10 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c  is used to enabl
17f20 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65  e or disable the
17f30 20 74 77 6f 2d 61 72 67 75 6d 65 6e 74 0a 2a 2a   two-argument.**
17f40 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20   version of the 
17f50 5b 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28  [fts3_tokenizer(
17f60 29 5d 20 66 75 6e 63 74 69 6f 6e 20 77 68 69 63  )] function whic
17f70 68 20 69 73 20 70 61 72 74 20 6f 66 20 74 68 65  h is part of the
17f80 0a 2a 2a 20 5b 46 54 53 33 5d 20 66 75 6c 6c 2d  .** [FTS3] full-
17f90 74 65 78 74 20 73 65 61 72 63 68 20 65 6e 67 69  text search engi
17fa0 6e 65 20 65 78 74 65 6e 73 69 6f 6e 2e 0a 2a 2a  ne extension..**
17fb0 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65   There should be
17fc0 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
17fd0 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68  arguments..** Th
17fe0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
17ff0 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77   is an integer w
18000 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73  hich is 0 to dis
18010 61 62 6c 65 20 66 74 73 33 5f 74 6f 6b 65 6e 69  able fts3_tokeni
18020 7a 65 72 28 29 20 6f 72 0a 2a 2a 20 70 6f 73 69  zer() or.** posi
18030 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 66  tive to enable f
18040 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28 29 20  ts3_tokenizer() 
18050 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c  or negative to l
18060 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e 67  eave the setting
18070 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a  .** unchanged..*
18080 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * The second par
18090 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
180a0 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
180b0 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20  r into which.** 
180c0 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20  is written 0 or 
180d0 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  1 to indicate wh
180e0 65 74 68 65 72 20 66 74 73 33 5f 74 6f 6b 65 6e  ether fts3_token
180f0 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65 64  izer is disabled
18100 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66   or enabled.** f
18110 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61  ollowing this ca
18120 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ll.  The second 
18130 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
18140 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
18150 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73   in.** which cas
18160 65 20 74 68 65 20 6e 65 77 20 73 65 74 74 69 6e  e the new settin
18170 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65  g is not reporte
18180 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a  d back. </dd>.**
18190 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
181a0 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 4c  BCONFIG_ENABLE_L
181b0 4f 41 44 5f 45 58 54 45 4e 53 49 4f 4e 3c 2f 64  OAD_EXTENSION</d
181c0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
181d0 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
181e0 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73  to enable or dis
181f0 61 62 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65  able the [sqlite
18200 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e  3_load_extension
18210 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
18220 20 69 6e 64 65 70 65 6e 64 65 6e 74 6c 79 20 6f   independently o
18230 66 20 74 68 65 20 5b 6c 6f 61 64 5f 65 78 74 65  f the [load_exte
18240 6e 73 69 6f 6e 28 29 5d 20 53 51 4c 20 66 75 6e  nsion()] SQL fun
18250 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20 5b 73  ction..** The [s
18260 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f  qlite3_enable_lo
18270 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20  ad_extension()] 
18280 41 50 49 20 65 6e 61 62 6c 65 73 20 6f 72 20 64  API enables or d
18290 69 73 61 62 6c 65 73 20 62 6f 74 68 20 74 68 65  isables both the
182a0 0a 2a 2a 20 43 2d 41 50 49 20 5b 73 71 6c 69 74  .** C-API [sqlit
182b0 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  e3_load_extensio
182c0 6e 28 29 5d 20 61 6e 64 20 74 68 65 20 53 51 4c  n()] and the SQL
182d0 20 66 75 6e 63 74 69 6f 6e 20 5b 6c 6f 61 64 5f   function [load_
182e0 65 78 74 65 6e 73 69 6f 6e 28 29 5d 2e 0a 2a 2a  extension()]..**
182f0 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65   There should be
18300 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
18310 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 57 68  arguments..** Wh
18320 65 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  en the first arg
18330 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 69 6e  ument to this in
18340 74 65 72 66 61 63 65 20 69 73 20 31 2c 20 74 68  terface is 1, th
18350 65 6e 20 6f 6e 6c 79 20 74 68 65 20 43 2d 41 50  en only the C-AP
18360 49 20 69 73 0a 2a 2a 20 65 6e 61 62 6c 65 64 20  I is.** enabled 
18370 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63  and the SQL func
18380 74 69 6f 6e 20 72 65 6d 61 69 6e 73 20 64 69 73  tion remains dis
18390 61 62 6c 65 64 2e 20 20 49 66 20 74 68 65 20 66  abled.  If the f
183a0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
183b0 0a 2a 2a 20 74 68 69 73 20 69 6e 74 65 72 66 61  .** this interfa
183c0 63 65 20 69 73 20 30 2c 20 74 68 65 6e 20 62 6f  ce is 0, then bo
183d0 74 68 20 74 68 65 20 43 2d 41 50 49 20 61 6e 64  th the C-API and
183e0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
183f0 6e 20 61 72 65 20 64 69 73 61 62 6c 65 64 2e 0a  n are disabled..
18400 2a 2a 20 49 66 20 74 68 65 20 66 69 72 73 74 20  ** If the first 
18410 61 72 67 75 6d 65 6e 74 20 69 73 20 2d 31 2c 20  argument is -1, 
18420 74 68 65 6e 20 6e 6f 20 63 68 61 6e 67 65 73 20  then no changes 
18430 61 72 65 20 6d 61 64 65 20 74 6f 20 73 74 61 74  are made to stat
18440 65 20 6f 66 20 65 69 74 68 65 72 20 74 68 65 0a  e of either the.
18450 2a 2a 20 43 2d 41 50 49 20 6f 72 20 74 68 65 20  ** C-API or the 
18460 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  SQL function..**
18470 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
18480 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74  meter is a point
18490 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
184a0 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69   into which.** i
184b0 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31  s written 0 or 1
184c0 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65   to indicate whe
184d0 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 6c 6f  ther [sqlite3_lo
184e0 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20  ad_extension()] 
184f0 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 73 20  interface.** is 
18500 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62  disabled or enab
18510 6c 65 64 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  led following th
18520 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65  is call.  The se
18530 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d  cond parameter m
18540 61 79 0a 2a 2a 20 62 65 20 61 20 4e 55 4c 4c 20  ay.** be a NULL 
18550 70 6f 69 6e 74 65 72 2c 20 69 6e 20 77 68 69 63  pointer, in whic
18560 68 20 63 61 73 65 20 74 68 65 20 6e 65 77 20 73  h case the new s
18570 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65  etting is not re
18580 70 6f 72 74 65 64 20 62 61 63 6b 2e 0a 2a 2a 20  ported back..** 
18590 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
185a0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
185b0 4d 41 49 4e 44 42 4e 41 4d 45 3c 2f 64 74 3e 0a  MAINDBNAME</dt>.
185c0 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
185d0 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
185e0 63 68 61 6e 67 65 20 74 68 65 20 6e 61 6d 65 20  change the name 
185f0 6f 66 20 74 68 65 20 22 6d 61 69 6e 22 20 64 61  of the "main" da
18600 74 61 62 61 73 65 0a 2a 2a 20 73 63 68 65 6d 61  tabase.** schema
18610 2e 20 20 5e 54 68 65 20 73 6f 6c 65 20 61 72 67  .  ^The sole arg
18620 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
18630 65 72 20 74 6f 20 61 20 63 6f 6e 73 74 61 6e 74  er to a constant
18640 20 55 54 46 38 20 73 74 72 69 6e 67 0a 2a 2a 20   UTF8 string.** 
18650 77 68 69 63 68 20 77 69 6c 6c 20 62 65 63 6f 6d  which will becom
18660 65 20 74 68 65 20 6e 65 77 20 73 63 68 65 6d 61  e the new schema
18670 20 6e 61 6d 65 20 69 6e 20 70 6c 61 63 65 20 6f   name in place o
18680 66 20 22 6d 61 69 6e 22 2e 20 20 5e 53 51 4c 69  f "main".  ^SQLi
18690 74 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6d  te.** does not m
186a0 61 6b 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68  ake a copy of th
186b0 65 20 6e 65 77 20 6d 61 69 6e 20 73 63 68 65 6d  e new main schem
186c0 61 20 6e 61 6d 65 20 73 74 72 69 6e 67 2c 20 73  a name string, s
186d0 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
186e0 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e 73 75 72 65  n.** must ensure
186f0 20 74 68 61 74 20 74 68 65 20 61 72 67 75 6d 65   that the argume
18700 6e 74 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74  nt passed into t
18710 68 69 73 20 44 42 43 4f 4e 46 49 47 20 6f 70 74  his DBCONFIG opt
18720 69 6f 6e 20 69 73 20 75 6e 63 68 61 6e 67 65 64  ion is unchanged
18730 0a 2a 2a 20 75 6e 74 69 6c 20 61 66 74 65 72 20  .** until after 
18740 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
18750 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 0a  nection closes..
18760 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </dd>.**.** <
18770 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
18780 49 47 5f 4e 4f 5f 43 4b 50 54 5f 4f 4e 5f 43 4c  IG_NO_CKPT_ON_CL
18790 4f 53 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  OSE</dt>.** <dd>
187a0 20 55 73 75 61 6c 6c 79 2c 20 77 68 65 6e 20 61   Usually, when a
187b0 20 64 61 74 61 62 61 73 65 20 69 6e 20 77 61 6c   database in wal
187c0 20 6d 6f 64 65 20 69 73 20 63 6c 6f 73 65 64 20   mode is closed 
187d0 6f 72 20 64 65 74 61 63 68 65 64 20 66 72 6f 6d  or detached from
187e0 20 61 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 20   a .** database 
187f0 68 61 6e 64 6c 65 2c 20 53 51 4c 69 74 65 20 63  handle, SQLite c
18800 68 65 63 6b 73 20 69 66 20 74 68 69 73 20 77 69  hecks if this wi
18810 6c 6c 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65  ll mean that the
18820 72 65 20 61 72 65 20 6e 6f 77 20 6e 6f 20 0a 2a  re are now no .*
18830 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 61 74  * connections at
18840 20 61 6c 6c 20 74 6f 20 74 68 65 20 64 61 74 61   all to the data
18850 62 61 73 65 2e 20 49 66 20 73 6f 2c 20 69 74 20  base. If so, it 
18860 70 65 72 66 6f 72 6d 73 20 61 20 63 68 65 63 6b  performs a check
18870 70 6f 69 6e 74 20 0a 2a 2a 20 6f 70 65 72 61 74  point .** operat
18880 69 6f 6e 20 62 65 66 6f 72 65 20 63 6c 6f 73 69  ion before closi
18890 6e 67 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  ng the connectio
188a0 6e 2e 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 6d  n. This option m
188b0 61 79 20 62 65 20 75 73 65 64 20 74 6f 0a 2a 2a  ay be used to.**
188c0 20 6f 76 65 72 72 69 64 65 20 74 68 69 73 20 62   override this b
188d0 65 68 61 76 69 6f 75 72 2e 20 54 68 65 20 66 69  ehaviour. The fi
188e0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 70 61  rst parameter pa
188f0 73 73 65 64 20 74 6f 20 74 68 69 73 20 6f 70 65  ssed to this ope
18900 72 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 61 6e 20  ration.** is an 
18910 69 6e 74 65 67 65 72 20 2d 20 6e 6f 6e 2d 7a 65  integer - non-ze
18920 72 6f 20 74 6f 20 64 69 73 61 62 6c 65 20 63 68  ro to disable ch
18930 65 63 6b 70 6f 69 6e 74 73 2d 6f 6e 2d 63 6c 6f  eckpoints-on-clo
18940 73 65 2c 20 6f 72 20 7a 65 72 6f 20 28 74 68 65  se, or zero (the
18950 0a 2a 2a 20 64 65 66 61 75 6c 74 29 20 74 6f 20  .** default) to 
18960 65 6e 61 62 6c 65 20 74 68 65 6d 2e 20 54 68 65  enable them. The
18970 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
18980 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  r is a pointer t
18990 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20  o an integer.** 
189a0 69 6e 74 6f 20 77 68 69 63 68 20 69 73 20 77 72  into which is wr
189b0 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20  itten 0 or 1 to 
189c0 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72  indicate whether
189d0 20 63 68 65 63 6b 70 6f 69 6e 74 73 2d 6f 6e 2d   checkpoints-on-
189e0 63 6c 6f 73 65 0a 2a 2a 20 68 61 76 65 20 62 65  close.** have be
189f0 65 6e 20 64 69 73 61 62 6c 65 64 20 2d 20 30 20  en disabled - 0 
18a00 69 66 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20  if they are not 
18a10 64 69 73 61 62 6c 65 64 2c 20 31 20 69 66 20 74  disabled, 1 if t
18a20 68 65 79 20 61 72 65 2e 0a 2a 2a 20 3c 2f 64 64  hey are..** </dd
18a30 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  >.**.** </dl>.*/
18a40 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18a50 44 42 43 4f 4e 46 49 47 5f 4d 41 49 4e 44 42 4e  DBCONFIG_MAINDBN
18a60 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 20 31  AME            1
18a70 30 30 30 20 2f 2a 20 63 6f 6e 73 74 20 63 68 61  000 /* const cha
18a80 72 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  r* */.#define SQ
18a90 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
18aa0 4f 4b 41 53 49 44 45 20 20 20 20 20 20 20 20 20  OKASIDE         
18ab0 20 20 20 20 31 30 30 31 20 2f 2a 20 76 6f 69 64      1001 /* void
18ac0 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65  * int int */.#de
18ad0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
18ae0 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59  NFIG_ENABLE_FKEY
18af0 20 20 20 20 20 20 20 20 20 20 20 31 30 30 32 20             1002 
18b00 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23  /* 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 54 52  CONFIG_ENABLE_TR
18b30 49 47 47 45 52 20 20 20 20 20 20 20 20 31 30 30  IGGER        100
18b40 33 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f  3 /* 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 46 54 53 33 5f 54 4f 4b 45 4e 49 5a 45 52 20 31  FTS3_TOKENIZER 1
18b80 30 30 34 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20  004 /* 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 4c 4f 41 44 5f 45 58 54 45 4e 53 49 4f 4e  E_LOAD_EXTENSION
18bc0 20 31 30 30 35 20 2f 2a 20 69 6e 74 20 69 6e 74   1005 /* 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 4e 4f 5f  ITE_DBCONFIG_NO_
18bf0 43 4b 50 54 5f 4f 4e 5f 43 4c 4f 53 45 20 20 20  CKPT_ON_CLOSE   
18c00 20 20 20 31 30 30 36 20 2f 2a 20 69 6e 74 20 69     1006 /* int i
18c10 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43  nt* */.../*.** C
18c20 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20  API3REF: Enable 
18c30 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e  Or Disable Exten
18c40 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73  ded Result Codes
18c50 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
18c60 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  te3.**.** ^The s
18c70 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
18c80 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72  result_codes() r
18c90 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f  outine enables o
18ca0 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a  r disables the.*
18cb0 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
18cc0 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72  lt codes] featur
18cd0 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68  e of SQLite. ^Th
18ce0 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  e extended resul
18cf0 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64  t.** codes are d
18d00 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
18d10 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61  lt for historica
18d20 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  l compatibility.
18d30 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
18d40 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
18d50 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20  codes(sqlite3*, 
18d60 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a  int onoff);../*.
18d70 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73  ** CAPI3REF: Las
18d80 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a  t Insert Rowid.*
18d90 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
18da0 33 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e  3.**.** ^Each en
18db0 74 72 79 20 69 6e 20 6d 6f 73 74 20 53 51 4c 69  try in most SQLi
18dc0 74 65 20 74 61 62 6c 65 73 20 28 65 78 63 65 70  te tables (excep
18dd0 74 20 66 6f 72 20 5b 57 49 54 48 4f 55 54 20 52  t for [WITHOUT R
18de0 4f 57 49 44 5d 20 74 61 62 6c 65 73 29 0a 2a 2a  OWID] tables).**
18df0 20 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 34   has a unique 64
18e00 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69  -bit signed.** i
18e10 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65  nteger key calle
18e20 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22  d the [ROWID | "
18e30 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f  rowid"]. ^The ro
18e40 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 76  wid is always av
18e50 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e  ailable.** as an
18e60 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75   undeclared colu
18e70 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20  mn named ROWID, 
18e80 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20  OID, or _ROWID_ 
18e90 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65  as long as those
18ea0 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f  .** names are no
18eb0 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65  t also used by e
18ec0 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72  xplicitly declar
18ed0 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a  ed columns. ^If.
18ee0 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61 73  ** the table has
18ef0 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70   a column of typ
18f00 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41  e [INTEGER PRIMA
18f10 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61  RY KEY] then tha
18f20 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61  t column.** is a
18f30 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72  nother alias for
18f40 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a   the rowid..**.*
18f50 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c  * ^The sqlite3_l
18f60 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
18f70 28 44 29 20 69 6e 74 65 72 66 61 63 65 20 75 73  (D) interface us
18f80 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68  ually returns th
18f90 65 20 5b 72 6f 77 69 64 5d 20 6f 66 0a 2a 2a 20  e [rowid] of.** 
18fa0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
18fb0 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45  successful [INSE
18fc0 52 54 5d 20 69 6e 74 6f 20 61 20 72 6f 77 69 64  RT] into a rowid
18fd0 20 74 61 62 6c 65 20 6f 72 20 5b 76 69 72 74 75   table or [virtu
18fe0 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e 20  al table].** on 
18ff0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
19000 69 6f 6e 20 44 2e 20 5e 49 6e 73 65 72 74 73 20  ion D. ^Inserts 
19010 69 6e 74 6f 20 5b 57 49 54 48 4f 55 54 20 52 4f  into [WITHOUT RO
19020 57 49 44 5d 20 74 61 62 6c 65 73 20 61 72 65 20  WID] tables are 
19030 6e 6f 74 0a 2a 2a 20 72 65 63 6f 72 64 65 64 2e  not.** recorded.
19040 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66   ^If no successf
19050 75 6c 20 5b 49 4e 53 45 52 54 5d 73 20 69 6e 74  ul [INSERT]s int
19060 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 73 20 68  o rowid tables h
19070 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 65  ave ever occurre
19080 64 20 0a 2a 2a 20 6f 6e 20 74 68 65 20 64 61 74  d .** on the dat
19090 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
190a0 20 44 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33   D, then sqlite3
190b0 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
190c0 69 64 28 44 29 20 72 65 74 75 72 6e 73 20 0a 2a  id(D) returns .*
190d0 2a 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 41 73  * zero..**.** As
190e0 20 77 65 6c 6c 20 61 73 20 62 65 69 6e 67 20 73   well as being s
190f0 65 74 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  et automatically
19100 20 61 73 20 72 6f 77 73 20 61 72 65 20 69 6e 73   as rows are ins
19110 65 72 74 65 64 20 69 6e 74 6f 20 64 61 74 61 62  erted into datab
19120 61 73 65 0a 2a 2a 20 74 61 62 6c 65 73 2c 20 74  ase.** tables, t
19130 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
19140 64 20 62 79 20 74 68 69 73 20 66 75 6e 63 74 69  d by this functi
19150 6f 6e 20 6d 61 79 20 62 65 20 73 65 74 20 65 78  on may be set ex
19160 70 6c 69 63 69 74 6c 79 20 62 79 0a 2a 2a 20 5b  plicitly by.** [
19170 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 74  sqlite3_set_last
19180 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
19190 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 76 69 72 74  .**.** Some virt
191a0 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d  ual table implem
191b0 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20 49 4e  entations may IN
191c0 53 45 52 54 20 72 6f 77 73 20 69 6e 74 6f 20 72  SERT rows into r
191d0 6f 77 69 64 20 74 61 62 6c 65 73 20 61 73 0a 2a  owid tables as.*
191e0 2a 20 70 61 72 74 20 6f 66 20 63 6f 6d 6d 69 74  * part of commit
191f0 74 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69  ting a transacti
19200 6f 6e 20 28 65 2e 67 2e 20 74 6f 20 66 6c 75 73  on (e.g. to flus
19210 68 20 64 61 74 61 20 61 63 63 75 6d 75 6c 61 74  h data accumulat
19220 65 64 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a 2a 20  ed in memory.** 
19230 74 6f 20 64 69 73 6b 29 2e 20 49 6e 20 74 68 69  to disk). In thi
19240 73 20 63 61 73 65 20 73 75 62 73 65 71 75 65 6e  s case subsequen
19250 74 20 63 61 6c 6c 73 20 74 6f 20 74 68 69 73 20  t calls to this 
19260 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 20  function return 
19270 74 68 65 20 72 6f 77 69 64 0a 2a 2a 20 61 73 73  the rowid.** ass
19280 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
19290 73 65 20 69 6e 74 65 72 6e 61 6c 20 49 4e 53 45  se internal INSE
192a0 52 54 20 6f 70 65 72 61 74 69 6f 6e 73 2c 20 77  RT operations, w
192b0 68 69 63 68 20 6c 65 61 64 73 20 74 6f 20 0a 2a  hich leads to .*
192c0 2a 20 75 6e 69 6e 74 75 69 74 69 76 65 20 72 65  * unintuitive re
192d0 73 75 6c 74 73 2e 20 56 69 72 74 75 61 6c 20 74  sults. Virtual t
192e0 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  able implementat
192f0 69 6f 6e 73 20 74 68 61 74 20 64 6f 20 77 72 69  ions that do wri
19300 74 65 20 74 6f 20 72 6f 77 69 64 0a 2a 2a 20 74  te to rowid.** t
19310 61 62 6c 65 73 20 69 6e 20 74 68 69 73 20 77 61  ables in this wa
19320 79 20 63 61 6e 20 61 76 6f 69 64 20 74 68 69 73  y can avoid this
19330 20 70 72 6f 62 6c 65 6d 20 62 79 20 72 65 73 74   problem by rest
19340 6f 72 69 6e 67 20 74 68 65 20 6f 72 69 67 69 6e  oring the origin
19350 61 6c 20 0a 2a 2a 20 72 6f 77 69 64 20 76 61 6c  al .** rowid val
19360 75 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ue using [sqlite
19370 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72  3_set_last_inser
19380 74 5f 72 6f 77 69 64 28 29 5d 20 62 65 66 6f 72  t_rowid()] befor
19390 65 20 72 65 74 75 72 6e 69 6e 67 20 0a 2a 2a 20  e returning .** 
193a0 63 6f 6e 74 72 6f 6c 20 74 6f 20 74 68 65 20 75  control to the u
193b0 73 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  ser..**.** ^(If 
193c0 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75  an [INSERT] occu
193d0 72 73 20 77 69 74 68 69 6e 20 61 20 74 72 69 67  rs within a trig
193e0 67 65 72 20 74 68 65 6e 20 74 68 69 73 20 72 6f  ger then this ro
193f0 75 74 69 6e 65 20 77 69 6c 6c 20 0a 2a 2a 20 72  utine will .** r
19400 65 74 75 72 6e 20 74 68 65 20 5b 72 6f 77 69 64  eturn the [rowid
19410 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65  ] of the inserte
19420 64 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61 73  d row as long as
19430 20 74 68 65 20 74 72 69 67 67 65 72 20 69 73 20   the trigger is 
19440 0a 2a 2a 20 72 75 6e 6e 69 6e 67 2e 20 4f 6e 63  .** running. Onc
19450 65 20 74 68 65 20 74 72 69 67 67 65 72 20 70 72  e the trigger pr
19460 6f 67 72 61 6d 20 65 6e 64 73 2c 20 74 68 65 20  ogram ends, the 
19470 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 0a  value returned .
19480 2a 2a 20 62 79 20 74 68 69 73 20 72 6f 75 74 69  ** by this routi
19490 6e 65 20 72 65 76 65 72 74 73 20 74 6f 20 77 68  ne reverts to wh
194a0 61 74 20 69 74 20 77 61 73 20 62 65 66 6f 72 65  at it was before
194b0 20 74 68 65 20 74 72 69 67 67 65 72 20 77 61 73   the trigger was
194c0 20 66 69 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20   fired.)^.**.** 
194d0 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68 61  ^An [INSERT] tha
194e0 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61  t fails due to a
194f0 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
19500 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a  ation is not a.*
19510 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e  * successful [IN
19520 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e  SERT] and does n
19530 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61  ot change the va
19540 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
19550 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e  this.** routine.
19560 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54 20 4f    ^Thus INSERT O
19570 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f  R FAIL, INSERT O
19580 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54  R IGNORE, INSERT
19590 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a   OR ROLLBACK,.**
195a0 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41   and INSERT OR A
195b0 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61  BORT make no cha
195c0 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65 74 75  nges to the retu
195d0 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73  rn value of this
195e0 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e  .** routine when
195f0 20 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e   their insertion
19600 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20   fails.  ^(When 
19610 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43  INSERT OR REPLAC
19620 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20  E.** encounters 
19630 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  a constraint vio
19640 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20  lation, it does 
19650 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a  not fail.  The.*
19660 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75  * INSERT continu
19670 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  es to completion
19680 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20   after deleting 
19690 72 6f 77 73 20 74 68 61 74 20 63 61 75 73 65 64  rows that caused
196a0 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69  .** the constrai
196b0 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e  nt problem so IN
196c0 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20  SERT OR REPLACE 
196d0 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e  will always chan
196e0 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e  ge.** the return
196f0 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69   value of this i
19700 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a  nterface.)^.**.*
19710 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f  * ^For the purpo
19720 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74  ses of this rout
19730 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d  ine, an [INSERT]
19740 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74   is considered t
19750 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66  o.** be successf
19760 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69 73  ul even if it is
19770 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f   subsequently ro
19780 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a  lled back..**.**
19790 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69   This function i
197a0 73 20 61 63 63 65 73 73 69 62 6c 65 20 74 6f 20  s accessible to 
197b0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 76  SQL statements v
197c0 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f  ia the.** [last_
197d0 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 20 53  insert_rowid() S
197e0 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
197f0 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
19800 65 20 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d  e thread perform
19810 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d  s a new [INSERT]
19820 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20   on the same.** 
19830 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
19840 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73  ion while the [s
19850 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
19860 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66  rt_rowid()].** f
19870 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
19880 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e  ng and thus chan
19890 67 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73  ges the last ins
198a0 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20  ert [rowid],.** 
198b0 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72  then the value r
198c0 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
198d0 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
198e0 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75  rowid()] is.** u
198f0 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
19900 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c   might not equal
19910 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20   either the old 
19920 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61  or the new.** la
19930 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64  st insert [rowid
19940 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e  ]..*/.sqlite3_in
19950 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74  t64 sqlite3_last
19960 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71  _insert_rowid(sq
19970 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
19980 43 41 50 49 33 52 45 46 3a 20 53 65 74 20 74 68  CAPI3REF: Set th
19990 65 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f  e Last Insert Ro
199a0 77 69 64 20 76 61 6c 75 65 2e 0a 2a 2a 20 4d 45  wid value..** ME
199b0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
199c0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
199d0 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  set_last_insert_
199e0 72 6f 77 69 64 28 44 2c 20 52 29 20 6d 65 74 68  rowid(D, R) meth
199f0 6f 64 20 61 6c 6c 6f 77 73 20 74 68 65 20 61 70  od allows the ap
19a00 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20  plication to.** 
19a10 73 65 74 20 74 68 65 20 76 61 6c 75 65 20 72 65  set the value re
19a20 74 75 72 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e  turned by callin
19a30 67 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69  g sqlite3_last_i
19a40 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20 74  nsert_rowid(D) t
19a50 6f 20 52 20 0a 2a 2a 20 77 69 74 68 6f 75 74 20  o R .** without 
19a60 69 6e 73 65 72 74 69 6e 67 20 61 20 72 6f 77 20  inserting a row 
19a70 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  into the databas
19a80 65 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  e..*/.void sqlit
19a90 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65  e3_set_last_inse
19aa0 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33  rt_rowid(sqlite3
19ab0 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  *,sqlite3_int64)
19ac0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
19ad0 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d  F: Count The Num
19ae0 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69  ber Of Rows Modi
19af0 66 69 65 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  fied.** METHOD: 
19b00 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
19b10 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
19b20 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
19b30 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 65 64  of rows modified
19b40 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 0a 2a 2a  , inserted or.**
19b50 20 64 65 6c 65 74 65 64 20 62 79 20 74 68 65 20   deleted by the 
19b60 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f  most recently co
19b70 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20  mpleted INSERT, 
19b80 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45  UPDATE or DELETE
19b90 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6f 6e  .** statement on
19ba0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
19bb0 6e 6e 65 63 74 69 6f 6e 20 73 70 65 63 69 66 69  nnection specifi
19bc0 65 64 20 62 79 20 74 68 65 20 6f 6e 6c 79 20 70  ed by the only p
19bd0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 45 78  arameter..** ^Ex
19be0 65 63 75 74 69 6e 67 20 61 6e 79 20 6f 74 68 65  ecuting any othe
19bf0 72 20 74 79 70 65 20 6f 66 20 53 51 4c 20 73 74  r type of SQL st
19c00 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74  atement does not
19c10 20 6d 6f 64 69 66 79 20 74 68 65 20 76 61 6c 75   modify the valu
19c20 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79  e.** returned by
19c30 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a   this function..
19c40 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 63 68 61 6e  **.** ^Only chan
19c50 67 65 73 20 6d 61 64 65 20 64 69 72 65 63 74 6c  ges made directl
19c60 79 20 62 79 20 74 68 65 20 49 4e 53 45 52 54 2c  y by the INSERT,
19c70 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54   UPDATE or DELET
19c80 45 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65 0a  E statement are.
19c90 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 2d 20  ** considered - 
19ca0 61 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65  auxiliary change
19cb0 73 20 63 61 75 73 65 64 20 62 79 20 5b 43 52 45  s caused by [CRE
19cc0 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72  ATE TRIGGER | tr
19cd0 69 67 67 65 72 73 5d 2c 20 0a 2a 2a 20 5b 66 6f  iggers], .** [fo
19ce0 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e  reign key action
19cf0 73 5d 20 6f 72 20 5b 52 45 50 4c 41 43 45 5d 20  s] or [REPLACE] 
19d00 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c  constraint resol
19d10 75 74 69 6f 6e 20 61 72 65 20 6e 6f 74 20 63 6f  ution are not co
19d20 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 43 68  unted..** .** Ch
19d30 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20  anges to a view 
19d40 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 63 65  that are interce
19d50 70 74 65 64 20 62 79 20 0a 2a 2a 20 5b 49 4e 53  pted by .** [INS
19d60 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 20  TEAD OF trigger 
19d70 7c 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69  | INSTEAD OF tri
19d80 67 67 65 72 73 5d 20 61 72 65 20 6e 6f 74 20 63  ggers] are not c
19d90 6f 75 6e 74 65 64 2e 20 5e 54 68 65 20 76 61 6c  ounted. ^The val
19da0 75 65 20 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  ue .** returned 
19db0 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  by sqlite3_chang
19dc0 65 73 28 29 20 69 6d 6d 65 64 69 61 74 65 6c 79  es() immediately
19dd0 20 61 66 74 65 72 20 61 6e 20 49 4e 53 45 52 54   after an INSERT
19de0 2c 20 55 50 44 41 54 45 20 6f 72 20 0a 2a 2a 20  , UPDATE or .** 
19df0 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74  DELETE statement
19e00 20 72 75 6e 20 6f 6e 20 61 20 76 69 65 77 20 69   run on a view i
19e10 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2e 20 4f  s always zero. O
19e20 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61 64 65  nly changes made
19e30 20 74 6f 20 72 65 61 6c 20 0a 2a 2a 20 74 61 62   to real .** tab
19e40 6c 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2e  les are counted.
19e50 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 67 73 20 61 72  .**.** Things ar
19e60 65 20 6d 6f 72 65 20 63 6f 6d 70 6c 69 63 61 74  e more complicat
19e70 65 64 20 69 66 20 74 68 65 20 73 71 6c 69 74 65  ed if the sqlite
19e80 33 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63  3_changes() func
19e90 74 69 6f 6e 20 69 73 0a 2a 2a 20 65 78 65 63 75  tion is.** execu
19ea0 74 65 64 20 77 68 69 6c 65 20 61 20 74 72 69 67  ted while a trig
19eb0 67 65 72 20 70 72 6f 67 72 61 6d 20 69 73 20 72  ger program is r
19ec0 75 6e 6e 69 6e 67 2e 20 54 68 69 73 20 6d 61 79  unning. This may
19ed0 20 68 61 70 70 65 6e 20 69 66 20 74 68 65 0a 2a   happen if the.*
19ee0 2a 20 70 72 6f 67 72 61 6d 20 75 73 65 73 20 74  * program uses t
19ef0 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51  he [changes() SQ
19f00 4c 20 66 75 6e 63 74 69 6f 6e 5d 2c 20 6f 72 20  L function], or 
19f10 69 66 20 73 6f 6d 65 20 6f 74 68 65 72 20 63 61  if some other ca
19f20 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69  llback.** functi
19f30 6f 6e 20 69 6e 76 6f 6b 65 73 20 73 71 6c 69 74  on invokes sqlit
19f40 65 33 5f 63 68 61 6e 67 65 73 28 29 20 64 69 72  e3_changes() dir
19f50 65 63 74 6c 79 2e 20 45 73 73 65 6e 74 69 61 6c  ectly. Essential
19f60 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a  ly:.** .** <ul>.
19f70 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 42 65 66 6f  **   <li> ^(Befo
19f80 72 65 20 65 6e 74 65 72 69 6e 67 20 61 20 74 72  re entering a tr
19f90 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 74 68  igger program th
19fa0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
19fb0 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 73 71   by.**        sq
19fc0 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20  lite3_changes() 
19fd0 66 75 6e 63 74 69 6f 6e 20 69 73 20 73 61 76 65  function is save
19fe0 64 2e 20 41 66 74 65 72 20 74 68 65 20 74 72 69  d. After the tri
19ff0 67 67 65 72 20 70 72 6f 67 72 61 6d 20 0a 2a 2a  gger program .**
1a000 20 20 20 20 20 20 20 20 68 61 73 20 66 69 6e 69          has fini
1a010 73 68 65 64 2c 20 74 68 65 20 6f 72 69 67 69 6e  shed, the origin
1a020 61 6c 20 76 61 6c 75 65 20 69 73 20 72 65 73 74  al value is rest
1a030 6f 72 65 64 2e 29 5e 0a 2a 2a 20 0a 2a 2a 20 20  ored.)^.** .**  
1a040 20 3c 6c 69 3e 20 5e 28 57 69 74 68 69 6e 20 61   <li> ^(Within a
1a050 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d   trigger program
1a060 20 65 61 63 68 20 49 4e 53 45 52 54 2c 20 55 50   each INSERT, UP
1a070 44 41 54 45 20 61 6e 64 20 44 45 4c 45 54 45 20  DATE and DELETE 
1a080 0a 2a 2a 20 20 20 20 20 20 20 20 73 74 61 74 65  .**        state
1a090 6d 65 6e 74 20 73 65 74 73 20 74 68 65 20 76 61  ment sets the va
1a0a0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
1a0b0 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
1a0c0 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 75 70 6f  ) .**        upo
1a0d0 6e 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 73 20  n completion as 
1a0e0 6e 6f 72 6d 61 6c 2e 20 4f 66 20 63 6f 75 72 73  normal. Of cours
1a0f0 65 2c 20 74 68 69 73 20 76 61 6c 75 65 20 77 69  e, this value wi
1a100 6c 6c 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 0a  ll not include .
1a110 2a 2a 20 20 20 20 20 20 20 20 61 6e 79 20 63 68  **        any ch
1a120 61 6e 67 65 73 20 70 65 72 66 6f 72 6d 65 64 20  anges performed 
1a130 62 79 20 73 75 62 2d 74 72 69 67 67 65 72 73 2c  by sub-triggers,
1a140 20 61 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f   as the sqlite3_
1a150 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20  changes() .**   
1a160 20 20 20 20 20 76 61 6c 75 65 20 77 69 6c 6c 20       value will 
1a170 62 65 20 73 61 76 65 64 20 61 6e 64 20 72 65 73  be saved and res
1a180 74 6f 72 65 64 20 61 66 74 65 72 20 65 61 63 68  tored after each
1a190 20 73 75 62 2d 74 72 69 67 67 65 72 20 68 61 73   sub-trigger has
1a1a0 20 72 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f 75 6c 3e   run.)^.** </ul>
1a1b0 0a 2a 2a 20 0a 2a 2a 20 5e 54 68 69 73 20 6d 65  .** .** ^This me
1a1c0 61 6e 73 20 74 68 61 74 20 69 66 20 74 68 65 20  ans that if the 
1a1d0 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75  changes() SQL fu
1a1e0 6e 63 74 69 6f 6e 20 28 6f 72 20 73 69 6d 69 6c  nction (or simil
1a1f0 61 72 29 20 69 73 20 75 73 65 64 0a 2a 2a 20 62  ar) is used.** b
1a200 79 20 74 68 65 20 66 69 72 73 74 20 49 4e 53 45  y the first INSE
1a210 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45  RT, UPDATE or DE
1a220 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77  LETE statement w
1a230 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 2c  ithin a trigger,
1a240 20 69 74 20 0a 2a 2a 20 72 65 74 75 72 6e 73 20   it .** returns 
1a250 74 68 65 20 76 61 6c 75 65 20 61 73 20 73 65 74  the value as set
1a260 20 77 68 65 6e 20 74 68 65 20 63 61 6c 6c 69 6e   when the callin
1a270 67 20 73 74 61 74 65 6d 65 6e 74 20 62 65 67 61  g statement bega
1a280 6e 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20  n executing..** 
1a290 5e 49 66 20 69 74 20 69 73 20 75 73 65 64 20 62  ^If it is used b
1a2a0 79 20 74 68 65 20 73 65 63 6f 6e 64 20 6f 72 20  y the second or 
1a2b0 73 75 62 73 65 71 75 65 6e 74 20 73 75 63 68 20  subsequent such 
1a2c0 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e  statement within
1a2d0 20 61 20 74 72 69 67 67 65 72 20 0a 2a 2a 20 70   a trigger .** p
1a2e0 72 6f 67 72 61 6d 2c 20 74 68 65 20 76 61 6c 75  rogram, the valu
1a2f0 65 20 72 65 74 75 72 6e 65 64 20 72 65 66 6c 65  e returned refle
1a300 63 74 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  cts the number o
1a310 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 65 64 20  f rows modified 
1a320 62 79 20 74 68 65 20 0a 2a 2a 20 70 72 65 76 69  by the .** previ
1a330 6f 75 73 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ous INSERT, UPDA
1a340 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61  TE or DELETE sta
1a350 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68  tement within th
1a360 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a  e same trigger..
1a370 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74  **.** See also t
1a380 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  he [sqlite3_tota
1a390 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74  l_changes()] int
1a3a0 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b  erface, the.** [
1a3b0 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72  count_changes pr
1a3c0 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b  agma], and the [
1a3d0 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75  changes() SQL fu
1a3e0 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49  nction]..**.** I
1a3f0 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
1a400 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65  ead makes change
1a410 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61  s on the same da
1a420 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1a430 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69  n.** while [sqli
1a440 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  te3_changes()] i
1a450 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74  s running then t
1a460 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
1a470 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 63  d.** is unpredic
1a480 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65  table and not me
1a490 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74  aningful..*/.int
1a4a0 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
1a4b0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
1a4c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74  ** CAPI3REF: Tot
1a4d0 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77  al Number Of Row
1a4e0 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45  s Modified.** ME
1a4f0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
1a500 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
1a510 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 74  on returns the t
1a520 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 72  otal number of r
1a530 6f 77 73 20 69 6e 73 65 72 74 65 64 2c 20 6d 6f  ows inserted, mo
1a540 64 69 66 69 65 64 20 6f 72 0a 2a 2a 20 64 65 6c  dified or.** del
1a550 65 74 65 64 20 62 79 20 61 6c 6c 20 5b 49 4e 53  eted by all [INS
1a560 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 20 6f  ERT], [UPDATE] o
1a570 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65  r [DELETE] state
1a580 6d 65 6e 74 73 20 63 6f 6d 70 6c 65 74 65 64 0a  ments completed.
1a590 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 64 61 74  ** since the dat
1a5a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1a5b0 20 77 61 73 20 6f 70 65 6e 65 64 2c 20 69 6e 63   was opened, inc
1a5c0 6c 75 64 69 6e 67 20 74 68 6f 73 65 20 65 78 65  luding those exe
1a5d0 63 75 74 65 64 20 61 73 0a 2a 2a 20 70 61 72 74  cuted as.** part
1a5e0 20 6f 66 20 74 72 69 67 67 65 72 20 70 72 6f 67   of trigger prog
1a5f0 72 61 6d 73 2e 20 5e 45 78 65 63 75 74 69 6e 67  rams. ^Executing
1a600 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20   any other type 
1a610 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  of SQL statement
1a620 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 61 66 66  .** does not aff
1a630 65 63 74 20 74 68 65 20 76 61 6c 75 65 20 72 65  ect the value re
1a640 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
1a650 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
1a660 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 61 6e 67  )..** .** ^Chang
1a670 65 73 20 6d 61 64 65 20 61 73 20 70 61 72 74 20  es made as part 
1a680 6f 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  of [foreign key 
1a690 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 69 6e 63  actions] are inc
1a6a0 6c 75 64 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20  luded in the.** 
1a6b0 63 6f 75 6e 74 2c 20 62 75 74 20 74 68 6f 73 65  count, but those
1a6c0 20 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f 66   made as part of
1a6d0 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61   REPLACE constra
1a6e0 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61  int resolution a
1a6f0 72 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 68 61 6e  re.** not. ^Chan
1a700 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 74 68  ges to a view th
1a710 61 74 20 61 72 65 20 69 6e 74 65 72 63 65 70 74  at are intercept
1a720 65 64 20 62 79 20 49 4e 53 54 45 41 44 20 4f 46  ed by INSTEAD OF
1a730 20 74 72 69 67 67 65 72 73 20 0a 2a 2a 20 61 72   triggers .** ar
1a740 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a  e not counted..*
1a750 2a 20 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74  * .** See also t
1a760 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e  he [sqlite3_chan
1a770 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ges()] interface
1a780 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f  , the.** [count_
1a790 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c  changes pragma],
1a7a0 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f   and the [total_
1a7b0 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75  changes() SQL fu
1a7c0 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49  nction]..**.** I
1a7d0 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
1a7e0 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65  ead makes change
1a7f0 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61  s on the same da
1a800 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1a810 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69  n.** while [sqli
1a820 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
1a830 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20  s()] is running 
1a840 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a  then the value.*
1a850 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e  * returned is un
1a860 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
1a870 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a  not meaningful..
1a880 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  */.int sqlite3_t
1a890 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c  otal_changes(sql
1a8a0 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
1a8b0 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75  API3REF: Interru
1a8c0 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e  pt A Long-Runnin
1a8d0 67 20 51 75 65 72 79 0a 2a 2a 20 4d 45 54 48 4f  g Query.** METHO
1a8e0 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
1a8f0 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
1a900 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69  causes any pendi
1a910 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 65 72  ng database oper
1a920 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61  ation to abort a
1a930 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20  nd.** return at 
1a940 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70  its earliest opp
1a950 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72  ortunity. This r
1a960 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 63 61  outine is typica
1a970 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e  lly.** called in
1a980 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75   response to a u
1a990 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20  ser action such 
1a9a0 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e  as pressing "Can
1a9b0 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d  cel".** or Ctrl-
1a9c0 43 20 77 68 65 72 65 20 74 68 65 20 75 73 65 72  C where the user
1a9d0 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75   wants a long qu
1a9e0 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f  ery operation to
1a9f0 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61   halt.** immedia
1aa00 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20  tely..**.** ^It 
1aa10 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20  is safe to call 
1aa20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f  this routine fro
1aa30 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66 65  m a thread diffe
1aa40 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a  rent from the.**
1aa50 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73 20   thread that is 
1aa60 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e  currently runnin
1aa70 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f  g the database o
1aa80 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69  peration.  But i
1aa90 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65  t.** is not safe
1aaa0 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f   to call this ro
1aab0 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61  utine with a [da
1aac0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1aad0 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c  n] that.** is cl
1aae0 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c  osed or might cl
1aaf0 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74  ose before sqlit
1ab00 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72  e3_interrupt() r
1ab10 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49  eturns..**.** ^I
1ab20 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69  f an SQL operati
1ab30 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c  on is very nearl
1ab40 79 20 66 69 6e 69 73 68 65 64 20 61 74 20 74 68  y finished at th
1ab50 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73  e time when.** s
1ab60 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1ab70 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68  () is called, th
1ab80 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20  en it might not 
1ab90 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e  have an opportun
1aba0 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74  ity.** to be int
1abb0 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67  errupted and mig
1abc0 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63  ht continue to c
1abd0 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  ompletion..**.**
1abe0 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69   ^An SQL operati
1abf0 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65 72  on that is inter
1ac00 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75  rupted will retu
1ac10 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52  rn [SQLITE_INTER
1ac20 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68  RUPT]..** ^If th
1ac30 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 53 51  e interrupted SQ
1ac40 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61  L operation is a
1ac50 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  n INSERT, UPDATE
1ac60 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74  , or DELETE.** t
1ac70 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e  hat is inside an
1ac80 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
1ac90 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20  ction, then the 
1aca0 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74 69  entire transacti
1acb0 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f  on.** will be ro
1acc0 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61  lled back automa
1acd0 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  tically..**.** ^
1ace0 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  The sqlite3_inte
1acf0 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69 73  rrupt(D) call is
1ad00 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69 6c   in effect until
1ad10 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 72   all currently r
1ad20 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74  unning.** SQL st
1ad30 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74  atements on [dat
1ad40 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1ad50 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e  ] D complete.  ^
1ad60 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61 74  Any new SQL stat
1ad70 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61  ements.** that a
1ad80 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72  re started after
1ad90 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
1ada0 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61 6e  errupt() call an
1adb0 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a  d before the .**
1adc0 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65   running stateme
1add0 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65 72 6f  nts reaches zero
1ade0 20 61 72 65 20 69 6e 74 65 72 72 75 70 74 65 64   are interrupted
1adf0 20 61 73 20 69 66 20 74 68 65 79 20 68 61 64 20   as if they had 
1ae00 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20  been.** running 
1ae10 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71 6c  prior to the sql
1ae20 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
1ae30 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c   call.  ^New SQL
1ae40 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
1ae50 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
1ae60 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69 6e  after the runnin
1ae70 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e  g statement coun
1ae80 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61  t reaches zero a
1ae90 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74  re.** not effect
1aea0 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65  ed by the sqlite
1aeb0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a  3_interrupt()..*
1aec0 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  * ^A call to sql
1aed0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44  ite3_interrupt(D
1aee0 29 20 74 68 61 74 20 6f 63 63 75 72 73 20 77 68  ) that occurs wh
1aef0 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20  en there are no 
1af00 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73  running.** SQL s
1af10 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20 6e  tatements is a n
1af20 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f 20  o-op and has no 
1af30 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74  effect on SQL st
1af40 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
1af50 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
1af60 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  er the sqlite3_i
1af70 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20  nterrupt() call 
1af80 72 65 74 75 72 6e 73 2e 0a 2a 2f 0a 76 6f 69 64  returns..*/.void
1af90 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
1afa0 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  pt(sqlite3*);../
1afb0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
1afc0 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53  etermine If An S
1afd0 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20  QL Statement Is 
1afe0 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54  Complete.**.** T
1aff0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
1b000 65 20 75 73 65 66 75 6c 20 64 75 72 69 6e 67 20  e useful during 
1b010 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70  command-line inp
1b020 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20  ut to determine 
1b030 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  if the.** curren
1b040 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78 74  tly entered text
1b050 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61   seems to form a
1b060 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74   complete SQL st
1b070 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66  atement or.** if
1b080 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75   additional inpu
1b090 74 20 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f  t is needed befo
1b0a0 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74  re sending the t
1b0b0 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69  ext into.** SQLi
1b0c0 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20  te for parsing. 
1b0d0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
1b0e0 20 72 65 74 75 72 6e 20 31 20 69 66 20 74 68 65   return 1 if the
1b0f0 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a   input string.**
1b100 20 61 70 70 65 61 72 73 20 74 6f 20 62 65 20 61   appears to be a
1b110 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74   complete SQL st
1b120 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61  atement.  ^A sta
1b130 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64  tement is judged
1b140 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65   to be.** comple
1b150 74 65 20 69 66 20 69 74 20 65 6e 64 73 20 77 69  te if it ends wi
1b160 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74  th a semicolon t
1b170 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20  oken and is not 
1b180 61 20 70 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a  a prefix of a.**
1b190 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45   well-formed CRE
1b1a0 41 54 45 20 54 52 49 47 47 45 52 20 73 74 61 74  ATE TRIGGER stat
1b1b0 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c  ement.  ^Semicol
1b1c0 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65 6d 62  ons that are emb
1b1d0 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20  edded within.** 
1b1e0 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20  string literals 
1b1f0 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69  or quoted identi
1b200 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f  fier names or co
1b210 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a  mments are not.*
1b220 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f  * independent to
1b230 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65 20 70  kens (they are p
1b240 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e  art of the token
1b250 20 69 6e 20 77 68 69 63 68 20 74 68 65 79 20 61   in which they a
1b260 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20  re.** embedded) 
1b270 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20  and thus do not 
1b280 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61 74 65  count as a state
1b290 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e  ment terminator.
1b2a0 20 20 5e 57 68 69 74 65 73 70 61 63 65 0a 2a 2a    ^Whitespace.**
1b2b0 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68   and comments th
1b2c0 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69  at follow the fi
1b2d0 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72  nal semicolon ar
1b2e0 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a  e ignored..**.**
1b2f0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
1b300 20 72 65 74 75 72 6e 20 30 20 69 66 20 74 68 65   return 0 if the
1b310 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 69 6e   statement is in
1b320 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20 61  complete.  ^If a
1b330 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
1b340 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65  ation fails, the
1b350 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69  n SQLITE_NOMEM i
1b360 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
1b370 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
1b380 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74  s do not parse t
1b390 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
1b3a0 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e  s thus.** will n
1b3b0 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74 61 63  ot detect syntac
1b3c0 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63  tically incorrec
1b3d0 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  t SQL..**.** ^(I
1b3e0 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e 6f 74  f SQLite has not
1b3f0 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65   been initialize
1b400 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
1b410 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 70  _initialize()] p
1b420 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f  rior .** to invo
1b430 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d  king sqlite3_com
1b440 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e 20 73  plete16() then s
1b450 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
1b460 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a  e() is invoked.*
1b470 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  * automatically 
1b480 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  by sqlite3_compl
1b490 65 74 65 31 36 28 29 2e 20 20 49 66 20 74 68 61  ete16().  If tha
1b4a0 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  t initialization
1b4b0 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20   fails,.** then 
1b4c0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
1b4d0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f   from sqlite3_co
1b4e0 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c 6c 20  mplete16() will 
1b4f0 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72  be non-zero.** r
1b500 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
1b510 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
1b520 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63 6f 6d  input SQL is com
1b530 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54  plete.)^.**.** T
1b540 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c  he input to [sql
1b550 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d  ite3_complete()]
1b560 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d   must be a zero-
1b570 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54  terminated.** UT
1b580 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  F-8 string..**.*
1b590 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b  * The input to [
1b5a0 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
1b5b0 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20  16()] must be a 
1b5c0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
1b5d0 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  ** UTF-16 string
1b5e0 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20   in native byte 
1b5f0 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71  order..*/.int sq
1b600 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63  lite3_complete(c
1b610 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b  onst char *sql);
1b620 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d  .int sqlite3_com
1b630 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f  plete16(const vo
1b640 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a  id *sql);../*.**
1b650 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73   CAPI3REF: Regis
1b660 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54  ter A Callback T
1b670 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f  o Handle SQLITE_
1b680 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a 20 4b  BUSY Errors.** K
1b690 45 59 57 4f 52 44 53 3a 20 7b 62 75 73 79 2d 68  EYWORDS: {busy-h
1b6a0 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 7d  andler callback}
1b6b0 20 7b 62 75 73 79 20 68 61 6e 64 6c 65 72 7d 0a   {busy handler}.
1b6c0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
1b6d0 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  e3.**.** ^The sq
1b6e0 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
1b6f0 65 72 28 44 2c 58 2c 50 29 20 72 6f 75 74 69 6e  er(D,X,P) routin
1b700 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63  e sets a callbac
1b710 6b 20 66 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20  k function X.** 
1b720 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e  that might be in
1b730 76 6f 6b 65 64 20 77 69 74 68 20 61 72 67 75 6d  voked with argum
1b740 65 6e 74 20 50 20 77 68 65 6e 65 76 65 72 0a 2a  ent P whenever.*
1b750 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20  * an attempt is 
1b760 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73 20 61  made to access a
1b770 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20   database table 
1b780 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a  associated with.
1b790 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
1b7a0 6e 65 63 74 69 6f 6e 5d 20 44 20 77 68 65 6e 20  nection] D when 
1b7b0 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a  another thread.*
1b7c0 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73  * or process has
1b7d0 20 74 68 65 20 74 61 62 6c 65 20 6c 6f 63 6b 65   the table locke
1b7e0 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  d..** The sqlite
1b7f0 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29  3_busy_handler()
1b800 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
1b810 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 0a  ed to implement.
1b820 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ** [sqlite3_busy
1b830 5f 74 69 6d 65 6f 75 74 28 29 5d 20 61 6e 64 20  _timeout()] and 
1b840 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d  [PRAGMA busy_tim
1b850 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  eout]..**.** ^If
1b860 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   the busy callba
1b870 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  ck is NULL, then
1b880 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a   [SQLITE_BUSY].*
1b890 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d  * is returned im
1b8a0 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65  mediately upon e
1b8b0 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20  ncountering the 
1b8c0 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 62  lock.  ^If the b
1b8d0 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  usy callback.** 
1b8e0 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65  is not NULL, the
1b8f0 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d  n the callback m
1b900 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20  ight be invoked 
1b910 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e  with two argumen
1b920 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ts..**.** ^The f
1b930 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
1b940 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
1b950 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  r is a copy of t
1b960 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72  he void* pointer
1b970 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65   which.** is the
1b980 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
1b990 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  to sqlite3_busy_
1b9a0 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 65  handler().  ^The
1b9b0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
1b9c0 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 20   to.** the busy 
1b9d0 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b  handler callback
1b9e0 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
1b9f0 66 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 65  f times that the
1ba00 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61   busy handler ha
1ba10 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65  s.** been invoke
1ba20 64 20 70 72 65 76 69 6f 75 73 6c 79 20 66 6f 72  d previously for
1ba30 20 74 68 65 20 73 61 6d 65 20 6c 6f 63 6b 69 6e   the same lockin
1ba40 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68  g event.  ^If th
1ba50 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61  e.** busy callba
1ba60 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68  ck returns 0, th
1ba70 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c  en no additional
1ba80 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61   attempts are ma
1ba90 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20  de to.** access 
1baa0 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64  the database and
1bab0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 69   [SQLITE_BUSY] i
1bac0 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 74 6f  s returned.** to
1bad0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1bae0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c  ..** ^If the cal
1baf0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
1bb00 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f  n-zero, then ano
1bb10 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20  ther attempt.** 
1bb20 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73  is made to acces
1bb30 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61  s the database a
1bb40 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 65 70  nd the cycle rep
1bb50 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  eats..**.** The 
1bb60 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75  presence of a bu
1bb70 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20  sy handler does 
1bb80 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74 68  not guarantee th
1bb90 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e  at it will be in
1bba0 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68  voked.** when th
1bbb0 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74  ere is lock cont
1bbc0 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69  ention. ^If SQLi
1bbd0 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68  te determines th
1bbe0 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  at invoking the 
1bbf0 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20  busy.** handler 
1bc00 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20  could result in 
1bc10 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77  a deadlock, it w
1bc20 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64  ill go ahead and
1bc30 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
1bc40 42 55 53 59 5d 0a 2a 2a 20 74 6f 20 74 68 65 20  BUSY].** to the 
1bc50 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 6e 73 74  application inst
1bc60 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20  ead of invoking 
1bc70 74 68 65 20 0a 2a 2a 20 62 75 73 79 20 68 61 6e  the .** busy han
1bc80 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65  dler..** Conside
1bc90 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65  r a scenario whe
1bca0 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69  re one process i
1bcb0 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64  s holding a read
1bcc0 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74   lock that.** it
1bcd0 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72   is trying to pr
1bce0 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72  omote to a reser
1bcf0 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20  ved lock and.** 
1bd00 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73  a second process
1bd10 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65   is holding a re
1bd20 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74  served lock that
1bd30 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a   it is trying.**
1bd40 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61   to promote to a
1bd50 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b  n exclusive lock
1bd60 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 72 6f  .  The first pro
1bd70 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63  cess cannot proc
1bd80 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69  eed.** because i
1bd90 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20  t is blocked by 
1bda0 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74  the second and t
1bdb0 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73  he second proces
1bdc0 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63  s cannot.** proc
1bdd0 65 65 64 20 62 65 63 61 75 73 65 20 69 74 20 69  eed because it i
1bde0 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65  s blocked by the
1bdf0 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68   first.  If both
1be00 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e   processes.** in
1be10 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68 61  voke the busy ha
1be20 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20  ndlers, neither 
1be30 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72  will make any pr
1be40 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f  ogress.  Therefo
1be50 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65  re,.** SQLite re
1be60 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55  turns [SQLITE_BU
1be70 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73  SY] for the firs
1be80 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e  t process, hopin
1be90 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77  g that this.** w
1bea0 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66  ill induce the f
1beb0 69 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20  irst process to 
1bec0 72 65 6c 65 61 73 65 20 69 74 73 20 72 65 61 64  release its read
1bed0 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a   lock and allow.
1bee0 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72  ** the second pr
1bef0 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64  ocess to proceed
1bf00 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66  ..**.** ^The def
1bf10 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61  ault busy callba
1bf20 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ck is NULL..**.*
1bf30 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e  * ^(There can on
1bf40 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62  ly be a single b
1bf50 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69  usy handler defi
1bf60 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20  ned for each.** 
1bf70 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1bf80 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20  tion].  Setting 
1bf90 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c  a new busy handl
1bfa0 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a  er clears any.**
1bfb0 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20   previously set 
1bfc0 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74  handler.)^  ^Not
1bfd0 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b  e that calling [
1bfe0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
1bff0 65 6f 75 74 28 29 5d 0a 2a 2a 20 6f 72 20 65 76  eout()].** or ev
1c000 61 6c 75 61 74 69 6e 67 20 5b 50 52 41 47 4d 41  aluating [PRAGMA
1c010 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 3d 4e 5d   busy_timeout=N]
1c020 20 77 69 6c 6c 20 63 68 61 6e 67 65 20 74 68 65   will change the
1c030 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 72  .** busy handler
1c040 20 61 6e 64 20 74 68 75 73 20 63 6c 65 61 72 20   and thus clear 
1c050 61 6e 79 20 70 72 65 76 69 6f 75 73 6c 79 20 73  any previously s
1c060 65 74 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  et busy handler.
1c070 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20  .**.** The busy 
1c080 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20  callback should 
1c090 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74  not take any act
1c0a0 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66  ions which modif
1c0b0 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  y the.** databas
1c0c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
1c0d0 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75  t invoked the bu
1c0e0 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 49 6e 20  sy handler.  In 
1c0f0 6f 74 68 65 72 20 77 6f 72 64 73 2c 0a 2a 2a 20  other words,.** 
1c100 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
1c110 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e   is not reentran
1c120 74 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 74  t.  Any such act
1c130 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69  ions.** result i
1c140 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61  n undefined beha
1c150 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62  vior..** .** A b
1c160 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74  usy handler must
1c170 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64   not close the d
1c180 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1c190 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72  on.** or [prepar
1c1a0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
1c1b0 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62  at invoked the b
1c1c0 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a  usy handler..*/.
1c1d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79  int sqlite3_busy
1c1e0 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33  _handler(sqlite3
1c1f0 2a 2c 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69  *,int(*)(void*,i
1c200 6e 74 29 2c 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  nt),void*);../*.
1c210 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74  ** CAPI3REF: Set
1c220 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74 0a   A Busy Timeout.
1c230 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
1c240 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  e3.**.** ^This r
1c250 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73  outine sets a [s
1c260 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
1c270 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c  ler | busy handl
1c280 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a  er] that sleeps.
1c290 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 69  ** for a specifi
1c2a0 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d  ed amount of tim
1c2b0 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69  e when a table i
1c2c0 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20  s locked.  ^The 
1c2d0 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20  handler.** will 
1c2e0 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74  sleep multiple t
1c2f0 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65  imes until at le
1c300 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65  ast "ms" millise
1c310 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e  conds of sleepin
1c320 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75  g.** have accumu
1c330 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61  lated.  ^After a
1c340 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c  t least "ms" mil
1c350 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
1c360 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61  eping,.** the ha
1c370 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20  ndler returns 0 
1c380 77 68 69 63 68 20 63 61 75 73 65 73 20 5b 73 71  which causes [sq
1c390 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f  lite3_step()] to
1c3a0 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49   return.** [SQLI
1c3b0 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20  TE_BUSY]..**.** 
1c3c0 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f  ^Calling this ro
1c3d0 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72  utine with an ar
1c3e0 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e  gument less than
1c3f0 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72   or equal to zer
1c400 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61  o.** turns off a
1c410 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73  ll busy handlers
1c420 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20  ..**.** ^(There 
1c430 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69  can only be a si
1c440 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65  ngle busy handle
1c450 72 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  r for a particul
1c460 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ar.** [database 
1c470 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 61  connection] at a
1c480 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e  ny given moment.
1c490 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73    If another bus
1c4a0 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73  y handler.** was
1c4b0 20 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67   defined  (using
1c4c0 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68   [sqlite3_busy_h
1c4d0 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72  andler()]) prior
1c4e0 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74   to calling.** t
1c4f0 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61  his routine, tha
1c500 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e  t other busy han
1c510 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e  dler is cleared.
1c520 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  )^.**.** See als
1c530 6f 3a 20 20 5b 50 52 41 47 4d 41 20 62 75 73 79  o:  [PRAGMA busy
1c540 5f 74 69 6d 65 6f 75 74 5d 0a 2a 2f 0a 69 6e 74  _timeout].*/.int
1c550 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69   sqlite3_busy_ti
1c560 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20  meout(sqlite3*, 
1c570 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20  int ms);../*.** 
1c580 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e  CAPI3REF: Conven
1c590 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46  ience Routines F
1c5a0 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69  or Running Queri
1c5b0 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  es.** METHOD: sq
1c5c0 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 69 73  lite3.**.** This
1c5d0 20 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74   is a legacy int
1c5e0 65 72 66 61 63 65 20 74 68 61 74 20 69 73 20 70  erface that is p
1c5f0 72 65 73 65 72 76 65 64 20 66 6f 72 20 62 61 63  reserved for bac
1c600 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
1c610 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20  lity..** Use of 
1c620 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69  this interface i
1c630 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65  s not recommende
1c640 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74  d..**.** Definit
1c650 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74  ion: A <b>result
1c660 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65   table</b> is me
1c670 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 74  mory data struct
1c680 75 72 65 20 63 72 65 61 74 65 64 20 62 79 20 74  ure created by t
1c690 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67  he.** [sqlite3_g
1c6a0 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65  et_table()] inte
1c6b0 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74  rface.  A result
1c6c0 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74   table records t
1c6d0 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71  he.** complete q
1c6e0 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f  uery results fro
1c6f0 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75  m one or more qu
1c700 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  eries..**.** The
1c710 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61   table conceptua
1c720 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72  lly has a number
1c730 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c   of rows and col
1c740 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68  umns.  But.** th
1c750 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20  ese numbers are 
1c760 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 20  not part of the 
1c770 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73  result table its
1c780 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e  elf.  These.** n
1c790 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 69  umbers are obtai
1c7a0 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20  ned separately. 
1c7b0 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75   Let N be the nu
1c7c0 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20  mber of rows.** 
1c7d0 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d  and M be the num
1c7e0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a  ber of columns..
1c7f0 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  **.** A result t
1c800 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79  able is an array
1c810 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20   of pointers to 
1c820 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
1c830 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a  UTF-8 strings..*
1c840 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31  * There are (N+1
1c850 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20  )*M elements in 
1c860 74 68 65 20 61 72 72 61 79 2e 20 20 54 68 65 20  the array.  The 
1c870 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73  first M pointers
1c880 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72   point.** to zer
1c890 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
1c8a0 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61  ings that  conta
1c8b0 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20  in the names of 
1c8c0 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20  the columns..** 
1c8d0 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e  The remaining en
1c8e0 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20  tries all point 
1c8f0 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 73  to query results
1c900 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72  .  NULL values r
1c910 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c  esult.** in NULL
1c920 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20   pointers.  All 
1c930 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 65  other values are
1c940 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20   in their UTF-8 
1c950 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
1c960 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65 73  ** string repres
1c970 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75  entation as retu
1c980 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
1c990 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e  _column_text()].
1c9a0 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  .**.** A result 
1c9b0 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73  table might cons
1c9c0 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f  ist of one or mo
1c9d0 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  re memory alloca
1c9e0 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20  tions..** It is 
1c9f0 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73 73  not safe to pass
1ca00 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   a result table 
1ca10 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c  directly to [sql
1ca20 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a  ite3_free()]..**
1ca30 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
1ca40 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f  should be deallo
1ca50 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  cated using [sql
1ca60 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
1ca70 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61  )]..**.** ^(As a
1ca80 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65  n example of the
1ca90 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f   result table fo
1caa0 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20  rmat, suppose a 
1cab0 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20  query result.** 
1cac0 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  is as follows:.*
1cad0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1cae0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20  ><pre>.**       
1caf0 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41   Name        | A
1cb00 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d  ge.**        ---
1cb10 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1cb20 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41  ----.**        A
1cb30 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a  lice       | 43.
1cb40 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 20  **        Bob   
1cb50 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20        | 28.**   
1cb60 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20       Cindy      
1cb70 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c   | 21.** </pre><
1cb80 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1cb90 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 77 6f  ** There are two
1cba0 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61   column (M==2) a
1cbb0 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e  nd three rows (N
1cbc0 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a  ==3).  Thus the.
1cbd0 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  ** result table 
1cbe0 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20  has 8 entries.  
1cbf0 53 75 70 70 6f 73 65 20 74 68 65 20 72 65 73 75  Suppose the resu
1cc00 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72  lt table is stor
1cc10 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61  ed.** in an arra
1cc20 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74  y names azResult
1cc30 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74  .  Then azResult
1cc40 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74   holds this cont
1cc50 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ent:.**.** <bloc
1cc60 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1cc70 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1cc80 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b  #91;0] = "Name";
1cc90 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1cca0 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67  ult&#91;1] = "Ag
1ccb0 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
1ccc0 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20  Result&#91;2] = 
1ccd0 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20  "Alice";.**     
1cce0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1ccf0 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20  3] = "43";.**   
1cd00 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1cd10 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a  1;4] = "Bob";.**
1cd20 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1cd30 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a  &#91;5] = "28";.
1cd40 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1cd50 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e  lt&#91;6] = "Cin
1cd60 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  dy";.**        a
1cd70 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d  zResult&#91;7] =
1cd80 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e   "21";.** </pre>
1cd90 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a  </blockquote>)^.
1cda0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1cdb0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66  e3_get_table() f
1cdc0 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65  unction evaluate
1cdd0 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a  s one or more.**
1cde0 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72   semicolon-separ
1cdf0 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  ated SQL stateme
1ce00 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d  nts in the zero-
1ce10 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
1ce20 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74  .** string of it
1ce30 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  s 2nd parameter 
1ce40 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72 65  and returns a re
1ce50 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68  sult table to th
1ce60 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76  e.** pointer giv
1ce70 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61  en in its 3rd pa
1ce80 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41  rameter..**.** A
1ce90 66 74 65 72 20 74 68 65 20 61 70 70 6c 69 63 61  fter the applica
1cea0 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65  tion has finishe
1ceb0 64 20 77 69 74 68 20 74 68 65 20 72 65 73 75 6c  d with the resul
1cec0 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67  t from sqlite3_g
1ced0 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69  et_table(),.** i
1cee0 74 20 6d 75 73 74 20 70 61 73 73 20 74 68 65 20  t must pass the 
1cef0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69  result table poi
1cf00 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  nter to sqlite3_
1cf10 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20  free_table() in 
1cf20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65  order to.** rele
1cf30 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74  ase the memory t
1cf40 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64  hat was malloced
1cf50 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68  .  Because of th
1cf60 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71  e way the.** [sq
1cf70 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
1cf80 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73  happens within s
1cf90 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1cfa0 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a  (), the calling.
1cfb0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ** function must
1cfc0 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c   not try to call
1cfd0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1cfe0 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c  ] directly.  Onl
1cff0 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  y.** [sqlite3_fr
1d000 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61  ee_table()] is a
1d010 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74  ble to release t
1d020 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72  he memory proper
1d030 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a  ly and safely..*
1d040 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
1d050 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74  _get_table() int
1d060 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d  erface is implem
1d070 65 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 70  ented as a wrapp
1d080 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71  er around.** [sq
1d090 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20  lite3_exec()].  
1d0a0 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
1d0b0 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20  table() routine 
1d0c0 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63  does not have ac
1d0d0 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69  cess.** to any i
1d0e0 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72  nternal data str
1d0f0 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74  uctures of SQLit
1d100 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79  e.  It uses only
1d110 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69   the public.** i
1d120 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 64  nterface defined
1d130 20 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e   here.  As a con
1d140 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73  sequence, errors
1d150 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74   that occur in t
1d160 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61  he.** wrapper la
1d170 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74  yer outside of t
1d180 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c  he internal [sql
1d190 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c  ite3_exec()] cal
1d1a0 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66  l are not.** ref
1d1b0 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 71  lected in subseq
1d1c0 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73  uent calls to [s
1d1d0 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
1d1e0 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
1d1f0 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69  _errmsg()]..*/.i
1d200 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  nt sqlite3_get_t
1d210 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20  able(.  sqlite3 
1d220 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a  *db,          /*
1d230 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   An open databas
1d240 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
1d250 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20  r *zSql,     /* 
1d260 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61  SQL to be evalua
1d270 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ted */.  char **
1d280 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f  *pazResult,    /
1d290 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65  * Results of the
1d2a0 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20   query */.  int 
1d2b0 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20  *pnRow,         
1d2c0 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72    /* Number of r
1d2d0 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74  esult rows writt
1d2e0 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74  en here */.  int
1d2f0 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20   *pnColumn,     
1d300 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
1d310 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77  result columns w
1d320 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20  ritten here */. 
1d330 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67   char **pzErrmsg
1d340 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20         /* Error 
1d350 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65  msg written here
1d360 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69   */.);.void sqli
1d370 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63  te3_free_table(c
1d380 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a  har **result);..
1d390 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1d3a0 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67  Formatted String
1d3b0 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69   Printing Functi
1d3c0 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ons.**.** These 
1d3d0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72  routines are wor
1d3e0 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20  k-alikes of the 
1d3f0 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c  "printf()" famil
1d400 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  y of functions.*
1d410 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64  * from the stand
1d420 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a  ard C library..*
1d430 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
1d440 20 75 6e 64 65 72 73 74 61 6e 64 20 6d 6f 73 74   understand most
1d450 20 6f 66 20 74 68 65 20 63 6f 6d 6d 6f 6e 20 4b   of the common K
1d460 26 52 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  &R formatting op
1d470 74 69 6f 6e 73 2c 0a 2a 2a 20 70 6c 75 73 20 73  tions,.** plus s
1d480 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 6e  ome additional n
1d490 6f 6e 2d 73 74 61 6e 64 61 72 64 20 66 6f 72 6d  on-standard form
1d4a0 61 74 73 2c 20 64 65 74 61 69 6c 65 64 20 62 65  ats, detailed be
1d4b0 6c 6f 77 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  low..** Note tha
1d4c0 74 20 73 6f 6d 65 20 6f 66 20 74 68 65 20 6d 6f  t some of the mo
1d4d0 72 65 20 6f 62 73 63 75 72 65 20 66 6f 72 6d 61  re obscure forma
1d4e0 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 66 72  tting options fr
1d4f0 6f 6d 20 72 65 63 65 6e 74 0a 2a 2a 20 43 2d 6c  om recent.** C-l
1d500 69 62 72 61 72 79 20 73 74 61 6e 64 61 72 64 73  ibrary standards
1d510 20 61 72 65 20 6f 6d 69 74 74 65 64 20 66 72 6f   are omitted fro
1d520 6d 20 74 68 69 73 20 69 6d 70 6c 65 6d 65 6e 74  m this implement
1d530 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ation..**.** ^Th
1d540 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  e sqlite3_mprint
1d550 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  f() and sqlite3_
1d560 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69  vmprintf() routi
1d570 6e 65 73 20 77 72 69 74 65 20 74 68 65 69 72 0a  nes write their.
1d580 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20  ** results into 
1d590 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
1d5a0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
1d5b0 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  lloc()]..** The 
1d5c0 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64  strings returned
1d5d0 20 62 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f   by these two ro
1d5e0 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65  utines should be
1d5f0 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20  .** released by 
1d600 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1d610 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65  .  ^Both routine
1d620 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55  s return a.** NU
1d630 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73  LL pointer if [s
1d640 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1d650 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
1d660 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a  locate enough.**
1d670 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20   memory to hold 
1d680 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74  the resulting st
1d690 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ring..**.** ^(Th
1d6a0 65 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  e sqlite3_snprin
1d6b0 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  tf() routine is 
1d6c0 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72  similar to "snpr
1d6d0 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20  intf()" from.** 
1d6e0 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
1d6f0 69 62 72 61 72 79 2e 20 20 54 68 65 20 72 65 73  ibrary.  The res
1d700 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20 69  ult is written i
1d710 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65  nto the.** buffe
1d720 72 20 73 75 70 70 6c 69 65 64 20 61 73 20 74 68  r supplied as th
1d730 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
1d740 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73  er whose size is
1d750 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65   given by.** the
1d760 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
1d770 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  . Note that the 
1d780 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20  order of the.** 
1d790 66 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65  first two parame
1d7a0 74 65 72 73 20 69 73 20 72 65 76 65 72 73 65 64  ters is reversed
1d7b0 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29   from snprintf()
1d7c0 2e 29 5e 20 20 54 68 69 73 20 69 73 20 61 6e 0a  .)^  This is an.
1d7d0 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63  ** historical ac
1d7e0 63 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e  cident that cann
1d7f0 6f 74 20 62 65 20 66 69 78 65 64 20 77 69 74 68  ot be fixed with
1d800 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20  out breaking.** 
1d810 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
1d820 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65  ibility.  ^(Note
1d830 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74   also that sqlit
1d840 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
1d850 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
1d860 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 72  er to its buffer
1d870 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20   instead of the 
1d880 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61  number of.** cha
1d890 72 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79  racters actually
1d8a0 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68   written into th
1d8b0 65 20 62 75 66 66 65 72 2e 29 5e 20 20 57 65 20  e buffer.)^  We 
1d8c0 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68  admit that.** th
1d8d0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
1d8e0 61 63 74 65 72 73 20 77 72 69 74 74 65 6e 20 77  acters written w
1d8f0 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75  ould be a more u
1d900 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20  seful return.** 
1d910 76 61 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e  value but we can
1d920 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 69  not change the i
1d930 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
1d940 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1d950 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f  f().** now witho
1d960 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70  ut breaking comp
1d970 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a  atibility..**.**
1d980 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65   ^As long as the
1d990 20 62 75 66 66 65 72 20 73 69 7a 65 20 69 73 20   buffer size is 
1d9a0 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72  greater than zer
1d9b0 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  o, sqlite3_snpri
1d9c0 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74  ntf().** guarant
1d9d0 65 65 73 20 74 68 61 74 20 74 68 65 20 62 75 66  ees that the buf
1d9e0 66 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65  fer is always ze
1d9f0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  ro-terminated.  
1da00 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61  ^The first.** pa
1da10 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74  rameter "n" is t
1da20 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66  he total size of
1da30 20 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63   the buffer, inc
1da40 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72  luding space for
1da50 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72  .** the zero ter
1da60 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65  minator.  So the
1da70 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20   longest string 
1da80 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70  that can be comp
1da90 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65  letely.** writte
1daa0 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68  n will be n-1 ch
1dab0 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  aracters..**.** 
1dac0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 73 6e  ^The sqlite3_vsn
1dad0 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65  printf() routine
1dae0 20 69 73 20 61 20 76 61 72 61 72 67 73 20 76 65   is a varargs ve
1daf0 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  rsion of sqlite3
1db00 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a  _snprintf()..**.
1db10 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
1db20 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20  s all implement 
1db30 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20  some additional 
1db40 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70  formatting.** op
1db50 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75  tions that are u
1db60 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72  seful for constr
1db70 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65  ucting SQL state
1db80 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66  ments..** All of
1db90 20 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74   the usual print
1dba0 66 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f  f() formatting o
1dbb0 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49  ptions apply.  I
1dbc0 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72  n addition, ther
1dbd0 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22  e.** is are "%q"
1dbe0 2c 20 22 25 51 22 2c 20 22 25 77 22 20 61 6e 64  , "%Q", "%w" and
1dbf0 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a   "%z" options..*
1dc00 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f 70  *.** ^(The %q op
1dc10 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20  tion works like 
1dc20 25 73 20 69 6e 20 74 68 61 74 20 69 74 20 73 75  %s in that it su
1dc30 62 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c 2d  bstitutes a nul-
1dc40 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74  terminated.** st
1dc50 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72  ring from the ar
1dc60 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75  gument list.  Bu
1dc70 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65  t %q also double
1dc80 73 20 65 76 65 72 79 20 27 5c 27 27 20 63 68 61  s every '\'' cha
1dc90 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73  racter..** %q is
1dca0 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73   designed for us
1dcb0 65 20 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e  e inside a strin
1dcc0 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42 79  g literal.)^  By
1dcd0 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27   doubling each '
1dce0 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72  \''.** character
1dcf0 20 69 74 20 65 73 63 61 70 65 73 20 74 68 61 74   it escapes that
1dd00 20 63 68 61 72 61 63 74 65 72 20 61 6e 64 20 61   character and a
1dd10 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69  llows it to be i
1dd20 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20  nserted into.** 
1dd30 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  the string..**.*
1dd40 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61  * For example, a
1dd50 73 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67  ssume the string
1dd60 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20   variable zText 
1dd70 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73  contains text as
1dd80 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
1dd90 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1dda0 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78  >.**  char *zTex
1ddb0 74 20 3d 20 22 49 74 27 73 20 61 20 68 61 70 70  t = "It's a happ
1ddc0 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72  y day!";.** </pr
1ddd0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
1dde0 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73  **.** One can us
1ddf0 65 20 74 68 69 73 20 74 65 78 74 20 69 6e 20 61  e this text in a
1de00 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
1de10 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
1de20 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1de30 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53  re>.**  char *zS
1de40 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72  QL = sqlite3_mpr
1de50 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54  intf("INSERT INT
1de60 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27  O table VALUES('
1de70 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a  %q')", zText);.*
1de80 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  *  sqlite3_exec(
1de90 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20  db, zSQL, 0, 0, 
1dea0 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  0);.**  sqlite3_
1deb0 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c  free(zSQL);.** <
1dec0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1ded0 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65  e>.**.** Because
1dee0 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73   the %q format s
1def0 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74  tring is used, t
1df00 68 65 20 27 5c 27 27 20 63 68 61 72 61 63 74 65  he '\'' characte
1df10 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73  r in zText.** is
1df20 20 65 73 63 61 70 65 64 20 61 6e 64 20 74 68 65   escaped and the
1df30 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69   SQL generated i
1df40 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  s as follows:.**
1df50 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1df60 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54  <pre>.**  INSERT
1df70 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c   INTO table1 VAL
1df80 55 45 53 28 27 49 74 27 27 73 20 61 20 68 61 70  UES('It''s a hap
1df90 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70  py day!').** </p
1dfa0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1dfb0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63  .**.** This is c
1dfc0 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77 65 20  orrect.  Had we 
1dfd0 75 73 65 64 20 25 73 20 69 6e 73 74 65 61 64 20  used %s instead 
1dfe0 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72  of %q, the gener
1dff0 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c  ated SQL.** woul
1e000 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69  d have looked li
1e010 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ke this:.**.** <
1e020 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1e030 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f  .**  INSERT INTO
1e040 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27   table1 VALUES('
1e050 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79  It's a happy day
1e060 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  !');.** </pre></
1e070 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
1e080 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78  * This second ex
1e090 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20  ample is an SQL 
1e0a0 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41  syntax error.  A
1e0b0 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65  s a general rule
1e0c0 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61   you should.** a
1e0d0 6c 77 61 79 73 20 75 73 65 20 25 71 20 69 6e 73  lways use %q ins
1e0e0 74 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20  tead of %s when 
1e0f0 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20 69  inserting text i
1e100 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74  nto a string lit
1e110 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  eral..**.** ^(Th
1e120 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b  e %Q option work
1e130 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74  s like %q except
1e140 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69   it also adds si
1e150 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75  ngle quotes arou
1e160 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64  nd.** the outsid
1e170 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73  e of the total s
1e180 74 72 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e  tring.  Addition
1e190 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72  ally, if the par
1e1a0 61 6d 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a  ameter in the.**
1e1b0 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69   argument list i
1e1c0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
1e1d0 2c 20 25 51 20 73 75 62 73 74 69 74 75 74 65 73  , %Q substitutes
1e1e0 20 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22   the text "NULL"
1e1f0 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e   (without.** sin
1e200 67 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e 20 20  gle quotes).)^  
1e210 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c  So, for example,
1e220 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a   one could say:.
1e230 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1e240 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72  e><pre>.**  char
1e250 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33   *zSQL = sqlite3
1e260 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54  _mprintf("INSERT
1e270 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55   INTO table VALU
1e280 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b  ES(%Q)", zText);
1e290 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65  .**  sqlite3_exe
1e2a0 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30  c(db, zSQL, 0, 0
1e2b0 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  , 0);.**  sqlite
1e2c0 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a  3_free(zSQL);.**
1e2d0 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1e2e0 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ote>.**.** The c
1e2f0 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72  ode above will r
1e300 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74 20  ender a correct 
1e310 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
1e320 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72   the zSQL.** var
1e330 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68  iable even if th
1e340 65 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65  e zText variable
1e350 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
1e360 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  er..**.** ^(The 
1e370 22 25 77 22 20 66 6f 72 6d 61 74 74 69 6e 67 20  "%w" formatting 
1e380 6f 70 74 69 6f 6e 20 69 73 20 6c 69 6b 65 20 22  option is like "
1e390 25 71 22 20 65 78 63 65 70 74 20 74 68 61 74 20  %q" except that 
1e3a0 69 74 20 65 78 70 65 63 74 73 20 74 6f 0a 2a 2a  it expects to.**
1e3b0 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 77 69   be contained wi
1e3c0 74 68 69 6e 20 64 6f 75 62 6c 65 2d 71 75 6f 74  thin double-quot
1e3d0 65 73 20 69 6e 73 74 65 61 64 20 6f 66 20 73 69  es instead of si
1e3e0 6e 67 6c 65 20 71 75 6f 74 65 73 2c 20 61 6e 64  ngle quotes, and
1e3f0 20 69 74 0a 2a 2a 20 65 73 63 61 70 65 73 20 74   it.** escapes t
1e400 68 65 20 64 6f 75 62 6c 65 2d 71 75 6f 74 65 20  he double-quote 
1e410 63 68 61 72 61 63 74 65 72 20 69 6e 73 74 65 61  character instea
1e420 64 20 6f 66 20 74 68 65 20 73 69 6e 67 6c 65 2d  d of the single-
1e430 71 75 6f 74 65 0a 2a 2a 20 63 68 61 72 61 63 74  quote.** charact
1e440 65 72 2e 29 5e 20 20 54 68 65 20 22 25 77 22 20  er.)^  The "%w" 
1e450 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f  formatting optio
1e460 6e 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f  n is intended fo
1e470 72 20 73 61 66 65 6c 79 20 69 6e 73 65 72 74 69  r safely inserti
1e480 6e 67 0a 2a 2a 20 74 61 62 6c 65 20 61 6e 64 20  ng.** table and 
1e490 63 6f 6c 75 6d 6e 20 6e 61 6d 65 73 20 69 6e 74  column names int
1e4a0 6f 20 61 20 63 6f 6e 73 74 72 75 63 74 65 64 20  o a constructed 
1e4b0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  SQL statement..*
1e4c0 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22 20  *.** ^(The "%z" 
1e4d0 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f  formatting optio
1e4e0 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73  n works like "%s
1e4f0 22 20 62 75 74 20 77 69 74 68 20 74 68 65 0a 2a  " but with the.*
1e500 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20  * addition that 
1e510 61 66 74 65 72 20 74 68 65 20 73 74 72 69 6e 67  after the string
1e520 20 68 61 73 20 62 65 65 6e 20 72 65 61 64 20 61   has been read a
1e530 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a  nd copied into.*
1e540 2a 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73  * the result, [s
1e550 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69  qlite3_free()] i
1e560 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20  s called on the 
1e570 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a  input string.)^.
1e580 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  */.char *sqlite3
1e590 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63  _mprintf(const c
1e5a0 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20  har*,...);.char 
1e5b0 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74  *sqlite3_vmprint
1e5c0 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76  f(const char*, v
1e5d0 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a 73  a_list);.char *s
1e5e0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1e5f0 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20  int,char*,const 
1e600 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 63 68 61  char*, ...);.cha
1e610 72 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e 70 72  r *sqlite3_vsnpr
1e620 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63  intf(int,char*,c
1e630 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c  onst char*, va_l
1e640 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ist);../*.** CAP
1e650 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c  I3REF: Memory Al
1e660 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74  location Subsyst
1e670 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  em.**.** The SQL
1e680 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 74 68  ite core uses th
1e690 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e  ese three routin
1e6a0 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  es for all of it
1e6b0 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61  s own.** interna
1e6c0 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
1e6d0 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65  ion needs. "Core
1e6e0 22 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75  " in the previou
1e6f0 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f  s sentence.** do
1e700 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f  es not include o
1e710 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20  perating-system 
1e720 73 70 65 63 69 66 69 63 20 56 46 53 20 69 6d 70  specific VFS imp
1e730 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68  lementation.  Th
1e740 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53  e.** Windows VFS
1e750 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c   uses native mal
1e760 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29  loc() and free()
1e770 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74   for some operat
1e780 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ions..**.** ^The
1e790 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1e7a0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
1e7b0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
1e7c0 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d   block.** of mem
1e7d0 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62  ory at least N b
1e7e0 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20  ytes in length, 
1e7f0 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 70  where N is the p
1e800 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66  arameter..** ^If
1e810 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1e820 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f  ) is unable to o
1e830 62 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74  btain sufficient
1e840 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c   free.** memory,
1e850 20 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55   it returns a NU
1e860 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66  LL pointer.  ^If
1e870 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e   the parameter N
1e880 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d   to.** sqlite3_m
1e890 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20  alloc() is zero 
1e8a0 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  or negative then
1e8b0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1e8c0 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e  ) returns.** a N
1e8d0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
1e8e0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1e8f0 6d 61 6c 6c 6f 63 36 34 28 4e 29 20 72 6f 75 74  malloc64(N) rout
1e900 69 6e 65 20 77 6f 72 6b 73 20 6a 75 73 74 20 6c  ine works just l
1e910 69 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d  ike.** sqlite3_m
1e920 61 6c 6c 6f 63 28 4e 29 20 65 78 63 65 70 74 20  alloc(N) except 
1e930 74 68 61 74 20 4e 20 69 73 20 61 6e 20 75 6e 73  that N is an uns
1e940 69 67 6e 65 64 20 36 34 2d 62 69 74 20 69 6e 74  igned 64-bit int
1e950 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20  eger instead.** 
1e960 6f 66 20 61 20 73 69 67 6e 65 64 20 33 32 2d 62  of a signed 32-b
1e970 69 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a  it integer..**.*
1e980 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74  * ^Calling sqlit
1e990 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20 61  e3_free() with a
1e9a0 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75   pointer previou
1e9b0 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  sly returned.** 
1e9c0 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  by sqlite3_mallo
1e9d0 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  c() or sqlite3_r
1e9e0 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65  ealloc() release
1e9f0 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f  s that memory so
1ea00 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68  .** that it migh
1ea10 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e 54  t be reused.  ^T
1ea20 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  he sqlite3_free(
1ea30 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20  ) routine is.** 
1ea40 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61  a no-op if is ca
1ea50 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c  lled with a NULL
1ea60 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69   pointer.  Passi
1ea70 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ng a NULL pointe
1ea80 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  r.** to sqlite3_
1ea90 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65  free() is harmle
1eaa0 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67  ss.  After being
1eab0 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a   freed, memory.*
1eac0 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72  * should neither
1ead0 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69   be read nor wri
1eae0 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64  tten.  Even read
1eaf0 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66  ing previously f
1eb00 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d  reed.** memory m
1eb10 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61  ight result in a
1eb20 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61   segmentation fa
1eb30 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76  ult or other sev
1eb40 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65  ere error..** Me
1eb50 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c  mory corruption,
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 2c 20 6f 72 20 6f 74 68 65 72 20  fault, or other 
1eb80 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20  severe error.** 
1eb90 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20  might result if 
1eba0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69  sqlite3_free() i
1ebb0 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  s called with a 
1ebc0 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  non-NULL pointer
1ebd0 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74   that.** was not
1ebe0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73   obtained from s
1ebf0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1ec00 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  or sqlite3_reall
1ec10 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  oc()..**.** ^The
1ec20 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1ec30 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20  (X,N) interface 
1ec40 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69  attempts to resi
1ec50 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65  ze a.** prior me
1ec60 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1ec70 58 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74  X to be at least
1ec80 20 4e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66   N bytes..** ^If
1ec90 20 74 68 65 20 58 20 70 61 72 61 6d 65 74 65 72   the X parameter
1eca0 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
1ecb0 6c 6f 63 28 58 2c 4e 29 0a 2a 2a 20 69 73 20 61  loc(X,N).** is a
1ecc0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
1ecd0 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72 20  en its behavior 
1ece0 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20  is identical to 
1ecf0 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74  calling.** sqlit
1ed00 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 2e 0a 2a 2a  e3_malloc(N)..**
1ed10 20 5e 49 66 20 74 68 65 20 4e 20 70 61 72 61 6d   ^If the N param
1ed20 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
1ed30 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 73 20  realloc(X,N) is 
1ed40 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74  zero or.** negat
1ed50 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 65 68  ive then the beh
1ed60 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79  avior is exactly
1ed70 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c   the same as cal
1ed80 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ling.** sqlite3_
1ed90 66 72 65 65 28 58 29 2e 0a 2a 2a 20 5e 73 71 6c  free(X)..** ^sql
1eda0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e  ite3_realloc(X,N
1edb0 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  ) returns a poin
1edc0 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20  ter to a memory 
1edd0 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66  allocation.** of
1ede0 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
1edf0 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c  s in size or NUL
1ee00 4c 20 69 66 20 69 6e 73 75 66 66 69 63 69 65 6e  L if insufficien
1ee10 74 20 6d 65 6d 6f 72 79 20 69 73 20 61 76 61 69  t memory is avai
1ee20 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20  lable..** ^If M 
1ee30 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  is the size of t
1ee40 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
1ee50 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c  ion, then min(N,
1ee60 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74  M) bytes.** of t
1ee70 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
1ee80 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69  ion are copied i
1ee90 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e  nto the beginnin
1eea0 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 74 75  g of buffer retu
1eeb0 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74  rned.** by sqlit
1eec0 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20  e3_realloc(X,N) 
1eed0 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c  and the prior al
1eee0 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65  location is free
1eef0 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  d..** ^If sqlite
1ef00 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72  3_realloc(X,N) r
1ef10 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 20  eturns NULL and 
1ef20 4e 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20 74  N is positive, t
1ef30 68 65 6e 20 74 68 65 0a 2a 2a 20 70 72 69 6f 72  hen the.** prior
1ef40 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 6e   allocation is n
1ef50 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20  ot freed..**.** 
1ef60 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61  ^The sqlite3_rea
1ef70 6c 6c 6f 63 36 34 28 58 2c 4e 29 20 69 6e 74 65  lloc64(X,N) inte
1ef80 72 66 61 63 65 73 20 77 6f 72 6b 73 20 74 68 65  rfaces works the
1ef90 20 73 61 6d 65 20 61 73 0a 2a 2a 20 73 71 6c 69   same as.** sqli
1efa0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
1efb0 20 65 78 63 65 70 74 20 74 68 61 74 20 4e 20 69   except that N i
1efc0 73 20 61 20 36 34 2d 62 69 74 20 75 6e 73 69 67  s a 64-bit unsig
1efd0 6e 65 64 20 69 6e 74 65 67 65 72 20 69 6e 73 74  ned integer inst
1efe0 65 61 64 0a 2a 2a 20 6f 66 20 61 20 33 32 2d 62  ead.** of a 32-b
1eff0 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
1f000 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 58 20 69  r..**.** ^If X i
1f010 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  s a memory alloc
1f020 61 74 69 6f 6e 20 70 72 65 76 69 6f 75 73 6c 79  ation previously
1f030 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73   obtained from s
1f040 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c  qlite3_malloc(),
1f050 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
1f060 6f 63 36 34 28 29 2c 20 73 71 6c 69 74 65 33 5f  oc64(), sqlite3_
1f070 72 65 61 6c 6c 6f 63 28 29 2c 20 6f 72 20 73 71  realloc(), or sq
1f080 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28  lite3_realloc64(
1f090 29 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  ), then.** sqlit
1f0a0 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 75  e3_msize(X) retu
1f0b0 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20  rns the size of 
1f0c0 74 68 61 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  that memory allo
1f0d0 63 61 74 69 6f 6e 20 69 6e 20 62 79 74 65 73 2e  cation in bytes.
1f0e0 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 20 72  .** ^The value r
1f0f0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
1f100 65 33 5f 6d 73 69 7a 65 28 58 29 20 6d 69 67 68  e3_msize(X) migh
1f110 74 20 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e  t be larger than
1f120 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f   the number.** o
1f130 66 20 62 79 74 65 73 20 72 65 71 75 65 73 74 65  f bytes requeste
1f140 64 20 77 68 65 6e 20 58 20 77 61 73 20 61 6c 6c  d when X was all
1f150 6f 63 61 74 65 64 2e 20 20 5e 49 66 20 58 20 69  ocated.  ^If X i
1f160 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
1f170 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   then.** sqlite3
1f180 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 75 72 6e  _msize(X) return
1f190 73 20 7a 65 72 6f 2e 20 20 49 66 20 58 20 70 6f  s zero.  If X po
1f1a0 69 6e 74 73 20 74 6f 20 73 6f 6d 65 74 68 69 6e  ints to somethin
1f1b0 67 20 74 68 61 74 20 69 73 20 6e 6f 74 0a 2a 2a  g that is not.**
1f1c0 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
1f1d0 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  f memory allocat
1f1e0 69 6f 6e 2c 20 6f 72 20 69 66 20 69 74 20 70 6f  ion, or if it po
1f1f0 69 6e 74 73 20 74 6f 20 61 20 66 6f 72 6d 65 72  ints to a former
1f200 6c 79 0a 2a 2a 20 76 61 6c 69 64 20 6d 65 6d 6f  ly.** valid memo
1f210 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 68  ry allocation th
1f220 61 74 20 68 61 73 20 6e 6f 77 20 62 65 65 6e 20  at has now been 
1f230 66 72 65 65 64 2c 20 74 68 65 6e 20 74 68 65 20  freed, then the 
1f240 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 73  behavior.** of s
1f250 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20  qlite3_msize(X) 
1f260 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  is undefined and
1f270 20 70 6f 73 73 69 62 6c 79 20 68 61 72 6d 66 75   possibly harmfu
1f280 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65  l..**.** ^The me
1f290 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 79  mory returned by
1f2a0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1f2b0 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  ), sqlite3_reall
1f2c0 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  oc(),.** sqlite3
1f2d0 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 61 6e 64  _malloc64(), and
1f2e0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1f2f0 36 34 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79  64().** is alway
1f300 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20  s aligned to at 
1f310 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74 65 20  least an 8 byte 
1f320 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f 20  boundary, or to 
1f330 61 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f 75 6e  a.** 4 byte boun
1f340 64 61 72 79 20 69 66 20 74 68 65 20 5b 53 51 4c  dary if the [SQL
1f350 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47 4e  ITE_4_BYTE_ALIGN
1f360 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69  ED_MALLOC] compi
1f370 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f  le-time.** optio
1f380 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  n is used..**.**
1f390 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69   In SQLite versi
1f3a0 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35  on 3.5.0 and 3.5
1f3b0 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69  .1, it was possi
1f3c0 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a  ble to define.**
1f3d0 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54   the SQLITE_OMIT
1f3e0 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49  _MEMORY_ALLOCATI
1f3f0 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63  ON which would c
1f400 61 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69  ause the built-i
1f410 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  n.** implementat
1f420 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75  ion of these rou
1f430 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74  tines to be omit
1f440 74 65 64 2e 20 20 54 68 61 74 20 63 61 70 61 62  ted.  That capab
1f450 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c  ility.** is no l
1f460 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20  onger provided. 
1f470 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d   Only built-in m
1f480 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73  emory allocators
1f490 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a   can be used..**
1f4a0 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51 4c  .** Prior to SQL
1f4b0 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e  ite version 3.7.
1f4c0 31 30 2c 20 74 68 65 20 57 69 6e 64 6f 77 73 20  10, the Windows 
1f4d0 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79  OS interface lay
1f4e0 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 68 65  er called.** the
1f4f0 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29   system malloc()
1f500 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72 65   and free() dire
1f510 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72  ctly when conver
1f520 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65  ting.** filename
1f530 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55 54  s between the UT
1f540 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65  F-8 encoding use
1f550 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61  d by SQLite.** a
1f560 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c 65  nd whatever file
1f570 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73  name encoding is
1f580 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61 72   used by the par
1f590 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a  ticular Windows.
1f5a0 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e  ** installation.
1f5b0 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74    Memory allocat
1f5c0 69 6f 6e 20 65 72 72 6f 72 73 20 77 65 72 65 20  ion errors were 
1f5d0 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a  detected, but.**
1f5e0 20 74 68 65 79 20 77 65 72 65 20 72 65 70 6f 72   they were repor
1f5f0 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c  ted back as [SQL
1f600 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72  ITE_CANTOPEN] or
1f610 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  .** [SQLITE_IOER
1f620 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b  R] rather than [
1f630 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a  SQLITE_NOMEM]..*
1f640 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72  *.** The pointer
1f650 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73   arguments to [s
1f660 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61  qlite3_free()] a
1f670 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  nd [sqlite3_real
1f680 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62  loc()].** must b
1f690 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72  e either NULL or
1f6a0 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f   else pointers o
1f6b0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70  btained from a p
1f6c0 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69  rior.** invocati
1f6d0 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  on of [sqlite3_m
1f6e0 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c  alloc()] or [sql
1f6f0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20  ite3_realloc()] 
1f700 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74  that have.** not
1f710 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73   yet been releas
1f720 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70  ed..**.** The ap
1f730 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
1f740 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 74 65  ot read or write
1f750 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20   any part of.** 
1f760 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72  a block of memor
1f770 79 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62  y after it has b
1f780 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69  een released usi
1f790 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  ng.** [sqlite3_f
1f7a0 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  ree()] or [sqlit
1f7b0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  e3_realloc()]..*
1f7c0 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
1f7d0 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69  malloc(int);.voi
1f7e0 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  d *sqlite3_mallo
1f7f0 63 36 34 28 73 71 6c 69 74 65 33 5f 75 69 6e 74  c64(sqlite3_uint
1f800 36 34 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74  64);.void *sqlit
1f810 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a  e3_realloc(void*
1f820 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71  , int);.void *sq
1f830 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28  lite3_realloc64(
1f840 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75  void*, sqlite3_u
1f850 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c  int64);.void sql
1f860 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29  ite3_free(void*)
1f870 3b 0a 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  ;.sqlite3_uint64
1f880 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 76   sqlite3_msize(v
1f890 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
1f8a0 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
1f8b0 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74  llocator Statist
1f8c0 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ics.**.** SQLite
1f8d0 20 70 72 6f 76 69 64 65 73 20 74 68 65 73 65 20   provides these 
1f8e0 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66  two interfaces f
1f8f0 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20  or reporting on 
1f900 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66  the status.** of
1f910 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61   the [sqlite3_ma
1f920 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65  lloc()], [sqlite
1f930 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b  3_free()], and [
1f940 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1f950 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20  )].** routines, 
1f960 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62  which form the b
1f970 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
1f980 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73  llocation subsys
1f990 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  tem..**.** ^The 
1f9a0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1f9b0 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20  used()] routine 
1f9c0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
1f9d0 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f  er of bytes.** o
1f9e0 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74  f memory current
1f9f0 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 28  ly outstanding (
1fa00 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74  malloced but not
1fa10 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65   freed)..** ^The
1fa20 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1fa30 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 72 6f  _highwater()] ro
1fa40 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
1fa50 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c  e maximum.** val
1fa60 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  ue of [sqlite3_m
1fa70 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 73 69  emory_used()] si
1fa80 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77 61 74  nce the high-wat
1fa90 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c  er mark.** was l
1faa0 61 73 74 20 72 65 73 65 74 2e 20 20 5e 54 68 65  ast reset.  ^The
1fab0 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
1fac0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d   by [sqlite3_mem
1fad0 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a  ory_used()] and.
1fae0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  ** [sqlite3_memo
1faf0 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
1fb00 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72  include any over
1fb10 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 20 62 79  head.** added by
1fb20 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69   SQLite in its i
1fb30 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
1fb40 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1fb50 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20  ()],.** but not 
1fb60 6f 76 65 72 68 65 61 64 20 61 64 64 65 64 20 62  overhead added b
1fb70 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72 6c  y the any underl
1fb80 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 72  ying system libr
1fb90 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ary.** routines 
1fba0 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61  that [sqlite3_ma
1fbb0 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c  lloc()] may call
1fbc0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d  ..**.** ^The mem
1fbd0 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d  ory high-water m
1fbe0 61 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20  ark is reset to 
1fbf0 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75  the current valu
1fc00 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  e of.** [sqlite3
1fc10 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
1fc20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74  if and only if t
1fc30 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  he parameter to.
1fc40 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  ** [sqlite3_memo
1fc50 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
1fc60 69 73 20 74 72 75 65 2e 20 20 5e 54 68 65 20 76  is true.  ^The v
1fc70 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a  alue returned.**
1fc80 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d   by [sqlite3_mem
1fc90 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 31 29  ory_highwater(1)
1fca0 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d 77 61  ] is the high-wa
1fcb0 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f  ter mark.** prio
1fcc0 72 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e 0a  r to the reset..
1fcd0 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  */.sqlite3_int64
1fce0 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
1fcf0 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69  used(void);.sqli
1fd00 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
1fd10 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
1fd20 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67  er(int resetFlag
1fd30 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1fd40 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f  EF: Pseudo-Rando
1fd50 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74  m Number Generat
1fd60 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  or.**.** SQLite 
1fd70 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d  contains a high-
1fd80 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72  quality pseudo-r
1fd90 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e  andom number gen
1fda0 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73  erator (PRNG) us
1fdb0 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20  ed to.** select 
1fdc0 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20  random [ROWID | 
1fdd0 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73  ROWIDs] when ins
1fde0 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72  erting new recor
1fdf0 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20  ds into a table 
1fe00 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20  that.** already 
1fe10 75 73 65 73 20 74 68 65 20 6c 61 72 67 65 73 74  uses the largest
1fe20 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44   possible [ROWID
1fe30 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73 20  ].  The PRNG is 
1fe40 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a  also used for.**
1fe50 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61   the build-in ra
1fe60 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f  ndom() and rando
1fe70 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63  mblob() SQL func
1fe80 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74  tions.  This int
1fe90 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a  erface allows.**
1fea0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f   applications to
1feb0 20 61 63 63 65 73 73 20 74 68 65 20 73 61 6d 65   access the same
1fec0 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20   PRNG for other 
1fed0 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20  purposes..**.** 
1fee0 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20  ^A call to this 
1fef0 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e  routine stores N
1ff00 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d   bytes of random
1ff10 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72  ness into buffer
1ff20 20 50 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 70 61   P..** ^The P pa
1ff30 72 61 6d 65 74 65 72 20 63 61 6e 20 62 65 20 61  rameter can be a
1ff40 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
1ff50 2a 0a 2a 2a 20 5e 49 66 20 74 68 69 73 20 72 6f  *.** ^If this ro
1ff60 75 74 69 6e 65 20 68 61 73 20 6e 6f 74 20 62 65  utine has not be
1ff70 65 6e 20 70 72 65 76 69 6f 75 73 6c 79 20 63 61  en previously ca
1ff80 6c 6c 65 64 20 6f 72 20 69 66 20 74 68 65 20 70  lled or if the p
1ff90 72 65 76 69 6f 75 73 0a 2a 2a 20 63 61 6c 6c 20  revious.** call 
1ffa0 68 61 64 20 4e 20 6c 65 73 73 20 74 68 61 6e 20  had N less than 
1ffb0 6f 6e 65 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f  one or a NULL po
1ffc0 69 6e 74 65 72 20 66 6f 72 20 50 2c 20 74 68 65  inter for P, the
1ffd0 6e 20 74 68 65 20 50 52 4e 47 20 69 73 0a 2a 2a  n the PRNG is.**
1ffe0 20 73 65 65 64 65 64 20 75 73 69 6e 67 20 72 61   seeded using ra
1fff0 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65  ndomness obtaine
20000 64 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64  d from the xRand
20010 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66  omness method of
20020 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 20  .** the default 
20030 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
20040 6a 65 63 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ject..** ^If the
20050 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74   previous call t
20060 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68  o this routine h
20070 61 64 20 61 6e 20 4e 20 6f 66 20 31 20 6f 72 20  ad an N of 1 or 
20080 6d 6f 72 65 20 61 6e 64 20 61 0a 2a 2a 20 6e 6f  more and a.** no
20090 6e 2d 4e 55 4c 4c 20 50 20 74 68 65 6e 20 74 68  n-NULL P then th
200a0 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e  e pseudo-randomn
200b0 65 73 73 20 69 73 20 67 65 6e 65 72 61 74 65 64  ess is generated
200c0 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61  .** internally a
200d0 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75  nd without recou
200e0 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  rse to the [sqli
200f0 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d  te3_vfs] xRandom
20100 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a  ness.** method..
20110 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
20120 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e  randomness(int N
20130 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a  , void *P);../*.
20140 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d  ** CAPI3REF: Com
20150 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72  pile-Time Author
20160 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b  ization Callback
20170 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
20180 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ite3.**.** ^This
20190 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65   routine registe
201a0 72 73 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72  rs an authorizer
201b0 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61   callback with a
201c0 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b   particular.** [
201d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
201e0 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69  ion], supplied i
201f0 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
20200 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75  ment..** ^The au
20210 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
20220 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20  k is invoked as 
20230 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61  SQL statements a
20240 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65  re being compile
20250 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33  d.** by [sqlite3
20260 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69  _prepare()] or i
20270 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c  ts variants [sql
20280 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
20290 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
202a0 70 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64  prepare16()] and
202b0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
202c0 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41 74 20  e16_v2()].  ^At 
202d0 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74  various.** point
202e0 73 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d  s during the com
202f0 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73  pilation process
20300 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65  , as logic is be
20310 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74  ing created.** t
20320 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75  o perform variou
20330 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61  s actions, the a
20340 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
20350 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f  ck is invoked to
20360 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65  .** see if those
20370 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c   actions are all
20380 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75 74 68  owed.  ^The auth
20390 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
203a0 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e  should.** return
203b0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20   [SQLITE_OK] to 
203c0 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e  allow the action
203d0 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  , [SQLITE_IGNORE
203e0 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68  ] to disallow th
203f0 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63  e.** specific ac
20400 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74  tion but allow t
20410 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
20420 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20   to continue to 
20430 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20  be.** compiled, 
20440 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  or [SQLITE_DENY]
20450 20 74 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e   to cause the en
20460 74 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65  tire SQL stateme
20470 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65  nt to be.** reje
20480 63 74 65 64 20 77 69 74 68 20 61 6e 20 65 72 72  cted with an err
20490 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61 75 74  or.  ^If the aut
204a0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
204b0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20   returns.** any 
204c0 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e  value other than
204d0 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
204e0 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f  , [SQLITE_OK], o
204f0 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a  r [SQLITE_DENY].
20500 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c  ** then the [sql
20510 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
20520 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74  )] or equivalent
20530 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67   call that trigg
20540 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68  ered.** the auth
20550 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c  orizer will fail
20560 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d   with an error m
20570 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68  essage..**.** Wh
20580 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
20590 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
205a0 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20  OK], that means 
205b0 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a  the operation.**
205c0 20 72 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b   requested is ok
205d0 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63 61 6c  .  ^When the cal
205e0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
205f0 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65  QLITE_DENY], the
20600 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
20610 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71  pare_v2()] or eq
20620 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68  uivalent call th
20630 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65  at triggered the
20640 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77  .** authorizer w
20650 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e  ill fail with an
20660 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65   error message e
20670 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a  xplaining that.*
20680 2a 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69  * access is deni
20690 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ed. .**.** ^The 
206a0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
206b0 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  to the authorize
206c0 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20  r callback is a 
206d0 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72  copy of the thir
206e0 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74  d.** parameter t
206f0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65  o the sqlite3_se
20700 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69  t_authorizer() i
20710 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65 20 73  nterface. ^The s
20720 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a  econd parameter.
20730 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  ** to the callba
20740 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ck is an integer
20750 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20   [SQLITE_COPY | 
20760 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61  action code] tha
20770 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74  t specifies.** t
20780 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63  he particular ac
20790 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f  tion to be autho
207a0 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 69 72  rized. ^The thir
207b0 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 20  d through sixth 
207c0 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f  parameters.** to
207d0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72   the callback ar
207e0 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  e zero-terminate
207f0 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 63  d strings that c
20800 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61  ontain additiona
20810 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 62 6f  l.** details abo
20820 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f  ut the action to
20830 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a   be authorized..
20840 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63  **.** ^If the ac
20850 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51  tion code is [SQ
20860 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e  LITE_READ].** an
20870 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  d the callback r
20880 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49  eturns [SQLITE_I
20890 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a  GNORE] then the.
208a0 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
208b0 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e  tement] statemen
208c0 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64  t is constructed
208d0 20 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a   to substitute.*
208e0 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69  * a NULL value i
208f0 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74  n place of the t
20900 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74  able column that
20910 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62   would have.** b
20920 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c  een read if [SQL
20930 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e  ITE_OK] had been
20940 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20   returned.  The 
20950 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a  [SQLITE_IGNORE].
20960 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65  ** return can be
20970 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e   used to deny an
20980 20 75 6e 74 72 75 73 74 65 64 20 75 73 65 72 20   untrusted user 
20990 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69  access to indivi
209a0 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20  dual.** columns 
209b0 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e  of a table..** ^
209c0 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f  If the action co
209d0 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 45  de is [SQLITE_DE
209e0 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20 63 61  LETE] and the ca
209f0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a  llback returns.*
20a00 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  * [SQLITE_IGNORE
20a10 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45 4c 45  ] then the [DELE
20a20 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70 72  TE] operation pr
20a30 6f 63 65 65 64 73 20 62 75 74 20 74 68 65 0a 2a  oceeds but the.*
20a40 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69  * [truncate opti
20a50 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69 73  mization] is dis
20a60 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f  abled and all ro
20a70 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 69  ws are deleted i
20a80 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a  ndividually..**.
20a90 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72  ** An authorizer
20aa0 20 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73   is used when [s
20ab0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c  qlite3_prepare |
20ac0 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53   preparing].** S
20ad0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72  QL statements fr
20ae0 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  om an untrusted 
20af0 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72  source, to ensur
20b00 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 73  e that the SQL s
20b10 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20  tatements.** do 
20b20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65 73  not try to acces
20b30 73 20 64 61 74 61 20 74 68 65 79 20 61 72 65 20  s data they are 
20b40 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73  not allowed to s
20b50 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79  ee, or that they
20b60 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74   do not.** try t
20b70 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69  o execute malici
20b80 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74  ous statements t
20b90 68 61 74 20 64 61 6d 61 67 65 20 74 68 65 20 64  hat damage the d
20ba0 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a  atabase.  For.**
20bb0 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70   example, an app
20bc0 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c  lication may all
20bd0 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74  ow a user to ent
20be0 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20  er arbitrary.** 
20bf0 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20  SQL queries for 
20c00 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20  evaluation by a 
20c10 64 61 74 61 62 61 73 65 2e 20 20 42 75 74 20 74  database.  But t
20c20 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
20c30 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20  oes.** not want 
20c40 74 68 65 20 75 73 65 72 20 74 6f 20 62 65 20 61  the user to be a
20c50 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69  ble to make arbi
20c60 74 72 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f  trary changes to
20c70 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
20c80 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72  .  An authorizer
20c90 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70   could then be p
20ca0 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c  ut in place whil
20cb0 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e  e the.** user-en
20cc0 74 65 72 65 64 20 53 51 4c 20 69 73 20 62 65 69  tered SQL is bei
20cd0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
20ce0 61 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20  are | prepared] 
20cf0 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77  that.** disallow
20d00 73 20 65 76 65 72 79 74 68 69 6e 67 20 65 78 63  s everything exc
20d10 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  ept [SELECT] sta
20d20 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41  tements..**.** A
20d30 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
20d40 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73   need to process
20d50 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73   SQL from untrus
20d60 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d  ted sources.** m
20d70 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64  ight also consid
20d80 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f  er lowering reso
20d90 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e  urce limits usin
20da0 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  g [sqlite3_limit
20db0 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74  ()].** and limit
20dc0 69 6e 67 20 64 61 74 61 62 61 73 65 20 73 69 7a  ing database siz
20dd0 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78  e using the [max
20de0 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52  _page_count] [PR
20df0 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69  AGMA].** in addi
20e00 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e  tion to using an
20e10 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a   authorizer..**.
20e20 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67  ** ^(Only a sing
20e30 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  le authorizer ca
20e40 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e  n be in place on
20e50 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
20e60 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74  ection.** at a t
20e70 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20  ime.  Each call 
20e80 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  to sqlite3_set_a
20e90 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69  uthorizer overri
20ea0 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69  des the.** previ
20eb0 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69  ous call.)^  ^Di
20ec0 73 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72  sable the author
20ed0 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69  izer by installi
20ee0 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61  ng a NULL callba
20ef0 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  ck..** The autho
20f00 72 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65  rizer is disable
20f10 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  d by default..**
20f20 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a  .** The authoriz
20f30 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74  er callback must
20f40 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67   not do anything
20f50 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66   that will modif
20f60 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  y.** the databas
20f70 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
20f80 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 75  t invoked the au
20f90 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
20fa0 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  k..** Note that 
20fb0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
20fc0 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
20fd0 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68  te3_step()] both
20fe0 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a   modify their.**
20ff0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
21000 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65  tions for the me
21010 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79  aning of "modify
21020 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72  " in this paragr
21030 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e  aph..**.** ^When
21040 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
21050 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64 20  e_v2()] is used 
21060 74 6f 20 70 72 65 70 61 72 65 20 61 20 73 74 61  to prepare a sta
21070 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73  tement, the.** s
21080 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20 62  tatement might b
21090 65 20 72 65 2d 70 72 65 70 61 72 65 64 20 64 75  e re-prepared du
210a0 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74  ring [sqlite3_st
210b0 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20 0a  ep()] due to a .
210c0 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  ** schema change
210d0 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61 70  .  Hence, the ap
210e0 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
210f0 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
21100 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74 68  .** correct auth
21110 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
21120 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 65  remains in place
21130 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71 6c   during the [sql
21140 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a  ite3_step()]..**
21150 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 74  .** ^Note that t
21160 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
21170 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
21180 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a  d only during.**
21190 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
211a0 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  e()] or its vari
211b0 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61  ants.  Authoriza
211c0 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70  tion is not.** p
211d0 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20  erformed during 
211e0 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61  statement evalua
211f0 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33  tion in [sqlite3
21200 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73  _step()], unless
21210 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20 69 6e  .** as stated in
21220 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 70 61   the previous pa
21230 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74 65 33  ragraph, sqlite3
21240 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a  _step() invokes.
21250 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  ** sqlite3_prepa
21260 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70 72 65  re_v2() to repre
21270 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74  pare a statement
21280 20 61 66 74 65 72 20 61 20 73 63 68 65 6d 61 20   after a schema 
21290 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20 73  change..*/.int s
212a0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
212b0 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33  rizer(.  sqlite3
212c0 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68  *,.  int (*xAuth
212d0 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
212e0 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
212f0 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
21300 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20  const char*),.  
21310 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a  void *pUserData.
21320 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
21330 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52  EF: Authorizer R
21340 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a  eturn Codes.**.*
21350 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  * The [sqlite3_s
21360 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20  et_authorizer | 
21370 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
21380 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75  ack function] mu
21390 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74  st.** return eit
213a0 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  her [SQLITE_OK] 
213b0 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  or one of these 
213c0 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e  two constants in
213d0 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67   order.** to sig
213e0 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68  nal SQLite wheth
213f0 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63  er or not the ac
21400 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65  tion is permitte
21410 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b  d.  See the.** [
21420 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
21430 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69  orizer | authori
21440 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  zer documentatio
21450 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  n] for additiona
21460 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  l.** information
21470 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
21480 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20  t SQLITE_IGNORE 
21490 69 73 20 61 6c 73 6f 20 75 73 65 64 20 61 73 20  is also used as 
214a0 61 20 5b 63 6f 6e 66 6c 69 63 74 20 72 65 73 6f  a [conflict reso
214b0 6c 75 74 69 6f 6e 20 6d 6f 64 65 5d 0a 2a 2a 20  lution mode].** 
214c0 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 74 68  returned from th
214d0 65 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  e [sqlite3_vtab_
214e0 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69  on_conflict()] i
214f0 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65  nterface..*/.#de
21500 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59  fine SQLITE_DENY
21510 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20     1   /* Abort 
21520 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
21530 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  t with an error 
21540 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
21550 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20  E_IGNORE 2   /* 
21560 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65  Don't allow acce
21570 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65  ss, but don't ge
21580 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20  nerate an error 
21590 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
215a0 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41  EF: Authorizer A
215b0 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a  ction Codes.**.*
215c0 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  * The [sqlite3_s
215d0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d  et_authorizer()]
215e0 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73   interface regis
215f0 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20  ters a callback 
21600 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74  function.** that
21610 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61   is invoked to a
21620 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e  uthorize certain
21630 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61   SQL statement a
21640 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20  ctions.  The.** 
21650 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
21660 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
21670 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63   is an integer c
21680 6f 64 65 20 74 68 61 74 20 73 70 65 63 69 66 69  ode that specifi
21690 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f  es.** what actio
216a0 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f  n is being autho
216b0 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72  rized.  These ar
216c0 65 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 63  e the integer ac
216d0 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a  tion codes that.
216e0 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ** the authorize
216f0 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62  r callback may b
21700 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  e passed..**.** 
21710 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64  These action cod
21720 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79  e values signify
21730 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70   what kind of op
21740 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65  eration is to be
21750 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20  .** authorized. 
21760 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68   The 3rd and 4th
21770 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74   parameters to t
21780 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e  he authorization
21790 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  .** callback fun
217a0 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61  ction will be pa
217b0 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c  rameters or NULL
217c0 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68   depending on wh
217d0 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  ich of these.** 
217e0 63 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73  codes is used as
217f0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
21800 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35 74  meter.  ^(The 5t
21810 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
21820 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72  he.** authorizer
21830 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65   callback is the
21840 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
21850 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22  abase ("main", "
21860 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20  temp",.** etc.) 
21870 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e  if applicable.)^
21880 20 20 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d    ^The 6th param
21890 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68  eter to the auth
218a0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a  orizer callback.
218b0 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ** is the name o
218c0 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74  f the inner-most
218d0 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77   trigger or view
218e0 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73   that is respons
218f0 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  ible for.** the 
21900 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f  access attempt o
21910 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61  r NULL if this a
21920 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73  ccess attempt is
21930 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a   directly from.*
21940 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20  * top-level SQL 
21950 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a  code..*/./******
21960 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
21970 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
21980 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a  ***** 3rd ******
21990 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a  ****** 4th *****
219a0 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20  ******/.#define 
219b0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e  SQLITE_CREATE_IN
219c0 44 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20  DEX          1  
219d0 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
219e0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
219f0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
21a00 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42  QLITE_CREATE_TAB
21a10 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20  LE          2   
21a20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
21a30 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
21a40 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
21a50 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
21a60 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f  _INDEX     3   /
21a70 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
21a80 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
21a90 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
21aa0 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
21ab0 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a  TABLE     4   /*
21ac0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
21ad0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
21ae0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
21af0 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54  TE_CREATE_TEMP_T
21b00 52 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20  RIGGER   5   /* 
21b10 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
21b20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
21b30 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
21b40 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49  E_CREATE_TEMP_VI
21b50 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56  EW      6   /* V
21b60 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
21b70 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
21b80 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
21b90 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20  _CREATE_TRIGGER 
21ba0 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72         7   /* Tr
21bb0 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
21bc0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
21bd0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
21be0 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20  CREATE_VIEW     
21bf0 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65        8   /* Vie
21c00 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
21c10 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
21c20 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
21c30 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20  ELETE           
21c40 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c       9   /* Tabl
21c50 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
21c60 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
21c70 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
21c80 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20  OP_INDEX        
21c90 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78     10   /* Index
21ca0 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
21cb0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
21cc0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
21cd0 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  P_TABLE         
21ce0 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20    11   /* Table 
21cf0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
21d00 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
21d10 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
21d20 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20  _TEMP_INDEX     
21d30 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   12   /* Index N
21d40 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
21d50 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
21d60 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
21d70 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20  TEMP_TABLE      
21d80 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  13   /* Table Na
21d90 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
21da0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
21db0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
21dc0 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31  EMP_TRIGGER    1
21dd0 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  4   /* Trigger N
21de0 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
21df0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
21e00 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
21e10 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35  MP_VIEW       15
21e20 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
21e30 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
21e40 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
21e50 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49   SQLITE_DROP_TRI
21e60 47 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20  GGER         16 
21e70 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
21e80 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
21e90 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
21ea0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57  SQLITE_DROP_VIEW
21eb0 20 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20              17  
21ec0 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
21ed0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
21ee0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
21ef0 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20  QLITE_INSERT    
21f00 20 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20             18   
21f10 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
21f20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
21f30 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
21f40 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20  LITE_PRAGMA     
21f50 20 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f            19   /
21f60 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20  * Pragma Name   
21f70 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c    1st arg or NUL
21f80 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  L */.#define SQL
21f90 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20  ITE_READ        
21fa0 20 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a           20   /*
21fb0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
21fc0 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20   Column Name    
21fd0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
21fe0 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20  TE_SELECT       
21ff0 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20          21   /* 
22000 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
22010 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
22020 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22030 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20  E_TRANSACTION   
22040 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f         22   /* O
22050 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e  peration       N
22060 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
22070 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22080 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20  _UPDATE         
22090 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61        23   /* Ta
220a0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f  ble Name      Co
220b0 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f  lumn Name     */
220c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
220d0 41 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20  ATTACH          
220e0 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c       24   /* Fil
220f0 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c  ename        NUL
22100 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
22110 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
22120 45 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20  ETACH           
22130 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61      25   /* Data
22140 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c  base Name   NULL
22150 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
22160 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c  define SQLITE_AL
22170 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20  TER_TABLE       
22180 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62     26   /* Datab
22190 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65  ase Name   Table
221a0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
221b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49  efine SQLITE_REI
221c0 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 20  NDEX            
221d0 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20    27   /* Index 
221e0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
221f0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
22200 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c  fine SQLITE_ANAL
22210 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20  YZE             
22220 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   28   /* Table N
22230 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
22240 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
22250 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
22260 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20  E_VTABLE        
22270 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  29   /* Table Na
22280 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e  me      Module N
22290 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
222a0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56  ne SQLITE_DROP_V
222b0 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 33  TABLE          3
222c0 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  0   /* Table Nam
222d0 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61  e      Module Na
222e0 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
222f0 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f  e SQLITE_FUNCTIO
22300 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 33 31  N             31
22310 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20     /* NULL      
22320 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e        Function N
22330 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  ame   */.#define
22340 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e   SQLITE_SAVEPOIN
22350 54 20 20 20 20 20 20 20 20 20 20 20 20 33 32 20  T            32 
22360 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20    /* Operation  
22370 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e       Savepoint N
22380 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ame  */.#define 
22390 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20  SQLITE_COPY     
223a0 20 20 20 20 20 20 20 20 20 20 20 20 20 30 20 20               0  
223b0 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73   /* No longer us
223c0 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
223d0 4c 49 54 45 5f 52 45 43 55 52 53 49 56 45 20 20  LITE_RECURSIVE  
223e0 20 20 20 20 20 20 20 20 20 20 33 33 20 20 20 2f            33   /
223f0 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20  * NULL          
22400 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
22410 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    */../*.** CAPI
22420 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e  3REF: Tracing An
22430 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63  d Profiling Func
22440 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  tions.** METHOD:
22450 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54   sqlite3.**.** T
22460 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
22470 65 20 64 65 70 72 65 63 61 74 65 64 2e 20 55 73  e deprecated. Us
22480 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74  e the [sqlite3_t
22490 72 61 63 65 5f 76 32 28 29 5d 20 69 6e 74 65 72  race_v2()] inter
224a0 66 61 63 65 0a 2a 2a 20 69 6e 73 74 65 61 64 20  face.** instead 
224b0 6f 66 20 74 68 65 20 72 6f 75 74 69 6e 65 73 20  of the routines 
224c0 64 65 73 63 72 69 62 65 64 20 68 65 72 65 2e 0a  described here..
224d0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
224e0 69 6e 65 73 20 72 65 67 69 73 74 65 72 20 63 61  ines register ca
224f0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73  llback functions
22500 20 74 68 61 74 20 63 61 6e 20 62 65 20 75 73 65   that can be use
22510 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67  d for.** tracing
22520 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74   and profiling t
22530 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20  he execution of 
22540 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
22550 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62  **.** ^The callb
22560 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
22570 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74  istered by sqlit
22580 65 33 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e  e3_trace() is in
22590 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69  voked at.** vari
225a0 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61  ous times when a
225b0 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
225c0 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20  is being run by 
225d0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
225e0 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
225f0 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61  3_trace() callba
22600 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69  ck is invoked wi
22610 74 68 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65  th a UTF-8 rende
22620 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53  ring of the.** S
22630 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  QL statement tex
22640 74 20 61 73 20 74 68 65 20 73 74 61 74 65 6d 65  t as the stateme
22650 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 20  nt first begins 
22660 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28  executing..** ^(
22670 41 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74  Additional sqlit
22680 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62  e3_trace() callb
22690 61 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72  acks might occur
226a0 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69 67  .** as each trig
226b0 67 65 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d  gered subprogram
226c0 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68   is entered.  Th
226d0 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20  e callbacks for 
226e0 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74  triggers.** cont
226f0 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20  ain a UTF-8 SQL 
22700 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65  comment that ide
22710 6e 74 69 66 69 65 73 20 74 68 65 20 74 72 69 67  ntifies the trig
22720 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  ger.)^.**.** The
22730 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53   [SQLITE_TRACE_S
22740 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69  IZE_LIMIT] compi
22750 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 63  le-time option c
22760 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6c 69  an be used to li
22770 6d 69 74 0a 2a 2a 20 74 68 65 20 6c 65 6e 67 74  mit.** the lengt
22780 68 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72 61  h of [bound para
22790 6d 65 74 65 72 5d 20 65 78 70 61 6e 73 69 6f 6e  meter] expansion
227a0 20 69 6e 20 74 68 65 20 6f 75 74 70 75 74 20 6f   in the output o
227b0 66 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  f sqlite3_trace(
227c0 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61  )..**.** ^The ca
227d0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
227e0 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71  registered by sq
227f0 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20  lite3_profile() 
22800 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73  is invoked.** as
22810 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d   each SQL statem
22820 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e  ent finishes.  ^
22830 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c  The profile call
22840 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a  back contains.**
22850 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74   the original st
22860 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64  atement text and
22870 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20   an estimate of 
22880 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a  wall-clock time.
22890 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74  ** of how long t
228a0 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  hat statement to
228b0 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65  ok to run.  ^The
228c0 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63   profile callbac
228d0 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e 20  k.** time is in 
228e0 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63  units of nanosec
228f0 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72 20 74 68  onds, however th
22900 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d  e current implem
22910 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f  entation.** is o
22920 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f 66 20 6d  nly capable of m
22930 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c  illisecond resol
22940 75 74 69 6f 6e 20 73 6f 20 74 68 65 20 73 69 78  ution so the six
22950 20 6c 65 61 73 74 20 73 69 67 6e 69 66 69 63 61   least significa
22960 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e 20  nt.** digits in 
22970 74 68 65 20 74 69 6d 65 20 61 72 65 20 6d 65 61  the time are mea
22980 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75 74 75 72  ningless.  Futur
22990 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
229a0 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72  Lite.** might pr
229b0 6f 76 69 64 65 20 67 72 65 61 74 65 72 20 72 65  ovide greater re
229c0 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20  solution on the 
229d0 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61 63  profiler callbac
229e0 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74  k.  The.** sqlit
229f0 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 66 75 6e  e3_profile() fun
22a00 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65  ction is conside
22a10 72 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c  red experimental
22a20 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65   and is.** subje
22a30 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20  ct to change in 
22a40 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  future versions 
22a50 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51  of SQLite..*/.SQ
22a60 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
22a70 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72  void *sqlite3_tr
22a80 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20  ace(sqlite3*,.  
22a90 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76   void(*xTrace)(v
22aa0 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  oid*,const char*
22ab0 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54  ), void*);.SQLIT
22ac0 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69  E_DEPRECATED voi
22ad0 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  d *sqlite3_profi
22ae0 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20  le(sqlite3*,.   
22af0 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28  void(*xProfile)(
22b00 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72  void*,const char
22b10 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  *,sqlite3_uint64
22b20 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
22b30 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20  * CAPI3REF: SQL 
22b40 54 72 61 63 65 20 45 76 65 6e 74 20 43 6f 64 65  Trace Event Code
22b50 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53  s.** KEYWORDS: S
22b60 51 4c 49 54 45 5f 54 52 41 43 45 0a 2a 2a 0a 2a  QLITE_TRACE.**.*
22b70 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
22b80 73 20 69 64 65 6e 74 69 66 79 20 63 6c 61 73 73  s identify class
22b90 65 73 20 6f 66 20 65 76 65 6e 74 73 20 74 68 61  es of events tha
22ba0 74 20 63 61 6e 20 62 65 20 6d 6f 6e 69 74 6f 72  t can be monitor
22bb0 65 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 20  ed.** using the 
22bc0 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76  [sqlite3_trace_v
22bd0 32 28 29 5d 20 74 72 61 63 69 6e 67 20 6c 6f 67  2()] tracing log
22be0 69 63 2e 20 20 54 68 65 20 74 68 69 72 64 20 61  ic.  The third a
22bf0 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73  rgument.** to [s
22c00 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28  qlite3_trace_v2(
22c10 29 5d 20 69 73 20 61 6e 20 4f 52 2d 65 64 20 63  )] is an OR-ed c
22c20 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 20 6f 6e  ombination of on
22c30 65 20 6f 72 20 6d 6f 72 65 20 6f 66 0a 2a 2a 20  e or more of.** 
22c40 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f  the following co
22c50 6e 73 74 61 6e 74 73 2e 20 20 5e 54 68 65 20 66  nstants.  ^The f
22c60 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
22c70 20 74 68 65 20 74 72 61 63 65 20 63 61 6c 6c 62   the trace callb
22c80 61 63 6b 0a 2a 2a 20 69 73 20 6f 6e 65 20 6f 66  ack.** is one of
22c90 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63   the following c
22ca0 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  onstants..**.** 
22cb0 4e 65 77 20 74 72 61 63 69 6e 67 20 63 6f 6e 73  New tracing cons
22cc0 74 61 6e 74 73 20 6d 61 79 20 62 65 20 61 64 64  tants may be add
22cd0 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
22ce0 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20  eases..**.** ^A 
22cf0 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 68  trace callback h
22d00 61 73 20 66 6f 75 72 20 61 72 67 75 6d 65 6e 74  as four argument
22d10 73 3a 20 78 43 61 6c 6c 62 61 63 6b 28 54 2c 43  s: xCallback(T,C
22d20 2c 50 2c 58 29 2e 0a 2a 2a 20 5e 54 68 65 20 54  ,P,X)..** ^The T
22d30 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65   argument is one
22d40 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72 20   of the integer 
22d50 74 79 70 65 20 63 6f 64 65 73 20 61 62 6f 76 65  type codes above
22d60 2e 0a 2a 2a 20 5e 54 68 65 20 43 20 61 72 67 75  ..** ^The C argu
22d70 6d 65 6e 74 20 69 73 20 61 20 63 6f 70 79 20 6f  ment is a copy o
22d80 66 20 74 68 65 20 63 6f 6e 74 65 78 74 20 70 6f  f the context po
22d90 69 6e 74 65 72 20 70 61 73 73 65 64 20 69 6e 20  inter passed in 
22da0 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68  as the.** fourth
22db0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71   argument to [sq
22dc0 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29  lite3_trace_v2()
22dd0 5d 2e 0a 2a 2a 20 54 68 65 20 50 20 61 6e 64 20  ]..** The P and 
22de0 58 20 61 72 67 75 6d 65 6e 74 73 20 61 72 65 20  X arguments are 
22df0 70 6f 69 6e 74 65 72 73 20 77 68 6f 73 65 20 6d  pointers whose m
22e00 65 61 6e 69 6e 67 73 20 64 65 70 65 6e 64 20 6f  eanings depend o
22e10 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  n T..**.** <dl>.
22e20 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43  ** [[SQLITE_TRAC
22e30 45 5f 53 54 4d 54 5d 5d 20 3c 64 74 3e 53 51 4c  E_STMT]] <dt>SQL
22e40 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 3c 2f  ITE_TRACE_STMT</
22e50 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53  dt>.** <dd>^An S
22e60 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54  QLITE_TRACE_STMT
22e70 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
22e80 6f 6b 65 64 20 77 68 65 6e 20 61 20 70 72 65 70  oked when a prep
22e90 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a  ared statement.*
22ea0 2a 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 72  * first begins r
22eb0 75 6e 6e 69 6e 67 20 61 6e 64 20 70 6f 73 73 69  unning and possi
22ec0 62 6c 79 20 61 74 20 6f 74 68 65 72 20 74 69 6d  bly at other tim
22ed0 65 73 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a  es during the.**
22ee0 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68   execution of th
22ef0 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
22f00 6d 65 6e 74 2c 20 73 75 63 68 20 61 73 20 61 74  ment, such as at
22f10 20 74 68 65 20 73 74 61 72 74 20 6f 66 20 65 61   the start of ea
22f20 63 68 0a 2a 2a 20 74 72 69 67 67 65 72 20 73 75  ch.** trigger su
22f30 62 70 72 6f 67 72 61 6d 2e 20 5e 54 68 65 20 50  bprogram. ^The P
22f40 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
22f50 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ointer to the.**
22f60 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
22f70 6d 65 6e 74 5d 2e 20 5e 54 68 65 20 58 20 61 72  ment]. ^The X ar
22f80 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
22f90 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67 20  ter to a string 
22fa0 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20  which.** is the 
22fb0 75 6e 65 78 70 61 6e 64 65 64 20 53 51 4c 20 74  unexpanded SQL t
22fc0 65 78 74 20 6f 66 20 74 68 65 20 70 72 65 70 61  ext of the prepa
22fd0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 72  red statement or
22fe0 20 61 6e 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20   an SQL comment 
22ff0 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74  .** that indicat
23000 65 73 20 74 68 65 20 69 6e 76 6f 63 61 74 69 6f  es the invocatio
23010 6e 20 6f 66 20 61 20 74 72 69 67 67 65 72 2e 20  n of a trigger. 
23020 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 63   ^The callback c
23030 61 6e 20 63 6f 6d 70 75 74 65 0a 2a 2a 20 74 68  an compute.** th
23040 65 20 73 61 6d 65 20 74 65 78 74 20 74 68 61 74  e same text that
23050 20 77 6f 75 6c 64 20 68 61 76 65 20 62 65 65 6e   would have been
23060 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
23070 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33   legacy [sqlite3
23080 5f 74 72 61 63 65 28 29 5d 0a 2a 2a 20 69 6e 74  _trace()].** int
23090 65 72 66 61 63 65 20 62 79 20 75 73 69 6e 67 20  erface by using 
230a0 74 68 65 20 58 20 61 72 67 75 6d 65 6e 74 20 77  the X argument w
230b0 68 65 6e 20 58 20 62 65 67 69 6e 73 20 77 69 74  hen X begins wit
230c0 68 20 22 2d 2d 22 20 61 6e 64 20 69 6e 76 6f 6b  h "--" and invok
230d0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
230e0 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 50 29 5d  expanded_sql(P)]
230f0 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a   otherwise..**.*
23100 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45  * [[SQLITE_TRACE
23110 5f 50 52 4f 46 49 4c 45 5d 5d 20 3c 64 74 3e 53  _PROFILE]] <dt>S
23120 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46  QLITE_TRACE_PROF
23130 49 4c 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ILE</dt>.** <dd>
23140 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45  ^An SQLITE_TRACE
23150 5f 50 52 4f 46 49 4c 45 20 63 61 6c 6c 62 61 63  _PROFILE callbac
23160 6b 20 70 72 6f 76 69 64 65 73 20 61 70 70 72 6f  k provides appro
23170 78 69 6d 61 74 65 6c 79 20 74 68 65 20 73 61 6d  ximately the sam
23180 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  e.** information
23190 20 61 73 20 69 73 20 70 72 6f 76 69 64 65 64 20   as is provided 
231a0 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
231b0 70 72 6f 66 69 6c 65 28 29 5d 20 63 61 6c 6c 62  profile()] callb
231c0 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 61  ack..** ^The P a
231d0 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
231e0 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 70 72 65  nter to the [pre
231f0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
23200 20 61 6e 64 20 74 68 65 0a 2a 2a 20 58 20 61 72   and the.** X ar
23210 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f  gument points to
23220 20 61 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65   a 64-bit intege
23230 72 20 77 68 69 63 68 20 69 73 20 74 68 65 20 65  r which is the e
23240 73 74 69 6d 61 74 65 64 20 6f 66 0a 2a 2a 20 74  stimated of.** t
23250 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6e 61 6e  he number of nan
23260 6f 73 65 63 6f 6e 64 20 74 68 61 74 20 74 68 65  osecond that the
23270 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
23280 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e  ent took to run.
23290 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  .** ^The SQLITE_
232a0 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 20 63 61  TRACE_PROFILE ca
232b0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
232c0 64 20 77 68 65 6e 20 74 68 65 20 73 74 61 74 65  d when the state
232d0 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 0a 2a  ment finishes..*
232e0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52  *.** [[SQLITE_TR
232f0 41 43 45 5f 52 4f 57 5d 5d 20 3c 64 74 3e 53 51  ACE_ROW]] <dt>SQ
23300 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 3c 2f  LITE_TRACE_ROW</
23310 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53  dt>.** <dd>^An S
23320 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 20  QLITE_TRACE_ROW 
23330 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
23340 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 70  ked whenever a p
23350 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65  repared.** state
23360 6d 65 6e 74 20 67 65 6e 65 72 61 74 65 73 20 61  ment generates a
23370 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 72   single row of r
23380 65 73 75 6c 74 2e 20 20 0a 2a 2a 20 5e 54 68 65  esult.  .** ^The
23390 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61   P argument is a
233a0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
233b0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
233c0 65 6e 74 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20  ent] and the.** 
233d0 58 20 61 72 67 75 6d 65 6e 74 20 69 73 20 75 6e  X argument is un
233e0 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  used..**.** [[SQ
233f0 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45  LITE_TRACE_CLOSE
23400 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52  ]] <dt>SQLITE_TR
23410 41 43 45 5f 43 4c 4f 53 45 3c 2f 64 74 3e 0a 2a  ACE_CLOSE</dt>.*
23420 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45  * <dd>^An SQLITE
23430 5f 54 52 41 43 45 5f 43 4c 4f 53 45 20 63 61 6c  _TRACE_CLOSE cal
23440 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
23450 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65   when a database
23460 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63  .** connection c
23470 6c 6f 73 65 73 2e 0a 2a 2a 20 5e 54 68 65 20 50  loses..** ^The P
23480 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
23490 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64  ointer to the [d
234a0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
234b0 6f 6e 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e  on] object.** an
234c0 64 20 74 68 65 20 58 20 61 72 67 75 6d 65 6e 74  d the X argument
234d0 20 69 73 20 75 6e 75 73 65 64 2e 0a 2a 2a 20 3c   is unused..** <
234e0 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
234f0 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d  SQLITE_TRACE_STM
23500 54 20 20 20 20 20 20 20 30 78 30 31 0a 23 64 65  T       0x01.#de
23510 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43  fine SQLITE_TRAC
23520 45 5f 50 52 4f 46 49 4c 45 20 20 20 20 30 78 30  E_PROFILE    0x0
23530 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
23540 5f 54 52 41 43 45 5f 52 4f 57 20 20 20 20 20 20  _TRACE_ROW      
23550 20 20 30 78 30 34 0a 23 64 65 66 69 6e 65 20 53    0x04.#define S
23560 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53  QLITE_TRACE_CLOS
23570 45 20 20 20 20 20 20 30 78 30 38 0a 0a 2f 2a 0a  E      0x08../*.
23580 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c  ** CAPI3REF: SQL
23590 20 54 72 61 63 65 20 48 6f 6f 6b 0a 2a 2a 20 4d   Trace Hook.** M
235a0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
235b0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
235c0 33 5f 74 72 61 63 65 5f 76 32 28 44 2c 4d 2c 58  3_trace_v2(D,M,X
235d0 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  ,P) interface re
235e0 67 69 73 74 65 72 73 20 61 20 74 72 61 63 65 20  gisters a trace 
235f0 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63  callback.** func
23600 74 69 6f 6e 20 58 20 61 67 61 69 6e 73 74 20 5b  tion X against [
23610 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
23620 69 6f 6e 5d 20 44 2c 20 75 73 69 6e 67 20 70 72  ion] D, using pr
23630 6f 70 65 72 74 79 20 6d 61 73 6b 20 4d 0a 2a 2a  operty mask M.**
23640 20 61 6e 64 20 63 6f 6e 74 65 78 74 20 70 6f 69   and context poi
23650 6e 74 65 72 20 50 2e 20 20 5e 49 66 20 74 68 65  nter P.  ^If the
23660 20 58 20 63 61 6c 6c 62 61 63 6b 20 69 73 0a 2a   X callback is.*
23670 2a 20 4e 55 4c 4c 20 6f 72 20 69 66 20 74 68 65  * NULL or if the
23680 20 4d 20 6d 61 73 6b 20 69 73 20 7a 65 72 6f 2c   M mask is zero,
23690 20 74 68 65 6e 20 74 72 61 63 69 6e 67 20 69 73   then tracing is
236a0 20 64 69 73 61 62 6c 65 64 2e 20 20 54 68 65 0a   disabled.  The.
236b0 2a 2a 20 4d 20 61 72 67 75 6d 65 6e 74 20 73 68  ** M argument sh
236c0 6f 75 6c 64 20 62 65 20 74 68 65 20 62 69 74 77  ould be the bitw
236d0 69 73 65 20 4f 52 2d 65 64 20 63 6f 6d 62 69 6e  ise OR-ed combin
236e0 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 7a 65 72 6f  ation of.** zero
236f0 20 6f 72 20 6d 6f 72 65 20 5b 53 51 4c 49 54 45   or more [SQLITE
23700 5f 54 52 41 43 45 5d 20 63 6f 6e 73 74 61 6e 74  _TRACE] constant
23710 73 2e 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 63  s..**.** ^Each c
23720 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 73 71  all to either sq
23730 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 6f 72  lite3_trace() or
23740 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76   sqlite3_trace_v
23750 32 28 29 20 6f 76 65 72 72 69 64 65 73 20 0a 2a  2() overrides .*
23760 2a 20 28 63 61 6e 63 65 6c 73 29 20 61 6e 79 20  * (cancels) any 
23770 70 72 69 6f 72 20 63 61 6c 6c 73 20 74 6f 20 73  prior calls to s
23780 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 6f  qlite3_trace() o
23790 72 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f  r sqlite3_trace_
237a0 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  v2()..**.** ^The
237b0 20 58 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69   X callback is i
237c0 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20  nvoked whenever 
237d0 61 6e 79 20 6f 66 20 74 68 65 20 65 76 65 6e 74  any of the event
237e0 73 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20  s identified by 
237f0 0a 2a 2a 20 6d 61 73 6b 20 4d 20 6f 63 63 75 72  .** mask M occur
23800 2e 20 20 5e 54 68 65 20 69 6e 74 65 67 65 72 20  .  ^The integer 
23810 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f  return value fro
23820 6d 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  m the callback i
23830 73 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 69  s currently.** i
23840 67 6e 6f 72 65 64 2c 20 74 68 6f 75 67 68 20 74  gnored, though t
23850 68 69 73 20 6d 61 79 20 63 68 61 6e 67 65 20 69  his may change i
23860 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
23870 73 2e 20 20 43 61 6c 6c 62 61 63 6b 0a 2a 2a 20  s.  Callback.** 
23880 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
23890 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 7a 65  should return ze
238a0 72 6f 20 74 6f 20 65 6e 73 75 72 65 20 66 75 74  ro to ensure fut
238b0 75 72 65 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  ure compatibilit
238c0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 74 72 61 63  y..**.** ^A trac
238d0 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  e callback is in
238e0 76 6f 6b 65 64 20 77 69 74 68 20 66 6f 75 72 20  voked with four 
238f0 61 72 67 75 6d 65 6e 74 73 3a 20 63 61 6c 6c 62  arguments: callb
23900 61 63 6b 28 54 2c 43 2c 50 2c 58 29 2e 0a 2a 2a  ack(T,C,P,X)..**
23910 20 5e 54 68 65 20 54 20 61 72 67 75 6d 65 6e 74   ^The T argument
23920 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b   is one of the [
23930 53 51 4c 49 54 45 5f 54 52 41 43 45 5d 0a 2a 2a  SQLITE_TRACE].**
23940 20 63 6f 6e 73 74 61 6e 74 73 20 74 6f 20 69 6e   constants to in
23950 64 69 63 61 74 65 20 77 68 79 20 74 68 65 20 63  dicate why the c
23960 61 6c 6c 62 61 63 6b 20 77 61 73 20 69 6e 76 6f  allback was invo
23970 6b 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 43 20 61  ked..** ^The C a
23980 72 67 75 6d 65 6e 74 20 69 73 20 61 20 63 6f 70  rgument is a cop
23990 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 78 74  y of the context
239a0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 54 68 65   pointer..** The
239b0 20 50 20 61 6e 64 20 58 20 61 72 67 75 6d 65 6e   P and X argumen
239c0 74 73 20 61 72 65 20 70 6f 69 6e 74 65 72 73 20  ts are pointers 
239d0 77 68 6f 73 65 20 6d 65 61 6e 69 6e 67 73 20 64  whose meanings d
239e0 65 70 65 6e 64 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a  epend on T..**.*
239f0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72  * The sqlite3_tr
23a00 61 63 65 5f 76 32 28 29 20 69 6e 74 65 72 66 61  ace_v2() interfa
23a10 63 65 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74  ce is intended t
23a20 6f 20 72 65 70 6c 61 63 65 20 74 68 65 20 6c 65  o replace the le
23a30 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
23a40 65 73 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63  es [sqlite3_trac
23a50 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
23a60 33 5f 70 72 6f 66 69 6c 65 28 29 5d 2c 20 62 6f  3_profile()], bo
23a70 74 68 20 6f 66 20 77 68 69 63 68 0a 2a 2a 20 61  th of which.** a
23a80 72 65 20 64 65 70 72 65 63 61 74 65 64 2e 0a 2a  re deprecated..*
23a90 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72  /.int sqlite3_tr
23aa0 61 63 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  ace_v2(.  sqlite
23ab0 33 2a 2c 0a 20 20 75 6e 73 69 67 6e 65 64 20 75  3*,.  unsigned u
23ac0 4d 61 73 6b 2c 0a 20 20 69 6e 74 28 2a 78 43 61  Mask,.  int(*xCa
23ad0 6c 6c 62 61 63 6b 29 28 75 6e 73 69 67 6e 65 64  llback)(unsigned
23ae0 2c 76 6f 69 64 2a 2c 76 6f 69 64 2a 2c 76 6f 69  ,void*,void*,voi
23af0 64 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 43 74  d*),.  void *pCt
23b00 78 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  x.);../*.** CAPI
23b10 33 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67  3REF: Query Prog
23b20 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a  ress Callbacks.*
23b30 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
23b40 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  3.**.** ^The sql
23b50 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61  ite3_progress_ha
23b60 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69  ndler(D,N,X,P) i
23b70 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20  nterface causes 
23b80 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  the callback.** 
23b90 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65  function X to be
23ba0 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69   invoked periodi
23bb0 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e  cally during lon
23bc0 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20  g running calls 
23bd0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  to.** [sqlite3_e
23be0 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  xec()], [sqlite3
23bf0 5f 73 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71  _step()] and [sq
23c00 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
23c10 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61  )] for.** databa
23c20 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e  se connection D.
23c30 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65    An example use
23c40 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74   for this.** int
23c50 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65  erface is to kee
23c60 70 20 61 20 47 55 49 20 75 70 64 61 74 65 64 20  p a GUI updated 
23c70 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71  during a large q
23c80 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  uery..**.** ^The
23c90 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20   parameter P is 
23ca0 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61  passed through a
23cb0 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d  s the only param
23cc0 65 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20  eter to the .** 
23cd0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
23ce0 6e 20 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d  n X.  ^The param
23cf0 65 74 65 72 20 4e 20 69 73 20 74 68 65 20 61 70  eter N is the ap
23d00 70 72 6f 78 69 6d 61 74 65 20 6e 75 6d 62 65 72  proximate number
23d10 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c   of .** [virtual
23d20 20 6d 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63   machine instruc
23d30 74 69 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 20  tions] that are 
23d40 65 76 61 6c 75 61 74 65 64 20 62 65 74 77 65 65  evaluated betwee
23d50 6e 20 73 75 63 63 65 73 73 69 76 65 0a 2a 2a 20  n successive.** 
23d60 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74  invocations of t
23d70 68 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e 20 20  he callback X.  
23d80 5e 49 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68  ^If N is less th
23d90 61 6e 20 6f 6e 65 20 74 68 65 6e 20 74 68 65 20  an one then the 
23da0 70 72 6f 67 72 65 73 73 0a 2a 2a 20 68 61 6e 64  progress.** hand
23db0 6c 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 2e  ler is disabled.
23dc0 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73  .**.** ^Only a s
23dd0 69 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68  ingle progress h
23de0 61 6e 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65  andler may be de
23df0 66 69 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d  fined at one tim
23e00 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61  e per.** [databa
23e10 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20  se connection]; 
23e20 73 65 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72  setting a new pr
23e30 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63  ogress handler c
23e40 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c  ancels the.** ol
23e50 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67  d one.  ^Setting
23e60 20 70 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20   parameter X to 
23e70 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68  NULL disables th
23e80 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
23e90 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67  er..** ^The prog
23ea0 72 65 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20  ress handler is 
23eb0 61 6c 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79  also disabled by
23ec0 20 73 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20   setting N to a 
23ed0 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68  value less.** th
23ee0 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  an 1..**.** ^If 
23ef0 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c  the progress cal
23f00 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
23f10 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72  n-zero, the oper
23f20 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65  ation is.** inte
23f30 72 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 66  rrupted.  This f
23f40 65 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 73  eature can be us
23f50 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
23f60 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75  a.** "Cancel" bu
23f70 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72  tton on a GUI pr
23f80 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f  ogress dialog bo
23f90 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f  x..**.** The pro
23fa0 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61  gress handler ca
23fb0 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20  llback must not 
23fc0 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
23fd0 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
23fe0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
23ff0 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
24000 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65 73  oked the progres
24010 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f  s handler..** No
24020 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  te that [sqlite3
24030 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
24040 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  nd [sqlite3_step
24050 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20  ()] both modify 
24060 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73  their.** databas
24070 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
24080 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
24090 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
240a0 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
240b0 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
240c0 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72  progress_handler
240d0 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20  (sqlite3*, int, 
240e0 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76  int(*)(void*), v
240f0 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
24100 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20  PI3REF: Opening 
24110 41 20 4e 65 77 20 44 61 74 61 62 61 73 65 20 43  A New Database C
24120 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 43 4f 4e  onnection.** CON
24130 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65  STRUCTOR: sqlite
24140 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  3.**.** ^These r
24150 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20  outines open an 
24160 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20  SQLite database 
24170 66 69 6c 65 20 61 73 20 73 70 65 63 69 66 69 65  file as specifie
24180 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 66 69 6c  d by the .** fil
24190 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20  ename argument. 
241a0 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72  ^The filename ar
241b0 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70  gument is interp
241c0 72 65 74 65 64 20 61 73 20 55 54 46 2d 38 20 66  reted as UTF-8 f
241d0 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  or.** sqlite3_op
241e0 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  en() and sqlite3
241f0 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61  _open_v2() and a
24200 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20  s UTF-16 in the 
24210 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f  native byte.** o
24220 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33  rder for sqlite3
24230 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b  _open16(). ^(A [
24240 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
24250 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75  ion] handle is u
24260 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e  sually.** return
24270 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65  ed in *ppDb, eve
24280 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63  n if an error oc
24290 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20  curs.  The only 
242a0 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61  exception is tha
242b0 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69  t.** if SQLite i
242c0 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  s unable to allo
242d0 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68  cate memory to h
242e0 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33  old the [sqlite3
242f0 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e  ] object,.** a N
24300 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74  ULL will be writ
24310 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69  ten into *ppDb i
24320 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e  nstead of a poin
24330 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ter to the [sqli
24340 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29  te3].** object.)
24350 5e 20 5e 28 49 66 20 74 68 65 20 64 61 74 61 62  ^ ^(If the datab
24360 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61  ase is opened (a
24370 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73  nd/or created) s
24380 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65  uccessfully, the
24390 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  n.** [SQLITE_OK]
243a0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f   is returned.  O
243b0 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72  therwise an [err
243c0 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
243d0 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20  rned.)^ ^The.** 
243e0 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
243f0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65  )] or [sqlite3_e
24400 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69  rrmsg16()] routi
24410 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  nes can be used 
24420 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20  to obtain.** an 
24430 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65  English language
24440 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20   description of 
24450 74 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77  the error follow
24460 69 6e 67 20 61 20 66 61 69 6c 75 72 65 20 6f 66  ing a failure of
24470 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73   any.** of the s
24480 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f  qlite3_open() ro
24490 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  utines..**.** ^T
244a0 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64  he default encod
244b0 69 6e 67 20 77 69 6c 6c 20 62 65 20 55 54 46 2d  ing will be UTF-
244c0 38 20 66 6f 72 20 64 61 74 61 62 61 73 65 73 20  8 for databases 
244d0 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a  created using.**
244e0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
244f0 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
24500 76 32 28 29 2e 20 20 5e 54 68 65 20 64 65 66 61  v2().  ^The defa
24510 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72  ult encoding for
24520 20 64 61 74 61 62 61 73 65 73 0a 2a 2a 20 63 72   databases.** cr
24530 65 61 74 65 64 20 75 73 69 6e 67 20 73 71 6c 69  eated using sqli
24540 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 77 69 6c  te3_open16() wil
24550 6c 20 62 65 20 55 54 46 2d 31 36 20 69 6e 20 74  l be UTF-16 in t
24560 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  he native byte o
24570 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74  rder..**.** Whet
24580 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72  her or not an er
24590 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20  ror occurs when 
245a0 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65  it is opened, re
245b0 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63  sources.** assoc
245c0 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b  iated with the [
245d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
245e0 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75  ion] handle shou
245f0 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64 20 62  ld be released b
24600 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20  y.** passing it 
24610 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  to [sqlite3_clos
24620 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20  e()] when it is 
24630 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72  no longer requir
24640 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
24650 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
24660 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20  interface works 
24670 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65  like sqlite3_ope
24680 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68  n().** except th
24690 61 74 20 69 74 20 61 63 63 65 70 74 73 20 74 77  at it accepts tw
246a0 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72  o additional par
246b0 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64 69  ameters for addi
246c0 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a  tional control.*
246d0 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64  * over the new d
246e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
246f0 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61 67 73  on.  ^(The flags
24700 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
24710 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
24720 28 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20  () can take one 
24730 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77  of.** the follow
24740 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65 73  ing three values
24750 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d  , optionally com
24760 62 69 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a  bined with the .
24770 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
24780 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54  NOMUTEX], [SQLIT
24790 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58  E_OPEN_FULLMUTEX
247a0 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ], [SQLITE_OPEN_
247b0 53 48 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a  SHAREDCACHE],.**
247c0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52   [SQLITE_OPEN_PR
247d0 49 56 41 54 45 43 41 43 48 45 5d 2c 20 61 6e 64  IVATECACHE], and
247e0 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  /or [SQLITE_OPEN
247f0 5f 55 52 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a  _URI] flags:)^.*
24800 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c  *.** <dl>.** ^(<
24810 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  dt>[SQLITE_OPEN_
24820 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a  READONLY]</dt>.*
24830 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61  * <dd>The databa
24840 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20  se is opened in 
24850 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20  read-only mode. 
24860 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65   If the database
24870 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72   does not.** alr
24880 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65  eady exist, an e
24890 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
248a0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  .</dd>)^.**.** ^
248b0 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45  (<dt>[SQLITE_OPE
248c0 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74  N_READWRITE]</dt
248d0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
248e0 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
248f0 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20  for reading and 
24900 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69  writing if possi
24910 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a  ble, or reading.
24920 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66  ** only if the f
24930 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 6f  ile is write pro
24940 74 65 63 74 65 64 20 62 79 20 74 68 65 20 6f 70  tected by the op
24950 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20  erating system. 
24960 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61   In either.** ca
24970 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
24980 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65 78 69  must already exi
24990 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e  st, otherwise an
249a0 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
249b0 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  ed.</dd>)^.**.**
249c0 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f   ^(<dt>[SQLITE_O
249d0 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c  PEN_READWRITE] |
249e0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52   [SQLITE_OPEN_CR
249f0 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  EATE]</dt>.** <d
24a00 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69  d>The database i
24a10 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
24a20 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67  ding and writing
24a30 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74 65 64  , and is created
24a40 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e   if.** it does n
24a50 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  ot already exist
24a60 2e 20 54 68 69 73 20 69 73 20 74 68 65 20 62 65  . This is the be
24a70 68 61 76 69 6f 72 20 74 68 61 74 20 69 73 20 61  havior that is a
24a80 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a  lways used for.*
24a90 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
24aa0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65   and sqlite3_ope
24ab0 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  n16().</dd>)^.**
24ac0 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20   </dl>.**.** If 
24ad0 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
24ae0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
24af0 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e  n_v2() is not on
24b00 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62  e of the.** comb
24b10 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61  inations shown a
24b20 62 6f 76 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20  bove optionally 
24b30 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 6f 74  combined with ot
24b40 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  her.** [SQLITE_O
24b50 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53  PEN_READONLY | S
24b60 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74  QLITE_OPEN_* bit
24b70 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62  s].** then the b
24b80 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
24b90 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ined..**.** ^If 
24ba0 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
24bb0 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69  _NOMUTEX] flag i
24bc0 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20  s set, then the 
24bd0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
24be0 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20  ion.** opens in 
24bf0 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 61 64  the multi-thread
24c00 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
24c10 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  ] as long as the
24c20 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a   single-thread.*
24c30 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20 62  * mode has not b
24c40 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d 70 69  een set at compi
24c50 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74  le-time or start
24c60 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a  -time.  ^If the.
24c70 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
24c80 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20  FULLMUTEX] flag 
24c90 69 73 20 73 65 74 20 74 68 65 6e 20 74 68 65 20  is set then the 
24ca0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
24cb0 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20  ion opens.** in 
24cc0 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b  the serialized [
24cd0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
24ce0 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68  unless single-th
24cf0 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76  read was.** prev
24d00 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20  iously selected 
24d10 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
24d20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a  or start-time..*
24d30 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  * ^The [SQLITE_O
24d40 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d  PEN_SHAREDCACHE]
24d50 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65   flag causes the
24d60 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
24d70 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c  tion to be.** el
24d80 69 67 69 62 6c 65 20 74 6f 20 75 73 65 20 5b 73  igible to use [s
24d90 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65  hared cache mode
24da0 5d 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ], regardless of
24db0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
24dc0 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20  shared.** cache 
24dd0 69 73 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67  is enabled using
24de0 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65   [sqlite3_enable
24df0 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d  _shared_cache()]
24e00 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49  .  ^The.** [SQLI
24e10 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
24e20 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65  ACHE] flag cause
24e30 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
24e40 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74  onnection to not
24e50 0a 2a 2a 20 70 61 72 74 69 63 69 70 61 74 65 20  .** participate 
24e60 69 6e 20 5b 73 68 61 72 65 64 20 63 61 63 68 65  in [shared cache
24e70 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66 20 69   mode] even if i
24e80 74 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  t is enabled..**
24e90 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20  .** ^The fourth 
24ea0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
24eb0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
24ec0 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
24ed0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66  e.** [sqlite3_vf
24ee0 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64  s] object that d
24ef0 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61  efines the opera
24f00 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65  ting system inte
24f10 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68  rface that.** th
24f20 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63  e new database c
24f30 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64  onnection should
24f40 20 75 73 65 2e 20 20 5e 49 66 20 74 68 65 20 66   use.  ^If the f
24f50 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
24f60 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69  is.** a NULL poi
24f70 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 64 65  nter then the de
24f80 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
24f90 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73  fs] object is us
24fa0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
24fb0 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a  e filename is ":
24fc0 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61  memory:", then a
24fd0 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72   private, tempor
24fe0 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61  ary in-memory da
24ff0 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65  tabase.** is cre
25000 61 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e  ated for the con
25010 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20  nection.  ^This 
25020 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61  in-memory databa
25030 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77  se will vanish w
25040 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  hen.** the datab
25050 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
25060 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72  s closed.  Futur
25070 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
25080 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61  Lite might.** ma
25090 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69 74 69  ke use of additi
250a0 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c  onal special fil
250b0 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67 69  enames that begi
250c0 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22 20 63  n with the ":" c
250d0 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20  haracter..** It 
250e0 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
250f0 68 61 74 20 77 68 65 6e 20 61 20 64 61 74 61 62  hat when a datab
25100 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74  ase filename act
25110 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e  ually does begin
25120 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63   with.** a ":" c
25130 68 61 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f  haracter you sho
25140 75 6c 64 20 70 72 65 66 69 78 20 74 68 65 20 66  uld prefix the f
25150 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70  ilename with a p
25160 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a  athname such as.
25170 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64  ** "./" to avoid
25180 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a   ambiguity..**.*
25190 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61  * ^If the filena
251a0 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73  me is an empty s
251b0 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72  tring, then a pr
251c0 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79  ivate, temporary
251d0 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61  .** on-disk data
251e0 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65  base will be cre
251f0 61 74 65 64 2e 20 20 5e 54 68 69 73 20 70 72 69  ated.  ^This pri
25200 76 61 74 65 20 64 61 74 61 62 61 73 65 20 77 69  vate database wi
25210 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74  ll be.** automat
25220 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61  ically deleted a
25230 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61  s soon as the da
25240 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
25250 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a  n is closed..**.
25260 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d  ** [[URI filenam
25270 65 73 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70  es in sqlite3_op
25280 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46  en()]] <h3>URI F
25290 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a  ilenames</h3>.**
252a0 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 20 66 69 6c  .** ^If [URI fil
252b0 65 6e 61 6d 65 5d 20 69 6e 74 65 72 70 72 65 74  ename] interpret
252c0 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64  ation is enabled
252d0 2c 20 61 6e 64 20 74 68 65 20 66 69 6c 65 6e 61  , and the filena
252e0 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62  me argument.** b
252f0 65 67 69 6e 73 20 77 69 74 68 20 22 66 69 6c 65  egins with "file
25300 3a 22 2c 20 74 68 65 6e 20 74 68 65 20 66 69 6c  :", then the fil
25310 65 6e 61 6d 65 20 69 73 20 69 6e 74 65 72 70 72  ename is interpr
25320 65 74 65 64 20 61 73 20 61 20 55 52 49 2e 20 5e  eted as a URI. ^
25330 55 52 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20  URI.** filename 
25340 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69  interpretation i
25350 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65  s enabled if the
25360 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52   [SQLITE_OPEN_UR
25370 49 5d 20 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65  I] flag is.** se
25380 74 20 69 6e 20 74 68 65 20 66 6f 75 72 74 68 20  t in the fourth 
25390 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
253a0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f  te3_open_v2(), o
253b0 72 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 62  r if it has.** b
253c0 65 65 6e 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62  een enabled glob
253d0 61 6c 6c 79 20 75 73 69 6e 67 20 74 68 65 20 5b  ally using the [
253e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
253f0 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74 68 20 74  I] option with t
25400 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  he.** [sqlite3_c
25410 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68 6f 64 20  onfig()] method 
25420 6f 72 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54  or by the [SQLIT
25430 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69  E_USE_URI] compi
25440 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a  le-time option..
25450 2a 2a 20 41 73 20 6f 66 20 53 51 4c 69 74 65 20  ** As of SQLite 
25460 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 55  version 3.7.7, U
25470 52 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65  RI filename inte
25480 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 74 75  rpretation is tu
25490 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79 20 64  rned off.** by d
254a0 65 66 61 75 6c 74 2c 20 62 75 74 20 66 75 74 75  efault, but futu
254b0 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
254c0 51 4c 69 74 65 20 6d 69 67 68 74 20 65 6e 61 62  QLite might enab
254d0 6c 65 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 0a  le URI filename.
254e0 2a 2a 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f  ** interpretatio
254f0 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20 53  n by default.  S
25500 65 65 20 22 5b 55 52 49 20 66 69 6c 65 6e 61 6d  ee "[URI filenam
25510 65 73 5d 22 20 66 6f 72 20 61 64 64 69 74 69 6f  es]" for additio
25520 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  nal.** informati
25530 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66 69  on..**.** URI fi
25540 6c 65 6e 61 6d 65 73 20 61 72 65 20 70 61 72 73  lenames are pars
25550 65 64 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20  ed according to 
25560 52 46 43 20 33 39 38 36 2e 20 5e 49 66 20 74 68  RFC 3986. ^If th
25570 65 20 55 52 49 20 63 6f 6e 74 61 69 6e 73 20 61  e URI contains a
25580 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79 2c 20  n.** authority, 
25590 74 68 65 6e 20 69 74 20 6d 75 73 74 20 62 65 20  then it must be 
255a0 65 69 74 68 65 72 20 61 6e 20 65 6d 70 74 79 20  either an empty 
255b0 73 74 72 69 6e 67 20 6f 72 20 74 68 65 20 73 74  string or the st
255c0 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68  ring .** "localh
255d0 6f 73 74 22 2e 20 5e 49 66 20 74 68 65 20 61 75  ost". ^If the au
255e0 74 68 6f 72 69 74 79 20 69 73 20 6e 6f 74 20 61  thority is not a
255f0 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f  n empty string o
25600 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c 20 61  r "localhost", a
25610 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73 20 72  n .** error is r
25620 65 74 75 72 6e 65 64 20 74 6f 20 74 68 65 20 63  eturned to the c
25630 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72 61 67  aller. ^The frag
25640 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  ment component o
25650 66 20 61 20 55 52 49 2c 20 69 66 20 0a 2a 2a 20  f a URI, if .** 
25660 70 72 65 73 65 6e 74 2c 20 69 73 20 69 67 6e 6f  present, is igno
25670 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  red..**.** ^SQLi
25680 74 65 20 75 73 65 73 20 74 68 65 20 70 61 74 68  te uses the path
25690 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68   component of th
256a0 65 20 55 52 49 20 61 73 20 74 68 65 20 6e 61 6d  e URI as the nam
256b0 65 20 6f 66 20 74 68 65 20 64 69 73 6b 20 66 69  e of the disk fi
256c0 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f 6e 74  le.** which cont
256d0 61 69 6e 73 20 74 68 65 20 64 61 74 61 62 61 73  ains the databas
256e0 65 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20  e. ^If the path 
256f0 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 27 2f  begins with a '/
25700 27 20 63 68 61 72 61 63 74 65 72 2c 20 0a 2a 2a  ' character, .**
25710 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 74 65   then it is inte
25720 72 70 72 65 74 65 64 20 61 73 20 61 6e 20 61 62  rpreted as an ab
25730 73 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e 49 66  solute path. ^If
25740 20 74 68 65 20 70 61 74 68 20 64 6f 65 73 20 6e   the path does n
25750 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77 69 74  ot begin .** wit
25760 68 20 61 20 27 2f 27 20 28 6d 65 61 6e 69 6e 67  h a '/' (meaning
25770 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72   that the author
25780 69 74 79 20 73 65 63 74 69 6f 6e 20 69 73 20 6f  ity section is o
25790 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20  mitted from the 
257a0 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65  URI).** then the
257b0 20 70 61 74 68 20 69 73 20 69 6e 74 65 72 70 72   path is interpr
257c0 65 74 65 64 20 61 73 20 61 20 72 65 6c 61 74 69  eted as a relati
257d0 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e 28 4f  ve path. .** ^(O
257e0 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68 65 20 66  n windows, the f
257f0 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  irst component o
25800 66 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61  f an absolute pa
25810 74 68 20 0a 2a 2a 20 69 73 20 61 20 64 72 69 76  th .** is a driv
25820 65 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e 20  e specification 
25830 28 65 2e 67 2e 20 22 43 3a 22 29 2e 29 5e 0a 2a  (e.g. "C:").)^.*
25840 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55 52 49 20  *.** [[core URI 
25850 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73  query parameters
25860 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65 72 79 20  ]].** The query 
25870 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55  component of a U
25880 52 49 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 70  RI may contain p
25890 61 72 61 6d 65 74 65 72 73 20 74 68 61 74 20 61  arameters that a
258a0 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 0a 2a  re interpreted.*
258b0 2a 20 65 69 74 68 65 72 20 62 79 20 53 51 4c 69  * either by SQLi
258c0 74 65 20 69 74 73 65 6c 66 2c 20 6f 72 20 62 79  te itself, or by
258d0 20 61 20 5b 56 46 53 20 7c 20 63 75 73 74 6f 6d   a [VFS | custom
258e0 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
258f0 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65 20  ion]..** SQLite 
25900 61 6e 64 20 69 74 73 20 62 75 69 6c 74 2d 69 6e  and its built-in
25910 20 5b 56 46 53 65 73 5d 20 69 6e 74 65 72 70 72   [VFSes] interpr
25920 65 74 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77  et the.** follow
25930 69 6e 67 20 71 75 65 72 79 20 70 61 72 61 6d 65  ing query parame
25940 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ters:.**.** <ul>
25950 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66  .**   <li> <b>vf
25960 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66 73  s</b>: ^The "vfs
25970 22 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  " parameter may 
25980 62 65 20 75 73 65 64 20 74 6f 20 73 70 65 63 69  be used to speci
25990 66 79 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a  fy the name of.*
259a0 2a 20 20 20 20 20 61 20 56 46 53 20 6f 62 6a 65  *     a VFS obje
259b0 63 74 20 74 68 61 74 20 70 72 6f 76 69 64 65 73  ct that provides
259c0 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
259d0 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20  ystem interface 
259e0 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20  that should.**  
259f0 20 20 20 62 65 20 75 73 65 64 20 74 6f 20 61 63     be used to ac
25a00 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73  cess the databas
25a10 65 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20  e file on disk. 
25a20 5e 49 66 20 74 68 69 73 20 6f 70 74 69 6f 6e 20  ^If this option 
25a30 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20  is set to.**    
25a40 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
25a50 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53   the default VFS
25a60 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e   object is used.
25a70 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20   ^Specifying an 
25a80 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56  unknown.**     V
25a90 46 53 20 69 73 20 61 6e 20 65 72 72 6f 72 2e 20  FS is an error. 
25aa0 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ^If sqlite3_open
25ab0 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e  _v2() is used an
25ac0 64 20 74 68 65 20 76 66 73 20 6f 70 74 69 6f 6e  d the vfs option
25ad0 20 69 73 0a 2a 2a 20 20 20 20 20 70 72 65 73 65   is.**     prese
25ae0 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 56 46 53  nt, then the VFS
25af0 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
25b00 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 70  e option takes p
25b10 72 65 63 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a  recedence over.*
25b20 2a 20 20 20 20 20 74 68 65 20 76 61 6c 75 65 20  *     the value 
25b30 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 6f  passed as the fo
25b40 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
25b50 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
25b60 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69  2()..**.**   <li
25b70 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e  > <b>mode</b>: ^
25b80 28 54 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65  (The mode parame
25b90 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 74  ter may be set t
25ba0 6f 20 65 69 74 68 65 72 20 22 72 6f 22 2c 20 22  o either "ro", "
25bb0 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72 77 63  rw",.**     "rwc
25bc0 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e 20  ", or "memory". 
25bd0 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 73 65  Attempting to se
25be0 74 20 69 74 20 74 6f 20 61 6e 79 20 6f 74 68 65  t it to any othe
25bf0 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 20 20  r value is.**   
25c00 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a 2a    an error)^. .*
25c10 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22 20 69  *     ^If "ro" i
25c20 73 20 73 70 65 63 69 66 69 65 64 2c 20 74 68 65  s specified, the
25c30 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
25c40 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
25c50 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 61  d-only .**     a
25c60 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73 20 69  ccess, just as i
25c70 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  f the [SQLITE_OP
25c80 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c 61  EN_READONLY] fla
25c90 67 20 68 61 64 20 62 65 65 6e 20 73 65 74 20 69  g had been set i
25ca0 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 74 68  n the .**     th
25cb0 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ird argument to 
25cc0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
25cd0 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20  ). ^If the mode 
25ce0 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f  option is set to
25cf0 20 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c 20 74   .**     "rw", t
25d00 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
25d10 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
25d20 65 61 64 2d 77 72 69 74 65 20 28 62 75 74 20 6e  ead-write (but n
25d30 6f 74 20 63 72 65 61 74 65 29 20 0a 2a 2a 20 20  ot create) .**  
25d40 20 20 20 61 63 63 65 73 73 2c 20 61 73 20 69 66     access, as if
25d50 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
25d60 44 57 52 49 54 45 20 28 62 75 74 20 6e 6f 74 20  DWRITE (but not 
25d70 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
25d80 54 45 29 20 68 61 64 20 0a 2a 2a 20 20 20 20 20  TE) had .**     
25d90 62 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65  been set. ^Value
25da0 20 22 72 77 63 22 20 69 73 20 65 71 75 69 76 61   "rwc" is equiva
25db0 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20  lent to setting 
25dc0 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c  both .**     SQL
25dd0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
25de0 54 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50  TE and SQLITE_OP
25df0 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49 66 20  EN_CREATE.  ^If 
25e00 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20  the mode option 
25e10 69 73 0a 2a 2a 20 20 20 20 20 73 65 74 20 74 6f  is.**     set to
25e20 20 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20 61   "memory" then a
25e30 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79   pure [in-memory
25e40 20 64 61 74 61 62 61 73 65 5d 20 74 68 61 74 20   database] that 
25e50 6e 65 76 65 72 20 72 65 61 64 73 0a 2a 2a 20 20  never reads.**  
25e60 20 20 20 6f 72 20 77 72 69 74 65 73 20 66 72 6f     or writes fro
25e70 6d 20 64 69 73 6b 20 69 73 20 75 73 65 64 2e 20  m disk is used. 
25e80 5e 49 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20  ^It is an error 
25e90 74 6f 20 73 70 65 63 69 66 79 20 61 20 76 61 6c  to specify a val
25ea0 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74 68  ue for.**     th
25eb0 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72  e mode parameter
25ec0 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 72 65   that is less re
25ed0 73 74 72 69 63 74 69 76 65 20 74 68 61 6e 20 74  strictive than t
25ee0 68 61 74 20 73 70 65 63 69 66 69 65 64 20 62 79  hat specified by
25ef0 0a 2a 2a 20 20 20 20 20 74 68 65 20 66 6c 61 67  .**     the flag
25f00 73 20 70 61 73 73 65 64 20 69 6e 20 74 68 65 20  s passed in the 
25f10 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
25f20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
25f30 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c  v2()..**.**   <l
25f40 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a  i> <b>cache</b>:
25f50 20 5e 54 68 65 20 63 61 63 68 65 20 70 61 72 61   ^The cache para
25f60 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74  meter may be set
25f70 20 74 6f 20 65 69 74 68 65 72 20 22 73 68 61 72   to either "shar
25f80 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70  ed" or.**     "p
25f90 72 69 76 61 74 65 22 2e 20 5e 53 65 74 74 69 6e  rivate". ^Settin
25fa0 67 20 69 74 20 74 6f 20 22 73 68 61 72 65 64 22  g it to "shared"
25fb0 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74   is equivalent t
25fc0 6f 20 73 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a  o setting the.**
25fd0 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e       SQLITE_OPEN
25fe0 5f 53 48 41 52 45 44 43 41 43 48 45 20 62 69 74  _SHAREDCACHE bit
25ff0 20 69 6e 20 74 68 65 20 66 6c 61 67 73 20 61 72   in the flags ar
26000 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 74 6f  gument passed to
26010 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65 33 5f  .**     sqlite3_
26020 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74  open_v2(). ^Sett
26030 69 6e 67 20 74 68 65 20 63 61 63 68 65 20 70 61  ing the cache pa
26040 72 61 6d 65 74 65 72 20 74 6f 20 22 70 72 69 76  rameter to "priv
26050 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 20 20 20  ate" is .**     
26060 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65  equivalent to se
26070 74 74 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45  tting the SQLITE
26080 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
26090 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e  HE bit..**     ^
260a0 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  If sqlite3_open_
260b0 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64  v2() is used and
260c0 20 74 68 65 20 22 63 61 63 68 65 22 20 70 61 72   the "cache" par
260d0 61 6d 65 74 65 72 20 69 73 20 70 72 65 73 65 6e  ameter is presen
260e0 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52  t in.**     a UR
260f0 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20  I filename, its 
26100 76 61 6c 75 65 20 6f 76 65 72 72 69 64 65 73 20  value overrides 
26110 61 6e 79 20 62 65 68 61 76 69 6f 72 20 72 65 71  any behavior req
26120 75 65 73 74 65 64 20 62 79 20 73 65 74 74 69 6e  uested by settin
26130 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f  g.**     SQLITE_
26140 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
26150 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45 4e  E or SQLITE_OPEN
26160 5f 53 48 41 52 45 44 43 41 43 48 45 20 66 6c 61  _SHAREDCACHE fla
26170 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c  g..**.**  <li> <
26180 62 3e 70 73 6f 77 3c 2f 62 3e 3a 20 5e 54 68 65  b>psow</b>: ^The
26190 20 70 73 6f 77 20 70 61 72 61 6d 65 74 65 72 20   psow parameter 
261a0 69 6e 64 69 63 61 74 65 73 20 77 68 65 74 68 65  indicates whethe
261b0 72 20 6f 72 20 6e 6f 74 20 74 68 65 0a 2a 2a 20  r or not the.** 
261c0 20 20 20 20 5b 70 6f 77 65 72 73 61 66 65 20 6f      [powersafe o
261d0 76 65 72 77 72 69 74 65 5d 20 70 72 6f 70 65 72  verwrite] proper
261e0 74 79 20 64 6f 65 73 20 6f 72 20 64 6f 65 73 20  ty does or does 
261f0 6e 6f 74 20 61 70 70 6c 79 20 74 6f 20 74 68 65  not apply to the
26200 0a 2a 2a 20 20 20 20 20 73 74 6f 72 61 67 65 20  .**     storage 
26210 6d 65 64 69 61 20 6f 6e 20 77 68 69 63 68 20 74  media on which t
26220 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
26230 20 72 65 73 69 64 65 73 2e 0a 2a 2a 0a 2a 2a 20   resides..**.** 
26240 20 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f 63 6b 3c   <li> <b>nolock<
26250 2f 62 3e 3a 20 5e 54 68 65 20 6e 6f 6c 6f 63 6b  /b>: ^The nolock
26260 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
26270 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 20 70 61  boolean query pa
26280 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 77  rameter.**     w
26290 68 69 63 68 20 69 66 20 73 65 74 20 64 69 73 61  hich if set disa
262a0 62 6c 65 73 20 66 69 6c 65 20 6c 6f 63 6b 69 6e  bles file lockin
262b0 67 20 69 6e 20 72 6f 6c 6c 62 61 63 6b 20 6a 6f  g in rollback jo
262c0 75 72 6e 61 6c 20 6d 6f 64 65 73 2e 20 20 54 68  urnal modes.  Th
262d0 69 73 0a 2a 2a 20 20 20 20 20 69 73 20 75 73 65  is.**     is use
262e0 66 75 6c 20 66 6f 72 20 61 63 63 65 73 73 69 6e  ful for accessin
262f0 67 20 61 20 64 61 74 61 62 61 73 65 20 6f 6e 20  g a database on 
26300 61 20 66 69 6c 65 73 79 73 74 65 6d 20 74 68 61  a filesystem tha
26310 74 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 20  t does not.**   
26320 20 20 73 75 70 70 6f 72 74 20 6c 6f 63 6b 69 6e    support lockin
26330 67 2e 20 20 43 61 75 74 69 6f 6e 3a 20 20 44 61  g.  Caution:  Da
26340 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f  tabase corruptio
26350 6e 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69  n might result i
26360 66 20 74 77 6f 0a 2a 2a 20 20 20 20 20 6f 72 20  f two.**     or 
26370 6d 6f 72 65 20 70 72 6f 63 65 73 73 65 73 20 77  more processes w
26380 72 69 74 65 20 74 6f 20 74 68 65 20 73 61 6d 65  rite to the same
26390 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6e   database and an
263a0 79 20 6f 6e 65 20 6f 66 20 74 68 6f 73 65 0a 2a  y one of those.*
263b0 2a 20 20 20 20 20 70 72 6f 63 65 73 73 65 73 20  *     processes 
263c0 75 73 65 73 20 6e 6f 6c 6f 63 6b 3d 31 2e 0a 2a  uses nolock=1..*
263d0 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 69 6d  *.**  <li> <b>im
263e0 6d 75 74 61 62 6c 65 3c 2f 62 3e 3a 20 5e 54 68  mutable</b>: ^Th
263f0 65 20 69 6d 6d 75 74 61 62 6c 65 20 70 61 72 61  e immutable para
26400 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65  meter is a boole
26410 61 6e 20 71 75 65 72 79 0a 2a 2a 20 20 20 20 20  an query.**     
26420 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 20 69  parameter that i
26430 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 74 68  ndicates that th
26440 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
26450 69 73 20 73 74 6f 72 65 64 20 6f 6e 0a 2a 2a 20  is stored on.** 
26460 20 20 20 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65      read-only me
26470 64 69 61 2e 20 20 5e 57 68 65 6e 20 69 6d 6d 75  dia.  ^When immu
26480 74 61 62 6c 65 20 69 73 20 73 65 74 2c 20 53 51  table is set, SQ
26490 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61  Lite assumes tha
264a0 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 64 61 74  t the.**     dat
264b0 61 62 61 73 65 20 66 69 6c 65 20 63 61 6e 6e 6f  abase file canno
264c0 74 20 62 65 20 63 68 61 6e 67 65 64 2c 20 65 76  t be changed, ev
264d0 65 6e 20 62 79 20 61 20 70 72 6f 63 65 73 73 20  en by a process 
264e0 77 69 74 68 20 68 69 67 68 65 72 0a 2a 2a 20 20  with higher.**  
264f0 20 20 20 70 72 69 76 69 6c 65 67 65 2c 20 61 6e     privilege, an
26500 64 20 73 6f 20 74 68 65 20 64 61 74 61 62 61 73  d so the databas
26510 65 20 69 73 20 6f 70 65 6e 65 64 20 72 65 61 64  e is opened read
26520 2d 6f 6e 6c 79 20 61 6e 64 20 61 6c 6c 20 6c 6f  -only and all lo
26530 63 6b 69 6e 67 0a 2a 2a 20 20 20 20 20 61 6e 64  cking.**     and
26540 20 63 68 61 6e 67 65 20 64 65 74 65 63 74 69 6f   change detectio
26550 6e 20 69 73 20 64 69 73 61 62 6c 65 64 2e 20 20  n is disabled.  
26560 43 61 75 74 69 6f 6e 3a 20 53 65 74 74 69 6e 67  Caution: Setting
26570 20 74 68 65 20 69 6d 6d 75 74 61 62 6c 65 0a 2a   the immutable.*
26580 2a 20 20 20 20 20 70 72 6f 70 65 72 74 79 20 6f  *     property o
26590 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  n a database fil
265a0 65 20 74 68 61 74 20 64 6f 65 73 20 69 6e 20 66  e that does in f
265b0 61 63 74 20 63 68 61 6e 67 65 20 63 61 6e 20 72  act change can r
265c0 65 73 75 6c 74 0a 2a 2a 20 20 20 20 20 69 6e 20  esult.**     in 
265d0 69 6e 63 6f 72 72 65 63 74 20 71 75 65 72 79 20  incorrect query 
265e0 72 65 73 75 6c 74 73 20 61 6e 64 2f 6f 72 20 5b  results and/or [
265f0 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 20  SQLITE_CORRUPT] 
26600 65 72 72 6f 72 73 2e 0a 2a 2a 20 20 20 20 20 53  errors..**     S
26610 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45  ee also: [SQLITE
26620 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45  _IOCAP_IMMUTABLE
26630 5d 2e 0a 2a 2a 20 20 20 20 20 20 20 0a 2a 2a 20  ]..**       .** 
26640 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65  </ul>.**.** ^Spe
26650 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f  cifying an unkno
26660 77 6e 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20  wn parameter in 
26670 74 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e  the query compon
26680 65 6e 74 20 6f 66 20 61 20 55 52 49 20 69 73 20  ent of a URI is 
26690 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e  not an.** error.
266a0 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e    Future version
266b0 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68  s of SQLite migh
266c0 74 20 75 6e 64 65 72 73 74 61 6e 64 20 61 64 64  t understand add
266d0 69 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a 2a  itional query.**
266e0 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 53 65   parameters.  Se
266f0 65 20 22 5b 71 75 65 72 79 20 70 61 72 61 6d 65  e "[query parame
26700 74 65 72 73 20 77 69 74 68 20 73 70 65 63 69 61  ters with specia
26710 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51 4c  l meaning to SQL
26720 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64 64  ite]" for.** add
26730 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
26740 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49  ion..**.** [[URI
26750 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c   filename exampl
26760 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69 6c  es]] <h3>URI fil
26770 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c 2f  ename examples</
26780 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65  h3>.**.** <table
26790 20 62 6f 72 64 65 72 3d 22 31 22 20 61 6c 69 67   border="1" alig
267a0 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70 61 64  n=center cellpad
267b0 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c  ding=5>.** <tr><
267c0 74 68 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  th> URI filename
267d0 73 20 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a 2a  s <th> Results.*
267e0 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
267f0 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a  data.db <td> .**
26800 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74            Open t
26810 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62  he file "data.db
26820 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  " in the current
26830 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c   directory..** <
26840 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f  tr><td> file:/ho
26850 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3c  me/fred/data.db<
26860 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  br>.**          
26870 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65  file:///home/fre
26880 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 0a  d/data.db <br> .
26890 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65  **          file
268a0 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d  ://localhost/hom
268b0 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c  e/fred/data.db <
268c0 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  br> <td> .**    
268d0 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 64        Open the d
268e0 61 74 61 62 61 73 65 20 66 69 6c 65 20 22 2f 68  atabase file "/h
268f0 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
26900 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  "..** <tr><td> f
26910 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f 68  ile://darkstar/h
26920 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
26930 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
26940 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 64 61     An error. "da
26950 72 6b 73 74 61 72 22 20 69 73 20 6e 6f 74 20 61  rkstar" is not a
26960 20 72 65 63 6f 67 6e 69 7a 65 64 20 61 75 74 68   recognized auth
26970 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  ority..** <tr><t
26980 64 20 73 74 79 6c 65 3d 22 77 68 69 74 65 2d 73  d style="white-s
26990 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a  pace:nowrap"> .*
269a0 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a  *          file:
269b0 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 25  ///C:/Documents%
269c0 32 30 61 6e 64 25 32 30 53 65 74 74 69 6e 67 73  20and%20Settings
269d0 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64 61  /fred/Desktop/da
269e0 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74 64  ta.db.**     <td
269f0 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20  > Windows only: 
26a00 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64  Open the file "d
26a10 61 74 61 2e 64 62 22 20 6f 6e 20 66 72 65 64 27  ata.db" on fred'
26a20 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72 69  s desktop on dri
26a30 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43  ve.**          C
26a40 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  :. Note that the
26a50 20 25 32 30 20 65 73 63 61 70 69 6e 67 20 69 6e   %20 escaping in
26a60 20 74 68 69 73 20 65 78 61 6d 70 6c 65 20 69 73   this example is
26a70 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 0a 2a   not strictly .*
26a80 2a 20 20 20 20 20 20 20 20 20 20 6e 65 63 65 73  *          neces
26a90 73 61 72 79 20 2d 20 73 70 61 63 65 20 63 68 61  sary - space cha
26aa0 72 61 63 74 65 72 73 20 63 61 6e 20 62 65 20 75  racters can be u
26ab0 73 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a  sed literally.**
26ac0 20 20 20 20 20 20 20 20 20 20 69 6e 20 55 52 49            in URI
26ad0 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c   filenames..** <
26ae0 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74  tr><td> file:dat
26af0 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 63  a.db?mode=ro&cac
26b00 68 65 3d 70 72 69 76 61 74 65 20 3c 74 64 3e 20  he=private <td> 
26b10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65  .**          Ope
26b20 6e 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22  n file "data.db"
26b30 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
26b40 64 69 72 65 63 74 6f 72 79 20 66 6f 72 20 72 65  directory for re
26b50 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e 0a  ad-only access..
26b60 2a 2a 20 20 20 20 20 20 20 20 20 20 52 65 67 61  **          Rega
26b70 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
26b80 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 2d  r or not shared-
26b90 63 61 63 68 65 20 6d 6f 64 65 20 69 73 20 65 6e  cache mode is en
26ba0 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20 20  abled by.**     
26bb0 20 20 20 20 20 64 65 66 61 75 6c 74 2c 20 75 73       default, us
26bc0 65 20 61 20 70 72 69 76 61 74 65 20 63 61 63 68  e a private cach
26bd0 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  e..** <tr><td> f
26be0 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  ile:/home/fred/d
26bf0 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78 2d  ata.db?vfs=unix-
26c00 64 6f 74 66 69 6c 65 20 3c 74 64 3e 0a 2a 2a 20  dotfile <td>.** 
26c10 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69           Open fi
26c20 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  le "/home/fred/d
26c30 61 74 61 2e 64 62 22 2e 20 55 73 65 20 74 68 65  ata.db". Use the
26c40 20 73 70 65 63 69 61 6c 20 56 46 53 20 22 75 6e   special VFS "un
26c50 69 78 2d 64 6f 74 66 69 6c 65 22 0a 2a 2a 20 20  ix-dotfile".**  
26c60 20 20 20 20 20 20 20 20 74 68 61 74 20 75 73 65          that use
26c70 73 20 64 6f 74 2d 66 69 6c 65 73 20 69 6e 20 70  s dot-files in p
26c80 6c 61 63 65 20 6f 66 20 70 6f 73 69 78 20 61 64  lace of posix ad
26c90 76 69 73 6f 72 79 20 6c 6f 63 6b 69 6e 67 2e 0a  visory locking..
26ca0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
26cb0 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 65  :data.db?mode=re
26cc0 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20  adonly <td> .** 
26cd0 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f           An erro
26ce0 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20 69 73  r. "readonly" is
26cf0 20 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f 70 74   not a valid opt
26d00 69 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f 64  ion for the "mod
26d10 65 22 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  e" parameter..**
26d20 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20   </table>.**.** 
26d30 5e 55 52 49 20 68 65 78 61 64 65 63 69 6d 61 6c  ^URI hexadecimal
26d40 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65   escape sequence
26d50 73 20 28 25 48 48 29 20 61 72 65 20 73 75 70 70  s (%HH) are supp
26d60 6f 72 74 65 64 20 77 69 74 68 69 6e 20 74 68 65  orted within the
26d70 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75 65   path and.** que
26d80 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66  ry components of
26d90 20 61 20 55 52 49 2e 20 41 20 68 65 78 61 64 65   a URI. A hexade
26da0 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71  cimal escape seq
26db0 75 65 6e 63 65 20 63 6f 6e 73 69 73 74 73 20 6f  uence consists o
26dc0 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20 73  f a.** percent s
26dd0 69 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c 6c  ign - "%" - foll
26de0 6f 77 65 64 20 62 79 20 65 78 61 63 74 6c 79 20  owed by exactly 
26df0 74 77 6f 20 68 65 78 61 64 65 63 69 6d 61 6c 20  two hexadecimal 
26e00 64 69 67 69 74 73 20 0a 2a 2a 20 73 70 65 63 69  digits .** speci
26e10 66 79 69 6e 67 20 61 6e 20 6f 63 74 65 74 20 76  fying an octet v
26e20 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20 74 68  alue. ^Before th
26e30 65 20 70 61 74 68 20 6f 72 20 71 75 65 72 79 20  e path or query 
26e40 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 0a  components of a.
26e50 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20  ** URI filename 
26e60 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 2c  are interpreted,
26e70 20 74 68 65 79 20 61 72 65 20 65 6e 63 6f 64 65   they are encode
26e80 64 20 75 73 69 6e 67 20 55 54 46 2d 38 20 61 6e  d using UTF-8 an
26e90 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 65  d all .** hexade
26ea0 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71  cimal escape seq
26eb0 75 65 6e 63 65 73 20 72 65 70 6c 61 63 65 64 20  uences replaced 
26ec0 62 79 20 61 20 73 69 6e 67 6c 65 20 62 79 74 65  by a single byte
26ed0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a   containing the.
26ee0 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  ** corresponding
26ef0 20 6f 63 74 65 74 2e 20 49 66 20 74 68 69 73 20   octet. If this 
26f00 70 72 6f 63 65 73 73 20 67 65 6e 65 72 61 74 65  process generate
26f10 73 20 61 6e 20 69 6e 76 61 6c 69 64 20 55 54 46  s an invalid UTF
26f20 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20  -8 encoding,.** 
26f30 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
26f40 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
26f50 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64   <b>Note to Wind
26f60 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20  ows users:</b>  
26f70 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65  The encoding use
26f80 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61  d for the filena
26f90 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f  me argument.** o
26fa0 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  f sqlite3_open()
26fb0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65   and sqlite3_ope
26fc0 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20 55  n_v2() must be U
26fd0 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76  TF-8, not whatev
26fe0 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69  er.** codepage i
26ff0 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  s currently defi
27000 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20  ned.  Filenames 
27010 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72  containing inter
27020 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72  national.** char
27030 61 63 74 65 72 73 20 6d 75 73 74 20 62 65 20 63  acters must be c
27040 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d  onverted to UTF-
27050 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69  8 prior to passi
27060 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20  ng them into.** 
27070 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f  sqlite3_open() o
27080 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
27090 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f  2()..**.** <b>No
270a0 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 52 75  te to Windows Ru
270b0 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62 3e  ntime users:</b>
270c0 20 20 54 68 65 20 74 65 6d 70 6f 72 61 72 79 20    The temporary 
270d0 64 69 72 65 63 74 6f 72 79 20 6d 75 73 74 20 62  directory must b
270e0 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20 74  e set.** prior t
270f0 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65  o calling sqlite
27100 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69  3_open() or sqli
27110 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20  te3_open_v2().  
27120 4f 74 68 65 72 77 69 73 65 2c 20 76 61 72 69 6f  Otherwise, vario
27130 75 73 0a 2a 2a 20 66 65 61 74 75 72 65 73 20 74  us.** features t
27140 68 61 74 20 72 65 71 75 69 72 65 20 74 68 65 20  hat require the 
27150 75 73 65 20 6f 66 20 74 65 6d 70 6f 72 61 72 79  use of temporary
27160 20 66 69 6c 65 73 20 6d 61 79 20 66 61 69 6c 2e   files may fail.
27170 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
27180 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64   [sqlite3_temp_d
27190 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 69 6e 74  irectory].*/.int
271a0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20   sqlite3_open(. 
271b0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c   const char *fil
271c0 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61  ename,   /* Data
271d0 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55  base filename (U
271e0 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74  TF-8) */.  sqlit
271f0 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20  e3 **ppDb       
27200 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74     /* OUT: SQLit
27210 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29  e db handle */.)
27220 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  ;.int sqlite3_op
27230 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f  en16(.  const vo
27240 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20  id *filename,   
27250 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65  /* Database file
27260 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f  name (UTF-16) */
27270 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
27280 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b          /* OU
27290 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
272a0 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  dle */.);.int sq
272b0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20  lite3_open_v2(. 
272c0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c   const char *fil
272d0 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61  ename,   /* Data
272e0 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55  base filename (U
272f0 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74  TF-8) */.  sqlit
27300 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20  e3 **ppDb,      
27310 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74     /* OUT: SQLit
27320 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  e db handle */. 
27330 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20   int flags,     
27340 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67           /* Flag
27350 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  s */.  const cha
27360 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f  r *zVfs        /
27370 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f  * Name of VFS mo
27380 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29  dule to use */.)
27390 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
273a0 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75 65 73  F: Obtain Values
273b0 20 46 6f 72 20 55 52 49 20 50 61 72 61 6d 65 74   For URI Paramet
273c0 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ers.**.** These 
273d0 61 72 65 20 75 74 69 6c 69 74 79 20 72 6f 75 74  are utility rout
273e0 69 6e 65 73 2c 20 75 73 65 66 75 6c 20 74 6f 20  ines, useful to 
273f0 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
27400 6f 6e 73 2c 20 74 68 61 74 20 63 68 65 63 6b 0a  ons, that check.
27410 2a 2a 20 74 6f 20 73 65 65 20 69 66 20 61 20 64  ** to see if a d
27420 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 73  atabase file was
27430 20 61 20 55 52 49 20 74 68 61 74 20 63 6f 6e 74   a URI that cont
27440 61 69 6e 65 64 20 61 20 73 70 65 63 69 66 69 63  ained a specific
27450 20 71 75 65 72 79 20 0a 2a 2a 20 70 61 72 61 6d   query .** param
27460 65 74 65 72 2c 20 61 6e 64 20 69 66 20 73 6f 20  eter, and if so 
27470 6f 62 74 61 69 6e 73 20 74 68 65 20 76 61 6c 75  obtains the valu
27480 65 20 6f 66 20 74 68 61 74 20 71 75 65 72 79 20  e of that query 
27490 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
274a0 20 49 66 20 46 20 69 73 20 74 68 65 20 64 61 74   If F is the dat
274b0 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 70  abase filename p
274c0 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20 69 6e  ointer passed in
274d0 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 20 6d  to the xOpen() m
274e0 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61 20 56  ethod of .** a V
274f0 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
27500 6e 20 77 68 65 6e 20 74 68 65 20 66 6c 61 67 73  n when the flags
27510 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f   parameter to xO
27520 70 65 6e 28 29 20 68 61 73 20 6f 6e 65 20 6f 72  pen() has one or
27530 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65   .** more of the
27540 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52   [SQLITE_OPEN_UR
27550 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50  I] or [SQLITE_OP
27560 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69 74 73  EN_MAIN_DB] bits
27570 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20 69 73   set and.** P is
27580 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
27590 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
275a0 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65  , then.** sqlite
275b0 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28  3_uri_parameter(
275c0 46 2c 50 29 20 72 65 74 75 72 6e 73 20 74 68 65  F,P) returns the
275d0 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 50 0a   value of the P.
275e0 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 66 20  ** parameter if 
275f0 69 74 20 65 78 69 73 74 73 20 6f 72 20 61 20 4e  it exists or a N
27600 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 50  ULL pointer if P
27610 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65 61 72   does not appear
27620 20 61 73 20 61 20 0a 2a 2a 20 71 75 65 72 79 20   as a .** query 
27630 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 2e 20  parameter on F. 
27640 20 49 66 20 50 20 69 73 20 61 20 71 75 65 72 79   If P is a query
27650 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 46 0a   parameter of F.
27660 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c 69 63  ** has no explic
27670 69 74 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 73  it value, then s
27680 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d  qlite3_uri_param
27690 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e  eter(F,P) return
276a0 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74  s.** a pointer t
276b0 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  o an empty strin
276c0 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  g..**.** The sql
276d0 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
276e0 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20  (F,P,B) routine 
276f0 61 73 73 75 6d 65 73 20 74 68 61 74 20 50 20 69  assumes that P i
27700 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70  s a boolean.** p
27710 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74  arameter and ret
27720 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 6f 72  urns true (1) or
27730 20 66 61 6c 73 65 20 28 30 29 20 61 63 63 6f 72   false (0) accor
27740 64 69 6e 67 20 74 6f 20 74 68 65 20 76 61 6c 75  ding to the valu
27750 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68 65 20  e.** of P.  The 
27760 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
27770 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69  ean(F,P,B) routi
27780 6e 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20  ne returns true 
27790 28 31 29 20 69 66 20 74 68 65 0a 2a 2a 20 76 61  (1) if the.** va
277a0 6c 75 65 20 6f 66 20 71 75 65 72 79 20 70 61 72  lue of query par
277b0 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20  ameter P is one 
277c0 6f 66 20 22 79 65 73 22 2c 20 22 74 72 75 65 22  of "yes", "true"
277d0 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20 61 6e 79  , or "on" in any
277e0 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69 66 20 74  .** case or if t
277f0 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20  he value begins 
27800 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20  with a non-zero 
27810 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 0a 2a 2a  number.  The .**
27820 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
27830 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74  lean(F,P,B) rout
27840 69 6e 65 73 20 72 65 74 75 72 6e 73 20 66 61 6c  ines returns fal
27850 73 65 20 28 30 29 20 69 66 20 74 68 65 20 76 61  se (0) if the va
27860 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65 72 79 20  lue of.** query 
27870 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f  parameter P is o
27880 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22 66 61 6c  ne of "no", "fal
27890 73 65 22 2c 20 6f 72 20 22 6f 66 66 22 20 69 6e  se", or "off" in
278a0 20 61 6e 79 20 63 61 73 65 20 6f 72 0a 2a 2a 20   any case or.** 
278b0 69 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 67  if the value beg
278c0 69 6e 73 20 77 69 74 68 20 61 20 6e 75 6d 65 72  ins with a numer
278d0 69 63 20 7a 65 72 6f 2e 20 20 49 66 20 50 20 69  ic zero.  If P i
278e0 73 20 6e 6f 74 20 61 20 71 75 65 72 79 0a 2a 2a  s not a query.**
278f0 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 20   parameter on F 
27900 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  or if the value 
27910 6f 66 20 50 20 69 73 20 64 6f 65 73 20 6e 6f 74  of P is does not
27920 20 6d 61 74 63 68 20 61 6e 79 20 6f 66 20 74 68   match any of th
27930 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 68 65 6e  e.** above, then
27940 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
27950 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75  lean(F,P,B) retu
27960 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a  rns (B!=0)..**.*
27970 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72  * The sqlite3_ur
27980 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29 20 72  i_int64(F,P,D) r
27990 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72 74 73 20  outine converts 
279a0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69  the value of P i
279b0 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69 74 20  nto a.** 64-bit 
279c0 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61  signed integer a
279d0 6e 64 20 72 65 74 75 72 6e 73 20 74 68 61 74 20  nd returns that 
279e0 69 6e 74 65 67 65 72 2c 20 6f 72 20 44 20 69 66  integer, or D if
279f0 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65   P does not.** e
27a00 78 69 73 74 2e 20 20 49 66 20 74 68 65 20 76 61  xist.  If the va
27a10 6c 75 65 20 6f 66 20 50 20 69 73 20 73 6f 6d 65  lue of P is some
27a20 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e  thing other than
27a30 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65   an integer, the
27a40 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72 65 74  n.** zero is ret
27a50 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66  urned..** .** If
27a60 20 46 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   F is a NULL poi
27a70 6e 74 65 72 2c 20 74 68 65 6e 20 73 71 6c 69 74  nter, then sqlit
27a80 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72  e3_uri_parameter
27a90 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 4e 55  (F,P) returns NU
27aa0 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65  LL and.** sqlite
27ab0 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c  3_uri_boolean(F,
27ac0 50 2c 42 29 20 72 65 74 75 72 6e 73 20 42 2e 20  P,B) returns B. 
27ad0 20 49 66 20 46 20 69 73 20 6e 6f 74 20 61 20 4e   If F is not a N
27ae0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 0a  ULL pointer and.
27af0 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61  ** is not a data
27b00 62 61 73 65 20 66 69 6c 65 20 70 61 74 68 6e 61  base file pathna
27b10 6d 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20  me pointer that 
27b20 53 51 4c 69 74 65 20 70 61 73 73 65 64 20 69 6e  SQLite passed in
27b30 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20  to the xOpen.** 
27b40 56 46 53 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e  VFS method, then
27b50 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
27b60 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
27b70 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70   undefined and p
27b80 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64 65 73  robably.** undes
27b90 69 72 61 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e 73 74  irable..*/.const
27ba0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 75   char *sqlite3_u
27bb0 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f 6e  ri_parameter(con
27bc0 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61  st char *zFilena
27bd0 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  me, const char *
27be0 7a 50 61 72 61 6d 29 3b 0a 69 6e 74 20 73 71 6c  zParam);.int sql
27bf0 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
27c00 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69  (const char *zFi
27c10 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  le, const char *
27c20 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62 44 65 66  zParam, int bDef
27c30 61 75 6c 74 29 3b 0a 73 71 6c 69 74 65 33 5f 69  ault);.sqlite3_i
27c40 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 72 69  nt64 sqlite3_uri
27c50 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20 63 68 61  _int64(const cha
27c60 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  r*, const char*,
27c70 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b   sqlite3_int64);
27c80 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
27c90 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41  F: Error Codes A
27ca0 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 20 4d  nd Messages.** M
27cb0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
27cc0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73  *.** ^If the mos
27cd0 74 20 72 65 63 65 6e 74 20 73 71 6c 69 74 65 33  t recent sqlite3
27ce0 5f 2a 20 41 50 49 20 63 61 6c 6c 20 61 73 73 6f  _* API call asso
27cf0 63 69 61 74 65 64 20 77 69 74 68 20 0a 2a 2a 20  ciated with .** 
27d00 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
27d10 74 69 6f 6e 5d 20 44 20 66 61 69 6c 65 64 2c 20  tion] D failed, 
27d20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
27d30 5f 65 72 72 63 6f 64 65 28 44 29 20 69 6e 74 65  _errcode(D) inte
27d40 72 66 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e 73  rface.** returns
27d50 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65   the numeric [re
27d60 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 5b 65  sult code] or [e
27d70 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
27d80 6f 64 65 5d 20 66 6f 72 20 74 68 61 74 0a 2a 2a  ode] for that.**
27d90 20 41 50 49 20 63 61 6c 6c 2e 0a 2a 2a 20 49 66   API call..** If
27da0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
27db0 20 41 50 49 20 63 61 6c 6c 20 77 61 73 20 73 75   API call was su
27dc0 63 63 65 73 73 66 75 6c 2c 0a 2a 2a 20 74 68 65  ccessful,.** the
27dd0 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  n the return val
27de0 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
27df0 65 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64  errcode() is und
27e00 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  efined..** ^The 
27e10 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
27e20 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e  _errcode().** in
27e30 74 65 72 66 61 63 65 20 69 73 20 74 68 65 20 73  terface is the s
27e40 61 6d 65 20 65 78 63 65 70 74 20 74 68 61 74 20  ame except that 
27e50 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  it always return
27e60 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e  s the .** [exten
27e70 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
27e80 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e   even when exten
27e90 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
27ea0 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64   are.** disabled
27eb0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
27ec0 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e  ite3_errmsg() an
27ed0 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  d sqlite3_errmsg
27ee0 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c  16() return Engl
27ef0 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20  ish-language.** 
27f00 74 65 78 74 20 74 68 61 74 20 64 65 73 63 72 69  text that descri
27f10 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61  bes the error, a
27f20 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f  s either UTF-8 o
27f30 72 20 55 54 46 2d 31 36 20 72 65 73 70 65 63 74  r UTF-16 respect
27f40 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f  ively..** ^(Memo
27f50 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65  ry to hold the e
27f60 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
27f70 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69  ing is managed i
27f80 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68  nternally..** Th
27f90 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f  e application do
27fa0 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77  es not need to w
27fb0 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65 65 69  orry about freei
27fc0 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a  ng the result..*
27fd0 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65  * However, the e
27fe0 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68  rror string migh
27ff0 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e  t be overwritten
28000 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   or deallocated 
28010 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74  by.** subsequent
28020 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20   calls to other 
28030 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
28040 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a   functions.)^.**
28050 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
28060 5f 65 72 72 73 74 72 28 29 20 69 6e 74 65 72 66  _errstr() interf
28070 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
28080 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65  English-language
28090 20 74 65 78 74 0a 2a 2a 20 74 68 61 74 20 64 65   text.** that de
280a0 73 63 72 69 62 65 73 20 74 68 65 20 5b 72 65 73  scribes the [res
280b0 75 6c 74 20 63 6f 64 65 5d 2c 20 61 73 20 55 54  ult code], as UT
280c0 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79  F-8..** ^(Memory
280d0 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72   to hold the err
280e0 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
280f0 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74  g is managed int
28100 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d  ernally.** and m
28110 75 73 74 20 6e 6f 74 20 62 65 20 66 72 65 65 64  ust not be freed
28120 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
28130 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65  ion)^..**.** Whe
28140 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64  n the serialized
28150 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
28160 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20  ] is in use, it 
28170 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20  might be the.** 
28180 63 61 73 65 20 74 68 61 74 20 61 20 73 65 63 6f  case that a seco
28190 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  nd error occurs 
281a0 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20 74 68  on a separate th
281b0 72 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a  read in between.
281c0 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74  ** the time of t
281d0 68 65 20 66 69 72 73 74 20 65 72 72 6f 72 20 61  he first error a
281e0 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74  nd the call to t
281f0 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e  hese interfaces.
28200 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61  .** When that ha
28210 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e  ppens, the secon
28220 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20  d error will be 
28230 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74  reported since t
28240 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63  hese.** interfac
28250 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74  es always report
28260 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
28270 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f   result.  To avo
28280 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68  id.** this, each
28290 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61   thread can obta
282a0 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73 65  in exclusive use
282b0 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
282c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a  e connection] D.
282d0 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b  ** by invoking [
282e0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e  sqlite3_mutex_en
282f0 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62  ter]([sqlite3_db
28300 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f  _mutex](D)) befo
28310 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20  re beginning.** 
28320 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76  to use D and inv
28330 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  oking [sqlite3_m
28340 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c  utex_leave]([sql
28350 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44  ite3_db_mutex](D
28360 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20  )) after.** all 
28370 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74  calls to the int
28380 65 72 66 61 63 65 73 20 6c 69 73 74 65 64 20 68  erfaces listed h
28390 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65  ere are complete
283a0 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69  d..**.** If an i
283b0 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77  nterface fails w
283c0 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53  ith SQLITE_MISUS
283d0 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68  E, that means th
283e0 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77  e interface.** w
283f0 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72  as invoked incor
28400 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 61 70  rectly by the ap
28410 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74  plication.  In t
28420 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a  hat case, the.**
28430 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20   error code and 
28440 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d  message may or m
28450 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a  ay not be set..*
28460 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72  /.int sqlite3_er
28470 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64  rcode(sqlite3 *d
28480 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  b);.int sqlite3_
28490 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
284a0 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63  (sqlite3 *db);.c
284b0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
284c0 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65  e3_errmsg(sqlite
284d0 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  3*);.const void 
284e0 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  *sqlite3_errmsg1
284f0 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e  6(sqlite3*);.con
28500 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
28510 5f 65 72 72 73 74 72 28 69 6e 74 29 3b 0a 0a 2f  _errstr(int);../
28520 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50  *.** CAPI3REF: P
28530 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
28540 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57  t Object.** KEYW
28550 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20  ORDS: {prepared 
28560 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70  statement} {prep
28570 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d  ared statements}
28580 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e  .**.** An instan
28590 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
285a0 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 20 73  t represents a s
285b0 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d  ingle SQL statem
285c0 65 6e 74 20 74 68 61 74 0a 2a 2a 20 68 61 73 20  ent that.** has 
285d0 62 65 65 6e 20 63 6f 6d 70 69 6c 65 64 20 69 6e  been compiled in
285e0 74 6f 20 62 69 6e 61 72 79 20 66 6f 72 6d 20 61  to binary form a
285f0 6e 64 20 69 73 20 72 65 61 64 79 20 74 6f 20 62  nd is ready to b
28600 65 20 65 76 61 6c 75 61 74 65 64 2e 0a 2a 2a 0a  e evaluated..**.
28610 2a 2a 20 54 68 69 6e 6b 20 6f 66 20 65 61 63 68  ** Think of each
28620 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61   SQL statement a
28630 73 20 61 20 73 65 70 61 72 61 74 65 20 63 6f 6d  s a separate com
28640 70 75 74 65 72 20 70 72 6f 67 72 61 6d 2e 20 20  puter program.  
28650 54 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20  The.** original 
28660 53 51 4c 20 74 65 78 74 20 69 73 20 73 6f 75 72  SQL text is sour
28670 63 65 20 63 6f 64 65 2e 20 20 41 20 70 72 65 70  ce code.  A prep
28680 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f  ared statement o
28690 62 6a 65 63 74 20 0a 2a 2a 20 69 73 20 74 68 65  bject .** is the
286a0 20 63 6f 6d 70 69 6c 65 64 20 6f 62 6a 65 63 74   compiled object
286b0 20 63 6f 64 65 2e 20 20 41 6c 6c 20 53 51 4c 20   code.  All SQL 
286c0 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
286d0 64 20 69 6e 74 6f 20 61 0a 2a 2a 20 70 72 65 70  d into a.** prep
286e0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 62  ared statement b
286f0 65 66 6f 72 65 20 69 74 20 63 61 6e 20 62 65 20  efore it can be 
28700 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c  run..**.** The l
28710 69 66 65 2d 63 79 63 6c 65 20 6f 66 20 61 20 70  ife-cycle of a p
28720 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
28730 74 20 6f 62 6a 65 63 74 20 75 73 75 61 6c 6c 79  t object usually
28740 20 67 6f 65 73 20 6c 69 6b 65 20 74 68 69 73 3a   goes like this:
28750 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c  .**.** <ol>.** <
28760 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65 20 70  li> Create the p
28770 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
28780 74 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b  t object using [
28790 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
287a0 76 32 28 29 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 42  v2()]..** <li> B
287b0 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 70  ind values to [p
287c0 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69 6e 67  arameters] using
287d0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
287e0 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e  d_*().**      in
287f0 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69  terfaces..** <li
28800 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79  > Run the SQL by
28810 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
28820 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72  3_step()] one or
28830 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20   more times..** 
28840 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20 70  <li> Reset the p
28850 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
28860 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
28870 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67  _reset()] then g
28880 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74  o back.**      t
28890 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68  o step 2.  Do th
288a0 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20  is zero or more 
288b0 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44  times..** <li> D
288c0 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63  estroy the objec
288d0 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
288e0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a  _finalize()]..**
288f0 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 74 79 70 65 64 65   </ol>.*/.typede
28900 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
28910 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74  _stmt sqlite3_st
28920 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  mt;../*.** CAPI3
28930 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69  REF: Run-time Li
28940 6d 69 74 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  mits.** METHOD: 
28950 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 28  sqlite3.**.** ^(
28960 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61  This interface a
28970 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f  llows the size o
28980 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72  f various constr
28990 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74  ucts to be limit
289a0 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65  ed.** on a conne
289b0 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74  ction by connect
289c0 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20  ion basis.  The 
289d0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
289e0 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62  is the.** [datab
289f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
28a00 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74  whose limit is t
28a10 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75 65 72  o be set or quer
28a20 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63  ied.  The.** sec
28a30 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
28a40 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d   one of the [lim
28a50 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74  it categories] t
28a60 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20  hat define a.** 
28a70 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75  class of constru
28a80 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c  cts to be size l
28a90 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68 69  imited.  The thi
28aa0 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rd parameter is 
28ab0 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74  the.** new limit
28ac0 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72   for that constr
28ad0 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66  uct.)^.**.** ^If
28ae0 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69   the new limit i
28af0 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d  s a negative num
28b00 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69  ber, the limit i
28b10 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20  s unchanged..** 
28b20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69 6d 69 74  ^(For each limit
28b30 20 63 61 74 65 67 6f 72 79 20 53 51 4c 49 54 45   category SQLITE
28b40 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f  _LIMIT_<i>NAME</
28b50 69 3e 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a  i> there is a .*
28b60 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64  * [limits | hard
28b70 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a   upper bound].**
28b80 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d   set at compile-
28b90 74 69 6d 65 20 62 79 20 61 20 43 20 70 72 65 70  time by a C prep
28ba0 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 63  rocessor macro c
28bb0 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73  alled.** [limits
28bc0 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69   | SQLITE_MAX_<i
28bd0 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28  >NAME</i>]..** (
28be0 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e  The "_LIMIT_" in
28bf0 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61   the name is cha
28c00 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e  nged to "_MAX_".
28c10 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73  ))^.** ^Attempts
28c20 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c   to increase a l
28c30 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20 68  imit above its h
28c40 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20  ard upper bound 
28c50 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20  are.** silently 
28c60 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65  truncated to the
28c70 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e   hard upper boun
28c80 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64  d..**.** ^Regard
28c90 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
28ca0 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74  or not the limit
28cb0 20 77 61 73 20 63 68 61 6e 67 65 64 2c 20 74 68   was changed, th
28cc0 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c  e .** [sqlite3_l
28cd0 69 6d 69 74 28 29 5d 20 69 6e 74 65 72 66 61 63  imit()] interfac
28ce0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 70 72  e returns the pr
28cf0 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 65  ior value of the
28d00 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63   limit..** ^Henc
28d10 65 2c 20 74 6f 20 66 69 6e 64 20 74 68 65 20 63  e, to find the c
28d20 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20  urrent value of 
28d30 61 20 6c 69 6d 69 74 20 77 69 74 68 6f 75 74 20  a limit without 
28d40 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20  changing it,.** 
28d50 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68  simply invoke th
28d60 69 73 20 69 6e 74 65 72 66 61 63 65 20 77 69 74  is interface wit
28d70 68 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  h the third para
28d80 6d 65 74 65 72 20 73 65 74 20 74 6f 20 2d 31 2e  meter set to -1.
28d90 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20  .**.** Run-time 
28da0 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e  limits are inten
28db0 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61  ded for use in a
28dc0 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
28dd0 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20   manage.** both 
28de0 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e  their own intern
28df0 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  al database and 
28e00 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20 74  also databases t
28e10 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c  hat are controll
28e20 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74  ed.** by untrust
28e30 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72  ed external sour
28e40 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65  ces.  An example
28e50 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67   application mig
28e60 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62  ht be a.** web b
28e70 72 6f 77 73 65 72 20 74 68 61 74 20 68 61 73 20  rowser that has 
28e80 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65  its own database
28e90 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69  s for storing hi
28ea0 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70  story and.** sep
28eb0 61 72 61 74 65 20 64 61 74 61 62 61 73 65 73 20  arate databases 
28ec0 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61  controlled by Ja
28ed0 76 61 53 63 72 69 70 74 20 61 70 70 6c 69 63 61  vaScript applica
28ee0 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64  tions downloaded
28ef0 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65  .** off the Inte
28f00 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72  rnet.  The inter
28f10 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20 63 61  nal databases ca
28f20 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a  n be given the.*
28f30 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74  * large, default
28f40 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61   limits.  Databa
28f50 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65  ses managed by e
28f60 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20  xternal sources 
28f70 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20  can.** be given 
28f80 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d  much smaller lim
28f90 69 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20  its designed to 
28fa0 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c  prevent a denial
28fb0 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61   of service.** a
28fc0 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65  ttack.  Develope
28fd0 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61  rs might also wa
28fe0 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73  nt to use the [s
28ff0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
29000 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65  rizer()].** inte
29010 72 66 61 63 65 20 74 6f 20 66 75 72 74 68 65 72  rface to further
29020 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74   control untrust
29030 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a  ed SQL.  The siz
29040 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
29050 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20  e.** created by 
29060 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63 72  an untrusted scr
29070 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61  ipt can be conta
29080 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a  ined using the.*
29090 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e  * [max_page_coun
290a0 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a  t] [PRAGMA]..**.
290b0 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20  ** New run-time 
290c0 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
290d0 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
290e0 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
290f0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
29100 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c  _limit(sqlite3*,
29110 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77   int id, int new
29120 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  Val);../*.** CAP
29130 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20  I3REF: Run-Time 
29140 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73  Limit Categories
29150 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c  .** KEYWORDS: {l
29160 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b  imit category} {
29170 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65  *limit categorie
29180 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  s}.**.** These c
29190 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20  onstants define 
291a0 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61  various performa
291b0 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68  nce limits.** th
291c0 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65  at can be lowere
291d0 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73  d at run-time us
291e0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  ing [sqlite3_lim
291f0 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79  it()]..** The sy
29200 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65  nopsis of the me
29210 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61  anings of the va
29220 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20  rious limits is 
29230 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20  shown below..** 
29240 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  Additional infor
29250 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61  mation is availa
29260 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c  ble at [limits |
29270 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74   Limits in SQLit
29280 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  e]..**.** <dl>.*
29290 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
292a0 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e  _LENGTH]] ^(<dt>
292b0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
292c0 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
292d0 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65  The maximum size
292e0 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f   of any string o
292f0 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20  r BLOB or table 
29300 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64  row, in bytes.<d
29310 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
29320 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
29330 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  NGTH]] ^(<dt>SQL
29340 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
29350 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
29360 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e  >The maximum len
29370 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74  gth of an SQL st
29380 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65  atement, in byte
29390 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  s.</dd>)^.**.** 
293a0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  [[SQLITE_LIMIT_C
293b0 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51  OLUMN]] ^(<dt>SQ
293c0 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
293d0 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  N</dt>.** <dd>Th
293e0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
293f0 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
29400 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f   table definitio
29410 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72  n or in the.** r
29420 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b  esult set of a [
29430 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d  SELECT] or the m
29440 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
29450 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69   columns in an i
29460 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e  ndex.** or in an
29470 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f   ORDER BY or GRO
29480 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64  UP BY clause.</d
29490 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
294a0 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44  ITE_LIMIT_EXPR_D
294b0 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  EPTH]] ^(<dt>SQL
294c0 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44  ITE_LIMIT_EXPR_D
294d0 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  EPTH</dt>.** <dd
294e0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70  >The maximum dep
294f0 74 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 20  th of the parse 
29500 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72  tree on any expr
29510 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a  ession.</dd>)^.*
29520 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
29530 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c  MIT_COMPOUND_SEL
29540 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  ECT]] ^(<dt>SQLI
29550 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e  TE_LIMIT_COMPOUN
29560 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a  D_SELECT</dt>.**
29570 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
29580 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73   number of terms
29590 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53   in a compound S
295a0 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e  ELECT statement.
295b0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
295c0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
295d0 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  E_OP]] ^(<dt>SQL
295e0 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f  ITE_LIMIT_VDBE_O
295f0 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  P</dt>.** <dd>Th
29600 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
29610 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73   of instructions
29620 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61   in a virtual ma
29630 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a  chine program.**
29640 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
29650 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  nt an SQL statem
29660 65 6e 74 2e 20 20 49 66 20 5b 73 71 6c 69 74 65  ent.  If [sqlite
29670 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
29680 6f 72 0a 2a 2a 20 74 68 65 20 65 71 75 69 76 61  or.** the equiva
29690 6c 65 6e 74 20 74 72 69 65 73 20 74 6f 20 61 6c  lent tries to al
296a0 6c 6f 63 61 74 65 20 73 70 61 63 65 20 66 6f 72  locate space for
296b0 20 6d 6f 72 65 20 74 68 61 6e 20 74 68 69 73 20   more than this 
296c0 6d 61 6e 79 20 6f 70 63 6f 64 65 73 0a 2a 2a 20  many opcodes.** 
296d0 69 6e 20 61 20 73 69 6e 67 6c 65 20 70 72 65 70  in a single prep
296e0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 2c 20  ared statement, 
296f0 61 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20  an SQLITE_NOMEM 
29700 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
29710 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  d.</dd>)^.**.** 
29720 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  [[SQLITE_LIMIT_F
29730 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28  UNCTION_ARG]] ^(
29740 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
29750 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64  _FUNCTION_ARG</d
29760 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
29770 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
29780 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66  arguments on a f
29790 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a  unction.</dd>)^.
297a0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
297b0 49 4d 49 54 5f 41 54 54 41 43 48 45 44 5d 5d 20  IMIT_ATTACHED]] 
297c0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
297d0 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e  IT_ATTACHED</dt>
297e0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
297f0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41  mum number of [A
29800 54 54 41 43 48 20 7c 20 61 74 74 61 63 68 65 64  TTACH | attached
29810 20 64 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f   databases].)^</
29820 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
29830 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41  TE_LIMIT_LIKE_PA
29840 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a  TTERN_LENGTH]].*
29850 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  * ^(<dt>SQLITE_L
29860 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52  IMIT_LIKE_PATTER
29870 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a  N_LENGTH</dt>.**
29880 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
29890 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70   length of the p
298a0 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20  attern argument 
298b0 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72  to the [LIKE] or
298c0 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61  .** [GLOB] opera
298d0 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  tors.</dd>)^.**.
298e0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
298f0 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
29900 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c  R]].** ^(<dt>SQL
29910 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
29920 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a  LE_NUMBER</dt>.*
29930 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
29940 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f  m index number o
29950 66 20 61 6e 79 20 5b 70 61 72 61 6d 65 74 65 72  f any [parameter
29960 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  ] in an SQL stat
29970 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  ement.)^.**.** [
29980 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52  [SQLITE_LIMIT_TR
29990 49 47 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28  IGGER_DEPTH]] ^(
299a0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
299b0 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f  _TRIGGER_DEPTH</
299c0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
299d0 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20  aximum depth of 
299e0 72 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72  recursion for tr
299f0 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a  iggers.</dd>)^.*
29a00 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
29a10 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41  MIT_WORKER_THREA
29a20 44 53 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  DS]] ^(<dt>SQLIT
29a30 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54  E_LIMIT_WORKER_T
29a40 48 52 45 41 44 53 3c 2f 64 74 3e 0a 2a 2a 20 3c  HREADS</dt>.** <
29a50 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
29a60 75 6d 62 65 72 20 6f 66 20 61 75 78 69 6c 69 61  umber of auxilia
29a70 72 79 20 77 6f 72 6b 65 72 20 74 68 72 65 61 64  ry worker thread
29a80 73 20 74 68 61 74 20 61 20 73 69 6e 67 6c 65 0a  s that a single.
29a90 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
29aa0 74 65 6d 65 6e 74 5d 20 6d 61 79 20 73 74 61 72  tement] may star
29ab0 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64  t.</dd>)^.** </d
29ac0 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
29ad0 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
29ae0 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
29af0 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53       0.#define S
29b00 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f  QLITE_LIMIT_SQL_
29b10 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20  LENGTH          
29b20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
29b30 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
29b40 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 20  UMN             
29b50 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
29b60 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58   SQLITE_LIMIT_EX
29b70 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20  PR_DEPTH        
29b80 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e          3.#defin
29b90 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  e SQLITE_LIMIT_C
29ba0 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20  OMPOUND_SELECT  
29bb0 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69           4.#defi
29bc0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
29bd0 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20  VDBE_OP         
29be0 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66            5.#def
29bf0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
29c00 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20  _FUNCTION_ARG   
29c10 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65             6.#de
29c20 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
29c30 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 20  T_ATTACHED      
29c40 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64              7.#d
29c50 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
29c60 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
29c70 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23  LENGTH       8.#
29c80 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
29c90 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
29ca0 42 45 52 20 20 20 20 20 20 20 20 20 20 20 39 0a  BER           9.
29cb0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
29cc0 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50  IMIT_TRIGGER_DEP
29cd0 54 48 20 20 20 20 20 20 20 20 20 20 20 20 31 30  TH            10
29ce0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
29cf0 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52  LIMIT_WORKER_THR
29d00 45 41 44 53 20 20 20 20 20 20 20 20 20 20 20 31  EADS           1
29d10 31 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  1.../*.** CAPI3R
29d20 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e  EF: Compiling An
29d30 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a   SQL Statement.*
29d40 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c  * KEYWORDS: {SQL
29d50 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69   statement compi
29d60 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ler}.** METHOD: 
29d70 73 71 6c 69 74 65 33 0a 2a 2a 20 43 4f 4e 53 54  sqlite3.** CONST
29d80 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 5f  RUCTOR: sqlite3_
29d90 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78  stmt.**.** To ex
29da0 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65  ecute an SQL que
29db0 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73  ry, it must firs
29dc0 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e  t be compiled in
29dd0 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a  to a byte-code.*
29de0 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20  * program using 
29df0 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75  one of these rou
29e00 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tines..**.** The
29e10 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c   first argument,
29e20 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74   "db", is a [dat
29e30 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
29e40 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  ] obtained from 
29e50 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65  a.** prior succe
29e60 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
29e70 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
29e80 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
29e90 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
29ea0 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54  e3_open16()].  T
29eb0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
29ec0 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  ection must not 
29ed0 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64  have been closed
29ee0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ..**.** The seco
29ef0 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53  nd argument, "zS
29f00 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61 74  ql", is the stat
29f10 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70  ement to be comp
29f20 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a  iled, encoded.**
29f30 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38   as either UTF-8
29f40 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65   or UTF-16.  The
29f50 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
29f60 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  () and sqlite3_p
29f70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69  repare_v2().** i
29f80 6e 74 65 72 66 61 63 65 73 20 75 73 65 20 55 54  nterfaces use UT
29f90 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33  F-8, and sqlite3
29fa0 5f 70 72 65 70 61 72 65 31 36 28 29 20 61 6e 64  _prepare16() and
29fb0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
29fc0 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55  16_v2().** use U
29fd0 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  TF-16..**.** ^If
29fe0 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d   the nByte argum
29ff0 65 6e 74 20 69 73 20 6e 65 67 61 74 69 76 65 2c  ent is negative,
2a000 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65   then zSql is re
2a010 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20  ad up to the.** 
2a020 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
2a030 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65  nator. ^If nByte
2a040 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20 74 68   is positive, th
2a050 65 6e 20 69 74 20 69 73 20 74 68 65 0a 2a 2a 20  en it is the.** 
2a060 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
2a070 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20  read from zSql. 
2a080 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 7a 65   ^If nByte is ze
2a090 72 6f 2c 20 74 68 65 6e 20 6e 6f 20 70 72 65 70  ro, then no prep
2a0a0 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  ared.** statemen
2a0b0 74 20 69 73 20 67 65 6e 65 72 61 74 65 64 2e 0a  t is generated..
2a0c0 2a 2a 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72  ** If the caller
2a0d0 20 6b 6e 6f 77 73 20 74 68 61 74 20 74 68 65 20   knows that the 
2a0e0 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20  supplied string 
2a0f0 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65  is nul-terminate
2a100 64 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 72 65  d, then.** there
2a110 20 69 73 20 61 20 73 6d 61 6c 6c 20 70 65 72 66   is a small perf
2a120 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67  ormance advantag
2a130 65 20 74 6f 20 70 61 73 73 69 6e 67 20 61 6e 20  e to passing an 
2a140 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65 72 20  nByte parameter 
2a150 74 68 61 74 0a 2a 2a 20 69 73 20 74 68 65 20 6e  that.** is the n
2a160 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
2a170 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  n the input stri
2a180 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c  ng <i>including<
2a190 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74  /i>.** the nul-t
2a1a0 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a  erminator..**.**
2a1b0 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 73 20 6e   ^If pzTail is n
2a1c0 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a  ot NULL then *pz
2a1d0 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20  Tail is made to 
2a1e0 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72  point to the fir
2a1f0 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 20  st byte.** past 
2a200 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66  the end of the f
2a210 69 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65  irst SQL stateme
2a220 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65  nt in zSql.  The
2a230 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79  se routines only
2a240 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 20  .** compile the 
2a250 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74 20  first statement 
2a260 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54  in zSql, so *pzT
2a270 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e  ail is left poin
2a280 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20  ting to.** what 
2a290 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c  remains uncompil
2a2a0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74  ed..**.** ^*ppSt
2a2b0 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74  mt is left point
2a2c0 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65  ing to a compile
2a2d0 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
2a2e0 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20  ement] that can 
2a2f0 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75  be.** executed u
2a300 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74  sing [sqlite3_st
2a310 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 72  ep()].  ^If ther
2a320 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a  e is an error, *
2a330 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a  ppStmt is set.**
2a340 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74   to NULL.  ^If t
2a350 68 65 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f  he input text co
2a360 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69  ntains no SQL (i
2a370 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 20 61  f the input is a
2a380 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e  n empty.** strin
2a390 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20  g or a comment) 
2a3a0 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20  then *ppStmt is 
2a3b0 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20  set to NULL..** 
2a3c0 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63  The calling proc
2a3d0 65 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73  edure is respons
2a3e0 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e  ible for deletin
2a3f0 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a  g the compiled.*
2a400 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  * SQL statement 
2a410 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
2a420 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72  inalize()] after
2a430 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64   it has finished
2a440 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53   with it..** ppS
2a450 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e  tmt may not be N
2a460 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73  ULL..**.** ^On s
2a470 75 63 63 65 73 73 2c 20 74 68 65 20 73 71 6c 69  uccess, the sqli
2a480 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 66 61  te3_prepare() fa
2a490 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65 73  mily of routines
2a4a0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
2a4b0 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73  OK];.** otherwis
2a4c0 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  e an [error code
2a4d0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  ] is returned..*
2a4e0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
2a4f0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e  _prepare_v2() an
2a500 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
2a510 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61  e16_v2() interfa
2a520 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d  ces are.** recom
2a530 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e  mended for all n
2a540 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65  ew programs. The
2a550 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72   two older inter
2a560 66 61 63 65 73 20 61 72 65 20 72 65 74 61 69 6e  faces are retain
2a570 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61  ed.** for backwa
2a580 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
2a590 79 2c 20 62 75 74 20 74 68 65 69 72 20 75 73 65  y, but their use
2a5a0 20 69 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e   is discouraged.
2a5b0 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 32 22  .** ^In the "v2"
2a5c0 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65   interfaces, the
2a5d0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2a5e0 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72  ent.** that is r
2a5f0 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71  eturned (the [sq
2a600 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65  lite3_stmt] obje
2a610 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63  ct) contains a c
2a620 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72  opy of the.** or
2a630 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e  iginal SQL text.
2a640 20 54 68 69 73 20 63 61 75 73 65 73 20 74 68 65   This causes the
2a650 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2a660 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a  ] interface to.*
2a670 2a 20 62 65 68 61 76 65 20 64 69 66 66 65 72 65  * behave differe
2a680 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77 61  ntly in three wa
2a690 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a  ys:.**.** <ol>.*
2a6a0 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68  * <li>.** ^If th
2a6b0 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
2a6c0 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65  a changes, inste
2a6d0 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20  ad of returning 
2a6e0 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20  [SQLITE_SCHEMA] 
2a6f0 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20  as it.** always 
2a700 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c  used to do, [sql
2a710 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c  ite3_step()] wil
2a720 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  l automatically 
2a730 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51  recompile the SQ
2a740 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61  L.** statement a
2a750 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74  nd try to run it
2a760 20 61 67 61 69 6e 2e 20 41 73 20 6d 61 6e 79 20   again. As many 
2a770 61 73 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 53  as [SQLITE_MAX_S
2a780 43 48 45 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a 20  CHEMA_RETRY].** 
2a790 72 65 74 72 69 65 73 20 77 69 6c 6c 20 6f 63 63  retries will occ
2a7a0 75 72 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65  ur before sqlite
2a7b0 33 5f 73 74 65 70 28 29 20 67 69 76 65 73 20 75  3_step() gives u
2a7c0 70 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 6e  p and returns an
2a7d0 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e   error..** </li>
2a7e0 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e  .**.** <li>.** ^
2a7f0 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63  When an error oc
2a800 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73  curs, [sqlite3_s
2a810 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  tep()] will retu
2a820 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65  rn one of the de
2a830 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72  tailed.** [error
2a840 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65   codes] or [exte
2a850 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73  nded error codes
2a860 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 79 20  ].  ^The legacy 
2a870 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 61  behavior was tha
2a880 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  t.** [sqlite3_st
2a890 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79  ep()] would only
2a8a0 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69   return a generi
2a8b0 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  c [SQLITE_ERROR]
2a8c0 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20   result code.** 
2a8d0 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  and the applicat
2a8e0 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 74  ion would have t
2a8f0 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20  o make a second 
2a900 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2a910 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20  _reset()].** in 
2a920 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68  order to find th
2a930 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75  e underlying cau
2a940 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65  se of the proble
2a950 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76 32 22  m. With the "v2"
2a960 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65   prepare.** inte
2a970 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65  rfaces, the unde
2a980 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f  rlying reason fo
2a990 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 20 72  r the error is r
2a9a0 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74  eturned immediat
2a9b0 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  ely..** </li>.**
2a9c0 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20  .** <li>.** ^If 
2a9d0 74 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c  the specific val
2a9e0 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72  ue bound to [par
2a9f0 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 70 61  ameter | host pa
2aa00 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20  rameter] in the 
2aa10 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65  .** WHERE clause
2aa20 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65   might influence
2aa30 20 74 68 65 20 63 68 6f 69 63 65 20 6f 66 20 71   the choice of q
2aa40 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 20  uery plan for a 
2aa50 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68  statement,.** th
2aa60 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  en the statement
2aa70 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74   will be automat
2aa80 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65  ically recompile
2aa90 64 2c 20 61 73 20 69 66 20 74 68 65 72 65 20 68  d, as if there h
2aaa0 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63  ad been .** a sc
2aab0 68 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20  hema change, on 
2aac0 74 68 65 20 66 69 72 73 74 20 20 5b 73 71 6c 69  the first  [sqli
2aad0 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c  te3_step()] call
2aae0 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63   following any c
2aaf0 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20  hange.** to the 
2ab00 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65  [sqlite3_bind_te
2ab10 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f  xt | bindings] o
2ab20 66 20 74 68 61 74 20 5b 70 61 72 61 6d 65 74 65  f that [paramete
2ab30 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65  r]. .** ^The spe
2ab40 63 69 66 69 63 20 76 61 6c 75 65 20 6f 66 20 57  cific value of W
2ab50 48 45 52 45 2d 63 6c 61 75 73 65 20 5b 70 61 72  HERE-clause [par
2ab60 61 6d 65 74 65 72 5d 20 6d 69 67 68 74 20 69 6e  ameter] might in
2ab70 66 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20  fluence the .** 
2ab80 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20  choice of query 
2ab90 70 6c 61 6e 20 69 66 20 74 68 65 20 70 61 72 61  plan if the para
2aba0 6d 65 74 65 72 20 69 73 20 74 68 65 20 6c 65 66  meter is the lef
2abb0 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 61  t-hand side of a
2abc0 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47   [LIKE].** or [G
2abd0 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72  LOB] operator or
2abe0 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
2abf0 72 20 69 73 20 63 6f 6d 70 61 72 65 64 20 74 6f  r is compared to
2ac00 20 61 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c 75   an indexed colu
2ac10 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53  mn.** and the [S
2ac20 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41  QLITE_ENABLE_STA
2ac30 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  T3] compile-time
2ac40 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c   option is enabl
2ac50 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20  ed..** </li>.** 
2ac60 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  </ol>.*/.int sql
2ac70 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20  ite3_prepare(.  
2ac80 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
2ac90 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
2aca0 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
2acb0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
2acc0 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
2acd0 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20  tatement, UTF-8 
2ace0 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
2acf0 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
2ad00 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
2ad10 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
2ad20 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
2ad30 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
2ad40 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
2ad50 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
2ad60 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
2ad70 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
2ad80 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
2ad90 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
2ada0 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20   zSql */.);.int 
2adb0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2adc0 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  sqlite3 *d
2add0 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
2ade0 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
2adf0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
2ae00 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
2ae10 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
2ae20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f  UTF-8 encoded */
2ae30 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
2ae40 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
2ae50 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
2ae60 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
2ae70 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
2ae80 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
2ae90 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
2aea0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2aeb0 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20  char **pzTail   
2aec0 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
2aed0 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
2aee0 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
2aef0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  ;.int sqlite3_pr
2af00 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74  epare16(.  sqlit
2af10 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
2af20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
2af30 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
2af40 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20   void *zSql,    
2af50 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
2af60 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f  ent, UTF-16 enco
2af70 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
2af80 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
2af90 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
2afa0 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
2afb0 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
2afc0 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
2afd0 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
2afe0 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
2aff0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54  const void **pzT
2b000 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
2b010 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
2b020 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
2b030 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  l */.);.int sqli
2b040 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
2b050 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
2b060 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
2b070 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
2b080 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
2b090 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
2b0a0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
2b0b0 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  F-16 encoded */.
2b0c0 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
2b0d0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
2b0e0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
2b0f0 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
2b100 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
2b110 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
2b120 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
2b130 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
2b140 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  oid **pzTail    
2b150 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
2b160 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
2b170 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
2b180 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2b190 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 74 61  : Retrieving Sta
2b1a0 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 20 4d 45  tement SQL.** ME
2b1b0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
2b1c0 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  mt.**.** ^The sq
2b1d0 6c 69 74 65 33 5f 73 71 6c 28 50 29 20 69 6e 74  lite3_sql(P) int
2b1e0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
2b1f0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 63 6f   pointer to a co
2b200 70 79 20 6f 66 20 74 68 65 20 55 54 46 2d 38 0a  py of the UTF-8.
2b210 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 64  ** SQL text used
2b220 20 74 6f 20 63 72 65 61 74 65 20 5b 70 72 65 70   to create [prep
2b230 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2b240 50 20 69 66 20 50 20 77 61 73 0a 2a 2a 20 63 72  P if P was.** cr
2b250 65 61 74 65 64 20 62 79 20 65 69 74 68 65 72 20  eated by either 
2b260 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2b270 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v2()] or [sqlit
2b280 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2b290 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  )]..** ^The sqli
2b2a0 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c  te3_expanded_sql
2b2b0 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (P) interface re
2b2c0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
2b2d0 74 6f 20 61 20 55 54 46 2d 38 0a 2a 2a 20 73 74  to a UTF-8.** st
2b2e0 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ring containing 
2b2f0 74 68 65 20 53 51 4c 20 74 65 78 74 20 6f 66 20  the SQL text of 
2b300 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2b310 6e 74 20 50 20 77 69 74 68 0a 2a 2a 20 5b 62 6f  nt P with.** [bo
2b320 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 5d 20  und parameters] 
2b330 65 78 70 61 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20  expanded..**.** 
2b340 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69  ^(For example, i
2b350 66 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61  f a prepared sta
2b360 74 65 6d 65 6e 74 20 69 73 20 63 72 65 61 74 65  tement is create
2b370 64 20 75 73 69 6e 67 20 74 68 65 20 53 51 4c 0a  d using the SQL.
2b380 2a 2a 20 74 65 78 74 20 22 53 45 4c 45 43 54 20  ** text "SELECT 
2b390 24 61 62 63 2c 3a 78 79 7a 22 20 61 6e 64 20 69  $abc,:xyz" and i
2b3a0 66 20 70 61 72 61 6d 65 74 65 72 20 24 61 62 63  f parameter $abc
2b3b0 20 69 73 20 62 6f 75 6e 64 20 74 6f 20 69 6e 74   is bound to int
2b3c0 65 67 65 72 20 32 33 34 35 0a 2a 2a 20 61 6e 64  eger 2345.** and
2b3d0 20 70 61 72 61 6d 65 74 65 72 20 3a 78 79 7a 20   parameter :xyz 
2b3e0 69 73 20 75 6e 62 6f 75 6e 64 2c 20 74 68 65 6e  is unbound, then
2b3f0 20 73 71 6c 69 74 65 33 5f 73 71 6c 28 29 20 77   sqlite3_sql() w
2b400 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68  ill return.** th
2b410 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 72 69 6e  e original strin
2b420 67 2c 20 22 53 45 4c 45 43 54 20 24 61 62 63 2c  g, "SELECT $abc,
2b430 3a 78 79 7a 22 20 62 75 74 20 73 71 6c 69 74 65  :xyz" but sqlite
2b440 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 29  3_expanded_sql()
2b450 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  .** will return 
2b460 22 53 45 4c 45 43 54 20 32 33 34 35 2c 4e 55 4c  "SELECT 2345,NUL
2b470 4c 22 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  L".)^.**.** ^The
2b480 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65   sqlite3_expande
2b490 64 5f 73 71 6c 28 29 20 69 6e 74 65 72 66 61 63  d_sql() interfac
2b4a0 65 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69  e returns NULL i
2b4b0 66 20 69 6e 73 75 66 66 69 63 69 65 6e 74 20 6d  f insufficient m
2b4c0 65 6d 6f 72 79 0a 2a 2a 20 69 73 20 61 76 61 69  emory.** is avai
2b4d0 6c 61 62 6c 65 20 74 6f 20 68 6f 6c 64 20 74 68  lable to hold th
2b4e0 65 20 72 65 73 75 6c 74 2c 20 6f 72 20 69 66 20  e result, or if 
2b4f0 74 68 65 20 72 65 73 75 6c 74 20 77 6f 75 6c 64  the result would
2b500 20 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 74   exceed the.** t
2b510 68 65 20 6d 61 78 69 6d 75 6d 20 73 74 72 69 6e  he maximum strin
2b520 67 20 6c 65 6e 67 74 68 20 64 65 74 65 72 6d 69  g length determi
2b530 6e 65 64 20 62 79 20 74 68 65 20 5b 53 51 4c 49  ned by the [SQLI
2b540 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d  TE_LIMIT_LENGTH]
2b550 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ..**.** ^The [SQ
2b560 4c 49 54 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f  LITE_TRACE_SIZE_
2b570 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74  LIMIT] compile-t
2b580 69 6d 65 20 6f 70 74 69 6f 6e 20 6c 69 6d 69 74  ime option limit
2b590 73 20 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a  s the size of.**
2b5a0 20 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72   bound parameter
2b5b0 20 65 78 70 61 6e 73 69 6f 6e 73 2e 20 20 5e 54   expansions.  ^T
2b5c0 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  he [SQLITE_OMIT_
2b5d0 54 52 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74  TRACE] compile-t
2b5e0 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 63 61  ime.** option ca
2b5f0 75 73 65 73 20 73 71 6c 69 74 65 33 5f 65 78 70  uses sqlite3_exp
2b600 61 6e 64 65 64 5f 73 71 6c 28 29 20 74 6f 20 61  anded_sql() to a
2b610 6c 77 61 79 73 20 72 65 74 75 72 6e 20 4e 55 4c  lways return NUL
2b620 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 74  L..**.** ^The st
2b630 72 69 6e 67 20 72 65 74 75 72 6e 65 64 20 62 79  ring returned by
2b640 20 73 71 6c 69 74 65 33 5f 73 71 6c 28 50 29 20   sqlite3_sql(P) 
2b650 69 73 20 6d 61 6e 61 67 65 64 20 62 79 20 53 51  is managed by SQ
2b660 4c 69 74 65 20 61 6e 64 20 69 73 0a 2a 2a 20 61  Lite and is.** a
2b670 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65  utomatically fre
2b680 65 64 20 77 68 65 6e 20 74 68 65 20 70 72 65 70  ed when the prep
2b690 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69  ared statement i
2b6a0 73 20 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a 20  s finalized..** 
2b6b0 5e 54 68 65 20 73 74 72 69 6e 67 20 72 65 74 75  ^The string retu
2b6c0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
2b6d0 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 50 29 2c  expanded_sql(P),
2b6e0 20 6f 6e 20 74 68 65 20 6f 74 68 65 72 20 68 61   on the other ha
2b6f0 6e 64 2c 0a 2a 2a 20 69 73 20 6f 62 74 61 69 6e  nd,.** is obtain
2b700 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
2b710 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 6d  _malloc()] and m
2b720 75 73 74 20 62 65 20 66 72 65 65 20 62 79 20 74  ust be free by t
2b730 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a  he application.*
2b740 2a 20 62 79 20 70 61 73 73 69 6e 67 20 69 74 20  * by passing it 
2b750 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  to [sqlite3_free
2b760 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ()]..*/.const ch
2b770 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28  ar *sqlite3_sql(
2b780 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
2b790 74 6d 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69  tmt);.char *sqli
2b7a0 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c  te3_expanded_sql
2b7b0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
2b7c0 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
2b7d0 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e  PI3REF: Determin
2b7e0 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74  e If An SQL Stat
2b7f0 65 6d 65 6e 74 20 57 72 69 74 65 73 20 54 68 65  ement Writes The
2b800 20 44 61 74 61 62 61 73 65 0a 2a 2a 20 4d 45 54   Database.** MET
2b810 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
2b820 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
2b830 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
2b840 6c 79 28 58 29 20 69 6e 74 65 72 66 61 63 65 20  ly(X) interface 
2b850 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f  returns true (no
2b860 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e  n-zero) if.** an
2b870 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70  d only if the [p
2b880 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2b890 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69  t] X makes no di
2b8a0 72 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a  rect changes to.
2b8b0 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  ** the content o
2b8c0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  f the database f
2b8d0 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  ile..**.** Note 
2b8e0 74 68 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f  that [applicatio
2b8f0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
2b900 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b  nctions] or.** [
2b910 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20  virtual tables] 
2b920 6d 69 67 68 74 20 63 68 61 6e 67 65 20 74 68 65  might change the
2b930 20 64 61 74 61 62 61 73 65 20 69 6e 64 69 72 65   database indire
2b940 63 74 6c 79 20 61 73 20 61 20 73 69 64 65 20 65  ctly as a side e
2b950 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f  ffect.  .** ^(Fo
2b960 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e  r example, if an
2b970 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
2b980 69 6e 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20  ines a function 
2b990 22 65 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a  "eval()" that .*
2b9a0 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33  * calls [sqlite3
2b9b0 5f 65 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74  _exec()], then t
2b9c0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c  he following SQL
2b9d0 20 73 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64   statement would
2b9e0 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64  .** change the d
2b9f0 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 72  atabase file thr
2ba00 6f 75 67 68 20 73 69 64 65 2d 65 66 66 65 63 74  ough side-effect
2ba10 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
2ba20 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
2ba30 20 53 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45   SELECT eval('DE
2ba40 4c 45 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46  LETE FROM t1') F
2ba50 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65  ROM t2;.** </pre
2ba60 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
2ba70 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65  *.** But because
2ba80 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74   the [SELECT] st
2ba90 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74  atement does not
2baa0 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61   change the data
2bab0 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72  base file.** dir
2bac0 65 63 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73  ectly, sqlite3_s
2bad0 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77  tmt_readonly() w
2bae0 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72  ould still retur
2baf0 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  n true.)^.**.** 
2bb00 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e  ^Transaction con
2bb10 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20  trol statements 
2bb20 73 75 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c  such as [BEGIN],
2bb30 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c   [COMMIT], [ROLL
2bb40 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50  BACK],.** [SAVEP
2bb50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45  OINT], and [RELE
2bb60 41 53 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74  ASE] cause sqlit
2bb70 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
2bb80 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75  () to return tru
2bb90 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20  e,.** since the 
2bba0 73 74 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73  statements thems
2bbb0 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74  elves do not act
2bbc0 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65  ually modify the
2bbd0 20 64 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a   database but.**
2bbe0 20 72 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e   rather they con
2bbf0 74 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20  trol the timing 
2bc00 6f 66 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74  of when other st
2bc10 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20  atements modify 
2bc20 74 68 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65  the .** database
2bc30 2e 20 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d  .  ^The [ATTACH]
2bc40 20 61 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74   and [DETACH] st
2bc50 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61  atements also ca
2bc60 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  use.** sqlite3_s
2bc70 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74  tmt_readonly() t
2bc80 6f 20 72 65 74 75 72 6e 20 74 72 75 65 20 73 69  o return true si
2bc90 6e 63 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65  nce, while those
2bca0 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63   statements.** c
2bcb0 68 61 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67  hange the config
2bcc0 75 72 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74  uration of a dat
2bcd0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2bce0 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61  , they do not ma
2bcf0 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74  ke .** changes t
2bd00 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  o the content of
2bd10 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
2bd20 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2a 20  les on disk..** 
2bd30 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d  ^The sqlite3_stm
2bd40 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 69 6e 74  t_readonly() int
2bd50 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
2bd60 72 75 65 20 66 6f 72 20 5b 42 45 47 49 4e 5d 20  rue for [BEGIN] 
2bd70 73 69 6e 63 65 0a 2a 2a 20 5b 42 45 47 49 4e 5d  since.** [BEGIN]
2bd80 20 6d 65 72 65 6c 79 20 73 65 74 73 20 69 6e 74   merely sets int
2bd90 65 72 6e 61 6c 20 66 6c 61 67 73 2c 20 62 75 74  ernal flags, but
2bda0 20 74 68 65 20 5b 42 45 47 49 4e 7c 42 45 47 49   the [BEGIN|BEGI
2bdb0 4e 20 49 4d 4d 45 44 49 41 54 45 5d 20 61 6e 64  N IMMEDIATE] and
2bdc0 0a 2a 2a 20 5b 42 45 47 49 4e 7c 42 45 47 49 4e  .** [BEGIN|BEGIN
2bdd0 20 45 58 43 4c 55 53 49 56 45 5d 20 63 6f 6d 6d   EXCLUSIVE] comm
2bde0 61 6e 64 73 20 64 6f 20 74 6f 75 63 68 20 74 68  ands do touch th
2bdf0 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 73  e database and s
2be00 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d  o.** sqlite3_stm
2be10 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 72 65 74  t_readonly() ret
2be20 75 72 6e 73 20 66 61 6c 73 65 20 66 6f 72 20 74  urns false for t
2be30 68 6f 73 65 20 63 6f 6d 6d 61 6e 64 73 2e 0a 2a  hose commands..*
2be40 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74  /.int sqlite3_st
2be50 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69  mt_readonly(sqli
2be60 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
2be70 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2be80 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20  F: Determine If 
2be90 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
2bea0 6d 65 6e 74 20 48 61 73 20 42 65 65 6e 20 52 65  ment Has Been Re
2beb0 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  set.** METHOD: s
2bec0 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
2bed0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73  * ^The sqlite3_s
2bee0 74 6d 74 5f 62 75 73 79 28 53 29 20 69 6e 74 65  tmt_busy(S) inte
2bef0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72  rface returns tr
2bf00 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66  ue (non-zero) if
2bf10 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
2bf20 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 68  d statement] S h
2bf30 61 73 20 62 65 65 6e 20 73 74 65 70 70 65 64 20  as been stepped 
2bf40 61 74 20 6c 65 61 73 74 20 6f 6e 63 65 20 75 73  at least once us
2bf50 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ing .** [sqlite3
2bf60 5f 73 74 65 70 28 53 29 5d 20 62 75 74 20 68 61  _step(S)] but ha
2bf70 73 20 6e 65 69 74 68 65 72 20 72 75 6e 20 74 6f  s neither run to
2bf80 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 28 72 65 74   completion (ret
2bf90 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45  urned.** [SQLITE
2bfa0 5f 44 4f 4e 45 5d 20 66 72 6f 6d 20 5b 73 71 6c  _DONE] from [sql
2bfb0 69 74 65 33 5f 73 74 65 70 28 53 29 5d 29 20 6e  ite3_step(S)]) n
2bfc0 6f 72 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65 74  or.** been reset
2bfd0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
2bfe0 72 65 73 65 74 28 53 29 5d 2e 20 20 5e 54 68 65  reset(S)].  ^The
2bff0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75   sqlite3_stmt_bu
2c000 73 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61  sy(S).** interfa
2c010 63 65 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65  ce returns false
2c020 20 69 66 20 53 20 69 73 20 61 20 4e 55 4c 4c 20   if S is a NULL 
2c030 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 53 20 69  pointer.  If S i
2c040 73 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c  s not a .** NULL
2c050 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 69 73 20   pointer and is 
2c060 6e 6f 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  not a pointer to
2c070 20 61 20 76 61 6c 69 64 20 5b 70 72 65 70 61 72   a valid [prepar
2c080 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
2c090 20 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20 74 68   object, then th
2c0a0 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
2c0b0 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62  defined and prob
2c0c0 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65  ably undesirable
2c0d0 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
2c0e0 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73  erface can be us
2c0f0 65 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f  ed in combinatio
2c100 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f  n [sqlite3_next_
2c110 73 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f  stmt()].** to lo
2c120 63 61 74 65 20 61 6c 6c 20 70 72 65 70 61 72 65  cate all prepare
2c130 64 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73  d statements ass
2c140 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 64  ociated with a d
2c150 61 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e  atabase .** conn
2c160 65 63 74 69 6f 6e 20 74 68 61 74 20 61 72 65 20  ection that are 
2c170 69 6e 20 6e 65 65 64 20 6f 66 20 62 65 69 6e 67  in need of being
2c180 20 72 65 73 65 74 2e 20 20 54 68 69 73 20 63 61   reset.  This ca
2c190 6e 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f  n be used,.** fo
2c1a0 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69  r example, in di
2c1b0 61 67 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e 65  agnostic routine
2c1c0 73 20 74 6f 20 73 65 61 72 63 68 20 66 6f 72 20  s to search for 
2c1d0 70 72 65 70 61 72 65 64 20 0a 2a 2a 20 73 74 61  prepared .** sta
2c1e0 74 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72 65  tements that are
2c1f0 20 68 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e 73   holding a trans
2c200 61 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a  action open..*/.
2c210 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  int sqlite3_stmt
2c220 5f 62 75 73 79 28 73 71 6c 69 74 65 33 5f 73 74  _busy(sqlite3_st
2c230 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
2c240 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c  I3REF: Dynamical
2c250 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f  ly Typed Value O
2c260 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44  bject.** KEYWORD
2c270 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71  S: {protected sq
2c280 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e  lite3_value} {un
2c290 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2c2a0 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53  3_value}.**.** S
2c2b0 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73  QLite uses the s
2c2c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2c2d0 65 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74  ect to represent
2c2e0 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74   all values.** t
2c2f0 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65  hat can be store
2c300 64 20 69 6e 20 61 20 64 61 74 61 62 61 73 65 20  d in a database 
2c310 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73  table. SQLite us
2c320 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e  es dynamic typin
2c330 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c  g.** for the val
2c340 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20  ues it stores.  
2c350 5e 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69  ^Values stored i
2c360 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  n sqlite3_value 
2c370 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62  objects.** can b
2c380 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61  e integers, floa
2c390 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
2c3a0 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42  s, strings, BLOB
2c3b0 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  s, or NULL..**.*
2c3c0 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c  * An sqlite3_val
2c3d0 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65  ue object may be
2c3e0 20 65 69 74 68 65 72 20 22 70 72 6f 74 65 63 74   either "protect
2c3f0 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63  ed" or "unprotec
2c400 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e  ted"..** Some in
2c410 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65  terfaces require
2c420 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c   a protected sql
2c430 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68  ite3_value.  Oth
2c440 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  er interfaces.**
2c450 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74   will accept eit
2c460 68 65 72 20 61 20 70 72 6f 74 65 63 74 65 64 20  her a protected 
2c470 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65  or an unprotecte
2c480 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
2c490 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66  .** Every interf
2c4a0 61 63 65 20 74 68 61 74 20 61 63 63 65 70 74 73  ace that accepts
2c4b0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61   sqlite3_value a
2c4c0 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69  rguments specifi
2c4d0 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72  es.** whether or
2c4e0 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65 73   not it requires
2c4f0 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c   a protected sql
2c500 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 54 68 65  ite3_value.  The
2c510 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
2c520 75 65 5f 64 75 70 28 29 5d 20 69 6e 74 65 72 66  ue_dup()] interf
2c530 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ace can be used 
2c540 74 6f 20 63 6f 6e 73 74 72 75 63 74 20 61 20 6e  to construct a n
2c550 65 77 20 0a 2a 2a 20 70 72 6f 74 65 63 74 65 64  ew .** protected
2c560 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 66   sqlite3_value f
2c570 72 6f 6d 20 61 6e 20 75 6e 70 72 6f 74 65 63 74  rom an unprotect
2c580 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2c590 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d  ..**.** The term
2c5a0 73 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e  s "protected" an
2c5b0 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20  d "unprotected" 
2c5c0 72 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72  refer to whether
2c5d0 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74   or not.** a mut
2c5e0 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20  ex is held.  An 
2c5f0 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69  internal mutex i
2c600 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f  s held for a pro
2c610 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
2c620 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62  3_value object b
2c630 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68  ut no mutex is h
2c640 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f  eld for an unpro
2c650 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
2c660 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20  3_value object. 
2c670 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   If SQLite is co
2c680 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e  mpiled to be sin
2c690 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20  gle-threaded.** 
2c6a0 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48  (with [SQLITE_TH
2c6b0 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20  READSAFE=0] and 
2c6c0 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68  with [sqlite3_th
2c6d0 72 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75  readsafe()] retu
2c6e0 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69  rning 0).** or i
2c6f0 66 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20  f SQLite is run 
2c700 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65  in one of reduce
2c710 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a  d mutex modes .*
2c720 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
2c730 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f  _SINGLETHREAD] o
2c740 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  r [SQLITE_CONFIG
2c750 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a  _MULTITHREAD].**
2c760 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e   then there is n
2c770 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65  o distinction be
2c780 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20  tween protected 
2c790 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a  and unprotected.
2c7a0 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
2c7b0 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65   objects and the
2c7c0 79 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e  y can be used in
2c7d0 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20  terchangeably.  
2c7e0 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20  However,.** for 
2c7f0 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72  maximum code por
2c800 74 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72  tability it is r
2c810 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20  ecommended that 
2c820 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
2c830 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64  still make the d
2c840 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65  istinction betwe
2c850 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64  en protected and
2c860 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
2c870 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2c880 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20  jects even when 
2c890 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71  not strictly req
2c8a0 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  uired..**.** ^Th
2c8b0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
2c8c0 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65  objects that are
2c8d0 20 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d   passed as param
2c8e0 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a  eters into the.*
2c8f0 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
2c900 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e   of [application
2c910 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
2c920 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74  ctions] are prot
2c930 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73  ected..** ^The s
2c940 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2c950 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ect returned by.
2c960 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
2c970 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75  mn_value()] is u
2c980 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55  nprotected..** U
2c990 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
2c9a0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
2c9b0 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65   may only be use
2c9c0 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74  d with.** [sqlit
2c9d0 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
2c9e0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
2c9f0 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a  bind_value()]..*
2ca00 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  * The [sqlite3_v
2ca10 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69  alue_blob | sqli
2ca20 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29  te3_value_type()
2ca30 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69  ] family of.** i
2ca40 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72  nterfaces requir
2ca50 65 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  e protected sqli
2ca60 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2ca70 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  s..*/.typedef st
2ca80 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33  ruct Mem sqlite3
2ca90 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _value;../*.** C
2caa0 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e  API3REF: SQL Fun
2cab0 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62  ction Context Ob
2cac0 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ject.**.** The c
2cad0 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20  ontext in which 
2cae0 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  an SQL function 
2caf0 65 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72  executes is stor
2cb00 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69  ed in an.** sqli
2cb10 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65  te3_context obje
2cb20 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20  ct.  ^A pointer 
2cb30 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f  to an sqlite3_co
2cb40 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20  ntext object.** 
2cb50 69 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20  is always first 
2cb60 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70  parameter to [ap
2cb70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2cb80 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d  d SQL functions]
2cb90 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
2cba0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
2cbb0 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
2cbc0 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61  entation will pa
2cbd0 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74  ss this.** point
2cbe0 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20  er through into 
2cbf0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
2cc00 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73  3_result_int | s
2cc10 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d  qlite3_result()]
2cc20 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67  ,.** [sqlite3_ag
2cc30 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
2cc40 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65  )], [sqlite3_use
2cc50 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73  r_data()],.** [s
2cc60 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64  qlite3_context_d
2cc70 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71  b_handle()], [sq
2cc80 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
2cc90 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20  a()],.** and/or 
2cca0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78  [sqlite3_set_aux
2ccb0 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65  data()]..*/.type
2ccc0 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
2ccd0 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74  e3_context sqlit
2cce0 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a  e3_context;../*.
2ccf0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e  ** CAPI3REF: Bin
2cd00 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50  ding Values To P
2cd10 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
2cd20 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ts.** KEYWORDS: 
2cd30 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d  {host parameter}
2cd40 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
2cd50 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  s} {host paramet
2cd60 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57  er name}.** KEYW
2cd70 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d  ORDS: {SQL param
2cd80 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d  eter} {SQL param
2cd90 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65  eters} {paramete
2cda0 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 20 4d 45  r binding}.** ME
2cdb0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
2cdc0 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68  mt.**.** ^(In th
2cdd0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
2cde0 74 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b 73  text input to [s
2cdf0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2ce00 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72  2()] and its var
2ce10 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61  iants,.** litera
2ce20 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63  ls may be replac
2ce30 65 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74  ed by a [paramet
2ce40 65 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73  er] that matches
2ce50 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e   one of followin
2ce60 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a  g.** templates:.
2ce70 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
2ce80 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f  i>  ?.** <li>  ?
2ce90 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56  NNN.** <li>  :VV
2cea0 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a  V.** <li>  @VVV.
2ceb0 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a  ** <li>  $VVV.**
2cec0 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20   </ul>.**.** In 
2ced0 74 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62  the templates ab
2cee0 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65  ove, NNN represe
2cef0 6e 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c  nts an integer l
2cf00 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56  iteral,.** and V
2cf10 56 56 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e  VV represents an
2cf20 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64   alphanumeric id
2cf30 65 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e 54 68  entifier.)^  ^Th
2cf40 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73  e values of thes
2cf50 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20  e.** parameters 
2cf60 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f  (also called "ho
2cf70 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d  st parameter nam
2cf80 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61  es" or "SQL para
2cf90 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20  meters").** can 
2cfa0 62 65 20 73 65 74 20 75 73 69 6e 67 20 74 68 65  be set using the
2cfb0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
2cfc0 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e  ) routines defin
2cfd0 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e  ed here..**.** ^
2cfe0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
2cff0 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  nt to the sqlite
2d000 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
2d010 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a  nes is always.**
2d020 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
2d030 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d  e [sqlite3_stmt]
2d040 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
2d050 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65   from.** [sqlite
2d060 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
2d070 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e  or its variants.
2d080 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f  .**.** ^The seco
2d090 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
2d0a0 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
2d0b0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f  SQL parameter to
2d0c0 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65   be set..** ^The
2d0d0 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61   leftmost SQL pa
2d0e0 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69  rameter has an i
2d0f0 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 65  ndex of 1.  ^Whe
2d100 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64  n the same named
2d110 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65  .** SQL paramete
2d120 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74  r is used more t
2d130 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64  han once, second
2d140 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a   and subsequent.
2d150 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68  ** occurrences h
2d160 61 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64  ave the same ind
2d170 65 78 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ex as the first 
2d180 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e  occurrence..** ^
2d190 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61  The index for na
2d1a0 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 63  med parameters c
2d1b0 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20  an be looked up 
2d1c0 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
2d1d0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2d1e0 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50  eter_index()] AP
2d1f0 49 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 5e  I if desired.  ^
2d200 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72  The index.** for
2d210 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65   "?NNN" paramete
2d220 72 73 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  rs is the value 
2d230 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20  of NNN..** ^The 
2d240 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62  NNN value must b
2d250 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20  e between 1 and 
2d260 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  the [sqlite3_lim
2d270 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74  it()].** paramet
2d280 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  er [SQLITE_LIMIT
2d290 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
2d2a0 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65  ] (default value
2d2b0 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  : 999)..**.** ^T
2d2c0 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
2d2d0 74 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 74  t is the value t
2d2e0 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61  o bind to the pa
2d2f0 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20  rameter..** ^If 
2d300 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
2d310 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ter to sqlite3_b
2d320 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71  ind_text() or sq
2d330 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
2d340 36 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  6().** or sqlite
2d350 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73  3_bind_blob() is
2d360 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
2d370 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20  then the fourth 
2d380 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20  parameter.** is 
2d390 69 67 6e 6f 72 65 64 20 61 6e 64 20 74 68 65 20  ignored and the 
2d3a0 65 6e 64 20 72 65 73 75 6c 74 20 69 73 20 74 68  end result is th
2d3b0 65 20 73 61 6d 65 20 61 73 20 73 71 6c 69 74 65  e same as sqlite
2d3c0 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a  3_bind_null()..*
2d3d0 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20  *.** ^(In those 
2d3e0 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 61  routines that ha
2d3f0 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 75  ve a fourth argu
2d400 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20  ment, its value 
2d410 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
2d420 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
2d430 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20   parameter.  To 
2d440 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61  be clear: the va
2d450 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75  lue is the.** nu
2d460 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73  mber of <u>bytes
2d470 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75  </u> in the valu
2d480 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65  e, not the numbe
2d490 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e  r of characters.
2d4a0 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f  )^.** ^If the fo
2d4b0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
2d4c0 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
2d4d0 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ext() or sqlite3
2d4e0 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a  _bind_text16().*
2d4f0 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  * is negative, t
2d500 68 65 6e 20 74 68 65 20 6c 65 6e 67 74 68 20 6f  hen the length o
2d510 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a  f the string is.
2d520 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
2d530 20 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 65   bytes up to the
2d540 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d   first zero term
2d550 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68  inator..** If th
2d560 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
2d570 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  er to sqlite3_bi
2d580 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65 67  nd_blob() is neg
2d590 61 74 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74  ative, then.** t
2d5a0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
2d5b0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20  ndefined..** If 
2d5c0 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66  a non-negative f
2d5d0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
2d5e0 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73  is provided to s
2d5f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2d600 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
2d610 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 6f  _bind_text16() o
2d620 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  r sqlite3_bind_t
2d630 65 78 74 36 34 28 29 20 74 68 65 6e 0a 2a 2a 20  ext64() then.** 
2d640 74 68 61 74 20 70 61 72 61 6d 65 74 65 72 20 6d  that parameter m
2d650 75 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20  ust be the byte 
2d660 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65 72 65 20  offset.** where 
2d670 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74  the NUL terminat
2d680 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75 72 20 61  or would occur a
2d690 73 73 75 6d 69 6e 67 20 74 68 65 20 73 74 72 69  ssuming the stri
2d6a0 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74  ng were NUL.** t
2d6b0 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61  erminated.  If a
2d6c0 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72  ny NUL character
2d6d0 73 20 6f 63 63 75 72 20 61 74 20 62 79 74 65 20  s occur at byte 
2d6e0 6f 66 66 73 65 74 73 20 6c 65 73 73 20 74 68 61  offsets less tha
2d6f0 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20  n .** the value 
2d700 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  of the fourth pa
2d710 72 61 6d 65 74 65 72 20 74 68 65 6e 20 74 68 65  rameter then the
2d720 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e   resulting strin
2d730 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20  g value will.** 
2d740 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64  contain embedded
2d750 20 4e 55 4c 73 2e 20 20 54 68 65 20 72 65 73 75   NULs.  The resu
2d760 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e  lt of expression
2d770 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69  s involving stri
2d780 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65  ngs.** with embe
2d790 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64  dded NULs is und
2d7a0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
2d7b0 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
2d7c0 74 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 61 6e  t to the BLOB an
2d7d0 64 20 73 74 72 69 6e 67 20 62 69 6e 64 69 6e 67  d string binding
2d7e0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69   interfaces.** i
2d7f0 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 75  s a destructor u
2d800 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f  sed to dispose o
2d810 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a  f the BLOB or.**
2d820 20 73 74 72 69 6e 67 20 61 66 74 65 72 20 53 51   string after SQ
2d830 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 65  Lite has finishe
2d840 64 20 77 69 74 68 20 69 74 2e 20 20 5e 54 68 65  d with it.  ^The
2d850 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 63   destructor is c
2d860 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70  alled.** to disp
2d870 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20  ose of the BLOB 
2d880 6f 72 20 73 74 72 69 6e 67 20 65 76 65 6e 20 69  or string even i
2d890 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 62 69  f the call to bi
2d8a0 6e 64 20 41 50 49 20 66 61 69 6c 73 2e 0a 2a 2a  nd API fails..**
2d8b0 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61   ^If the fifth a
2d8c0 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68  rgument is.** th
2d8d0 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20  e special value 
2d8e0 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c  [SQLITE_STATIC],
2d8f0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73   then SQLite ass
2d900 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a  umes that the.**
2d910 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
2d920 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e  in static, unman
2d930 61 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 64  aged space and d
2d940 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
2d950 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66  be freed..** ^If
2d960 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d   the fifth argum
2d970 65 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75  ent has the valu
2d980 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  e [SQLITE_TRANSI
2d990 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51  ENT], then.** SQ
2d9a0 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f  Lite makes its o
2d9b0 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  wn private copy 
2d9c0 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65  of the data imme
2d9d0 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a  diately, before.
2d9e0 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ** the sqlite3_b
2d9f0 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20  ind_*() routine 
2da00 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  returns..**.** ^
2da10 54 68 65 20 73 69 78 74 68 20 61 72 67 75 6d 65  The sixth argume
2da20 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  nt to sqlite3_bi
2da30 6e 64 5f 74 65 78 74 36 34 28 29 20 6d 75 73 74  nd_text64() must
2da40 20 62 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 5b 53   be one of.** [S
2da50 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51  QLITE_UTF8], [SQ
2da60 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 5b 53 51  LITE_UTF16], [SQ
2da70 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 6f  LITE_UTF16BE], o
2da80 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  r [SQLITE_UTF16L
2da90 45 5d 0a 2a 2a 20 74 6f 20 73 70 65 63 69 66 79  E].** to specify
2daa0 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66   the encoding of
2dab0 20 74 68 65 20 74 65 78 74 20 69 6e 20 74 68 65   the text in the
2dac0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
2dad0 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20 73 69 78  .  If.** the six
2dae0 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  th argument to s
2daf0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2db00 36 34 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20  64() is not one 
2db10 6f 66 20 74 68 65 0a 2a 2a 20 61 6c 6c 6f 77 65  of the.** allowe
2db20 64 20 76 61 6c 75 65 73 20 73 68 6f 77 6e 20 61  d values shown a
2db30 62 6f 76 65 2c 20 6f 72 20 69 66 20 74 68 65 20  bove, or if the 
2db40 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 69 73  text encoding is
2db50 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20 66 72   different.** fr
2db60 6f 6d 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  om the encoding 
2db70 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
2db80 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72   sixth parameter
2db90 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
2dba0 69 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69  ior.** is undefi
2dbb0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
2dbc0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
2dbd0 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20  oblob() routine 
2dbe0 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20  binds a BLOB of 
2dbf0 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a  length N that.**
2dc00 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
2dc10 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f  zeroes.  ^A zero
2dc20 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65  blob uses a fixe
2dc30 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f  d amount of memo
2dc40 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69  ry.** (just an i
2dc50 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69  nteger to hold i
2dc60 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69  ts size) while i
2dc70 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65  t is being proce
2dc80 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f  ssed..** Zeroblo
2dc90 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  bs are intended 
2dca0 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63  to serve as plac
2dcb0 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f  eholders for BLO
2dcc0 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74  Bs whose.** cont
2dcd0 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69  ent is later wri
2dce0 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  tten using.** [s
2dcf0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e  qlite3_blob_open
2dd00 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42   | incremental B
2dd10 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65  LOB I/O] routine
2dd20 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76  s..** ^A negativ
2dd30 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20  e value for the 
2dd40 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73  zeroblob results
2dd50 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74   in a zero-lengt
2dd60 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49  h BLOB..**.** ^I
2dd70 66 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71 6c  f any of the sql
2dd80 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
2dd90 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65  utines are calle
2dda0 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f  d with a NULL po
2ddb0 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65  inter.** for the
2ddc0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2ddd0 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 20  ment] or with a 
2dde0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2ddf0 6e 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20  nt for which.** 
2de00 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2de10 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64   has been called
2de20 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 74   more recently t
2de30 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  han [sqlite3_res
2de40 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74  et()],.** then t
2de50 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74  he call will ret
2de60 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  urn [SQLITE_MISU
2de70 53 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 6c  SE].  If any sql
2de80 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20  ite3_bind_().** 
2de90 72 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73 65  routine is passe
2dea0 64 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  d a [prepared st
2deb0 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61  atement] that ha
2dec0 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64  s been finalized
2ded0 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  , the.** result 
2dee0 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  is undefined and
2def0 20 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 75   probably harmfu
2df00 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e  l..**.** ^Bindin
2df10 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72  gs are not clear
2df20 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
2df30 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74  e3_reset()] rout
2df40 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64  ine..** ^Unbound
2df50 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
2df60 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 4e  interpreted as N
2df70 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ULL..**.** ^The 
2df80 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72  sqlite3_bind_* r
2df90 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b  outines return [
2dfa0 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75  SQLITE_OK] on su
2dfb0 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b  ccess or an.** [
2dfc0 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61  error code] if a
2dfd0 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f  nything goes wro
2dfe0 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  ng..** ^[SQLITE_
2dff0 54 4f 4f 42 49 47 5d 20 6d 69 67 68 74 20 62 65  TOOBIG] might be
2e000 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65   returned if the
2e010 20 73 69 7a 65 20 6f 66 20 61 20 73 74 72 69 6e   size of a strin
2e020 67 20 6f 72 20 42 4c 4f 42 0a 2a 2a 20 65 78 63  g or BLOB.** exc
2e030 65 65 64 73 20 6c 69 6d 69 74 73 20 69 6d 70 6f  eeds limits impo
2e040 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  sed by [sqlite3_
2e050 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c  limit]([SQLITE_L
2e060 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 29 20 6f 72  IMIT_LENGTH]) or
2e070 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f  .** [SQLITE_MAX_
2e080 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 20 5e 5b 53 51  LENGTH]..** ^[SQ
2e090 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72  LITE_RANGE] is r
2e0a0 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 70  eturned if the p
2e0b0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65  arameter.** inde
2e0c0 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  x is out of rang
2e0d0 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d  e.  ^[SQLITE_NOM
2e0e0 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  EM] is returned 
2e0f0 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c  if malloc() fail
2e100 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  s..**.** See als
2e110 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
2e120 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
2e130 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
2e140 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2e150 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71  name()], and [sq
2e160 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2e170 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
2e180 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  /.int sqlite3_bi
2e190 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  nd_blob(sqlite3_
2e1a0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
2e1b0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20  t void*, int n, 
2e1c0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
2e1d0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
2e1e0 64 5f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33  d_blob64(sqlite3
2e1f0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
2e200 73 74 20 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65  st void*, sqlite
2e210 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20  3_uint64,.      
2e220 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2e230 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29    void(*)(void*)
2e240 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
2e250 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  ind_double(sqlit
2e260 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64  e3_stmt*, int, d
2e270 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69  ouble);.int sqli
2e280 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c  te3_bind_int(sql
2e290 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
2e2a0 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74   int);.int sqlit
2e2b0 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71  e3_bind_int64(sq
2e2c0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2e2d0 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  , sqlite3_int64)
2e2e0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
2e2f0 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f  nd_null(sqlite3_
2e300 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74  stmt*, int);.int
2e310 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2e320 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  xt(sqlite3_stmt*
2e330 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a  ,int,const char*
2e340 2c 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69  ,int,void(*)(voi
2e350 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
2e360 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71  3_bind_text16(sq
2e370 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2e380 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
2e390 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
2e3a0 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  *));.int sqlite3
2e3b0 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 73 71 6c  _bind_text64(sql
2e3c0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
2e3d0 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71   const char*, sq
2e3e0 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20  lite3_uint64,.  
2e3f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2e400 20 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28 76         void(*)(v
2e410 6f 69 64 2a 29 2c 20 75 6e 73 69 67 6e 65 64 20  oid*), unsigned 
2e420 63 68 61 72 20 65 6e 63 6f 64 69 6e 67 29 3b 0a  char encoding);.
2e430 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2e440 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73  _value(sqlite3_s
2e450 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
2e460 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29   sqlite3_value*)
2e470 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
2e480 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69  nd_zeroblob(sqli
2e490 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
2e4a0 69 6e 74 20 6e 29 3b 0a 69 6e 74 20 73 71 6c 69  int n);.int sqli
2e4b0 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f  te3_bind_zeroblo
2e4c0 62 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  b64(sqlite3_stmt
2e4d0 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f  *, int, sqlite3_
2e4e0 75 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20  uint64);../*.** 
2e4f0 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72  CAPI3REF: Number
2e500 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65   Of SQL Paramete
2e510 72 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  rs.** METHOD: sq
2e520 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
2e530 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63   ^This routine c
2e540 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66 69  an be used to fi
2e550 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  nd the number of
2e560 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73   [SQL parameters
2e570 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61  ].** in a [prepa
2e580 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
2e590 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20   SQL parameters 
2e5a0 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68  are tokens of th
2e5b0 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22  e.** form "?", "
2e5c0 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22  ?NNN", ":AAA", "
2e5d0 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22  $AAA", or "@AAA"
2e5e0 20 74 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a   that serve as.*
2e5f0 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66  * placeholders f
2e600 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74 20 61  or values that a
2e610 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  re [sqlite3_bind
2e620 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a  _blob | bound].*
2e630 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74  * to the paramet
2e640 65 72 73 20 61 74 20 61 20 6c 61 74 65 72 20 74  ers at a later t
2e650 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69  ime..**.** ^(Thi
2e660 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c  s routine actual
2e670 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 20 69  ly returns the i
2e680 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67  ndex of the larg
2e690 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a  est (rightmost).
2e6a0 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f  ** parameter. Fo
2e6b0 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65  r all forms exce
2e6c0 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69  pt ?NNN, this wi
2e6d0 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f  ll correspond to
2e6e0 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
2e6f0 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74  f unique paramet
2e700 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74  ers.  If paramet
2e710 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20  ers of the ?NNN 
2e720 66 6f 72 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a  form are used,.*
2e730 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65 20 67  * there may be g
2e740 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e  aps in the list.
2e750 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  )^.**.** See als
2e760 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
2e770 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
2e780 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
2e790 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2e7a0 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a  r_name()], and.*
2e7b0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2e7c0 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
2e7d0 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
2e7e0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2e7f0 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  r_count(sqlite3_
2e800 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
2e810 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66  API3REF: Name Of
2e820 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65   A Host Paramete
2e830 72 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  r.** METHOD: sql
2e840 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
2e850 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e  ^The sqlite3_bin
2e860 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
2e870 28 50 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20  (P,N) interface 
2e880 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
2e890 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20  ame of the N-th 
2e8a0 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20  [SQL parameter] 
2e8b0 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  in the [prepared
2e8c0 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a   statement] P..*
2e8d0 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65  * ^(SQL paramete
2e8e0 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22  rs of the form "
2e8f0 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20  ?NNN" or ":AAA" 
2e900 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41  or "@AAA" or "$A
2e910 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61  AA".** have a na
2e920 6d 65 20 77 68 69 63 68 20 69 73 20 74 68 65 20  me which is the 
2e930 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72  string "?NNN" or
2e940 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41   ":AAA" or "@AAA
2e950 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72  " or "$AAA".** r
2e960 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20  espectively..** 
2e970 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
2e980 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20  the initial ":" 
2e990 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72  or "$" or "@" or
2e9a0 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75   "?".** is inclu
2e9b0 64 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74  ded as part of t
2e9c0 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50  he name.)^.** ^P
2e9d0 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
2e9e0 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75   form "?" withou
2e9f0 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e  t a following in
2ea00 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61  teger have no na
2ea10 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65  me.** and are re
2ea20 66 65 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61  ferred to as "na
2ea30 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e  meless" or "anon
2ea40 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73  ymous parameters
2ea50 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  "..**.** ^The fi
2ea60 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74  rst host paramet
2ea70 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20  er has an index 
2ea80 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a  of 1, not 0..**.
2ea90 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65  ** ^If the value
2eaa0 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e   N is out of ran
2eab0 67 65 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74  ge or if the N-t
2eac0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a  h parameter is.*
2ead0 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e  * nameless, then
2eae0 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65   NULL is returne
2eaf0 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65  d.  ^The returne
2eb00 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61  d string is.** a
2eb10 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65  lways in UTF-8 e
2eb20 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20  ncoding even if 
2eb30 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65  the named parame
2eb40 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69  ter was.** origi
2eb50 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20  nally specified 
2eb60 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71  as UTF-16 in [sq
2eb70 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
2eb80 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
2eb90 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
2eba0 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  ]..**.** See als
2ebb0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
2ebc0 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
2ebd0 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
2ebe0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2ebf0 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a  r_count()], and.
2ec00 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
2ec10 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
2ec20 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ()]..*/.const ch
2ec30 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64  ar *sqlite3_bind
2ec40 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
2ec50 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2ec60 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
2ec70 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41  3REF: Index Of A
2ec80 20 50 61 72 61 6d 65 74 65 72 20 57 69 74 68 20   Parameter With 
2ec90 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 20  A Given Name.** 
2eca0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
2ecb0 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75  stmt.**.** ^Retu
2ecc0 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  rn the index of 
2ecd0 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  an SQL parameter
2ece0 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e   given its name.
2ecf0 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20    ^The.** index 
2ed00 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69  value returned i
2ed10 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75  s suitable for u
2ed20 73 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  se as the second
2ed30 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f  .** parameter to
2ed40 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2ed50 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
2ed60 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a  ()].  ^A zero.**
2ed70 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
2ed80 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61  no matching para
2ed90 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20  meter is found. 
2eda0 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a   ^The parameter.
2edb0 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20  ** name must be 
2edc0 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65  given in UTF-8 e
2edd0 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69  ven if the origi
2ede0 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  nal statement.**
2edf0 20 77 61 73 20 70 72 65 70 61 72 65 64 20 66 72   was prepared fr
2ee00 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20 75  om UTF-16 text u
2ee10 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  sing [sqlite3_pr
2ee20 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a  epare16_v2()]..*
2ee30 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
2ee40 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2ee50 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
2ee60 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
2ee70 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
2ee80 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  unt()], and.** [
2ee90 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2eea0 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2e 0a  ameter_name()]..
2eeb0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
2eec0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
2eed0 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  dex(sqlite3_stmt
2eee0 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
2eef0 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Name);../*.** CA
2ef00 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c  PI3REF: Reset Al
2ef10 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20  l Bindings On A 
2ef20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
2ef30 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  nt.** METHOD: sq
2ef40 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
2ef50 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68   ^Contrary to th
2ef60 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d  e intuition of m
2ef70 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65  any, [sqlite3_re
2ef80 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20  set()] does not 
2ef90 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71  reset.** the [sq
2efa0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
2efb0 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61  | bindings] on a
2efc0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2efd0 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74  ment]..** ^Use t
2efe0 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72  his routine to r
2eff0 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61  eset all host pa
2f000 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c  rameters to NULL
2f010 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2f020 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28  _clear_bindings(
2f030 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
2f040 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2f050 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d   Number Of Colum
2f060 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53  ns In A Result S
2f070 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  et.** METHOD: sq
2f080 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
2f090 20 5e 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d   ^Return the num
2f0a0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
2f0b0 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  n the result set
2f0c0 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
2f0d0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
2f0e0 61 74 65 6d 65 6e 74 5d 2e 20 5e 49 66 20 74 68  atement]. ^If th
2f0f0 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
2f100 6e 73 20 30 2c 20 74 68 61 74 20 6d 65 61 6e 73  ns 0, that means
2f110 20 74 68 65 20 0a 2a 2a 20 5b 70 72 65 70 61 72   the .** [prepar
2f120 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 72 65  ed statement] re
2f130 74 75 72 6e 73 20 6e 6f 20 64 61 74 61 20 28 66  turns no data (f
2f140 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55  or example an [U
2f150 50 44 41 54 45 5d 29 2e 0a 2a 2a 20 5e 48 6f 77  PDATE])..** ^How
2f160 65 76 65 72 2c 20 6a 75 73 74 20 62 65 63 61 75  ever, just becau
2f170 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  se this routine 
2f180 72 65 74 75 72 6e 73 20 61 20 70 6f 73 69 74 69  returns a positi
2f190 76 65 20 6e 75 6d 62 65 72 20 64 6f 65 73 20 6e  ve number does n
2f1a0 6f 74 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20  ot.** mean that 
2f1b0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 72 6f 77 73  one or more rows
2f1c0 20 6f 66 20 64 61 74 61 20 77 69 6c 6c 20 62 65   of data will be
2f1d0 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 41 20 53   returned.  ^A S
2f1e0 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 0a  ELECT statement.
2f1f0 2a 2a 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 68  ** will always h
2f200 61 76 65 20 61 20 70 6f 73 69 74 69 76 65 20 73  ave a positive s
2f210 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
2f220 75 6e 74 28 29 20 62 75 74 20 64 65 70 65 6e 64  unt() but depend
2f230 69 6e 67 20 6f 6e 20 74 68 65 0a 2a 2a 20 57 48  ing on the.** WH
2f240 45 52 45 20 63 6c 61 75 73 65 20 63 6f 6e 73 74  ERE clause const
2f250 72 61 69 6e 74 73 20 61 6e 64 20 74 68 65 20 74  raints and the t
2f260 61 62 6c 65 20 63 6f 6e 74 65 6e 74 2c 20 69 74  able content, it
2f270 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20 6e 6f   might return no
2f280 20 72 6f 77 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   rows..**.** See
2f290 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
2f2a0 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f  data_count()].*/
2f2b0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
2f2c0 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  umn_count(sqlite
2f2d0 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
2f2e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2f2f0 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e   Column Names In
2f300 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a   A Result Set.**
2f310 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2f320 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _stmt.**.** ^The
2f330 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
2f340 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69  rn the name assi
2f350 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69 63  gned to a partic
2f360 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  ular column.** i
2f370 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  n the result set
2f380 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73   of a [SELECT] s
2f390 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20  tatement.  ^The 
2f3a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
2f3b0 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  ame().** interfa
2f3c0 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
2f3d0 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74  nter to a zero-t
2f3e0 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
2f3f0 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71  string.** and sq
2f400 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
2f410 65 31 36 28 29 20 72 65 74 75 72 6e 73 20 61 20  e16() returns a 
2f420 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72  pointer to a zer
2f430 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
2f440 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20  UTF-16 string.  
2f450 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  ^The first param
2f460 65 74 65 72 20 69 73 20 74 68 65 20 5b 70 72 65  eter is the [pre
2f470 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2f480 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  .** that impleme
2f490 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43 54 5d  nts the [SELECT]
2f4a0 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65   statement. ^The
2f4b0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
2f4c0 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75  r is the.** colu
2f4d0 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65  mn number.  ^The
2f4e0 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e   leftmost column
2f4f0 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a   is number 0..**
2f500 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65  .** ^The returne
2f510 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72  d string pointer
2f520 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20   is valid until 
2f530 65 69 74 68 65 72 20 74 68 65 20 5b 70 72 65 70  either the [prep
2f540 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
2f550 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64 20  ** is destroyed 
2f560 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  by [sqlite3_fina
2f570 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c  lize()] or until
2f580 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
2f590 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a  s automatically.
2f5a0 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62 79  ** reprepared by
2f5b0 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20   the first call 
2f5c0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
2f5d0 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63  ()] for a partic
2f5e0 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75  ular run.** or u
2f5f0 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61  ntil the next ca
2f600 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ll to.** sqlite3
2f610 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f  _column_name() o
2f620 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
2f630 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65  _name16() on the
2f640 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a   same column..**
2f650 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
2f660 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64  malloc() fails d
2f670 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73  uring the proces
2f680 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72  sing of either r
2f690 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65  outine.** (for e
2f6a0 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20  xample during a 
2f6b0 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20  conversion from 
2f6c0 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29  UTF-8 to UTF-16)
2f6d0 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20   then a.** NULL 
2f6e0 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72  pointer is retur
2f6f0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
2f700 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74  name of a result
2f710 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76   column is the v
2f720 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53 22  alue of the "AS"
2f730 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74   clause for.** t
2f740 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74  hat column, if t
2f750 68 65 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c  here is an AS cl
2f760 61 75 73 65 2e 20 20 49 66 20 74 68 65 72 65 20  ause.  If there 
2f770 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a  is no AS clause.
2f780 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65  ** then the name
2f790 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69   of the column i
2f7a0 73 20 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e  s unspecified an
2f7b0 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f  d may change fro
2f7c0 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65  m.** one release
2f7d0 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68   of SQLite to th
2f7e0 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f 6e 73 74  e next..*/.const
2f7f0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
2f800 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74  olumn_name(sqlit
2f810 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29  e3_stmt*, int N)
2f820 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
2f830 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
2f840 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
2f850 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a  *, int N);../*.*
2f860 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72  * CAPI3REF: Sour
2f870 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20  ce Of Data In A 
2f880 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 20  Query Result.** 
2f890 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
2f8a0 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  stmt.**.** ^Thes
2f8b0 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69  e routines provi
2f8c0 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65  de a means to de
2f8d0 74 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74 61  termine the data
2f8e0 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64  base, table, and
2f8f0 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  .** table column
2f900 20 74 68 61 74 20 69 73 20 74 68 65 20 6f 72 69   that is the ori
2f910 67 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63 75  gin of a particu
2f920 6c 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  lar result colum
2f930 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d  n in.** [SELECT]
2f940 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e   statement..** ^
2f950 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  The name of the 
2f960 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c  database or tabl
2f970 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20  e or column can 
2f980 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a  be returned as.*
2f990 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 2d 38  * either a UTF-8
2f9a0 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e   or UTF-16 strin
2f9b0 67 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62 61  g.  ^The _databa
2f9c0 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  se_ routines ret
2f9d0 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  urn.** the datab
2f9e0 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74  ase name, the _t
2f9f0 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72  able_ routines r
2fa00 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20  eturn the table 
2fa10 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65  name, and.** the
2fa20 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65   origin_ routine
2fa30 73 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c  s return the col
2fa40 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68  umn name..** ^Th
2fa50 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
2fa60 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c  g is valid until
2fa70 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2fa80 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73  tatement] is des
2fa90 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20  troyed.** using 
2faa0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2fab0 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68  e()] or until th
2fac0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
2fad0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20  utomatically.** 
2fae0 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68  reprepared by th
2faf0 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20  e first call to 
2fb00 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2fb10 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
2fb20 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69  r run.** or unti
2fb30 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72  l the same infor
2fb40 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73  mation is reques
2fb50 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20  ted.** again in 
2fb60 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f  a different enco
2fb70 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ding..**.** ^The
2fb80 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20   names returned 
2fb90 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  are the original
2fba0 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65   un-aliased name
2fbb0 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61  s of the.** data
2fbc0 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64  base, table, and
2fbd0 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e   column..**.** ^
2fbe0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
2fbf0 6e 74 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65  nt to these inte
2fc00 72 66 61 63 65 73 20 69 73 20 61 20 5b 70 72 65  rfaces is a [pre
2fc10 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2fc20 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63  ..** ^These func
2fc30 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66  tions return inf
2fc40 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74  ormation about t
2fc50 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f  he Nth result co
2fc60 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79  lumn returned by
2fc70 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e  .** the statemen
2fc80 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  t, where N is th
2fc90 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f  e second functio
2fca0 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e  n argument..** ^
2fcb0 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f  The left-most co
2fcc0 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30  lumn is column 0
2fcd0 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69   for these routi
2fce0 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  nes..**.** ^If t
2fcf0 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65  he Nth column re
2fd00 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 73 74  turned by the st
2fd10 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78  atement is an ex
2fd20 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73  pression or.** s
2fd30 75 62 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e  ubquery and is n
2fd40 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75  ot a column valu
2fd50 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74  e, then all of t
2fd60 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  hese functions r
2fd70 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20  eturn.** NULL.  
2fd80 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d  ^These routine m
2fd90 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e  ight also return
2fda0 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72   NULL if a memor
2fdb0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
2fdc0 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e  or.** occurs.  ^
2fdd0 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 79 20  Otherwise, they 
2fde0 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20  return the name 
2fdf0 6f 66 20 74 68 65 20 61 74 74 61 63 68 65 64 20  of the attached 
2fe00 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
2fe10 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68  .** or column th
2fe20 61 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 20  at query result 
2fe30 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61  column was extra
2fe40 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a  cted from..**.**
2fe50 20 5e 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74   ^As with all ot
2fe60 68 65 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c  her SQLite APIs,
2fe70 20 74 68 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d   those whose nam
2fe80 65 73 20 65 6e 64 20 77 69 74 68 20 22 31 36 22  es end with "16"
2fe90 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31   return.** UTF-1
2fea0 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67  6 encoded string
2feb0 73 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20  s and the other 
2fec0 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
2fed0 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54   UTF-8..**.** ^T
2fee0 68 65 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e  hese APIs are on
2fef0 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20  ly available if 
2ff00 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20  the library was 
2ff10 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
2ff20 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41  e.** [SQLITE_ENA
2ff30 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44  BLE_COLUMN_METAD
2ff40 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73  ATA] C-preproces
2ff50 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a  sor symbol..**.*
2ff60 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65  * If two or more
2ff70 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e   threads call on
2ff80 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65  e or more of the
2ff90 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69  se routines agai
2ffa0 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  nst the same.** 
2ffb0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2ffc0 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74  nt and column at
2ffd0 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74   the same time t
2ffe0 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
2fff0 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64  are.** undefined
30000 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f  ..**.** If two o
30010 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63  r more threads c
30020 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a  all one or more.
30030 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
30040 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
30050 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61   | column metada
30060 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a  ta interfaces].*
30070 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b  * for the same [
30080 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
30090 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63  nt] and result c
300a0 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20  olumn.** at the 
300b0 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74  same time then t
300c0 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
300d0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e  ndefined..*/.con
300e0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
300f0 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
30100 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
30110 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
30120 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
30130 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
30140 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
30150 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63  t*,int);.const c
30160 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
30170 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73  umn_table_name(s
30180 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
30190 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
301a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
301b0 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  ble_name16(sqlit
301c0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
301d0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
301e0 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e  e3_column_origin
301f0 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
30200 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
30210 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
30220 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65  lumn_origin_name
30230 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
30240 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ,int);../*.** CA
30250 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64  PI3REF: Declared
30260 20 44 61 74 61 74 79 70 65 20 4f 66 20 41 20 51   Datatype Of A Q
30270 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 20 4d  uery Result.** M
30280 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
30290 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  tmt.**.** ^(The 
302a0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
302b0 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  is a [prepared s
302c0 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66  tatement]..** If
302d0 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20   this statement 
302e0 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74  is a [SELECT] st
302f0 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20  atement and the 
30300 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  Nth column of th
30310 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65  e.** returned re
30320 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74  sult set of that
30330 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74   [SELECT] is a t
30340 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74  able column (not
30350 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f   an.** expressio
30360 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29 20 74  n or subquery) t
30370 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64  hen the declared
30380 20 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62   type of the tab
30390 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20  le.** column is 
303a0 72 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66  returned.)^  ^If
303b0 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
303c0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
303d0 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65  t is an.** expre
303e0 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72  ssion or subquer
303f0 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70  y, then a NULL p
30400 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e  ointer is return
30410 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75  ed..** ^The retu
30420 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 61  rned string is a
30430 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f  lways UTF-8 enco
30440 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72  ded..**.** ^(For
30450 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20   example, given 
30460 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68  the database sch
30470 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54  ema:.**.** CREAT
30480 45 20 54 41 42 4c 45 20 74 31 28 63 31 20 56 41  E TABLE t1(c1 VA
30490 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e  RIANT);.**.** an
304a0 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  d the following 
304b0 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20  statement to be 
304c0 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20  compiled:.**.** 
304d0 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63  SELECT c1 + 1, c
304e0 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a  1 FROM t1;.**.**
304f0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f   this routine wo
30500 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 73  uld return the s
30510 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20  tring "VARIANT" 
30520 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72  for the second r
30530 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  esult.** column 
30540 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55  (i==1), and a NU
30550 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74  LL pointer for t
30560 68 65 20 66 69 72 73 74 20 72 65 73 75 6c 74 20  he first result 
30570 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e  column (i==0).)^
30580 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75  .**.** ^SQLite u
30590 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d  ses dynamic run-
305a0 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53  time typing.  ^S
305b0 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 61  o just because a
305c0 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65   column.** is de
305d0 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69  clared to contai
305e0 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 74  n a particular t
305f0 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61  ype does not mea
30600 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61  n that the.** da
30610 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61  ta stored in tha
30620 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74  t column is of t
30630 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65  he declared type
30640 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20  .  SQLite is.** 
30650 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20  strongly typed, 
30660 62 75 74 20 74 68 65 20 74 79 70 69 6e 67 20 69  but the typing i
30670 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74  s dynamic not st
30680 61 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20  atic.  ^Type.** 
30690 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  is associated wi
306a0 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61  th individual va
306b0 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74  lues, not with t
306c0 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a  he containers.**
306d0 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68   used to hold th
306e0 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63  ose values..*/.c
306f0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
30700 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
30710 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  pe(sqlite3_stmt*
30720 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
30730 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
30740 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c  n_decltype16(sql
30750 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
30760 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
30770 3a 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51  : Evaluate An SQ
30780 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d  L Statement.** M
30790 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
307a0 74 6d 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20  tmt.**.** After 
307b0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
307c0 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20  ement] has been 
307d0 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 65  prepared using e
307e0 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ither.** [sqlite
307f0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
30800 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
30810 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f  are16_v2()] or o
30820 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79  ne of the legacy
30830 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b  .** interfaces [
30840 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
30850 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
30860 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69  repare16()], thi
30870 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75  s function.** mu
30880 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65  st be called one
30890 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74   or more times t
308a0 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65 20 73  o evaluate the s
308b0 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  tatement..**.** 
308c0 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74  The details of t
308d0 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74  he behavior of t
308e0 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  he sqlite3_step(
308f0 29 20 69 6e 74 65 72 66 61 63 65 20 64 65 70 65  ) interface depe
30900 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72  nd.** on whether
30910 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77   the statement w
30920 61 73 20 70 72 65 70 61 72 65 64 20 75 73 69 6e  as prepared usin
30930 67 20 74 68 65 20 6e 65 77 65 72 20 22 76 32 22  g the newer "v2"
30940 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73   interface.** [s
30950 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
30960 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
30970 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
30980 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c  ] or the older l
30990 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61  egacy.** interfa
309a0 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ce [sqlite3_prep
309b0 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  are()] and [sqli
309c0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
309d0 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68  .  The use of th
309e0 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e  e.** new "v2" in
309f0 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d  terface is recom
30a00 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61  mended for new a
30a10 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20  pplications but 
30a20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  the legacy.** in
30a30 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e  terface will con
30a40 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70  tinue to be supp
30a50 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e  orted..**.** ^In
30a60 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
30a70 72 66 61 63 65 2c 20 74 68 65 20 72 65 74 75 72  rface, the retur
30a80 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20  n value will be 
30a90 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42  either [SQLITE_B
30aa0 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  USY],.** [SQLITE
30ab0 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  _DONE], [SQLITE_
30ac0 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52  ROW], [SQLITE_ER
30ad0 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  ROR], or [SQLITE
30ae0 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69  _MISUSE]..** ^Wi
30af0 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  th the "v2" inte
30b00 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68  rface, any of th
30b10 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20  e other [result 
30b20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78  codes] or.** [ex
30b30 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
30b40 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65  des] might be re
30b50 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a  turned as well..
30b60 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42  **.** ^[SQLITE_B
30b70 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  USY] means that 
30b80 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67  the database eng
30b90 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74  ine was unable t
30ba0 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a  o acquire the.**
30bb0 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20   database locks 
30bc0 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69  it needs to do i
30bd0 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65  ts job.  ^If the
30be0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20   statement is a 
30bf0 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f  [COMMIT].** or o
30c00 63 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66  ccurs outside of
30c10 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61   an explicit tra
30c20 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79  nsaction, then y
30c30 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74 68 65  ou can retry the
30c40 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  .** statement.  
30c50 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  If the statement
30c60 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49   is not a [COMMI
30c70 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69  T] and occurs wi
30c80 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69  thin an.** expli
30c90 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  cit transaction 
30ca0 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20  then you should 
30cb0 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61  rollback the tra
30cc0 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a  nsaction before.
30cd0 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a  ** continuing..*
30ce0 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f  *.** ^[SQLITE_DO
30cf0 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  NE] means that t
30d00 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73  he statement has
30d10 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74   finished execut
30d20 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  ing.** successfu
30d30 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74  lly.  sqlite3_st
30d40 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ep() should not 
30d50 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  be called again 
30d60 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a  on this virtual.
30d70 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f  ** machine witho
30d80 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67  ut first calling
30d90 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
30da0 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  )] to reset the 
30db0 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69  virtual.** machi
30dc0 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69  ne back to its i
30dd0 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a  nitial state..**
30de0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20  .** ^If the SQL 
30df0 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20  statement being 
30e00 65 78 65 63 75 74 65 64 20 72 65 74 75 72 6e 73  executed returns
30e10 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20   any data, then 
30e20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20  [SQLITE_ROW].** 
30e30 69 73 20 72 65 74 75 72 6e 65 64 20 65 61 63 68  is returned each
30e40 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20   time a new row 
30e50 6f 66 20 64 61 74 61 20 69 73 20 72 65 61 64 79  of data is ready
30e60 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20   for processing 
30e70 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72  by the.** caller
30e80 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79  . The values may
30e90 20 62 65 20 61 63 63 65 73 73 65 64 20 75 73 69   be accessed usi
30ea0 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61  ng the [column a
30eb0 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d  ccess functions]
30ec0 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65  ..** sqlite3_ste
30ed0 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67  p() is called ag
30ee0 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20  ain to retrieve 
30ef0 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20  the next row of 
30f00 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51  data..**.** ^[SQ
30f10 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e  LITE_ERROR] mean
30f20 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d  s that a run-tim
30f30 65 20 65 72 72 6f 72 20 28 73 75 63 68 20 61 73  e error (such as
30f40 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a   a constraint.**
30f50 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20   violation) has 
30f60 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74  occurred.  sqlit
30f70 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64  e3_step() should
30f80 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61   not be called a
30f90 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56  gain on.** the V
30fa0 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74  M. More informat
30fb0 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64  ion may be found
30fc0 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
30fd0 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a  ite3_errmsg()]..
30fe0 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67  ** ^With the leg
30ff0 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61  acy interface, a
31000 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65   more specific e
31010 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65  rror code (for e
31020 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49  xample,.** [SQLI
31030 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b  TE_INTERRUPT], [
31040 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20  SQLITE_SCHEMA], 
31050 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d  [SQLITE_CORRUPT]
31060 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a  , and so forth).
31070 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e  ** can be obtain
31080 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  ed by calling [s
31090 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
310a0 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  on the.** [prepa
310b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
310c0 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e   ^In the "v2" in
310d0 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20  terface,.** the 
310e0 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72  more specific er
310f0 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75  ror code is retu
31100 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62 79  rned directly by
31110 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
31120 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d  .**.** [SQLITE_M
31130 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61  ISUSE] means tha
31140 74 20 74 68 65 20 74 68 69 73 20 72 6f 75 74 69  t the this routi
31150 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e  ne was called in
31160 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a  appropriately..*
31170 2a 20 50 65 72 68 61 70 73 20 69 74 20 77 61 73  * Perhaps it was
31180 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72   called on a [pr
31190 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
311a0 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c  ] that has.** al
311b0 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69  ready been [sqli
311c0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66  te3_finalize | f
311d0 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20  inalized] or on 
311e0 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20  one that had.** 
311f0 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72  previously retur
31200 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ned [SQLITE_ERRO
31210 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f  R] or [SQLITE_DO
31220 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c  NE].  Or it coul
31230 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65  d.** be the case
31240 20 74 68 61 74 20 74 68 65 20 73 61 6d 65 20 64   that the same d
31250 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
31260 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65 64  on is being used
31270 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f   by two or.** mo
31280 72 65 20 74 68 72 65 61 64 73 20 61 74 20 74 68  re threads at th
31290 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e  e same moment in
312a0 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72   time..**.** For
312b0 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66   all versions of
312c0 20 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e   SQLite up to an
312d0 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e  d including 3.6.
312e0 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a  23.1, a call to.
312f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
31300 74 28 29 5d 20 77 61 73 20 72 65 71 75 69 72 65  t()] was require
31310 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f  d after sqlite3_
31320 73 74 65 70 28 29 20 72 65 74 75 72 6e 65 64 20  step() returned 
31330 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65  anything.** othe
31340 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52  r than [SQLITE_R
31350 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e 79 20 73  OW] before any s
31360 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61  ubsequent invoca
31370 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74  tion of.** sqlit
31380 65 33 5f 73 74 65 70 28 29 2e 20 20 46 61 69 6c  e3_step().  Fail
31390 75 72 65 20 74 6f 20 72 65 73 65 74 20 74 68 65  ure to reset the
313a0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
313b0 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73  ent using .** [s
313c0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
313d0 77 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20  would result in 
313e0 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  an [SQLITE_MISUS
313f0 45 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a  E] return from.*
31400 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
31410 2e 20 20 42 75 74 20 61 66 74 65 72 20 5b 76 65  .  But after [ve
31420 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 5d 20  rsion 3.6.23.1] 
31430 28 5b 64 61 74 65 6f 66 3a 33 2e 36 2e 32 33 2e  ([dateof:3.6.23.
31440 31 5d 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  1],.** sqlite3_s
31450 74 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63  tep() began.** c
31460 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
31470 72 65 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 74  reset()] automat
31480 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63  ically in this c
31490 69 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68  ircumstance rath
314a0 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 72  er.** than retur
314b0 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53  ning [SQLITE_MIS
314c0 55 53 45 5d 2e 20 20 54 68 69 73 20 69 73 20 6e  USE].  This is n
314d0 6f 74 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20  ot considered a 
314e0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a  compatibility.**
314f0 20 62 72 65 61 6b 20 62 65 63 61 75 73 65 20 61   break because a
31500 6e 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  ny application t
31510 68 61 74 20 65 76 65 72 20 72 65 63 65 69 76 65  hat ever receive
31520 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55  s an SQLITE_MISU
31530 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62  SE error.** is b
31540 72 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 74  roken by definit
31550 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ion.  The [SQLIT
31560 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 54  E_OMIT_AUTORESET
31570 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
31580 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20  ption.** can be 
31590 75 73 65 64 20 74 6f 20 72 65 73 74 6f 72 65 20  used to restore 
315a0 74 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76  the legacy behav
315b0 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f  ior..**.** <b>Go
315c0 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c  ofy Interface Al
315d0 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20  ert:</b> In the 
315e0 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
315f0 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74  , the sqlite3_st
31600 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61  ep().** API alwa
31610 79 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e  ys returns a gen
31620 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c  eric error code,
31630 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c   [SQLITE_ERROR],
31640 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a   following any.*
31650 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68  * error other th
31660 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  an [SQLITE_BUSY]
31670 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53   and [SQLITE_MIS
31680 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20  USE].  You must 
31690 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  call.** [sqlite3
316a0 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71  _reset()] or [sq
316b0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
316c0 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69  ] in order to fi
316d0 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a  nd one of the.**
316e0 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72   specific [error
316f0 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74   codes] that bet
31700 74 65 72 20 64 65 73 63 72 69 62 65 73 20 74 68  ter describes th
31710 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61  e error..** We a
31720 64 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 69  dmit that this i
31730 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e  s a goofy design
31740 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68  .  The problem h
31750 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a  as been fixed.**
31760 20 77 69 74 68 20 74 68 65 20 22 76 32 22 20 69   with the "v2" i
31770 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f  nterface.  If yo
31780 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66  u prepare all of
31790 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d   your SQL statem
317a0 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69  ents.** using ei
317b0 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ther [sqlite3_pr
317c0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
317d0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
317e0 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a  6_v2()] instead.
317f0 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79  ** of the legacy
31800 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
31810 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
31820 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 69  3_prepare16()] i
31830 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68  nterfaces,.** th
31840 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63  en the more spec
31850 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65  ific [error code
31860 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 20  s] are returned 
31870 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73  directly.** by s
31880 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
31890 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 22  The use of the "
318a0 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73  v2" interface is
318b0 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f   recommended..*/
318c0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65  .int sqlite3_ste
318d0 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  p(sqlite3_stmt*)
318e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
318f0 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  F: Number of col
31900 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74  umns in a result
31910 20 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20   set.** METHOD: 
31920 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
31930 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
31940 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e  data_count(P) in
31950 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
31960 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
31970 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20  lumns in the.** 
31980 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74  current row of t
31990 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  he result set of
319a0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
319b0 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20  ment] P..** ^If 
319c0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
319d0 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74 20 68 61  nt P does not ha
319e0 76 65 20 72 65 73 75 6c 74 73 20 72 65 61 64 79  ve results ready
319f0 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76   to return.** (v
31a00 69 61 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20  ia calls to the 
31a10 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
31a20 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f  int | sqlite3_co
31a30 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20  lumn_*()] of.** 
31a40 69 6e 74 65 72 66 61 63 65 73 29 20 74 68 65 6e  interfaces) then
31a50 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
31a60 75 6e 74 28 50 29 20 72 65 74 75 72 6e 73 20 30  unt(P) returns 0
31a70 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
31a80 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
31a90 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72 65 74  routine also ret
31aa0 75 72 6e 73 20 30 20 69 66 20 50 20 69 73 20 61  urns 0 if P is a
31ab0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
31ac0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
31ad0 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75  ata_count(P) rou
31ae0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69  tine returns 0 i
31af0 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63  f the previous c
31b00 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
31b10 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75  e3_step](P) retu
31b20 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  rned [SQLITE_DON
31b30 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  E].  ^The sqlite
31b40 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a  3_data_count(P).
31b50 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e  ** will return n
31b60 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72 65 76 69  on-zero if previ
31b70 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ous call to [sql
31b80 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65  ite3_step](P) re
31b90 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54  turned.** [SQLIT
31ba0 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70 74 20 69  E_ROW], except i
31bb0 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20 74 68  n the case of th
31bc0 65 20 5b 50 52 41 47 4d 41 20 69 6e 63 72 65 6d  e [PRAGMA increm
31bd0 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a  ental_vacuum].**
31be0 20 77 68 65 72 65 20 69 74 20 61 6c 77 61 79 73   where it always
31bf0 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 73 69   returns zero si
31c00 6e 63 65 20 65 61 63 68 20 73 74 65 70 20 6f 66  nce each step of
31c10 20 74 68 61 74 20 6d 75 6c 74 69 2d 73 74 65 70   that multi-step
31c20 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65 74 75 72  .** pragma retur
31c30 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20  ns 0 columns of 
31c40 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  data..**.** See 
31c50 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63  also: [sqlite3_c
31c60 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a  olumn_count()].*
31c70 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61  /.int sqlite3_da
31c80 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  ta_count(sqlite3
31c90 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
31ca0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
31cb0 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61  Fundamental Data
31cc0 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  types.** KEYWORD
31cd0 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a  S: SQLITE_TEXT.*
31ce0 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61 6c  *.** ^(Every val
31cf0 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73  ue in SQLite has
31d00 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e   one of five fun
31d10 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70  damental datatyp
31d20 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  es:.**.** <ul>.*
31d30 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69  * <li> 64-bit si
31d40 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20  gned integer.** 
31d50 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45  <li> 64-bit IEEE
31d60 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
31d70 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73  number.** <li> s
31d80 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c  tring.** <li> BL
31d90 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a  OB.** <li> NULL.
31da0 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a  ** </ul>)^.**.**
31db0 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
31dc0 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65   are codes for e
31dd0 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70  ach of those typ
31de0 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  es..**.** Note t
31df0 68 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54  hat the SQLITE_T
31e00 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73  EXT constant was
31e10 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51   also used in SQ
31e20 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a  Lite version 2.*
31e30 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65  * for a complete
31e40 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61  ly different mea
31e50 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20  ning.  Software 
31e60 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e  that links again
31e70 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74  st both.** SQLit
31e80 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20  e version 2 and 
31e90 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
31ea0 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49   should use SQLI
31eb0 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a  TE3_TEXT, not.**
31ec0 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f   SQLITE_TEXT..*/
31ed0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
31ee0 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66 69  INTEGER  1.#defi
31ef0 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20  ne SQLITE_FLOAT 
31f00 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
31f10 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23  ITE_BLOB     4.#
31f20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55  define SQLITE_NU
31f30 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66 20  LL     5.#ifdef 
31f40 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e  SQLITE_TEXT.# un
31f50 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  def SQLITE_TEXT.
31f60 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53  #else.# define S
31f70 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20 33  QLITE_TEXT     3
31f80 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20  .#endif.#define 
31f90 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20  SQLITE3_TEXT    
31fa0 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   3../*.** CAPI3R
31fb0 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65  EF: Result Value
31fc0 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a  s From A Query.*
31fd0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c  * KEYWORDS: {col
31fe0 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74  umn access funct
31ff0 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a  ions}.** METHOD:
32000 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
32010 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
32020 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72  nes return infor
32030 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73  mation about a s
32040 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20  ingle column of 
32050 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72  the current.** r
32060 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71  esult row of a q
32070 75 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79  uery.  ^In every
32080 20 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20   case the first 
32090 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
320a0 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
320b0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
320c0 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69  ent] that is bei
320d0 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 68  ng evaluated (th
320e0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  e [sqlite3_stmt*
320f0 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65  ].** that was re
32100 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  turned from [sql
32110 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
32120 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73  )] or one of its
32130 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e   variants).** an
32140 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  d the second arg
32150 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64  ument is the ind
32160 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  ex of the column
32170 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72   for which infor
32180 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64  mation.** should
32190 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54   be returned. ^T
321a0 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75  he leftmost colu
321b0 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  mn of the result
321c0 20 73 65 74 20 68 61 73 20 74 68 65 20 69 6e 64   set has the ind
321d0 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75  ex 0..** ^The nu
321e0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
321f0 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63 61  in the result ca
32200 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20  n be determined 
32210 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
32220 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29  3_column_count()
32230 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  ]..**.** If the 
32240 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f  SQL statement do
32250 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  es not currently
32260 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69   point to a vali
32270 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65  d row, or if the
32280 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78  .** column index
32290 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
322a0 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  , the result is 
322b0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68  undefined..** Th
322c0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79  ese routines may
322d0 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20   only be called 
322e0 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65  when the most re
322f0 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  cent call to.** 
32300 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
32310 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53   has returned [S
32320 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e  QLITE_ROW] and n
32330 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74  either.** [sqlit
32340 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20  e3_reset()] nor 
32350 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
32360 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63  e()] have been c
32370 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74  alled subsequent
32380 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66  ly..** If any of
32390 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
323a0 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72  are called after
323b0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
323c0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
323d0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
323e0 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
323f0 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75  step()] has retu
32400 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e  rned.** somethin
32410 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  g other than [SQ
32420 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72  LITE_ROW], the r
32430 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
32440 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c  ined..** If [sql
32450 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20  ite3_step()] or 
32460 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
32470 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69  ] or [sqlite3_fi
32480 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65  nalize()].** are
32490 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64   called from a d
324a0 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20  ifferent thread 
324b0 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65  while any of the
324c0 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61  se routines.** a
324d0 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e  re pending, then
324e0 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
324f0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
32500 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
32510 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75  olumn_type() rou
32520 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
32530 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  .** [SQLITE_INTE
32540 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 63  GER | datatype c
32550 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69  ode] for the ini
32560 74 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a  tial data type.*
32570 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  * of the result 
32580 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65  column.  ^The re
32590 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20  turned value is 
325a0 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49  one of [SQLITE_I
325b0 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c  NTEGER],.** [SQL
325c0 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c  ITE_FLOAT], [SQL
325d0 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49  ITE_TEXT], [SQLI
325e0 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51  TE_BLOB], or [SQ
325f0 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65  LITE_NULL].  The
32600 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e   value.** return
32610 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
32620 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f  lumn_type() is o
32630 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69  nly meaningful i
32640 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e  f no type.** con
32650 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63  versions have oc
32660 63 75 72 72 65 64 20 61 73 20 64 65 73 63 72 69  curred as descri
32670 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65  bed below.  Afte
32680 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73  r a type convers
32690 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75  ion,.** the valu
326a0 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  e returned by sq
326b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
326c0 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64  e() is undefined
326d0 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72  .  Future.** ver
326e0 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
326f0 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65 20 62  may change the b
32700 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74  ehavior of sqlit
32710 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
32720 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  .** following a 
32730 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e  type conversion.
32740 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  .**.** ^If the r
32750 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20  esult is a BLOB 
32760 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20  or UTF-8 string 
32770 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
32780 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a  _column_bytes().
32790 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
327a0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
327b0 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42   bytes in that B
327c0 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a  LOB or string..*
327d0 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
327e0 20 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 72   is a UTF-16 str
327f0 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ing, then sqlite
32800 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
32810 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65   converts.** the
32820 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38   string to UTF-8
32830 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e   and then return
32840 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
32850 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68  bytes..** ^If th
32860 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75  e result is a nu
32870 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e  meric value then
32880 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
32890 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20  bytes() uses.** 
328a0 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
328b0 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20  f()] to convert 
328c0 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20  that value to a 
328d0 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64  UTF-8 string and
328e0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20   returns.** the 
328f0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
32900 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a  in that string..
32910 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
32920 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  t is NULL, then 
32930 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
32940 79 74 65 73 28 29 20 72 65 74 75 72 6e 73 20 7a  ytes() returns z
32950 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ero..**.** ^If t
32960 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42  he result is a B
32970 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36 20 73 74  LOB or UTF-16 st
32980 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71  ring then the sq
32990 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
329a0 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  es16().** routin
329b0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
329c0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
329d0 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74   that BLOB or st
329e0 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
329f0 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46   result is a UTF
32a00 2d 38 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  -8 string, then 
32a10 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
32a20 79 74 65 73 31 36 28 29 20 63 6f 6e 76 65 72 74  ytes16() convert
32a30 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20  s.** the string 
32a40 74 6f 20 55 54 46 2d 31 36 20 61 6e 64 20 74 68  to UTF-16 and th
32a50 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  en returns the n
32a60 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a  umber of bytes..
32a70 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
32a80 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76  t is a numeric v
32a90 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65  alue then sqlite
32aa0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
32ab0 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69  () uses.** [sqli
32ac0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
32ad0 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20  to convert that 
32ae0 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 31  value to a UTF-1
32af0 36 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74  6 string and ret
32b00 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  urns.** the numb
32b10 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
32b20 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e  hat string..** ^
32b30 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
32b40 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69   NULL, then sqli
32b50 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
32b60 31 36 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72  16() returns zer
32b70 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61  o..**.** ^The va
32b80 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79  lues returned by
32b90 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
32ba0 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a  _bytes()] and .*
32bb0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
32bc0 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 64 6f 20  n_bytes16()] do 
32bd0 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20  not include the 
32be0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73  zero terminators
32bf0 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f   at the end.** o
32c00 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20 5e  f the string.  ^
32c10 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65  For clarity: the
32c20 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
32c30 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
32c40 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20  column_bytes()] 
32c50 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  and [sqlite3_col
32c60 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 61  umn_bytes16()] a
32c70 72 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  re the number of
32c80 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65  .** bytes in the
32c90 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65   string, not the
32ca0 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
32cb0 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74  cters..**.** ^St
32cc0 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62  rings returned b
32cd0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
32ce0 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69  _text() and sqli
32cf0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
32d00 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70  6(),.** even emp
32d10 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20  ty strings, are 
32d20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d  always zero-term
32d30 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 72 65  inated.  ^The re
32d40 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72  turn.** value fr
32d50 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  om sqlite3_colum
32d60 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a  n_blob() for a z
32d70 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20  ero-length BLOB 
32d80 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
32d90 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 57 61 72 6e  r..**.** <b>Warn
32da0 69 6e 67 3a 3c 2f 62 3e 20 5e 54 68 65 20 6f 62  ing:</b> ^The ob
32db0 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79  ject returned by
32dc0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
32dd0 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a  _value()] is an.
32de0 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  ** [unprotected 
32df0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
32e00 62 6a 65 63 74 2e 20 20 49 6e 20 61 20 6d 75 6c  bject.  In a mul
32e10 74 69 74 68 72 65 61 64 65 64 20 65 6e 76 69 72  tithreaded envir
32e20 6f 6e 6d 65 6e 74 2c 0a 2a 2a 20 61 6e 20 75 6e  onment,.** an un
32e30 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
32e40 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d  3_value object m
32e50 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20  ay only be used 
32e60 73 61 66 65 6c 79 20 77 69 74 68 0a 2a 2a 20 5b  safely with.** [
32e70 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c  sqlite3_bind_val
32e80 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ue()] and [sqlit
32e90 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
32ea0 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75  )]..** If the [u
32eb0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
32ec0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
32ed0 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
32ee0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
32ef0 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64  value()] is used
32f00 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61   in any other wa
32f10 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c  y, including cal
32f20 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65  ls.** to routine
32f30 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f  s like [sqlite3_
32f40 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73  value_int()], [s
32f50 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
32f60 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c  t()],.** or [sql
32f70 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
32f80 28 29 5d 2c 20 74 68 65 20 62 65 68 61 76 69 6f  ()], the behavio
32f90 72 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73  r is not threads
32fa0 61 66 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  afe..**.** These
32fb0 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70   routines attemp
32fc0 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65  t to convert the
32fd0 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 70   value where app
32fe0 72 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a  ropriate.  ^For.
32ff0 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74  ** example, if t
33000 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72  he internal repr
33010 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c  esentation is FL
33020 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 72  OAT and a text r
33030 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75  esult.** is requ
33040 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f  ested, [sqlite3_
33050 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75  snprintf()] is u
33060 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74  sed internally t
33070 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a  o perform the.**
33080 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f   conversion auto
33090 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68  matically.  ^(Th
330a0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c  e following tabl
330b0 65 20 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f  e details the co
330c0 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61  nversions.** tha
330d0 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a  t are applied:.*
330e0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
330f0 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64  >.** <table bord
33100 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c  er="1">.** <tr><
33110 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e  th> Internal<br>
33120 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73  Type <th> Reques
33130 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e  ted<br>Type <th>
33140 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a    Conversion.**.
33150 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
33160 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  L    <td> INTEGE
33170 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20  R   <td> Result 
33180 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  is 0.** <tr><td>
33190 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
331a0 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65  FLOAT    <td> Re
331b0 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c  sult is 0.0.** <
331c0 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
331d0 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
331e0 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 61  <td> Result is a
331f0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
33200 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
33210 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
33220 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
33230 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a   a NULL pointer.
33240 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45  ** <tr><td> INTE
33250 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  GER  <td>  FLOAT
33260 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74      <td> Convert
33270 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f   from integer to
33280 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74   float.** <tr><t
33290 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
332a0 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
332b0 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20  ASCII rendering 
332c0 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a  of the integer.*
332d0 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
332e0 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20  ER  <td>   BLOB 
332f0 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20     <td> Same as 
33300 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a  INTEGER->TEXT.**
33310 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54   <tr><td>  FLOAT
33320 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
33330 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f    <td> [CAST] to
33340 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e   INTEGER.** <tr>
33350 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74  <td>  FLOAT   <t
33360 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
33370 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e  > ASCII renderin
33380 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a  g of the float.*
33390 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
333a0 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20  T   <td>   BLOB 
333b0 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74     <td> [CAST] t
333c0 6f 20 42 4c 4f 42 0a 2a 2a 20 3c 74 72 3e 3c 74  o BLOB.** <tr><t
333d0 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
333e0 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
333f0 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45  [CAST] to INTEGE
33400 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  R.** <tr><td>  T
33410 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f  EXT    <td>  FLO
33420 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54  AT    <td> [CAST
33430 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72  ] to REAL.** <tr
33440 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
33450 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
33460 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20  d> No change.** 
33470 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
33480 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
33490 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20   <td> [CAST] to 
334a0 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c  INTEGER.** <tr><
334b0 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
334c0 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
334d0 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a   [CAST] to REAL.
334e0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
334f0 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54  B    <td>   TEXT
33500 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a      <td> Add a z
33510 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69  ero terminator i
33520 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61  f needed.** </ta
33530 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71  ble>.** </blockq
33540 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f  uote>)^.**.** No
33550 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 79 70  te that when typ
33560 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63  e conversions oc
33570 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65  cur, pointers re
33580 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a  turned by prior.
33590 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ** calls to sqli
335a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
335b0 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ), sqlite3_colum
335c0 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72  n_text(), and/or
335d0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
335e0 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20  mn_text16() may 
335f0 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a  be invalidated..
33600 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69  ** Type conversi
33610 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20  ons and pointer 
33620 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69  invalidations mi
33630 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20  ght occur.** in 
33640 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61  the following ca
33650 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ses:.**.** <ul>.
33660 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
33670 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61  ial content is a
33680 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65   BLOB and sqlite
33690 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
336a0 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74  or.**      sqlit
336b0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
336c0 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41  () is called.  A
336d0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72   zero-terminator
336e0 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e   might.**      n
336f0 65 65 64 20 74 6f 20 62 65 20 61 64 64 65 64 20  eed to be added 
33700 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f  to the string.</
33710 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  li>.** <li> The 
33720 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
33730 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e  is UTF-8 text an
33740 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
33750 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a  _bytes16() or.**
33760 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
33770 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73  lumn_text16() is
33780 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f   called.  The co
33790 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f  ntent must be co
337a0 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20  nverted.**      
337b0 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a  to UTF-16.</li>.
337c0 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
337d0 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55  ial content is U
337e0 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73  TF-16 text and s
337f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
33800 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  tes() or.**     
33810 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
33820 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64  text() is called
33830 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d  .  The content m
33840 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
33850 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d  .**      to UTF-
33860 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e  8.</li>.** </ul>
33870 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69  .**.** ^Conversi
33880 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d  ons between UTF-
33890 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c  16be and UTF-16l
338a0 65 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e  e are always don
338b0 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64  e in place and d
338c0 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64  o.** not invalid
338d0 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e  ate a prior poin
338e0 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63  ter, though of c
338f0 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e  ourse the conten
33900 74 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a  t of the buffer.
33910 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 69 6f  ** that the prio
33920 72 20 70 6f 69 6e 74 65 72 20 72 65 66 65 72 65  r pointer refere
33930 6e 63 65 73 20 77 69 6c 6c 20 68 61 76 65 20 62  nces will have b
33940 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f  een modified.  O
33950 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66  ther kinds.** of
33960 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20   conversion are 
33970 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68  done in place wh
33980 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c  en it is possibl
33990 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73  e, but sometimes
339a0 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74   they.** are not
339b0 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e   possible and in
339c0 20 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 69   those cases pri
339d0 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20  or pointers are 
339e0 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a  invalidated..**.
339f0 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20 70 6f  ** The safest po
33a00 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b  licy is to invok
33a10 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  e these routines
33a20 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68  .** in one of th
33a30 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73  e following ways
33a40 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
33a50 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
33a60 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f  umn_text() follo
33a70 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
33a80 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c  olumn_bytes()</l
33a90 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  i>.**  <li>sqlit
33aa0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
33ab0 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
33ac0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
33ad0 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69  s()</li>.**  <li
33ae0 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
33af0 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65  text16() followe
33b00 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
33b10 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c  umn_bytes16()</l
33b20 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  i>.** </ul>.**.*
33b30 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  * In other words
33b40 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c  , you should cal
33b50 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  l sqlite3_column
33b60 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69  _text(),.** sqli
33b70 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
33b80 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  ), or sqlite3_co
33b90 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69  lumn_text16() fi
33ba0 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65  rst to force the
33bb0 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20   result.** into 
33bc0 74 68 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d  the desired form
33bd0 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20  at, then invoke 
33be0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
33bf0 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c  ytes() or.** sql
33c00 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
33c10 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68  s16() to find th
33c20 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65  e size of the re
33c30 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69  sult.  Do not mi
33c40 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71  x calls.** to sq
33c50 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
33c60 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  t() or sqlite3_c
33c70 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74  olumn_blob() wit
33c80 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71  h calls to.** sq
33c90 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
33ca0 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e  es16(), and do n
33cb0 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20  ot mix calls to 
33cc0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
33cd0 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20  ext16().** with 
33ce0 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
33cf0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e  _column_bytes().
33d00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e  .**.** ^The poin
33d10 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 61 72  ters returned ar
33d20 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20  e valid until a 
33d30 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20  type conversion 
33d40 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73  occurs as.** des
33d50 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72  cribed above, or
33d60 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f   until [sqlite3_
33d70 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69  step()] or [sqli
33d80 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a  te3_reset()] or.
33d90 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ** [sqlite3_fina
33da0 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65  lize()] is calle
33db0 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20  d.  ^The memory 
33dc0 73 70 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f  space used to ho
33dd0 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e  ld strings.** an
33de0 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64  d BLOBs is freed
33df0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
33e00 20 44 6f 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e   Do <em>not</em>
33e10 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65   pass the pointe
33e20 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66  rs returned.** f
33e30 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  rom [sqlite3_col
33e40 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71  umn_blob()], [sq
33e50 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
33e60 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a  t()], etc. into.
33e70 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ** [sqlite3_free
33e80 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  ()]..**.** ^(If 
33e90 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
33ea0 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ion error occurs
33eb0 20 64 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c   during the eval
33ec0 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a  uation of any.**
33ed0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
33ee0 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61  es, a default va
33ef0 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e  lue is returned.
33f00 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61    The default va
33f10 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72  lue.** is either
33f20 20 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20   the integer 0, 
33f30 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  the floating poi
33f40 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f  nt number 0.0, o
33f50 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e  r a NULL.** poin
33f60 74 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74  ter.  Subsequent
33f70 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
33f80 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69  e3_errcode()] wi
33f90 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51  ll return.** [SQ
33fa0 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a  LITE_NOMEM].)^.*
33fb0 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  /.const void *sq
33fc0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
33fd0 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
33fe0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20   int iCol);.int 
33ff0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
34000 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d  ytes(sqlite3_stm
34010 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
34020 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
34030 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65  n_bytes16(sqlite
34040 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
34050 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74  l);.double sqlit
34060 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65  e3_column_double
34070 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
34080 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
34090 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
340a0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
340b0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69   int iCol);.sqli
340c0 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
340d0 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73  3_column_int64(s
340e0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
340f0 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75  t iCol);.const u
34100 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71  nsigned char *sq
34110 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
34120 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
34130 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73   int iCol);.cons
34140 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
34150 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71  column_text16(sq
34160 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
34170 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
34180 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
34190 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
341a0 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65  nt iCol);.sqlite
341b0 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33  3_value *sqlite3
341c0 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71  _column_value(sq
341d0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
341e0 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43   iCol);../*.** C
341f0 41 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79  API3REF: Destroy
34200 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
34210 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20  ement Object.** 
34220 44 45 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69  DESTRUCTOR: sqli
34230 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
34240 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  The sqlite3_fina
34250 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  lize() function 
34260 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c  is called to del
34270 65 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20  ete a [prepared 
34280 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e  statement]..** ^
34290 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
342a0 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66  nt evaluation of
342b0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 65   the statement e
342c0 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65 72  ncountered no er
342d0 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68  rors.** or if th
342e0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e  e statement is n
342f0 65 76 65 72 20 62 65 65 6e 20 65 76 61 6c 75 61  ever been evalua
34300 74 65 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ted, then sqlite
34310 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72 65 74  3_finalize() ret
34320 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f  urns.** SQLITE_O
34330 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  K.  ^If the most
34340 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69   recent evaluati
34350 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e 74 20  on of statement 
34360 53 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a  S failed, then.*
34370 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  * sqlite3_finali
34380 7a 65 28 53 29 20 72 65 74 75 72 6e 73 20 74 68  ze(S) returns th
34390 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65  e appropriate [e
343a0 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a  rror code] or.**
343b0 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   [extended error
343c0 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54   code]..**.** ^T
343d0 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  he sqlite3_final
343e0 69 7a 65 28 53 29 20 72 6f 75 74 69 6e 65 20 63  ize(S) routine c
343f0 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20  an be called at 
34400 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67  any point during
34410 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20 63 79 63  .** the life cyc
34420 6c 65 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20  le of [prepared 
34430 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a  statement] S:.**
34440 20 62 65 66 6f 72 65 20 73 74 61 74 65 6d 65 6e   before statemen
34450 74 20 53 20 69 73 20 65 76 65 72 20 65 76 61 6c  t S is ever eval
34460 75 61 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20  uated, after.** 
34470 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c  one or more call
34480 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  s to [sqlite3_re
34490 73 65 74 28 29 5d 2c 20 6f 72 20 61 66 74 65 72  set()], or after
344a0 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20   any call.** to 
344b0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
344c0 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   regardless of w
344d0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
344e0 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 0a  e statement has.
344f0 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65  ** completed exe
34500 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49  cution..**.** ^I
34510 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f  nvoking sqlite3_
34520 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20  finalize() on a 
34530 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
34540 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  a harmless no-op
34550 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ..**.** The appl
34560 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e  ication must fin
34570 61 6c 69 7a 65 20 65 76 65 72 79 20 5b 70 72 65  alize every [pre
34580 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
34590 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 61 76 6f   in order to avo
345a0 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c  id.** resource l
345b0 65 61 6b 73 2e 20 20 49 74 20 69 73 20 61 20 67  eaks.  It is a g
345c0 72 69 65 76 6f 75 73 20 65 72 72 6f 72 20 66 6f  rievous error fo
345d0 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
345e0 6e 20 74 6f 20 74 72 79 20 74 6f 20 75 73 65 0a  n to try to use.
345f0 2a 2a 20 61 20 70 72 65 70 61 72 65 64 20 73 74  ** a prepared st
34600 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74  atement after it
34610 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69   has been finali
34620 7a 65 64 2e 20 20 41 6e 79 20 75 73 65 20 6f 66  zed.  Any use of
34630 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73   a prepared.** s
34640 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69  tatement after i
34650 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c  t has been final
34660 69 7a 65 64 20 63 61 6e 20 72 65 73 75 6c 74 20  ized can result 
34670 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  in undefined and
34680 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 20  .** undesirable 
34690 62 65 68 61 76 69 6f 72 20 73 75 63 68 20 61 73  behavior such as
346a0 20 73 65 67 66 61 75 6c 74 73 20 61 6e 64 20 68   segfaults and h
346b0 65 61 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a  eap corruption..
346c0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66  */.int sqlite3_f
346d0 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f  inalize(sqlite3_
346e0 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
346f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
34700 65 73 65 74 20 41 20 50 72 65 70 61 72 65 64 20  eset A Prepared 
34710 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
34720 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
34730 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54  te3_stmt.**.** T
34740 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74  he sqlite3_reset
34750 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  () function is c
34760 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61  alled to reset a
34770 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
34780 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  ment].** object 
34790 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74  back to its init
347a0 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79  ial state, ready
347b0 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74   to be re-execut
347c0 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20  ed..** ^Any SQL 
347d0 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62  statement variab
347e0 6c 65 73 20 74 68 61 74 20 68 61 64 20 76 61 6c  les that had val
347f0 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65  ues bound to the
34800 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b  m using.** the [
34810 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
34820 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  b | sqlite3_bind
34830 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e  _*() API] retain
34840 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a   their values..*
34850 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63  * Use [sqlite3_c
34860 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d  lear_bindings()]
34870 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 62 69   to reset the bi
34880 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ndings..**.** ^T
34890 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
348a0 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(S)] interface 
348b0 72 65 73 65 74 73 20 74 68 65 20 5b 70 72 65 70  resets the [prep
348c0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
348d0 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65  S.** back to the
348e0 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74   beginning of it
348f0 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a  s program..**.**
34900 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
34910 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
34920 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66  lite3_step(S)] f
34930 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  or the.** [prepa
34940 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
34950 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
34960 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54  E_ROW] or [SQLIT
34970 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69  E_DONE],.** or i
34980 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  f [sqlite3_step(
34990 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65  S)] has never be
349a0 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64  fore been called
349b0 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b   on S,.** then [
349c0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
349d0 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  ] returns [SQLIT
349e0 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  E_OK]..**.** ^If
349f0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
34a00 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
34a10 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74  3_step(S)] for t
34a20 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
34a30 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64  statement] S ind
34a40 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c  icated an error,
34a50 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65   then.** [sqlite
34a60 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75  3_reset(S)] retu
34a70 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61  rns an appropria
34a80 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e  te [error code].
34a90 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  .**.** ^The [sql
34aa0 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69  ite3_reset(S)] i
34ab0 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f  nterface does no
34ac0 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c  t change the val
34ad0 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73  ues.** of any [s
34ae0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
34af0 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68  |bindings] on th
34b00 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
34b10 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74  ement] S..*/.int
34b20 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73   sqlite3_reset(s
34b30 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
34b40 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
34b50 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20  3REF: Create Or 
34b60 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e  Redefine SQL Fun
34b70 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52  ctions.** KEYWOR
34b80 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72  DS: {function cr
34b90 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d  eation routines}
34ba0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
34bb0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
34bc0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d  ed SQL function}
34bd0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
34be0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
34bf0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
34c00 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  }.** METHOD: sql
34c10 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ite3.**.** ^Thes
34c20 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c  e functions (col
34c30 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20  lectively known 
34c40 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65  as "function cre
34c50 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29  ation routines")
34c60 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20  .** are used to 
34c70 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  add SQL function
34c80 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 20  s or aggregates 
34c90 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74  or to redefine t
34ca0 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f  he behavior.** o
34cb0 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66  f existing SQL f
34cc0 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72  unctions or aggr
34cd0 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c  egates.  The onl
34ce0 79 20 64 69 66 66 65 72 65 6e 63 65 73 20 62 65  y differences be
34cf0 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72  tween.** these r
34d00 6f 75 74 69 6e 65 73 20 61 72 65 20 74 68 65 20  outines are the 
34d10 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78  text encoding ex
34d20 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68  pected for.** th
34d30 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
34d40 65 72 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20  er (the name of 
34d50 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69  the function bei
34d60 6e 67 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61  ng created).** a
34d70 6e 64 20 74 68 65 20 70 72 65 73 65 6e 63 65 20  nd the presence 
34d80 6f 72 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20  or absence of a 
34d90 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62  destructor callb
34da0 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61  ack for.** the a
34db0 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
34dc0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
34dd0 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
34de0 74 65 72 20 69 73 20 74 68 65 20 5b 64 61 74 61  ter is the [data
34df0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
34e00 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 53 51   to which the SQ
34e10 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73  L.** function is
34e20 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e   to be added.  ^
34e30 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  If an applicatio
34e40 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e  n uses more than
34e50 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   one database.**
34e60 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e   connection then
34e70 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
34e80 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
34e90 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64 65 64  ns must be added
34ea0 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61  .** to each data
34eb0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
34ec0 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a  separately..**.*
34ed0 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  * ^The second pa
34ee0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e  rameter is the n
34ef0 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66  ame of the SQL f
34f00 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72  unction to be cr
34f10 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65  eated or.** rede
34f20 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e  fined.  ^The len
34f30 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20  gth of the name 
34f40 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35  is limited to 25
34f50 35 20 62 79 74 65 73 20 69 6e 20 61 20 55 54 46  5 bytes in a UTF
34f60 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61  -8.** representa
34f70 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20  tion, exclusive 
34f80 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d  of the zero-term
34f90 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74  inator.  ^Note t
34fa0 68 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20  hat the name.** 
34fb0 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20  length limit is 
34fc0 69 6e 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20  in UTF-8 bytes, 
34fd0 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 20 6e  not characters n
34fe0 6f 72 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e  or UTF-16 bytes.
34ff0 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d    .** ^Any attem
35000 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66  pt to create a f
35010 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c  unction with a l
35020 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69  onger name.** wi
35030 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51  ll result in [SQ
35040 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69  LITE_MISUSE] bei
35050 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  ng returned..**.
35060 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 70 61  ** ^The third pa
35070 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a  rameter (nArg).*
35080 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  * is the number 
35090 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  of arguments tha
350a0 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
350b0 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61  on or.** aggrega
350c0 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68  te takes. ^If th
350d0 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  is parameter is 
350e0 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c  -1, then the SQL
350f0 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
35100 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61  aggregate may ta
35110 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66  ke any number of
35120 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65   arguments betwe
35130 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d  en 0 and the lim
35140 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71  it.** set by [sq
35150 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51  lite3_limit]([SQ
35160 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
35170 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74  ION_ARG]).  If t
35180 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61  he third.** para
35190 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20 74 68  meter is less th
351a0 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72  an -1 or greater
351b0 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74   than 127 then t
351c0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a  he behavior is.*
351d0 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  * undefined..**.
351e0 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70  ** ^The fourth p
351f0 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52  arameter, eTextR
35200 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68  ep, specifies wh
35210 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54  at.** [SQLITE_UT
35220 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69  F8 | text encodi
35230 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e  ng] this SQL fun
35240 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f  ction prefers fo
35250 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74  r.** its paramet
35260 65 72 73 2e 20 20 54 68 65 20 61 70 70 6c 69 63  ers.  The applic
35270 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 73 65 74  ation should set
35280 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20   this parameter 
35290 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54  to.** [SQLITE_UT
352a0 46 31 36 4c 45 5d 20 69 66 20 74 68 65 20 66 75  F16LE] if the fu
352b0 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
352c0 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 0a 2a  ation invokes .*
352d0 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
352e0 5f 74 65 78 74 31 36 6c 65 28 29 5d 20 6f 6e 20  _text16le()] on 
352f0 61 6e 20 69 6e 70 75 74 2c 20 6f 72 20 5b 53 51  an input, or [SQ
35300 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 20 69 66  LITE_UTF16BE] if
35310 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   the.** implemen
35320 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 5b  tation invokes [
35330 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
35340 78 74 31 36 62 65 28 29 5d 20 6f 6e 20 61 6e 20  xt16be()] on an 
35350 69 6e 70 75 74 2c 20 6f 72 0a 2a 2a 20 5b 53 51  input, or.** [SQ
35360 4c 49 54 45 5f 55 54 46 31 36 5d 20 69 66 20 5b  LITE_UTF16] if [
35370 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
35380 78 74 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c  xt16()] is used,
35390 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 38   or [SQLITE_UTF8
353a0 5d 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 2e 20  ].** otherwise. 
353b0 20 5e 54 68 65 20 73 61 6d 65 20 53 51 4c 20 66   ^The same SQL f
353c0 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72  unction may be r
353d0 65 67 69 73 74 65 72 65 64 20 6d 75 6c 74 69 70  egistered multip
353e0 6c 65 20 74 69 6d 65 73 20 75 73 69 6e 67 0a 2a  le times using.*
353f0 2a 20 64 69 66 66 65 72 65 6e 74 20 70 72 65 66  * different pref
35400 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
35410 69 6e 67 73 2c 20 77 69 74 68 20 64 69 66 66 65  ings, with diffe
35420 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74  rent implementat
35430 69 6f 6e 73 20 66 6f 72 0a 2a 2a 20 65 61 63 68  ions for.** each
35440 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 20 5e 57   encoding..** ^W
35450 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70  hen multiple imp
35460 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
35470 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
35480 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c  n are available,
35490 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20   SQLite.** will 
354a0 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61  pick the one tha
354b0 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c  t involves the l
354c0 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64  east amount of d
354d0 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a  ata conversion..
354e0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74  **.** ^The fourt
354f0 68 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  h parameter may 
35500 6f 70 74 69 6f 6e 61 6c 6c 79 20 62 65 20 4f 52  optionally be OR
35510 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  ed with [SQLITE_
35520 44 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 0a 2a  DETERMINISTIC].*
35530 2a 20 74 6f 20 73 69 67 6e 61 6c 20 74 68 61 74  * to signal that
35540 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 77 69   the function wi
35550 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  ll always return
35560 20 74 68 65 20 73 61 6d 65 20 72 65 73 75 6c 74   the same result
35570 20 67 69 76 65 6e 0a 2a 2a 20 74 68 65 20 73 61   given.** the sa
35580 6d 65 20 69 6e 70 75 74 73 20 77 69 74 68 69 6e  me inputs within
35590 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74   a single SQL st
355a0 61 74 65 6d 65 6e 74 2e 20 20 4d 6f 73 74 20 53  atement.  Most S
355b0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  QL functions are
355c0 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 69 73 74 69  .** deterministi
355d0 63 2e 20 20 54 68 65 20 62 75 69 6c 74 2d 69 6e  c.  The built-in
355e0 20 5b 72 61 6e 64 6f 6d 28 29 5d 20 53 51 4c 20   [random()] SQL 
355f0 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 6e 20 65  function is an e
35600 78 61 6d 70 6c 65 20 6f 66 20 61 0a 2a 2a 20 66  xample of a.** f
35610 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 69 73 20  unction that is 
35620 6e 6f 74 20 64 65 74 65 72 6d 69 6e 69 73 74 69  not deterministi
35630 63 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 71  c.  The SQLite q
35640 75 65 72 79 20 70 6c 61 6e 6e 65 72 20 69 73 20  uery planner is 
35650 61 62 6c 65 20 74 6f 0a 2a 2a 20 70 65 72 66 6f  able to.** perfo
35660 72 6d 20 61 64 64 69 74 69 6f 6e 61 6c 20 6f 70  rm additional op
35670 74 69 6d 69 7a 61 74 69 6f 6e 73 20 6f 6e 20 64  timizations on d
35680 65 74 65 72 6d 69 6e 69 73 74 69 63 20 66 75 6e  eterministic fun
35690 63 74 69 6f 6e 73 2c 20 73 6f 20 75 73 65 0a 2a  ctions, so use.*
356a0 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45  * of the [SQLITE
356b0 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 20  _DETERMINISTIC] 
356c0 66 6c 61 67 20 69 73 20 72 65 63 6f 6d 6d 65 6e  flag is recommen
356d0 64 65 64 20 77 68 65 72 65 20 70 6f 73 73 69 62  ded where possib
356e0 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  le..**.** ^(The 
356f0 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20  fifth parameter 
35700 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20  is an arbitrary 
35710 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d  pointer.  The im
35720 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
35730 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  the.** function 
35740 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20  can gain access 
35750 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20  to this pointer 
35760 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75  using [sqlite3_u
35770 73 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a  ser_data()].)^.*
35780 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c  *.** ^The sixth,
35790 20 73 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67   seventh and eig
357a0 68 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20  hth parameters, 
357b0 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64  xFunc, xStep and
357c0 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20   xFinal, are.** 
357d0 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61  pointers to C-la
357e0 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73  nguage functions
357f0 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20   that implement 
35800 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
35810 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
35820 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20  . ^A scalar SQL 
35830 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
35840 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  s an implementat
35850 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63  ion of the xFunc
35860 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c  .** callback onl
35870 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  y; NULL pointers
35880 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20   must be passed 
35890 61 73 20 74 68 65 20 78 53 74 65 70 20 61 6e 64  as the xStep and
358a0 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d   xFinal.** param
358b0 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65  eters. ^An aggre
358c0 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
358d0 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d  n requires an im
358e0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
358f0 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69  xStep.** and xFi
35900 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69  nal and NULL poi
35910 6e 74 65 72 20 6d 75 73 74 20 62 65 20 70 61 73  nter must be pas
35920 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e  sed for xFunc. ^
35930 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69  To delete an exi
35940 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e  sting.** SQL fun
35950 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61  ction or aggrega
35960 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f  te, pass NULL po
35970 69 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 74  inters for all t
35980 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  hree function.**
35990 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a   callbacks..**.*
359a0 2a 20 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68  * ^(If the ninth
359b0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
359c0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
359d0 63 74 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f  ction_v2() is no
359e0 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20  t NULL,.** then 
359f0 69 74 20 69 73 20 64 65 73 74 72 75 63 74 6f 72  it is destructor
35a00 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61   for the applica
35a10 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65  tion data pointe
35a20 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72  r. .** The destr
35a30 75 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64  uctor is invoked
35a40 20 77 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69   when the functi
35a50 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65  on is deleted, e
35a60 69 74 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a  ither by being.*
35a70 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20  * overloaded or 
35a80 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  when the databas
35a90 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f  e connection clo
35aa0 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64  ses.)^.** ^The d
35ab0 65 73 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73  estructor is als
35ac0 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65  o invoked if the
35ad0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69   call to.** sqli
35ae0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
35af0 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a  ion_v2() fails..
35b00 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73  ** ^When the des
35b10 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b  tructor callback
35b20 20 6f 66 20 74 68 65 20 74 65 6e 74 68 20 70 61   of the tenth pa
35b30 72 61 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b  rameter is invok
35b40 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73  ed, it.** is pas
35b50 73 65 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67  sed a single arg
35b60 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
35b70 20 63 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70   copy of the app
35b80 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a  lication data .*
35b90 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20  * pointer which 
35ba0 77 61 73 20 74 68 65 20 66 69 66 74 68 20 70 61  was the fifth pa
35bb0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
35bc0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
35bd0 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  on_v2()..**.** ^
35be0 49 74 20 69 73 20 70 65 72 6d 69 74 74 65 64 20  It is permitted 
35bf0 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74  to register mult
35c00 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  iple implementat
35c10 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
35c20 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69  .** functions wi
35c30 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  th the same name
35c40 20 62 75 74 20 77 69 74 68 20 65 69 74 68 65 72   but with either
35c50 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65   differing numbe
35c60 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e  rs of.** argumen
35c70 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20  ts or differing 
35c80 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65  preferred text e
35c90 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69  ncodings.  ^SQLi
35ca0 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74  te will use.** t
35cb0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
35cc0 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73  n that most clos
35cd0 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 20  ely matches the 
35ce0 77 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 65  way in which the
35cf0 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  .** SQL function
35d00 20 69 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75   is used.  ^A fu
35d10 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
35d20 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e  ation with a non
35d30 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72  -negative.** nAr
35d40 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  g parameter is a
35d50 20 62 65 74 74 65 72 20 6d 61 74 63 68 20 74 68   better match th
35d60 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d  an a function im
35d70 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74  plementation wit
35d80 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20  h.** a negative 
35d90 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69  nArg.  ^A functi
35da0 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70 72 65  on where the pre
35db0 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f  ferred text enco
35dc0 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20  ding.** matches 
35dd0 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 63  the database enc
35de0 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74 74 65  oding is a bette
35df0 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20  r.** match than 
35e00 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  a function where
35e10 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73   the encoding is
35e20 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a   different.  .**
35e30 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65   ^A function whe
35e40 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  re the encoding 
35e50 64 69 66 66 65 72 65 6e 63 65 20 69 73 20 62 65  difference is be
35e60 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e  tween UTF16le an
35e70 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20  d UTF16be.** is 
35e80 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74  a closer match t
35e90 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  han a function w
35ea0 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e  here the encodin
35eb0 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a  g difference is.
35ec0 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38 20  ** between UTF8 
35ed0 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a  and UTF16..**.**
35ee0 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74   ^Built-in funct
35ef0 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72  ions may be over
35f00 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61 70  loaded by new ap
35f10 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
35f20 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a  d functions..**.
35f30 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69  ** ^An applicati
35f40 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
35f50 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64  ion is permitted
35f60 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a   to call other.*
35f70 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  * SQLite interfa
35f80 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73  ces.  However, s
35f90 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e  uch calls must n
35fa0 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20  ot.** close the 
35fb0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
35fc0 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65  ion nor finalize
35fd0 20 6f 72 20 72 65 73 65 74 20 74 68 65 20 70 72   or reset the pr
35fe0 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d  epared.** statem
35ff0 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68 65  ent in which the
36000 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
36010 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ning..*/.int sql
36020 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
36030 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20  tion(.  sqlite3 
36040 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61  *db,.  const cha
36050 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65  r *zFunctionName
36060 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20  ,.  int nArg,.  
36070 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20  int eTextRep,.  
36080 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f  void *pApp,.  vo
36090 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69  id (*xFunc)(sqli
360a0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
360b0 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
360c0 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65  ),.  void (*xSte
360d0 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  p)(sqlite3_conte
360e0 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
360f0 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
36100 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74   (*xFinal)(sqlit
36110 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a  e3_context*).);.
36120 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
36130 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20  te_function16(. 
36140 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20   sqlite3 *db,.  
36150 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e  const void *zFun
36160 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74  ctionName,.  int
36170 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65   nArg,.  int eTe
36180 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70  xtRep,.  void *p
36190 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  App,.  void (*xF
361a0 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
361b0 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
361c0 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
361d0 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69  id (*xStep)(sqli
361e0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
361f0 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
36200 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e  ),.  void (*xFin
36210 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  al)(sqlite3_cont
36220 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  ext*).);.int sql
36230 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
36240 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74  tion_v2(.  sqlit
36250 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20  e3 *db,.  const 
36260 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e  char *zFunctionN
36270 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c  ame,.  int nArg,
36280 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
36290 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20  .  void *pApp,. 
362a0 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73   void (*xFunc)(s
362b0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
362c0 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
362d0 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
362e0 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f  Step)(sqlite3_co
362f0 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
36300 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
36310 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71  oid (*xFinal)(sq
36320 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c  lite3_context*),
36330 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f  .  void(*xDestro
36340 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a  y)(void*).);../*
36350 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65  .** CAPI3REF: Te
36360 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a  xt Encodings.**.
36370 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
36380 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72  t define integer
36390 20 63 6f 64 65 73 20 74 68 61 74 20 72 65 70 72   codes that repr
363a0 65 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75  esent the variou
363b0 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69  s.** text encodi
363c0 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20 62 79  ngs supported by
363d0 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66   SQLite..*/.#def
363e0 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20  ine SQLITE_UTF8 
363f0 20 20 20 20 20 20 20 20 20 20 31 20 20 20 20 2f            1    /
36400 2a 20 49 4d 50 3a 20 52 2d 33 37 35 31 34 2d 33  * IMP: R-37514-3
36410 35 35 36 36 20 2a 2f 0a 23 64 65 66 69 6e 65 20  5566 */.#define 
36420 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20  SQLITE_UTF16LE  
36430 20 20 20 20 20 20 32 20 20 20 20 2f 2a 20 49 4d        2    /* IM
36440 50 3a 20 52 2d 30 33 33 37 31 2d 33 37 36 33 37  P: R-03371-37637
36450 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
36460 54 45 5f 55 54 46 31 36 42 45 20 20 20 20 20 20  TE_UTF16BE      
36470 20 20 33 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52    3    /* IMP: R
36480 2d 35 31 39 37 31 2d 33 34 31 35 34 20 2a 2f 0a  -51971-34154 */.
36490 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
364a0 54 46 31 36 20 20 20 20 20 20 20 20 20 20 34 20  TF16          4 
364b0 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65     /* Use native
364c0 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23   byte order */.#
364d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e  define SQLITE_AN
364e0 59 20 20 20 20 20 20 20 20 20 20 20 20 35 20 20  Y            5  
364f0 20 20 2f 2a 20 44 65 70 72 65 63 61 74 65 64 20    /* Deprecated 
36500 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
36510 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20  E_UTF16_ALIGNED 
36520 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33   8    /* sqlite3
36530 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
36540 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  n only */../*.**
36550 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74   CAPI3REF: Funct
36560 69 6f 6e 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20  ion Flags.**.** 
36570 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
36580 6d 61 79 20 62 65 20 4f 52 65 64 20 74 6f 67 65  may be ORed toge
36590 74 68 65 72 20 77 69 74 68 20 74 68 65 20 0a 2a  ther with the .*
365a0 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c  * [SQLITE_UTF8 |
365b0 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
365c0 65 6e 63 6f 64 69 6e 67 5d 20 61 73 20 74 68 65  encoding] as the
365d0 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
365e0 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  .** to [sqlite3_
365f0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
36600 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  )], [sqlite3_cre
36610 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
36620 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ], or.** [sqlite
36630 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
36640 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66  n_v2()]..*/.#def
36650 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 45 52  ine SQLITE_DETER
36660 4d 49 4e 49 53 54 49 43 20 20 20 20 30 78 38 30  MINISTIC    0x80
36670 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  0../*.** CAPI3RE
36680 46 3a 20 44 65 70 72 65 63 61 74 65 64 20 46 75  F: Deprecated Fu
36690 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45  nctions.** DEPRE
366a0 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73  CATED.**.** Thes
366b0 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20  e functions are 
366c0 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49  [deprecated].  I
366d0 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74  n order to maint
366e0 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73  ain.** backwards
366f0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77   compatibility w
36700 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20  ith older code, 
36710 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  these functions 
36720 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20  continue .** to 
36730 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48  be supported.  H
36740 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c  owever, new appl
36750 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
36760 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65  avoid.** the use
36770 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69   of these functi
36780 6f 6e 73 2e 20 20 54 6f 20 65 6e 63 6f 75 72 61  ons.  To encoura
36790 67 65 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 74  ge programmers t
367a0 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 73 65  o avoid.** these
367b0 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 77   functions, we w
367c0 69 6c 6c 20 6e 6f 74 20 65 78 70 6c 61 69 6e 20  ill not explain 
367d0 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f  what they do..*/
367e0 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f  .#ifndef SQLITE_
367f0 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a  OMIT_DEPRECATED.
36800 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
36810 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67  D int sqlite3_ag
36820 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71  gregate_count(sq
36830 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
36840 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
36850 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  ED int sqlite3_e
36860 78 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73  xpired(sqlite3_s
36870 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45  tmt*);.SQLITE_DE
36880 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
36890 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69  ite3_transfer_bi
368a0 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73  ndings(sqlite3_s
368b0 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74  tmt*, sqlite3_st
368c0 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  mt*);.SQLITE_DEP
368d0 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
368e0 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76  te3_global_recov
368f0 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  er(void);.SQLITE
36900 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64  _DEPRECATED void
36910 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f   sqlite3_thread_
36920 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53  cleanup(void);.S
36930 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
36940 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d   int sqlite3_mem
36950 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a  ory_alarm(void(*
36960 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f  )(void*,sqlite3_
36970 69 6e 74 36 34 2c 69 6e 74 29 2c 0a 20 20 20 20  int64,int),.    
36980 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
36990 20 20 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f    void*,sqlite3_
369a0 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a  int64);.#endif..
369b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
369c0 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 56 61  Obtaining SQL Va
369d0 6c 75 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  lues.** METHOD: 
369e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 0a 2a 2a  sqlite3_value.**
369f0 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61  .** The C-langua
36a00 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ge implementatio
36a10 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f  n of SQL functio
36a20 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
36a30 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73  s uses.** this s
36a40 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20  et of interface 
36a50 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65  routines to acce
36a60 73 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  ss the parameter
36a70 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68   values on.** th
36a80 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67  e function or ag
36a90 67 72 65 67 61 74 65 2e 20 20 0a 2a 2a 0a 2a 2a  gregate.  .**.**
36aa0 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20   The xFunc (for 
36ab0 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73  scalar functions
36ac0 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20  ) or xStep (for 
36ad0 61 67 67 72 65 67 61 74 65 73 29 20 70 61 72 61  aggregates) para
36ae0 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71  meters.** to [sq
36af0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
36b00 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  ction()] and [sq
36b10 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
36b20 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65  ction16()].** de
36b30 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74  fine callbacks t
36b40 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68  hat implement th
36b50 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  e SQL functions 
36b60 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a  and aggregates..
36b70 2a 2a 20 54 68 65 20 33 72 64 20 70 61 72 61 6d  ** The 3rd param
36b80 65 74 65 72 20 74 6f 20 74 68 65 73 65 20 63 61  eter to these ca
36b90 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72  llbacks is an ar
36ba0 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
36bb0 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64  to.** [protected
36bc0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
36bd0 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20  objects.  There 
36be0 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f  is one [sqlite3_
36bf0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f  value] object fo
36c00 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65  r.** each parame
36c10 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66  ter to the SQL f
36c20 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20  unction.  These 
36c30 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
36c40 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20  d to.** extract 
36c50 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20  values from the 
36c60 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
36c70 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  objects..**.** T
36c80 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f  hese routines wo
36c90 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72  rk only with [pr
36ca0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
36cb0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a  value] objects..
36cc0 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74  ** Any attempt t
36cd0 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f 75 74  o use these rout
36ce0 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72  ines on an [unpr
36cf0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
36d00 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74  value].** object
36d10 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65   results in unde
36d20 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a  fined behavior..
36d30 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
36d40 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20  tines work just 
36d50 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70  like the corresp
36d60 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61  onding [column a
36d70 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d  ccess functions]
36d80 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20  .** except that 
36d90 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74  these routines t
36da0 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72  ake a single [pr
36db0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
36dc0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a  value] object.**
36dd0 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64   pointer instead
36de0 20 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73   of a [sqlite3_s
36df0 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e  tmt*] pointer an
36e00 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c  d an integer col
36e10 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a  umn number..**.*
36e20 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
36e30 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e  alue_text16() in
36e40 74 65 72 66 61 63 65 20 65 78 74 72 61 63 74 73  terface extracts
36e50 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
36e60 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76  .** in the nativ
36e70 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20  e byte-order of 
36e80 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65  the host machine
36e90 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74  .  ^The.** sqlit
36ea0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62  e3_value_text16b
36eb0 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
36ec0 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29  value_text16le()
36ed0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65   interfaces.** e
36ee0 78 74 72 61 63 74 20 55 54 46 2d 31 36 20 73 74  xtract UTF-16 st
36ef0 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64  rings as big-end
36f00 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65  ian and little-e
36f10 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69 76 65  ndian respective
36f20 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ly..**.** ^(The 
36f30 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75  sqlite3_value_nu
36f40 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74  meric_type() int
36f50 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20  erface attempts 
36f60 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65  to apply.** nume
36f70 72 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20  ric affinity to 
36f80 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73  the value.  This
36f90 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61   means that an a
36fa0 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64  ttempt is.** mad
36fb0 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65  e to convert the
36fc0 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74   value to an int
36fd0 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67  eger or floating
36fe0 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73   point.  If.** s
36ff0 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e  uch a conversion
37000 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74   is possible wit
37010 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66  hout loss of inf
37020 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68  ormation (in oth
37030 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20  er.** words, if 
37040 74 68 65 20 76 61 6c 75 65 20 69 73 20 61 20 73  the value is a s
37050 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73  tring that looks
37060 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a   like a number).
37070 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76  ** then the conv
37080 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72  ersion is perfor
37090 6d 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20  med.  Otherwise 
370a0 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63  no conversion oc
370b0 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51  curs..** The [SQ
370c0 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64  LITE_INTEGER | d
370d0 61 74 61 74 79 70 65 5d 20 61 66 74 65 72 20 63  atatype] after c
370e0 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74  onversion is ret
370f0 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50  urned.)^.**.** P
37100 6c 65 61 73 65 20 70 61 79 20 70 61 72 74 69 63  lease pay partic
37110 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74  ular attention t
37120 6f 20 74 68 65 20 66 61 63 74 20 74 68 61 74 20  o the fact that 
37130 74 68 65 20 70 6f 69 6e 74 65 72 20 72 65 74 75  the pointer retu
37140 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  rned.** from [sq
37150 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62  lite3_value_blob
37160 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
37170 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a  lue_text()], or.
37180 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
37190 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20  e_text16()] can 
371a0 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62  be invalidated b
371b0 79 20 61 20 73 75 62 73 65 71 75 65 6e 74 20 63  y a subsequent c
371c0 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
371d0 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29  e3_value_bytes()
371e0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
371f0 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73  e_bytes16()], [s
37200 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
37210 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c  t()],.** or [sql
37220 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
37230 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  6()]..**.** Thes
37240 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20  e routines must 
37250 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
37260 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 61  he same thread a
37270 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e  s.** the SQL fun
37280 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c  ction that suppl
37290 69 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ied the [sqlite3
372a0 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74  _value*] paramet
372b0 65 72 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f  ers..*/.const vo
372c0 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
372d0 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76  e_blob(sqlite3_v
372e0 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
372f0 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
37300 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
37310 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
37320 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74  ue_bytes16(sqlit
37330 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 62  e3_value*);.doub
37340 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  le sqlite3_value
37350 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
37360 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
37370 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73  ite3_value_int(s
37380 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
37390 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
373a0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36  lite3_value_int6
373b0 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  4(sqlite3_value*
373c0 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65  );.const unsigne
373d0 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  d char *sqlite3_
373e0 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74  value_text(sqlit
373f0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73  e3_value*);.cons
37400 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
37410 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c  value_text16(sql
37420 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f  ite3_value*);.co
37430 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
37440 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65  3_value_text16le
37450 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
37460 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
37470 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
37480 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  16be(sqlite3_val
37490 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
374a0 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c  3_value_type(sql
374b0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
374c0 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
374d0 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c  numeric_type(sql
374e0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f  ite3_value*);../
374f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
37500 69 6e 64 69 6e 67 20 54 68 65 20 53 75 62 74 79  inding The Subty
37510 70 65 20 4f 66 20 53 51 4c 20 56 61 6c 75 65 73  pe Of SQL Values
37520 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
37530 74 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20  te3_value.**.** 
37540 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
37550 65 5f 73 75 62 74 79 70 65 28 56 29 20 66 75 6e  e_subtype(V) fun
37560 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
37570 65 20 73 75 62 74 79 70 65 20 66 6f 72 0a 2a 2a  e subtype for.**
37580 20 61 6e 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e   an [application
37590 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
375a0 63 74 69 6f 6e 5d 20 61 72 67 75 6d 65 6e 74 20  ction] argument 
375b0 56 2e 20 20 54 68 65 20 73 75 62 74 79 70 65 0a  V.  The subtype.
375c0 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 63  ** information c
375d0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 70 61  an be used to pa
375e0 73 73 20 61 20 6c 69 6d 69 74 65 64 20 61 6d 6f  ss a limited amo
375f0 75 6e 74 20 6f 66 20 63 6f 6e 74 65 78 74 20 66  unt of context f
37600 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 53 51 4c 20 66  rom.** one SQL f
37610 75 6e 63 74 69 6f 6e 20 74 6f 20 61 6e 6f 74 68  unction to anoth
37620 65 72 2e 20 20 55 73 65 20 74 68 65 20 5b 73 71  er.  Use the [sq
37630 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 73 75 62  lite3_result_sub
37640 74 79 70 65 28 29 5d 0a 2a 2a 20 72 6f 75 74 69  type()].** routi
37650 6e 65 20 74 6f 20 73 65 74 20 74 68 65 20 73 75  ne to set the su
37660 62 74 79 70 65 20 66 6f 72 20 74 68 65 20 72 65  btype for the re
37670 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 61 6e  turn value of an
37680 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a   SQL function..*
37690 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65  *.** SQLite make
376a0 73 20 6e 6f 20 75 73 65 20 6f 66 20 73 75 62 74  s no use of subt
376b0 79 70 65 20 69 74 73 65 6c 66 2e 20 20 49 74 20  ype itself.  It 
376c0 6d 65 72 65 6c 79 20 70 61 73 73 65 73 20 74 68  merely passes th
376d0 65 20 73 75 62 74 79 70 65 0a 2a 2a 20 66 72 6f  e subtype.** fro
376e0 6d 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20  m the result of 
376f0 6f 6e 65 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e  one [application
37700 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
37710 63 74 69 6f 6e 5d 20 69 6e 74 6f 20 74 68 65 0a  ction] into the.
37720 2a 2a 20 69 6e 70 75 74 20 6f 66 20 61 6e 6f 74  ** input of anot
37730 68 65 72 2e 0a 2a 2f 0a 75 6e 73 69 67 6e 65 64  her..*/.unsigned
37740 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c   int sqlite3_val
37750 75 65 5f 73 75 62 74 79 70 65 28 73 71 6c 69 74  ue_subtype(sqlit
37760 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a  e3_value*);../*.
37770 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 70  ** CAPI3REF: Cop
37780 79 20 41 6e 64 20 46 72 65 65 20 53 51 4c 20 56  y And Free SQL V
37790 61 6c 75 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  alues.** METHOD:
377a0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 0a 2a   sqlite3_value.*
377b0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
377c0 33 5f 76 61 6c 75 65 5f 64 75 70 28 56 29 20 69  3_value_dup(V) i
377d0 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61  nterface makes a
377e0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71   copy of the [sq
377f0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20  lite3_value].** 
37800 6f 62 6a 65 63 74 20 44 20 61 6e 64 20 72 65 74  object D and ret
37810 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
37820 6f 20 74 68 61 74 20 63 6f 70 79 2e 20 20 5e 54  o that copy.  ^T
37830 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
37840 65 5d 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69  e] returned.** i
37850 73 20 61 20 5b 70 72 6f 74 65 63 74 65 64 20 73  s a [protected s
37860 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
37870 6a 65 63 74 20 65 76 65 6e 20 69 66 20 74 68 65  ject even if the
37880 20 69 6e 70 75 74 20 69 73 20 6e 6f 74 2e 0a 2a   input is not..*
37890 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
378a0 61 6c 75 65 5f 64 75 70 28 56 29 20 69 6e 74 65  alue_dup(V) inte
378b0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 4e 55  rface returns NU
378c0 4c 4c 20 69 66 20 56 20 69 73 20 4e 55 4c 4c 20  LL if V is NULL 
378d0 6f 72 20 69 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72  or if a.** memor
378e0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
378f0 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ls..**.** ^The s
37900 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 66 72 65  qlite3_value_fre
37910 65 28 56 29 20 69 6e 74 65 72 66 61 63 65 20 66  e(V) interface f
37920 72 65 65 73 20 61 6e 20 5b 73 71 6c 69 74 65 33  rees an [sqlite3
37930 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a  _value] object.*
37940 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74  * previously obt
37950 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
37960 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 29 5d  te3_value_dup()]
37970 2e 20 20 5e 49 66 20 56 20 69 73 20 61 20 4e 55  .  ^If V is a NU
37980 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 68  LL pointer.** th
37990 65 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  en sqlite3_value
379a0 5f 66 72 65 65 28 56 29 20 69 73 20 61 20 68 61  _free(V) is a ha
379b0 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f  rmless no-op..*/
379c0 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a  .sqlite3_value *
379d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75  sqlite3_value_du
379e0 70 28 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f  p(const sqlite3_
379f0 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71  value*);.void sq
37a00 6c 69 74 65 33 5f 76 61 6c 75 65 5f 66 72 65 65  lite3_value_free
37a10 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
37a20 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
37a30 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67  F: Obtain Aggreg
37a40 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e  ate Function Con
37a50 74 65 78 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  text.** METHOD: 
37a60 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a  sqlite3_context.
37a70 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74 61  **.** Implementa
37a80 74 69 6f 6e 73 20 6f 66 20 61 67 67 72 65 67 61  tions of aggrega
37a90 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  te SQL functions
37aa0 20 75 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f 75   use this.** rou
37ab0 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  tine to allocate
37ac0 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f 72   memory for stor
37ad0 69 6e 67 20 74 68 65 69 72 20 73 74 61 74 65 2e  ing their state.
37ae0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
37af0 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74  t time the sqlit
37b00 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
37b10 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e  text(C,N) routin
37b20 65 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a 20  e is called .** 
37b30 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
37b40 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
37b50 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 61  ion, SQLite.** a
37b60 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d 65  llocates N of me
37b70 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74  mory, zeroes out
37b80 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e   that memory, an
37b90 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  d returns a poin
37ba0 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e 65  ter.** to the ne
37bb0 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65  w memory. ^On se
37bc0 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75  cond and subsequ
37bd0 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  ent calls to.** 
37be0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
37bf0 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 20  e_context() for 
37c00 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61  the same aggrega
37c10 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74  te function inst
37c20 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61 6d  ance,.** the sam
37c30 65 20 62 75 66 66 65 72 20 69 73 20 72 65 74 75  e buffer is retu
37c40 72 6e 65 64 2e 20 20 53 71 6c 69 74 65 33 5f 61  rned.  Sqlite3_a
37c50 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
37c60 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a  () is normally.*
37c70 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f  * called once fo
37c80 72 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f  r each invocatio
37c90 6e 20 6f 66 20 74 68 65 20 78 53 74 65 70 20 63  n of the xStep c
37ca0 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68 65 6e  allback and then
37cb0 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69 6d   one.** last tim
37cc0 65 20 77 68 65 6e 20 74 68 65 20 78 46 69 6e 61  e when the xFina
37cd0 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  l callback is in
37ce0 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20 6e  voked.  ^(When n
37cf0 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a 20  o rows match.** 
37d00 61 6e 20 61 67 67 72 65 67 61 74 65 20 71 75 65  an aggregate que
37d10 72 79 2c 20 74 68 65 20 78 53 74 65 70 28 29 20  ry, the xStep() 
37d20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20  callback of the 
37d30 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
37d40 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  on.** implementa
37d50 74 69 6f 6e 20 69 73 20 6e 65 76 65 72 20 63 61  tion is never ca
37d60 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e 61 6c 28  lled and xFinal(
37d70 29 20 69 73 20 63 61 6c 6c 65 64 20 65 78 61 63  ) is called exac
37d80 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20  tly once..** In 
37d90 74 68 6f 73 65 20 63 61 73 65 73 2c 20 73 71 6c  those cases, sql
37da0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
37db0 6f 6e 74 65 78 74 28 29 20 6d 69 67 68 74 20 62  ontext() might b
37dc0 65 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65  e called for the
37dd0 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d 65 20 66  .** first time f
37de0 72 6f 6d 20 77 69 74 68 69 6e 20 78 46 69 6e 61  rom within xFina
37df0 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  l().)^.**.** ^Th
37e00 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  e sqlite3_aggreg
37e10 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29  ate_context(C,N)
37e20 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
37e30 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
37e40 0a 2a 2a 20 77 68 65 6e 20 66 69 72 73 74 20 63  .** when first c
37e50 61 6c 6c 65 64 20 69 66 20 4e 20 69 73 20 6c 65  alled if N is le
37e60 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c  ss than or equal
37e70 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61   to zero or if a
37e80 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
37e90 61 74 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ate error occurs
37ea0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d  ..**.** ^(The am
37eb0 6f 75 6e 74 20 6f 66 20 73 70 61 63 65 20 61 6c  ount of space al
37ec0 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74  located by sqlit
37ed0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
37ee0 74 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20  text(C,N) is.** 
37ef0 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68  determined by th
37f00 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 6f 6e  e N parameter on
37f10 20 66 69 72 73 74 20 73 75 63 63 65 73 73 66 75   first successfu
37f20 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e  l call.  Changin
37f30 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f  g the.** value o
37f40 66 20 4e 20 69 6e 20 73 75 62 73 65 71 75 65 6e  f N in subsequen
37f50 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  t call to sqlite
37f60 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
37f70 65 78 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20  ext() within.** 
37f80 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61  the same aggrega
37f90 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74  te function inst
37fa0 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65  ance will not re
37fb0 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a  size the memory.
37fc0 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e  ** allocation.)^
37fd0 20 20 57 69 74 68 69 6e 20 74 68 65 20 78 46 69    Within the xFi
37fe0 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 2c 20 69 74  nal callback, it
37ff0 20 69 73 20 63 75 73 74 6f 6d 61 72 79 20 74 6f   is customary to
38000 20 73 65 74 0a 2a 2a 20 4e 3d 30 20 69 6e 20 63   set.** N=0 in c
38010 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
38020 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
38030 74 28 43 2c 4e 29 20 73 6f 20 74 68 61 74 20 6e  t(C,N) so that n
38040 6f 20 0a 2a 2a 20 70 6f 69 6e 74 6c 65 73 73 20  o .** pointless 
38050 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
38060 6e 73 20 6f 63 63 75 72 2e 0a 2a 2a 0a 2a 2a 20  ns occur..**.** 
38070 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69  ^SQLite automati
38080 63 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20  cally frees the 
38090 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64  memory allocated
380a0 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   by .** sqlite3_
380b0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
380c0 74 28 29 20 77 68 65 6e 20 74 68 65 20 61 67 67  t() when the agg
380d0 72 65 67 61 74 65 20 71 75 65 72 79 20 63 6f 6e  regate query con
380e0 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  cludes..**.** Th
380f0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
38100 72 20 6d 75 73 74 20 62 65 20 61 20 63 6f 70 79  r must be a copy
38110 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
38120 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51  te3_context | SQ
38130 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65  L function conte
38140 78 74 5d 20 74 68 61 74 20 69 73 20 74 68 65 20  xt] that is the 
38150 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 0a  first parameter.
38160 2a 2a 20 74 6f 20 74 68 65 20 78 53 74 65 70 20  ** to the xStep 
38170 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61  or xFinal callba
38180 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20  ck routine that 
38190 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61  implements the a
381a0 67 67 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63  ggregate.** func
381b0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  tion..**.** This
381c0 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65   routine must be
381d0 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
381e0 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20   same thread in 
381f0 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67  which.** the agg
38200 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
38210 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
38220 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
38230 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
38240 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt(sqlite3_conte
38250 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29  xt*, int nBytes)
38260 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
38270 46 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f 72  F: User Data For
38280 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45   Functions.** ME
38290 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f  THOD: sqlite3_co
382a0 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ntext.**.** ^The
382b0 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61   sqlite3_user_da
382c0 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ta() interface r
382d0 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66  eturns a copy of
382e0 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20  .** the pointer 
382f0 74 68 61 74 20 77 61 73 20 74 68 65 20 70 55 73  that was the pUs
38300 65 72 44 61 74 61 20 70 61 72 61 6d 65 74 65 72  erData parameter
38310 20 28 74 68 65 20 35 74 68 20 70 61 72 61 6d 65   (the 5th parame
38320 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  ter).** of the [
38330 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
38340 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e  unction()].** an
38350 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
38360 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20  e_function16()] 
38370 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72  routines that or
38380 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69  iginally.** regi
38390 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69  stered the appli
383a0 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66  cation defined f
383b0 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  unction..**.** T
383c0 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74  his routine must
383d0 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
383e0 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
383f0 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20  in which.** the 
38400 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
38410 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ned function is 
38420 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64  running..*/.void
38430 20 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   *sqlite3_user_d
38440 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
38450 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ext*);../*.** CA
38460 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65  PI3REF: Database
38470 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20   Connection For 
38480 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54  Functions.** MET
38490 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e  HOD: sqlite3_con
384a0 74 65 78 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  text.**.** ^The 
384b0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f  sqlite3_context_
384c0 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65  db_handle() inte
384d0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
384e0 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70  copy of.** the p
384f0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64  ointer to the [d
38500 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
38510 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 70 61 72  on] (the 1st par
38520 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68  ameter).** of th
38530 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
38540 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a  e_function()].**
38550 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
38560 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
38570 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  )] routines that
38580 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72   originally.** r
38590 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70  egistered the ap
385a0 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
385b0 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 73  d function..*/.s
385c0 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f  qlite3 *sqlite3_
385d0 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c  context_db_handl
385e0 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
385f0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
38600 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41  3REF: Function A
38610 75 78 69 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a  uxiliary Data.**
38620 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
38630 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 54  _context.**.** T
38640 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 6d  hese functions m
38650 61 79 20 62 65 20 75 73 65 64 20 62 79 20 28 6e  ay be used by (n
38660 6f 6e 2d 61 67 67 72 65 67 61 74 65 29 20 53 51  on-aggregate) SQ
38670 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a  L functions to.*
38680 2a 20 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61  * associate meta
38690 64 61 74 61 20 77 69 74 68 20 61 72 67 75 6d 65  data with argume
386a0 6e 74 20 76 61 6c 75 65 73 2e 20 49 66 20 74 68  nt values. If th
386b0 65 20 73 61 6d 65 20 76 61 6c 75 65 20 69 73 20  e same value is 
386c0 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c  passed to.** mul
386d0 74 69 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e  tiple invocation
386e0 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 53 51  s of the same SQ
386f0 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e  L function durin
38700 67 20 71 75 65 72 79 20 65 78 65 63 75 74 69 6f  g query executio
38710 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65  n, under.** some
38720 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 74   circumstances t
38730 68 65 20 61 73 73 6f 63 69 61 74 65 64 20 6d 65  he associated me
38740 74 61 64 61 74 61 20 6d 61 79 20 62 65 20 70 72  tadata may be pr
38750 65 73 65 72 76 65 64 2e 20 20 41 6e 20 65 78 61  eserved.  An exa
38760 6d 70 6c 65 0a 2a 2a 20 6f 66 20 77 68 65 72 65  mple.** of where
38770 20 74 68 69 73 20 6d 69 67 68 74 20 62 65 20 75   this might be u
38780 73 65 66 75 6c 20 69 73 20 69 6e 20 61 20 72 65  seful is in a re
38790 67 75 6c 61 72 2d 65 78 7