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

Artifact c0be974111cac31e64f25376cf601ecdb3f1dfdaeeafd087642179ecdbc9094e:


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 73 20 74  rst integer is t
9e70: 68 65 20 6e 65 77 20 72 65 74 72 79 20 63 6f 75  he new retry cou
9e80: 6e 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  nt and the secon
9e90: 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 69 73 20  d.** integer is 
9ea0: 74 68 65 20 64 65 6c 61 79 2e 20 20 49 66 20 65  the delay.  If e
9eb0: 69 74 68 65 72 20 69 6e 74 65 67 65 72 20 69 73  ither integer is
9ec0: 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
9ed0: 74 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69  the setting.** i
9ee0: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 62 75  s not changed bu
9ef0: 74 20 69 6e 73 74 65 61 64 20 74 68 65 20 70 72  t instead the pr
9f00: 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 61  ior value of tha
9f10: 74 20 73 65 74 74 69 6e 67 20 69 73 20 77 72 69  t setting is wri
9f20: 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65  tten.** into the
9f30: 20 61 72 72 61 79 20 65 6e 74 72 79 2c 20 61 6c   array entry, al
9f40: 6c 6f 77 69 6e 67 20 74 68 65 20 63 75 72 72 65  lowing the curre
9f50: 6e 74 20 72 65 74 72 79 20 73 65 74 74 69 6e 67  nt retry setting
9f60: 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72  s to be.** inter
9f70: 72 6f 67 61 74 65 64 2e 20 20 54 68 65 20 7a 44  rogated.  The zD
9f80: 62 4e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  bName parameter 
9f90: 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a  is ignored..**.*
9fa0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
9fb0: 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c  CNTL_PERSIST_WAL
9fc0: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
9fd0: 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54  TE_FCNTL_PERSIST
9fe0: 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20  _WAL] opcode is 
9ff0: 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71  used to set or q
a000: 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73  uery the.** pers
a010: 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72  istent [WAL | Wr
a020: 69 74 65 20 41 68 65 61 64 20 4c 6f 67 5d 20 73  ite Ahead Log] s
a030: 65 74 74 69 6e 67 2e 20 20 42 79 20 64 65 66 61  etting.  By defa
a040: 75 6c 74 2c 20 74 68 65 20 61 75 78 69 6c 69 61  ult, the auxilia
a050: 72 79 0a 2a 2a 20 77 72 69 74 65 20 61 68 65 61  ry.** write ahea
a060: 64 20 6c 6f 67 20 61 6e 64 20 73 68 61 72 65 64  d log and shared
a070: 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 75 73   memory files us
a080: 65 64 20 66 6f 72 20 74 72 61 6e 73 61 63 74 69  ed for transacti
a090: 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72  on control.** ar
a0a0: 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
a0b0: 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65  deleted when the
a0c0: 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65 63 74 69   latest connecti
a0d0: 6f 6e 20 74 6f 20 74 68 65 20 64 61 74 61 62 61  on to the databa
a0e0: 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53  se.** closes.  S
a0f0: 65 74 74 69 6e 67 20 70 65 72 73 69 73 74 65 6e  etting persisten
a100: 74 20 57 41 4c 20 6d 6f 64 65 20 63 61 75 73 65  t WAL mode cause
a110: 73 20 74 68 6f 73 65 20 66 69 6c 65 73 20 74 6f  s those files to
a120: 20 70 65 72 73 69 73 74 20 61 66 74 65 72 0a 2a   persist after.*
a130: 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72 73 69 73  * close.  Persis
a140: 74 69 6e 67 20 74 68 65 20 66 69 6c 65 73 20 69  ting the files i
a150: 73 20 75 73 65 66 75 6c 20 77 68 65 6e 20 6f 74  s useful when ot
a160: 68 65 72 20 70 72 6f 63 65 73 73 65 73 20 74 68  her processes th
a170: 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76  at do not.** hav
a180: 65 20 77 72 69 74 65 20 70 65 72 6d 69 73 73 69  e write permissi
a190: 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72 65 63 74  on on the direct
a1a0: 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  ory containing t
a1b0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
a1c0: 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64   want.** to read
a1d0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
a1e0: 6c 65 2c 20 61 73 20 74 68 65 20 57 41 4c 20 61  le, as the WAL a
a1f0: 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79  nd shared memory
a200: 20 66 69 6c 65 73 20 6d 75 73 74 20 65 78 69 73   files must exis
a210: 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f  t.** in order fo
a220: 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74  r the database t
a230: 6f 20 62 65 20 72 65 61 64 61 62 6c 65 2e 20 20  o be readable.  
a240: 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
a250: 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  eter to.** [sqli
a260: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
a270: 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63  ()] for this opc
a280: 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20  ode should be a 
a290: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
a2a0: 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69  teger..** That i
a2b0: 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f 20 64  nteger is 0 to d
a2c0: 69 73 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e  isable persisten
a2d0: 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20  t WAL mode or 1 
a2e0: 74 6f 20 65 6e 61 62 6c 65 20 70 65 72 73 69 73  to enable persis
a2f0: 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65  tent.** WAL mode
a300: 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65  .  If the intege
a310: 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74  r is -1, then it
a320: 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20   is overwritten 
a330: 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74  with the current
a340: 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69 73 74 65  .** WAL persiste
a350: 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a  nce setting..**.
a360: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
a370: 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f  FCNTL_POWERSAFE_
a380: 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e  OVERWRITE]].** ^
a390: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
a3a0: 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  L_POWERSAFE_OVER
a3b0: 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73  WRITE] opcode is
a3c0: 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20   used to set or 
a3d0: 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72  query the.** per
a3e0: 73 69 73 74 65 6e 74 20 22 70 6f 77 65 72 73 61  sistent "powersa
a3f0: 66 65 2d 6f 76 65 72 77 72 69 74 65 22 20 6f 72  fe-overwrite" or
a400: 20 22 50 53 4f 57 22 20 73 65 74 74 69 6e 67 2e   "PSOW" setting.
a410: 20 20 54 68 65 20 50 53 4f 57 20 73 65 74 74 69    The PSOW setti
a420: 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73  ng.** determines
a430: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43   the [SQLITE_IOC
a440: 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  AP_POWERSAFE_OVE
a450: 52 57 52 49 54 45 5d 20 62 69 74 20 6f 66 20 74  RWRITE] bit of t
a460: 68 65 0a 2a 2a 20 78 44 65 76 69 63 65 43 68 61  he.** xDeviceCha
a470: 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74  racteristics met
a480: 68 6f 64 73 2e 20 54 68 65 20 66 6f 75 72 74 68  hods. The fourth
a490: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
a4a0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
a4b0: 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68  ontrol()] for th
a4c0: 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64  is opcode should
a4d0: 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   be a pointer to
a4e0: 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20   an integer..** 
a4f0: 54 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20  That integer is 
a500: 30 20 74 6f 20 64 69 73 61 62 6c 65 20 7a 65 72  0 to disable zer
a510: 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 6f 72  o-damage mode or
a520: 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 7a 65 72   1 to enable zer
a530: 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65  o-damage.** mode
a540: 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65  .  If the intege
a550: 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74  r is -1, then it
a560: 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20   is overwritten 
a570: 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74  with the current
a580: 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20  .** zero-damage 
a590: 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a  mode setting..**
a5a0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
a5b0: 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45  _FCNTL_OVERWRITE
a5c0: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
a5d0: 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49  TE_FCNTL_OVERWRI
a5e0: 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6e  TE] opcode is in
a5f0: 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20  voked by SQLite 
a600: 61 66 74 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a  after opening.**
a610: 20 61 20 77 72 69 74 65 20 74 72 61 6e 73 61 63   a write transac
a620: 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63 61 74 65  tion to indicate
a630: 20 74 68 61 74 2c 20 75 6e 6c 65 73 73 20 69 74   that, unless it
a640: 20 69 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20   is rolled back 
a650: 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73  for some.** reas
a660: 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72 65 20 64  on, the entire d
a670: 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c  atabase file wil
a680: 6c 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e  l be overwritten
a690: 20 62 79 20 74 68 65 20 63 75 72 72 65 6e 74 20   by the current 
a6a0: 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e  .** transaction.
a6b0: 20 54 68 69 73 20 69 73 20 75 73 65 64 20 62 79   This is used by
a6c0: 20 56 41 43 55 55 4d 20 6f 70 65 72 61 74 69 6f   VACUUM operatio
a6d0: 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ns..**.** <li>[[
a6e0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53  SQLITE_FCNTL_VFS
a6f0: 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  NAME]].** ^The [
a700: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53  SQLITE_FCNTL_VFS
a710: 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e  NAME] opcode can
a720: 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61   be used to obta
a730: 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 0a  in the names of.
a740: 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73 5d 20 69  ** all [VFSes] i
a750: 6e 20 74 68 65 20 56 46 53 20 73 74 61 63 6b 2e  n the VFS stack.
a760: 20 20 54 68 65 20 6e 61 6d 65 73 20 61 72 65 20    The names are 
a770: 6f 66 20 61 6c 6c 20 56 46 53 20 73 68 69 6d 73  of all VFS shims
a780: 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 69 6e 61   and the.** fina
a790: 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 56  l bottom-level V
a7a0: 46 53 20 61 72 65 20 77 72 69 74 74 65 6e 20 69  FS are written i
a7b0: 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69  nto memory obtai
a7c0: 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71  ned from .** [sq
a7d0: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
a7e0: 61 6e 64 20 74 68 65 20 72 65 73 75 6c 74 20 69  and the result i
a7f0: 73 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20  s stored in the 
a800: 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65 0a 2a  char* variable.*
a810: 2a 20 74 68 61 74 20 74 68 65 20 66 6f 75 72 74  * that the fourt
a820: 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 5b  h parameter of [
a830: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
a840: 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74 73 20 74  trol()] points t
a850: 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 65 72  o..** The caller
a860: 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
a870: 66 6f 72 20 66 72 65 65 69 6e 67 20 74 68 65 20  for freeing the 
a880: 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64 6f 6e 65  memory when done
a890: 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a 20 61 6c  .  As with.** al
a8a0: 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61  l file-control a
a8b0: 63 74 69 6f 6e 73 2c 20 74 68 65 72 65 20 69 73  ctions, there is
a8c0: 20 6e 6f 20 67 75 61 72 61 6e 74 65 65 20 74 68   no guarantee th
a8d0: 61 74 20 74 68 69 73 20 77 69 6c 6c 20 61 63 74  at this will act
a8e0: 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 74  ually.** do anyt
a8f0: 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72 73 20 73  hing.  Callers s
a900: 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c 69 7a 65  hould initialize
a910: 20 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61   the char* varia
a920: 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a  ble to a NULL.**
a930: 20 70 6f 69 6e 74 65 72 20 69 6e 20 63 61 73 65   pointer in case
a940: 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72   this file-contr
a950: 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d  ol is not implem
a960: 65 6e 74 65 64 2e 20 20 54 68 69 73 20 66 69 6c  ented.  This fil
a970: 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20  e-control.** is 
a980: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 64 69 61  intended for dia
a990: 67 6e 6f 73 74 69 63 20 75 73 65 20 6f 6e 6c 79  gnostic use only
a9a0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
a9b0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50  LITE_FCNTL_VFS_P
a9c0: 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65  OINTER]].** ^The
a9d0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56   [SQLITE_FCNTL_V
a9e0: 46 53 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f  FS_POINTER] opco
a9f0: 64 65 20 66 69 6e 64 73 20 61 20 70 6f 69 6e 74  de finds a point
aa00: 65 72 20 74 6f 20 74 68 65 20 74 6f 70 2d 6c 65  er to the top-le
aa10: 76 65 6c 0a 2a 2a 20 5b 56 46 53 65 73 5d 20 63  vel.** [VFSes] c
aa20: 75 72 72 65 6e 74 6c 79 20 69 6e 20 75 73 65 2e  urrently in use.
aa30: 20 20 5e 28 54 68 65 20 61 72 67 75 6d 65 6e 74    ^(The argument
aa40: 20 58 20 69 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   X in.** sqlite3
aa50: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 64 62  _file_control(db
aa60: 2c 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46  ,SQLITE_FCNTL_VF
aa70: 53 5f 50 4f 49 4e 54 45 52 2c 58 29 20 6d 75 73  S_POINTER,X) mus
aa80: 74 20 62 65 0a 2a 2a 20 6f 66 20 74 79 70 65 20  t be.** of type 
aa90: 22 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 2a  "[sqlite3_vfs] *
aaa0: 2a 22 2e 20 20 54 68 69 73 20 6f 70 63 6f 64 65  *".  This opcode
aab0: 73 20 77 69 6c 6c 20 73 65 74 20 2a 58 0a 2a 2a  s will set *X.**
aac0: 20 74 6f 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   to a pointer to
aad0: 20 74 68 65 20 74 6f 70 2d 6c 65 76 65 6c 20 56   the top-level V
aae0: 46 53 2e 29 5e 0a 2a 2a 20 5e 57 68 65 6e 20 74  FS.)^.** ^When t
aaf0: 68 65 72 65 20 61 72 65 20 6d 75 6c 74 69 70 6c  here are multipl
ab00: 65 20 56 46 53 20 73 68 69 6d 73 20 69 6e 20 74  e VFS shims in t
ab10: 68 65 20 73 74 61 63 6b 2c 20 74 68 69 73 20 6f  he stack, this o
ab20: 70 63 6f 64 65 20 66 69 6e 64 73 20 74 68 65 0a  pcode finds the.
ab30: 2a 2a 20 75 70 70 65 72 2d 6d 6f 73 74 20 73 68  ** upper-most sh
ab40: 69 6d 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c  im only..**.** <
ab50: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
ab60: 4c 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57  L_PRAGMA]].** ^W
ab70: 68 65 6e 65 76 65 72 20 61 20 5b 50 52 41 47 4d  henever a [PRAGM
ab80: 41 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  A] statement is 
ab90: 70 61 72 73 65 64 2c 20 61 6e 20 5b 53 51 4c 49  parsed, an [SQLI
aba0: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
abb0: 20 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f   .** file contro
abc0: 6c 20 69 73 20 73 65 6e 74 20 74 6f 20 74 68 65  l is sent to the
abd0: 20 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66   open [sqlite3_f
abe0: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 63 6f 72 72  ile] object corr
abf0: 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20  esponding.** to 
ac00: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
ac10: 65 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 70  e to which the p
ac20: 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20  ragma statement 
ac30: 72 65 66 65 72 73 2e 20 5e 54 68 65 20 61 72 67  refers. ^The arg
ac40: 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20  ument.** to the 
ac50: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
ac60: 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72  AGMA] file contr
ac70: 6f 6c 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  ol is an array o
ac80: 66 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f  f.** pointers to
ac90: 20 73 74 72 69 6e 67 73 20 28 63 68 61 72 2a 2a   strings (char**
aca0: 29 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 73  ) in which the s
acb0: 65 63 6f 6e 64 20 65 6c 65 6d 65 6e 74 20 6f 66  econd element of
acc0: 20 74 68 65 20 61 72 72 61 79 0a 2a 2a 20 69 73   the array.** is
acd0: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
ace0: 20 70 72 61 67 6d 61 20 61 6e 64 20 74 68 65 20   pragma and the 
acf0: 74 68 69 72 64 20 65 6c 65 6d 65 6e 74 20 69 73  third element is
ad00: 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f   the argument to
ad10: 20 74 68 65 0a 2a 2a 20 70 72 61 67 6d 61 20 6f   the.** pragma o
ad20: 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 70 72  r NULL if the pr
ad30: 61 67 6d 61 20 68 61 73 20 6e 6f 20 61 72 67 75  agma has no argu
ad40: 6d 65 6e 74 2e 20 20 5e 54 68 65 20 68 61 6e 64  ment.  ^The hand
ad50: 6c 65 72 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53  ler for an.** [S
ad60: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
ad70: 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  MA] file control
ad80: 20 63 61 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79 20   can optionally 
ad90: 6d 61 6b 65 20 74 68 65 20 66 69 72 73 74 20 65  make the first e
ada0: 6c 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 65  lement.** of the
adb0: 20 63 68 61 72 2a 2a 20 61 72 67 75 6d 65 6e 74   char** argument
adc0: 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69   point to a stri
add0: 6e 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ng obtained from
ade0: 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74   [sqlite3_mprint
adf0: 66 28 29 5d 0a 2a 2a 20 6f 72 20 74 68 65 20 65  f()].** or the e
ae00: 71 75 69 76 61 6c 65 6e 74 20 61 6e 64 20 74 68  quivalent and th
ae10: 61 74 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62  at string will b
ae20: 65 63 6f 6d 65 20 74 68 65 20 72 65 73 75 6c 74  ecome the result
ae30: 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 6f   of the pragma o
ae40: 72 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 6d  r.** the error m
ae50: 65 73 73 61 67 65 20 69 66 20 74 68 65 20 70 72  essage if the pr
ae60: 61 67 6d 61 20 66 61 69 6c 73 2e 20 5e 49 66 20  agma fails. ^If 
ae70: 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46  the.** [SQLITE_F
ae80: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c  CNTL_PRAGMA] fil
ae90: 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e  e control return
aea0: 73 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  s [SQLITE_NOTFOU
aeb0: 4e 44 5d 2c 20 74 68 65 6e 20 6e 6f 72 6d 61 6c  ND], then normal
aec0: 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d 20 70 72   .** [PRAGMA] pr
aed0: 6f 63 65 73 73 69 6e 67 20 63 6f 6e 74 69 6e 75  ocessing continu
aee0: 65 73 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51  es.  ^If the [SQ
aef0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
af00: 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72  A].** file contr
af10: 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ol returns [SQLI
af20: 54 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20 74 68 65  TE_OK], then the
af30: 20 70 61 72 73 65 72 20 61 73 73 75 6d 65 73 20   parser assumes 
af40: 74 68 61 74 20 74 68 65 0a 2a 2a 20 56 46 53 20  that the.** VFS 
af50: 68 61 73 20 68 61 6e 64 6c 65 64 20 74 68 65 20  has handled the 
af60: 50 52 41 47 4d 41 20 69 74 73 65 6c 66 20 61 6e  PRAGMA itself an
af70: 64 20 74 68 65 20 70 61 72 73 65 72 20 67 65 6e  d the parser gen
af80: 65 72 61 74 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a  erates a no-op.*
af90: 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  * prepared state
afa0: 6d 65 6e 74 20 69 66 20 72 65 73 75 6c 74 20 73  ment if result s
afb0: 74 72 69 6e 67 20 69 73 20 4e 55 4c 4c 2c 20 6f  tring is NULL, o
afc0: 72 20 74 68 61 74 20 72 65 74 75 72 6e 73 20 61  r that returns a
afd0: 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20   copy.** of the 
afe0: 72 65 73 75 6c 74 20 73 74 72 69 6e 67 20 69 66  result string if
aff0: 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 20 6e   the string is n
b000: 6f 6e 2d 4e 55 4c 4c 2e 0a 2a 2a 20 5e 49 66 20  on-NULL..** ^If 
b010: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  the [SQLITE_FCNT
b020: 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63  L_PRAGMA] file c
b030: 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 0a 2a  ontrol returns.*
b040: 2a 20 61 6e 79 20 72 65 73 75 6c 74 20 63 6f 64  * any result cod
b050: 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  e other than [SQ
b060: 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c  LITE_OK] or [SQL
b070: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74  ITE_NOTFOUND], t
b080: 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61  hat means.** tha
b090: 74 20 74 68 65 20 56 46 53 20 65 6e 63 6f 75 6e  t the VFS encoun
b0a0: 74 65 72 65 64 20 61 6e 20 65 72 72 6f 72 20 77  tered an error w
b0b0: 68 69 6c 65 20 68 61 6e 64 6c 69 6e 67 20 74 68  hile handling th
b0c0: 65 20 5b 50 52 41 47 4d 41 5d 20 61 6e 64 20 74  e [PRAGMA] and t
b0d0: 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74 69 6f  he.** compilatio
b0e0: 6e 20 6f 66 20 74 68 65 20 50 52 41 47 4d 41 20  n of the PRAGMA 
b0f0: 66 61 69 6c 73 20 77 69 74 68 20 61 6e 20 65 72  fails with an er
b100: 72 6f 72 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49  ror.  ^The [SQLI
b110: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
b120: 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  .** file control
b130: 20 6f 63 63 75 72 73 20 61 74 20 74 68 65 20 62   occurs at the b
b140: 65 67 69 6e 6e 69 6e 67 20 6f 66 20 70 72 61 67  eginning of prag
b150: 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 61  ma statement ana
b160: 6c 79 73 69 73 20 61 6e 64 20 73 6f 0a 2a 2a 20  lysis and so.** 
b170: 69 74 20 69 73 20 61 62 6c 65 20 74 6f 20 6f 76  it is able to ov
b180: 65 72 72 69 64 65 20 62 75 69 6c 74 2d 69 6e 20  erride built-in 
b190: 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65  [PRAGMA] stateme
b1a0: 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  nts..**.** <li>[
b1b0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55  [SQLITE_FCNTL_BU
b1c0: 53 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e  SYHANDLER]].** ^
b1d0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
b1e0: 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 0a 2a  L_BUSYHANDLER].*
b1f0: 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d  * file-control m
b200: 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 62 79  ay be invoked by
b210: 20 53 51 4c 69 74 65 20 6f 6e 20 74 68 65 20 64   SQLite on the d
b220: 61 74 61 62 61 73 65 20 66 69 6c 65 20 68 61 6e  atabase file han
b230: 64 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c 79 20 61  dle.** shortly a
b240: 66 74 65 72 20 69 74 20 69 73 20 6f 70 65 6e 65  fter it is opene
b250: 64 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72  d in order to pr
b260: 6f 76 69 64 65 20 61 20 63 75 73 74 6f 6d 20 56  ovide a custom V
b270: 46 53 20 77 69 74 68 20 61 63 63 65 73 73 0a 2a  FS with access.*
b280: 2a 20 74 6f 20 74 68 65 20 63 6f 6e 6e 65 63 74  * to the connect
b290: 69 6f 6e 73 20 62 75 73 79 2d 68 61 6e 64 6c 65  ions busy-handle
b2a0: 72 20 63 61 6c 6c 62 61 63 6b 2e 20 54 68 65 20  r callback. The 
b2b0: 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 66 20 74  argument is of t
b2c0: 79 70 65 20 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a  ype (void **).**
b2d0: 20 2d 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74   - an array of t
b2e0: 77 6f 20 28 76 6f 69 64 20 2a 29 20 76 61 6c 75  wo (void *) valu
b2f0: 65 73 2e 20 54 68 65 20 66 69 72 73 74 20 28 76  es. The first (v
b300: 6f 69 64 20 2a 29 20 61 63 74 75 61 6c 6c 79 20  oid *) actually 
b310: 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 61 20 66  points.** to a f
b320: 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20  unction of type 
b330: 28 69 6e 74 20 28 2a 29 28 76 6f 69 64 20 2a 29  (int (*)(void *)
b340: 29 2e 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 69  ). In order to i
b350: 6e 76 6f 6b 65 20 74 68 65 20 63 6f 6e 6e 65 63  nvoke the connec
b360: 74 69 6f 6e 73 0a 2a 2a 20 62 75 73 79 2d 68 61  tions.** busy-ha
b370: 6e 64 6c 65 72 2c 20 74 68 69 73 20 66 75 6e 63  ndler, this func
b380: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 69  tion should be i
b390: 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 68 65 20  nvoked with the 
b3a0: 73 65 63 6f 6e 64 20 28 76 6f 69 64 20 2a 29 20  second (void *) 
b3b0: 69 6e 0a 2a 2a 20 74 68 65 20 61 72 72 61 79 20  in.** the array 
b3c0: 61 73 20 74 68 65 20 6f 6e 6c 79 20 61 72 67 75  as the only argu
b3d0: 6d 65 6e 74 2e 20 49 66 20 69 74 20 72 65 74 75  ment. If it retu
b3e0: 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
b3f0: 65 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  en the operation
b400: 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65  .** should be re
b410: 74 72 69 65 64 2e 20 49 66 20 69 74 20 72 65 74  tried. If it ret
b420: 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20 63  urns zero, the c
b430: 75 73 74 6f 6d 20 56 46 53 20 73 68 6f 75 6c 64  ustom VFS should
b440: 20 61 62 61 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20   abandon the.** 
b450: 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f  current operatio
b460: 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  n..**.** <li>[[S
b470: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50  QLITE_FCNTL_TEMP
b480: 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41  FILENAME]].** ^A
b490: 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 69  pplication can i
b4a0: 6e 76 6f 6b 65 20 74 68 65 20 5b 53 51 4c 49 54  nvoke the [SQLIT
b4b0: 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45  E_FCNTL_TEMPFILE
b4c0: 4e 41 4d 45 5d 20 66 69 6c 65 2d 63 6f 6e 74 72  NAME] file-contr
b4d0: 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76 65 20 53 51  ol.** to have SQ
b4e0: 4c 69 74 65 20 67 65 6e 65 72 61 74 65 20 61 0a  Lite generate a.
b4f0: 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  ** temporary fil
b500: 65 6e 61 6d 65 20 75 73 69 6e 67 20 74 68 65 20  ename using the 
b510: 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 74  same algorithm t
b520: 68 61 74 20 69 73 20 66 6f 6c 6c 6f 77 65 64 20  hat is followed 
b530: 74 6f 20 67 65 6e 65 72 61 74 65 0a 2a 2a 20 74  to generate.** t
b540: 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d  emporary filenam
b550: 65 73 20 66 6f 72 20 54 45 4d 50 20 74 61 62 6c  es for TEMP tabl
b560: 65 73 20 61 6e 64 20 6f 74 68 65 72 20 69 6e 74  es and other int
b570: 65 72 6e 61 6c 20 75 73 65 73 2e 20 20 54 68 65  ernal uses.  The
b580: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  .** argument sho
b590: 75 6c 64 20 62 65 20 61 20 63 68 61 72 2a 2a 20  uld be a char** 
b5a0: 77 68 69 63 68 20 77 69 6c 6c 20 62 65 20 66 69  which will be fi
b5b0: 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 66 69  lled with the fi
b5c0: 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72 69 74 74 65  lename.** writte
b5d0: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
b5e0: 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
b5f0: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20  ite3_malloc()]. 
b600: 20 54 68 65 20 63 61 6c 6c 65 72 20 73 68 6f 75   The caller shou
b610: 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20 5b 73 71  ld.** invoke [sq
b620: 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e  lite3_free()] on
b630: 20 74 68 65 20 72 65 73 75 6c 74 20 74 6f 20 61   the result to a
b640: 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65  void a memory le
b650: 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ak..**.** <li>[[
b660: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41  SQLITE_FCNTL_MMA
b670: 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20  P_SIZE]].** The 
b680: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d  [SQLITE_FCNTL_MM
b690: 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f  AP_SIZE] file co
b6a0: 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20 74 6f  ntrol is used to
b6b0: 20 71 75 65 72 79 20 6f 72 20 73 65 74 20 74 68   query or set th
b6c0: 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  e.** maximum num
b6d0: 62 65 72 20 6f 66 20 62 79 74 65 73 20 74 68 61  ber of bytes tha
b6e0: 74 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 66  t will be used f
b6f0: 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61 70 70 65 64  or memory-mapped
b700: 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20 61 72 67   I/O..** The arg
b710: 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
b720: 65 72 20 74 6f 20 61 20 76 61 6c 75 65 20 6f 66  er to a value of
b730: 20 74 79 70 65 20 73 71 6c 69 74 65 33 5f 69 6e   type sqlite3_in
b740: 74 36 34 20 74 68 61 74 0a 2a 2a 20 69 73 20 61  t64 that.** is a
b750: 6e 20 61 64 76 69 73 6f 72 79 20 6d 61 78 69 6d  n advisory maxim
b760: 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  um number of byt
b770: 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 20 74  es in the file t
b780: 6f 20 6d 65 6d 6f 72 79 20 6d 61 70 2e 20 20 54  o memory map.  T
b790: 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 73  he.** pointer is
b7a0: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74   overwritten wit
b7b0: 68 20 74 68 65 20 6f 6c 64 20 76 61 6c 75 65 2e  h the old value.
b7c0: 20 20 54 68 65 20 6c 69 6d 69 74 20 69 73 20 6e    The limit is n
b7d0: 6f 74 20 63 68 61 6e 67 65 64 20 69 66 0a 2a 2a  ot changed if.**
b7e0: 20 74 68 65 20 76 61 6c 75 65 20 6f 72 69 67 69   the value origi
b7f0: 6e 61 6c 6c 79 20 70 6f 69 6e 74 65 64 20 74 6f  nally pointed to
b800: 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 61 6e   is negative, an
b810: 64 20 73 6f 20 74 68 65 20 63 75 72 72 65 6e 74  d so the current
b820: 20 6c 69 6d 69 74 20 0a 2a 2a 20 63 61 6e 20 62   limit .** can b
b830: 65 20 71 75 65 72 69 65 64 20 62 79 20 70 61 73  e queried by pas
b840: 73 69 6e 67 20 69 6e 20 61 20 70 6f 69 6e 74 65  sing in a pointe
b850: 72 20 74 6f 20 61 20 6e 65 67 61 74 69 76 65 20  r to a negative 
b860: 6e 75 6d 62 65 72 2e 20 20 54 68 69 73 0a 2a 2a  number.  This.**
b870: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73   file-control is
b880: 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79   used internally
b890: 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 50   to implement [P
b8a0: 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d  RAGMA mmap_size]
b8b0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
b8c0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45  LITE_FCNTL_TRACE
b8d0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
b8e0: 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 66  E_FCNTL_TRACE] f
b8f0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 70 72 6f 76  ile control prov
b900: 69 64 65 73 20 61 64 76 69 73 6f 72 79 20 69 6e  ides advisory in
b910: 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20  formation.** to 
b920: 74 68 65 20 56 46 53 20 61 62 6f 75 74 20 77 68  the VFS about wh
b930: 61 74 20 74 68 65 20 68 69 67 68 65 72 20 6c 61  at the higher la
b940: 79 65 72 73 20 6f 66 20 74 68 65 20 53 51 4c 69  yers of the SQLi
b950: 74 65 20 73 74 61 63 6b 20 61 72 65 20 64 6f 69  te stack are doi
b960: 6e 67 2e 0a 2a 2a 20 54 68 69 73 20 66 69 6c 65  ng..** This file
b970: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64   control is used
b980: 20 62 79 20 73 6f 6d 65 20 56 46 53 20 61 63 74   by some VFS act
b990: 69 76 69 74 79 20 74 72 61 63 69 6e 67 20 5b 73  ivity tracing [s
b9a0: 68 69 6d 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 72  hims]..** The ar
b9b0: 67 75 6d 65 6e 74 20 69 73 20 61 20 7a 65 72 6f  gument is a zero
b9c0: 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
b9d0: 6e 67 2e 20 20 48 69 67 68 65 72 20 6c 61 79 65  ng.  Higher laye
b9e0: 72 73 20 69 6e 20 74 68 65 0a 2a 2a 20 53 51 4c  rs in the.** SQL
b9f0: 69 74 65 20 73 74 61 63 6b 20 6d 61 79 20 67 65  ite stack may ge
ba00: 6e 65 72 61 74 65 20 69 6e 73 74 61 6e 63 65 73  nerate instances
ba10: 20 6f 66 20 74 68 69 73 20 66 69 6c 65 20 63 6f   of this file co
ba20: 6e 74 72 6f 6c 20 69 66 0a 2a 2a 20 74 68 65 20  ntrol if.** the 
ba30: 5b 53 51 4c 49 54 45 5f 55 53 45 5f 46 43 4e 54  [SQLITE_USE_FCNT
ba40: 4c 5f 54 52 41 43 45 5d 20 63 6f 6d 70 69 6c 65  L_TRACE] compile
ba50: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20  -time option is 
ba60: 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  enabled..**.** <
ba70: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
ba80: 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 5d 0a 2a 2a  L_HAS_MOVED]].**
ba90: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
baa0: 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 20 66 69  TL_HAS_MOVED] fi
bab0: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 6e 74 65 72  le control inter
bac0: 70 72 65 74 73 20 69 74 73 20 61 72 67 75 6d 65  prets its argume
bad0: 6e 74 20 61 73 20 61 0a 2a 2a 20 70 6f 69 6e 74  nt as a.** point
bae0: 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
baf0: 20 61 6e 64 20 69 74 20 77 72 69 74 65 73 20 61   and it writes a
bb00: 20 62 6f 6f 6c 65 61 6e 20 69 6e 74 6f 20 74 68   boolean into th
bb10: 61 74 20 69 6e 74 65 67 65 72 20 64 65 70 65 6e  at integer depen
bb20: 64 69 6e 67 0a 2a 2a 20 6f 6e 20 77 68 65 74 68  ding.** on wheth
bb30: 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 66 69  er or not the fi
bb40: 6c 65 20 68 61 73 20 62 65 65 6e 20 72 65 6e 61  le has been rena
bb50: 6d 65 64 2c 20 6d 6f 76 65 64 2c 20 6f 72 20 64  med, moved, or d
bb60: 65 6c 65 74 65 64 20 73 69 6e 63 65 20 69 74 0a  eleted since it.
bb70: 2a 2a 20 77 61 73 20 66 69 72 73 74 20 6f 70 65  ** was first ope
bb80: 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ned..**.** <li>[
bb90: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49  [SQLITE_FCNTL_WI
bba0: 4e 33 32 5f 47 45 54 5f 48 41 4e 44 4c 45 5d 5d  N32_GET_HANDLE]]
bbb0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
bbc0: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f  FCNTL_WIN32_GET_
bbd0: 48 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 65 20 63  HANDLE] opcode c
bbe0: 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62  an be used to ob
bbf0: 74 61 69 6e 20 74 68 65 0a 2a 2a 20 75 6e 64 65  tain the.** unde
bc00: 72 6c 79 69 6e 67 20 6e 61 74 69 76 65 20 66 69  rlying native fi
bc10: 6c 65 20 68 61 6e 64 6c 65 20 61 73 73 6f 63 69  le handle associ
bc20: 61 74 65 64 20 77 69 74 68 20 61 20 66 69 6c 65  ated with a file
bc30: 20 68 61 6e 64 6c 65 2e 20 20 54 68 69 73 20 66   handle.  This f
bc40: 69 6c 65 0a 2a 2a 20 63 6f 6e 74 72 6f 6c 20 69  ile.** control i
bc50: 6e 74 65 72 70 72 65 74 73 20 69 74 73 20 61 72  nterprets its ar
bc60: 67 75 6d 65 6e 74 20 61 73 20 61 20 70 6f 69 6e  gument as a poin
bc70: 74 65 72 20 74 6f 20 61 20 6e 61 74 69 76 65 20  ter to a native 
bc80: 66 69 6c 65 20 68 61 6e 64 6c 65 20 61 6e 64 0a  file handle and.
bc90: 2a 2a 20 77 72 69 74 65 73 20 74 68 65 20 72 65  ** writes the re
bca0: 73 75 6c 74 69 6e 67 20 76 61 6c 75 65 20 74 68  sulting value th
bcb0: 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ere..**.** <li>[
bcc0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49  [SQLITE_FCNTL_WI
bcd0: 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 5d  N32_SET_HANDLE]]
bce0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
bcf0: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f  FCNTL_WIN32_SET_
bd00: 48 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 65 20 69  HANDLE] opcode i
bd10: 73 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67  s used for debug
bd20: 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f  ging.  This.** o
bd30: 70 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65  pcode causes the
bd40: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
bd50: 74 68 6f 64 20 74 6f 20 73 77 61 70 20 74 68 65  thod to swap the
bd60: 20 66 69 6c 65 20 68 61 6e 64 6c 65 20 77 69 74   file handle wit
bd70: 68 20 74 68 65 20 6f 6e 65 0a 2a 2a 20 70 6f 69  h the one.** poi
bd80: 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 70  nted to by the p
bd90: 41 72 67 20 61 72 67 75 6d 65 6e 74 2e 20 20 54  Arg argument.  T
bda0: 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 20 69  his capability i
bdb0: 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65  s used during te
bdc0: 73 74 69 6e 67 0a 2a 2a 20 61 6e 64 20 6f 6e 6c  sting.** and onl
bdd0: 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75  y needs to be su
bde0: 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c  pported when SQL
bdf0: 49 54 45 5f 54 45 53 54 20 69 73 20 64 65 66 69  ITE_TEST is defi
be00: 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ned..**.** <li>[
be10: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41  [SQLITE_FCNTL_WA
be20: 4c 5f 42 4c 4f 43 4b 5d 5d 0a 2a 2a 20 54 68 65  L_BLOCK]].** The
be30: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57   [SQLITE_FCNTL_W
be40: 41 4c 5f 42 4c 4f 43 4b 5d 20 69 73 20 61 20 73  AL_BLOCK] is a s
be50: 69 67 6e 61 6c 20 74 6f 20 74 68 65 20 56 46 53  ignal to the VFS
be60: 20 6c 61 79 65 72 20 74 68 61 74 20 69 74 20 6d   layer that it m
be70: 69 67 68 74 0a 2a 2a 20 62 65 20 61 64 76 61 6e  ight.** be advan
be80: 74 61 67 65 6f 75 73 20 74 6f 20 62 6c 6f 63 6b  tageous to block
be90: 20 6f 6e 20 74 68 65 20 6e 65 78 74 20 57 41 4c   on the next WAL
bea0: 20 6c 6f 63 6b 20 69 66 20 74 68 65 20 6c 6f 63   lock if the loc
beb0: 6b 20 69 73 20 6e 6f 74 20 69 6d 6d 65 64 69 61  k is not immedia
bec0: 74 65 6c 79 0a 2a 2a 20 61 76 61 69 6c 61 62 6c  tely.** availabl
bed0: 65 2e 20 20 54 68 65 20 57 41 4c 20 73 75 62 73  e.  The WAL subs
bee0: 79 73 74 65 6d 20 69 73 73 75 65 73 20 74 68 69  ystem issues thi
bef0: 73 20 73 69 67 6e 61 6c 20 64 75 72 69 6e 67 20  s signal during 
bf00: 72 61 72 65 0a 2a 2a 20 63 69 72 63 75 6d 73 74  rare.** circumst
bf10: 61 6e 63 65 73 20 69 6e 20 6f 72 64 65 72 20 74  ances in order t
bf20: 6f 20 66 69 78 20 61 20 70 72 6f 62 6c 65 6d 20  o fix a problem 
bf30: 77 69 74 68 20 70 72 69 6f 72 69 74 79 20 69 6e  with priority in
bf40: 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 41 70 70 6c  version..** Appl
bf50: 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
bf60: 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20 75 73 65  <em>not</em> use
bf70: 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72   this file-contr
bf80: 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ol..**.** <li>[[
bf90: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50  SQLITE_FCNTL_ZIP
bfa0: 56 46 53 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  VFS]].** The [SQ
bfb0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46  LITE_FCNTL_ZIPVF
bfc0: 53 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6d 70  S] opcode is imp
bfd0: 6c 65 6d 65 6e 74 65 64 20 62 79 20 7a 69 70 76  lemented by zipv
bfe0: 66 73 20 6f 6e 6c 79 2e 20 41 6c 6c 20 6f 74 68  fs only. All oth
bff0: 65 72 0a 2a 2a 20 56 46 53 20 73 68 6f 75 6c 64  er.** VFS should
c000: 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e   return SQLITE_N
c010: 4f 54 46 4f 55 4e 44 20 66 6f 72 20 74 68 69 73  OTFOUND for this
c020: 20 6f 70 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 3c   opcode..**.** <
c030: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
c040: 4c 5f 52 42 55 5d 5d 0a 2a 2a 20 54 68 65 20 5b  L_RBU]].** The [
c050: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55  SQLITE_FCNTL_RBU
c060: 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6d 70 6c  ] opcode is impl
c070: 65 6d 65 6e 74 65 64 20 62 79 20 74 68 65 20 73  emented by the s
c080: 70 65 63 69 61 6c 20 56 46 53 20 75 73 65 64 20  pecial VFS used 
c090: 62 79 0a 2a 2a 20 74 68 65 20 52 42 55 20 65 78  by.** the RBU ex
c0a0: 74 65 6e 73 69 6f 6e 20 6f 6e 6c 79 2e 20 20 41  tension only.  A
c0b0: 6c 6c 20 6f 74 68 65 72 20 56 46 53 20 73 68 6f  ll other VFS sho
c0c0: 75 6c 64 20 72 65 74 75 72 6e 20 53 51 4c 49 54  uld return SQLIT
c0d0: 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f 72 0a 2a  E_NOTFOUND for.*
c0e0: 2a 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 20  * this opcode.  
c0f0: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65  .** </ul>.*/.#de
c100: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c110: 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20  L_LOCKSTATE     
c120: 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66            1.#def
c130: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c140: 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _GET_LOCKPROXYFI
c150: 4c 45 20 20 20 20 20 20 20 32 0a 23 64 65 66 69  LE       2.#defi
c160: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c170: 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  SET_LOCKPROXYFIL
c180: 45 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e  E       3.#defin
c190: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c  e SQLITE_FCNTL_L
c1a0: 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20  AST_ERRNO       
c1b0: 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65         4.#define
c1c0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49   SQLITE_FCNTL_SI
c1d0: 5a 45 5f 48 49 4e 54 20 20 20 20 20 20 20 20 20  ZE_HINT         
c1e0: 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20        5.#define 
c1f0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55  SQLITE_FCNTL_CHU
c200: 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20  NK_SIZE         
c210: 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53       6.#define S
c220: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45  QLITE_FCNTL_FILE
c230: 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20  _POINTER        
c240: 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51      7.#define SQ
c250: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f  LITE_FCNTL_SYNC_
c260: 4f 4d 49 54 54 45 44 20 20 20 20 20 20 20 20 20  OMITTED         
c270: 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c     8.#define SQL
c280: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
c290: 41 56 5f 52 45 54 52 59 20 20 20 20 20 20 20 20  AV_RETRY        
c2a0: 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    9.#define SQLI
c2b0: 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54  TE_FCNTL_PERSIST
c2c0: 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20  _WAL            
c2d0: 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  10.#define SQLIT
c2e0: 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54  E_FCNTL_OVERWRIT
c2f0: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31  E              1
c300: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
c310: 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 20  _FCNTL_VFSNAME  
c320: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 32                12
c330: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c340: 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f  FCNTL_POWERSAFE_
c350: 4f 56 45 52 57 52 49 54 45 20 20 20 20 31 33 0a  OVERWRITE    13.
c360: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c370: 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20 20 20  CNTL_PRAGMA     
c380: 20 20 20 20 20 20 20 20 20 20 20 20 31 34 0a 23              14.#
c390: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
c3a0: 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 20  NTL_BUSYHANDLER 
c3b0: 20 20 20 20 20 20 20 20 20 20 20 31 35 0a 23 64             15.#d
c3c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
c3d0: 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 20  TL_TEMPFILENAME 
c3e0: 20 20 20 20 20 20 20 20 20 20 31 36 0a 23 64 65            16.#de
c3f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c400: 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 20  L_MMAP_SIZE     
c410: 20 20 20 20 20 20 20 20 20 31 38 0a 23 64 65 66           18.#def
c420: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c430: 5f 54 52 41 43 45 20 20 20 20 20 20 20 20 20 20  _TRACE          
c440: 20 20 20 20 20 20 20 20 31 39 0a 23 64 65 66 69          19.#defi
c450: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c460: 48 41 53 5f 4d 4f 56 45 44 20 20 20 20 20 20 20  HAS_MOVED       
c470: 20 20 20 20 20 20 20 32 30 0a 23 64 65 66 69 6e         20.#defin
c480: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  e SQLITE_FCNTL_S
c490: 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20  YNC             
c4a0: 20 20 20 20 20 20 32 31 0a 23 64 65 66 69 6e 65        21.#define
c4b0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f   SQLITE_FCNTL_CO
c4c0: 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 20 20 20  MMIT_PHASETWO   
c4d0: 20 20 20 20 20 32 32 0a 23 64 65 66 69 6e 65 20       22.#define 
c4e0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
c4f0: 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 20 20 20  32_SET_HANDLE   
c500: 20 20 20 20 32 33 0a 23 64 65 66 69 6e 65 20 53      23.#define S
c510: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f  QLITE_FCNTL_WAL_
c520: 42 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  BLOCK           
c530: 20 20 20 32 34 0a 23 64 65 66 69 6e 65 20 53 51     24.#define SQ
c540: 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46  LITE_FCNTL_ZIPVF
c550: 53 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  S               
c560: 20 20 32 35 0a 23 64 65 66 69 6e 65 20 53 51 4c    25.#define SQL
c570: 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 20 20 20  ITE_FCNTL_RBU   
c580: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
c590: 20 32 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   26.#define SQLI
c5a0: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49  TE_FCNTL_VFS_POI
c5b0: 4e 54 45 52 20 20 20 20 20 20 20 20 20 20 20 20  NTER            
c5c0: 32 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  27.#define SQLIT
c5d0: 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f  E_FCNTL_JOURNAL_
c5e0: 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 32  POINTER        2
c5f0: 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
c600: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54  _FCNTL_WIN32_GET
c610: 5f 48 41 4e 44 4c 45 20 20 20 20 20 20 20 32 39  _HANDLE       29
c620: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c630: 46 43 4e 54 4c 5f 50 44 42 20 20 20 20 20 20 20  FCNTL_PDB       
c640: 20 20 20 20 20 20 20 20 20 20 20 20 20 33 30 0a               30.
c650: 0a 2f 2a 20 64 65 70 72 65 63 61 74 65 64 20 6e  ./* deprecated n
c660: 61 6d 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ames */.#define 
c670: 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50  SQLITE_GET_LOCKP
c680: 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 53 51  ROXYFILE      SQ
c690: 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c  LITE_FCNTL_GET_L
c6a0: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65  OCKPROXYFILE.#de
c6b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f  fine SQLITE_SET_
c6c0: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20  LOCKPROXYFILE   
c6d0: 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f     SQLITE_FCNTL_
c6e0: 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  SET_LOCKPROXYFIL
c6f0: 45 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  E.#define SQLITE
c700: 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20  _LAST_ERRNO     
c710: 20 20 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46          SQLITE_F
c720: 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 0a  CNTL_LAST_ERRNO.
c730: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
c740: 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a  : Mutex Handle.*
c750: 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d  *.** The mutex m
c760: 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c  odule within SQL
c770: 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c  ite defines [sql
c780: 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62  ite3_mutex] to b
c790: 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74  e an.** abstract
c7a0: 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65   type for a mute
c7b0: 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53  x object.  The S
c7c0: 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72  QLite core never
c7d0: 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65   looks.** at the
c7e0: 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73   internal repres
c7f0: 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b  entation of an [
c800: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20  sqlite3_mutex]. 
c810: 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c   It only.** deal
c820: 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20  s with pointers 
c830: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
c840: 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a  mutex] object..*
c850: 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65  *.** Mutexes are
c860: 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b   created using [
c870: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c  sqlite3_mutex_al
c880: 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64  loc()]..*/.typed
c890: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
c8a0: 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f  3_mutex sqlite3_
c8b0: 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  mutex;../*.** CA
c8c0: 50 49 33 52 45 46 3a 20 4c 6f 61 64 61 62 6c 65  PI3REF: Loadable
c8d0: 20 45 78 74 65 6e 73 69 6f 6e 20 54 68 75 6e 6b   Extension Thunk
c8e0: 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72  .**.** A pointer
c8f0: 20 74 6f 20 74 68 65 20 6f 70 61 71 75 65 20 73   to the opaque s
c900: 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74 69  qlite3_api_routi
c910: 6e 65 73 20 73 74 72 75 63 74 75 72 65 20 69 73  nes structure is
c920: 20 70 61 73 73 65 64 20 61 73 0a 2a 2a 20 74 68   passed as.** th
c930: 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
c940: 72 20 74 6f 20 65 6e 74 72 79 20 70 6f 69 6e 74  r to entry point
c950: 73 20 6f 66 20 5b 6c 6f 61 64 61 62 6c 65 20 65  s of [loadable e
c960: 78 74 65 6e 73 69 6f 6e 73 5d 2e 20 20 54 68 69  xtensions].  Thi
c970: 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 6d  s.** structure m
c980: 75 73 74 20 62 65 20 74 79 70 65 64 65 66 65 64  ust be typedefed
c990: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 77 6f 72   in order to wor
c9a0: 6b 20 61 72 6f 75 6e 64 20 63 6f 6d 70 69 6c 65  k around compile
c9b0: 72 20 77 61 72 6e 69 6e 67 73 0a 2a 2a 20 6f 6e  r warnings.** on
c9c0: 20 73 6f 6d 65 20 70 6c 61 74 66 6f 72 6d 73 2e   some platforms.
c9d0: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
c9e0: 63 74 20 73 71 6c 69 74 65 33 5f 61 70 69 5f 72  ct sqlite3_api_r
c9f0: 6f 75 74 69 6e 65 73 20 73 71 6c 69 74 65 33 5f  outines sqlite3_
ca00: 61 70 69 5f 72 6f 75 74 69 6e 65 73 3b 0a 0a 2f  api_routines;../
ca10: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
ca20: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65  S Interface Obje
ca30: 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  ct.**.** An inst
ca40: 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69  ance of the sqli
ca50: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64  te3_vfs object d
ca60: 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72  efines the inter
ca70: 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20  face between.** 
ca80: 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  the SQLite core 
ca90: 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69  and the underlyi
caa0: 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  ng operating sys
cab0: 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a  tem.  The "vfs".
cac0: 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f  ** in the name o
cad0: 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61  f the object sta
cae0: 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c  nds for "virtual
caf0: 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 20 20   file system".  
cb00: 53 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20  See.** the [VFS 
cb10: 7c 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 61 74  | VFS documentat
cb20: 69 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 65 72  ion] for further
cb30: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
cb40: 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66  .** The value of
cb50: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69   the iVersion fi
cb60: 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79  eld is initially
cb70: 20 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61   1 but may be la
cb80: 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72  rger in.** futur
cb90: 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
cba0: 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61  Lite.  Additiona
cbb0: 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20  l fields may be 
cbc0: 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73  appended to this
cbd0: 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20  .** object when 
cbe0: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c  the iVersion val
cbf0: 75 65 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e  ue is increased.
cc00: 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20    Note that the 
cc10: 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20  structure.** of 
cc20: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20  the sqlite3_vfs 
cc30: 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69  object changes i
cc40: 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  n the transactio
cc50: 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c  n between.** SQL
cc60: 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
cc70: 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20  9 and 3.6.0 and 
cc80: 79 65 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e  yet the iVersion
cc90: 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a   field was not.*
cca0: 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a  * modified..**.*
ccb0: 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66  * The szOsFile f
ccc0: 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65  ield is the size
ccd0: 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 73   of the subclass
cce0: 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ed [sqlite3_file
ccf0: 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75  ].** structure u
cd00: 73 65 64 20 62 79 20 74 68 69 73 20 56 46 53 2e  sed by this VFS.
cd10: 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20    mxPathname is 
cd20: 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  the maximum leng
cd30: 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e  th of.** a pathn
cd40: 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e  ame in this VFS.
cd50: 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65  .**.** Registere
cd60: 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62  d sqlite3_vfs ob
cd70: 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f  jects are kept o
cd80: 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20  n a linked list 
cd90: 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65  formed by.** the
cda0: 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20   pNext pointer. 
cdb0: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   The [sqlite3_vf
cdc0: 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a  s_register()].**
cdd0: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66   and [sqlite3_vf
cde0: 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20  s_unregister()] 
cdf0: 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67  interfaces manag
ce00: 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69  e this list.** i
ce10: 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 20  n a thread-safe 
ce20: 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  way.  The [sqlit
ce30: 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69  e3_vfs_find()] i
ce40: 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72  nterface.** sear
ce50: 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20  ches the list.  
ce60: 4e 65 69 74 68 65 72 20 74 68 65 20 61 70 70 6c  Neither the appl
ce70: 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72  ication code nor
ce80: 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c   the VFS.** impl
ce90: 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c  ementation shoul
cea0: 64 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 20  d use the pNext 
ceb0: 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  pointer..**.** T
cec0: 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69  he pNext field i
ced0: 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64  s the only field
cee0: 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f   in the sqlite3_
cef0: 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  vfs.** structure
cf00: 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
cf10: 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20  l ever modify.  
cf20: 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79  SQLite will only
cf30: 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f   access.** or mo
cf40: 64 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 20  dify this field 
cf50: 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20  while holding a 
cf60: 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 69  particular stati
cf70: 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20  c mutex..** The 
cf80: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
cf90: 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20  ld never modify 
cfa0: 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20  anything within 
cfb0: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a  the sqlite3_vfs.
cfc0: 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74  ** object once t
cfd0: 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65  he object has be
cfe0: 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a  en registered..*
cff0: 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66  *.** The zName f
d000: 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e  ield holds the n
d010: 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d  ame of the VFS m
d020: 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65  odule.  The name
d030: 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71   must.** be uniq
d040: 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46  ue across all VF
d050: 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a  S modules..**.**
d060: 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78   [[sqlite3_vfs.x
d070: 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74  Open]].** ^SQLit
d080: 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  e guarantees tha
d090: 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20  t the zFilename 
d0a0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70  parameter to xOp
d0b0: 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20  en.** is either 
d0c0: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f  a NULL pointer o
d0d0: 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65  r string obtaine
d0e0: 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50  d.** from xFullP
d0f0: 61 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20 61  athname() with a
d100: 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66 69  n optional suffi
d110: 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20  x added..** ^If 
d120: 61 20 73 75 66 66 69 78 20 69 73 20 61 64 64 65  a suffix is adde
d130: 64 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61  d to the zFilena
d140: 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69 74  me parameter, it
d150: 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74   will.** consist
d160: 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d 22   of a single "-"
d170: 20 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f   character follo
d180: 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74  wed by no more t
d190: 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e  han.** 11 alphan
d1a0: 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d  umeric and/or "-
d1b0: 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  " characters..**
d1c0: 20 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65 72   ^SQLite further
d1d0: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
d1e0: 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77  .** the string w
d1f0: 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64  ill be valid and
d200: 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c   unchanged until
d210: 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20   xClose() is.** 
d220: 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20  called. Because 
d230: 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  of the previous 
d240: 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65  sentence,.** the
d250: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
d260: 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65  can safely store
d270: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
d280: 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66  e.** filename if
d290: 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d   it needs to rem
d2a0: 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61  ember the filena
d2b0: 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73  me for some reas
d2c0: 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46  on..** If the zF
d2d0: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
d2e0: 72 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 20  r to xOpen is a 
d2f0: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
d300: 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20  n xOpen.** must 
d310: 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74  invent its own t
d320: 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f  emporary name fo
d330: 72 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57 68  r the file.  ^Wh
d340: 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78  enever the .** x
d350: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
d360: 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69  er is NULL it wi
d370: 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63  ll also be the c
d380: 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ase that the.** 
d390: 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20  flags parameter 
d3a0: 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51  will include [SQ
d3b0: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
d3c0: 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20  ONCLOSE]..**.** 
d3d0: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
d3e0: 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e  nt to xOpen() in
d3f0: 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20  cludes all bits 
d400: 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c  set in.** the fl
d410: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
d420: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
d430: 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c  ()].  Or if [sql
d440: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20  ite3_open()].** 
d450: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  or [sqlite3_open
d460: 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74  16()] is used, t
d470: 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64  hen flags includ
d480: 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b  es at least.** [
d490: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
d4a0: 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45  WRITE] | [SQLITE
d4b0: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a  _OPEN_CREATE]. .
d4c0: 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70  ** If xOpen() op
d4d0: 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d  ens a file read-
d4e0: 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74  only then it set
d4f0: 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a  s *pOutFlags to.
d500: 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49  ** include [SQLI
d510: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
d520: 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20 69  ].  Other bits i
d530: 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79  n *pOutFlags may
d540: 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e   be set..**.** ^
d550: 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73  (SQLite will als
d560: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65  o add one of the
d570: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73   following flags
d580: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a   to the xOpen().
d590: 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69  ** call, dependi
d5a0: 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74  ng on the object
d5b0: 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a   being opened:.*
d5c0: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
d5d0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
d5e0: 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e  MAIN_DB].** <li>
d5f0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
d600: 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  AIN_JOURNAL].** 
d610: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
d620: 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c  EN_TEMP_DB].** <
d630: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
d640: 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a  N_TEMP_JOURNAL].
d650: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
d660: 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f  _OPEN_TRANSIENT_
d670: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  DB].** <li>  [SQ
d680: 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55  LITE_OPEN_SUBJOU
d690: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
d6a0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54  SQLITE_OPEN_MAST
d6b0: 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  ER_JOURNAL].** <
d6c0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
d6d0: 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29  N_WAL].** </ul>)
d6e0: 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65  ^.**.** The file
d6f0: 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74   I/O implementat
d700: 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20  ion can use the 
d710: 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67  object type flag
d720: 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74  s to.** change t
d730: 68 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20  he way it deals 
d740: 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72  with files.  For
d750: 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70   example, an app
d760: 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74  lication.** that
d770: 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61   does not care a
d780: 62 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76  bout crash recov
d790: 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20  ery or rollback 
d7a0: 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68  might make.** th
d7b0: 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72  e open of a jour
d7c0: 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70  nal file a no-op
d7d0: 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 69  .  Writes to thi
d7e0: 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a  s journal would.
d7f0: 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70  ** also be no-op
d800: 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d  s, and any attem
d810: 70 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a  pt to read the j
d820: 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74  ournal would ret
d830: 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f  urn.** SQLITE_IO
d840: 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70  ERR.  Or the imp
d850: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68  lementation migh
d860: 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74  t recognize that
d870: 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66   a database.** f
d880: 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e  ile will be doin
d890: 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73  g page-aligned s
d8a0: 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20  ector reads and 
d8b0: 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64  writes in a rand
d8c0: 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20  om.** order and 
d8d0: 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73  set up its I/O s
d8e0: 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69  ubsystem accordi
d8f0: 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  ngly..**.** SQLi
d900: 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64  te might also ad
d910: 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  d one of the fol
d920: 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20  lowing flags to 
d930: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  the xOpen method
d940: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
d950: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45  <li> [SQLITE_OPE
d960: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
d970: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
d980: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d  _OPEN_EXCLUSIVE]
d990: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
d9a0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
d9b0: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20  _DELETEONCLOSE] 
d9c0: 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66  flag means the f
d9d0: 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a  ile should be.**
d9e0: 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74   deleted when it
d9f0: 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68   is closed.  ^Th
da00: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  e [SQLITE_OPEN_D
da10: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a  ELETEONCLOSE].**
da20: 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72   will be set for
da30: 20 54 45 4d 50 20 64 61 74 61 62 61 73 65 73 20   TEMP databases 
da40: 61 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e 61  and their journa
da50: 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a  ls, transient.**
da60: 20 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64 20   databases, and 
da70: 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a  subjournals..**.
da80: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
da90: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20  OPEN_EXCLUSIVE] 
daa0: 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20 75  flag is always u
dab0: 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69  sed in conjuncti
dac0: 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  on.** with the [
dad0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
dae0: 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20  TE] flag, which 
daf0: 61 72 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c  are both directl
db00: 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74  y.** analogous t
db10: 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64  o the O_EXCL and
db20: 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f   O_CREAT flags o
db30: 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e  f the POSIX open
db40: 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20  ().** API.  The 
db50: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
db60: 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e  USIVE flag, when
db70: 20 70 61 69 72 65 64 20 77 69 74 68 20 74 68 65   paired with the
db80: 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e   .** SQLITE_OPEN
db90: 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73 65 64  _CREATE, is used
dba0: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61   to indicate tha
dbb0: 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c  t file should al
dbc0: 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74  ways.** be creat
dbd0: 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20  ed, and that it 
dbe0: 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69  is an error if i
dbf0: 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 73  t already exists
dc00: 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f  ..** It is <i>no
dc10: 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e  t</i> used to in
dc20: 64 69 63 61 74 65 20 74 68 65 20 66 69 6c 65 20  dicate the file 
dc30: 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64  should be opened
dc40: 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69   .** for exclusi
dc50: 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a  ve access..**.**
dc60: 20 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46   ^At least szOsF
dc70: 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d  ile bytes of mem
dc80: 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65  ory are allocate
dc90: 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74  d by SQLite.** t
dca0: 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c  o hold the  [sql
dcb0: 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63  ite3_file] struc
dcc0: 74 75 72 65 20 70 61 73 73 65 64 20 61 73 20 74  ture passed as t
dcd0: 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75  he third.** argu
dce0: 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20  ment to xOpen.  
dcf0: 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  The xOpen method
dd00: 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74   does not have t
dd10: 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68  o.** allocate th
dd20: 65 20 73 74 72 75 63 74 75 72 65 3b 20 69 74 20  e structure; it 
dd30: 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c  should just fill
dd40: 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68   it in.  Note th
dd50: 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20  at.** the xOpen 
dd60: 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20  method must set 
dd70: 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  the sqlite3_file
dd80: 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74  .pMethods to eit
dd90: 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b  her.** a valid [
dda0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
ddb0: 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f  ds] object or to
ddc0: 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75   NULL.  xOpen mu
ddd0: 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76  st do.** this ev
dde0: 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66  en if the open f
ddf0: 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78  ails.  SQLite ex
de00: 70 65 63 74 73 20 74 68 61 74 20 74 68 65 20 73  pects that the s
de10: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74  qlite3_file.pMet
de20: 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20  hods.** element 
de30: 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66  will be valid af
de40: 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e  ter xOpen return
de50: 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  s regardless of 
de60: 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f  the success.** o
de70: 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65  r failure of the
de80: 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a   xOpen call..**.
de90: 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73  ** [[sqlite3_vfs
dea0: 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54  .xAccess]].** ^T
deb0: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
dec0: 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d  t to xAccess() m
ded0: 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43  ay be [SQLITE_AC
dee0: 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20  CESS_EXISTS].** 
def0: 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 20  to test for the 
df00: 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66  existence of a f
df10: 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ile, or [SQLITE_
df20: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
df30: 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65  ] to.** test whe
df40: 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 72  ther a file is r
df50: 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74  eadable and writ
df60: 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45  able, or [SQLITE
df70: 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a  _ACCESS_READ].**
df80: 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65 72   to test whether
df90: 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65   a file is at le
dfa0: 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20  ast readable.   
dfb0: 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20  The file can be 
dfc0: 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a  a.** directory..
dfd0: 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  **.** ^SQLite wi
dfe0: 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61  ll always alloca
dff0: 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61  te at least mxPa
e000: 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66  thname+1 bytes f
e010: 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74  or the.** output
e020: 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74   buffer xFullPat
e030: 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63  hname.  The exac
e040: 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75  t size of the ou
e050: 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69  tput buffer.** i
e060: 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73  s also passed as
e070: 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   a parameter to 
e080: 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49  both  methods. I
e090: 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66  f the output buf
e0a0: 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61  fer.** is not la
e0b0: 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c  rge enough, [SQL
e0c0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68  ITE_CANTOPEN] sh
e0d0: 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64  ould be returned
e0e0: 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a  . Since this is.
e0f0: 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20  ** handled as a 
e100: 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53  fatal error by S
e110: 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65  QLite, vfs imple
e120: 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c  mentations shoul
e130: 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f  d endeavor.** to
e140: 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79   prevent this by
e150: 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e   setting mxPathn
e160: 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 69  ame to a suffici
e170: 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75  ently large valu
e180: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61  e..**.** The xRa
e190: 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65  ndomness(), xSle
e1a0: 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69  ep(), xCurrentTi
e1b0: 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65  me(), and xCurre
e1c0: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a  ntTimeInt64().**
e1d0: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
e1e0: 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20 70  not strictly a p
e1f0: 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73  art of the files
e200: 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20  ystem, but they 
e210: 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20  are.** included 
e220: 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 75 63  in the VFS struc
e230: 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74  ture for complet
e240: 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52  eness..** The xR
e250: 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63  andomness() func
e260: 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f  tion attempts to
e270: 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62   return nBytes b
e280: 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d  ytes.** of good-
e290: 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65  quality randomne
e2a0: 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54  ss into zOut.  T
e2b0: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
e2c0: 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c  is.** the actual
e2d0: 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
e2e0: 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f   of randomness o
e2f0: 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20  btained..** The 
e300: 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20  xSleep() method 
e310: 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69  causes the calli
e320: 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65  ng thread to sle
e330: 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61  ep for at.** lea
e340: 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  st the number of
e350: 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69   microseconds gi
e360: 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72  ven.  ^The xCurr
e370: 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74  entTime().** met
e380: 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75  hod returns a Ju
e390: 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20  lian Day Number 
e3a0: 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20  for the current 
e3b0: 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73  date and time as
e3c0: 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70  .** a floating p
e3d0: 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e  oint value..** ^
e3e0: 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  The xCurrentTime
e3f0: 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72  Int64() method r
e400: 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e  eturns, as an in
e410: 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61  teger, the Julia
e420: 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20  n.** Day Number 
e430: 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38 36  multiplied by 86
e440: 34 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62  400000 (the numb
e450: 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  er of millisecon
e460: 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68  ds in .** a 24-h
e470: 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e  our day).  .** ^
e480: 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
e490: 74 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  the xCurrentTime
e4a0: 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74  Int64() method t
e4b0: 6f 20 67 65 74 20 74 68 65 20 63 75 72 72 65 6e  o get the curren
e4c0: 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69  t.** date and ti
e4d0: 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f  me if that metho
e4e0: 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28  d is available (
e4f0: 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32  if iVersion is 2
e500: 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20   or .** greater 
e510: 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  and the function
e520: 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
e530: 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66  NULL) and will f
e540: 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78  all back.** to x
e550: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66  CurrentTime() if
e560: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74   xCurrentTimeInt
e570: 36 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61  64() is unavaila
e580: 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ble..**.** ^The 
e590: 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29  xSetSystemCall()
e5a0: 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c  , xGetSystemCall
e5b0: 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73  (), and xNestSys
e5c0: 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66  temCall() interf
e5d0: 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20  aces.** are not 
e5e0: 75 73 65 64 20 62 79 20 74 68 65 20 53 51 4c 69  used by the SQLi
e5f0: 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20  te core.  These 
e600: 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61  optional interfa
e610: 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64  ces are provided
e620: 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65  .** by some VFSe
e630: 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20  s to facilitate 
e640: 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56  testing of the V
e650: 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72  FS code. By over
e660: 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65  riding .** syste
e670: 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e  m calls with fun
e680: 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73  ctions under its
e690: 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74   control, a test
e6a0: 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20   program can.** 
e6b0: 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20  simulate faults 
e6c0: 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74  and error condit
e6d0: 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20  ions that would 
e6e0: 6f 74 68 65 72 77 69 73 65 20 62 65 20 64 69 66  otherwise be dif
e6f0: 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70  ficult.** or imp
e700: 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63  ossible to induc
e710: 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20 73  e.  The set of s
e720: 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74  ystem calls that
e730: 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64   can be overridd
e740: 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f  en.** varies fro
e750: 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f  m one VFS to ano
e760: 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f  ther, and from o
e770: 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68  ne version of th
e780: 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68  e same VFS to th
e790: 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c  e.** next.  Appl
e7a0: 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73  ications that us
e7b0: 65 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  e these interfac
e7c0: 65 73 20 6d 75 73 74 20 62 65 20 70 72 65 70 61  es must be prepa
e7d0: 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f  red for any.** o
e7e0: 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69  r all of these i
e7f0: 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62 65 20  nterfaces to be 
e800: 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69  NULL or for thei
e810: 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68  r behavior to ch
e820: 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65  ange.** from one
e830: 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20   release to the 
e840: 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69  next.  Applicati
e850: 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74  ons must not att
e860: 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a  empt to access.*
e870: 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d  * any of these m
e880: 65 74 68 6f 64 73 20 69 66 20 74 68 65 20 69 56  ethods if the iV
e890: 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46  ersion of the VF
e8a0: 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33  S is less than 3
e8b0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
e8c0: 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20  uct sqlite3_vfs 
e8d0: 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70  sqlite3_vfs;.typ
e8e0: 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69  edef void (*sqli
e8f0: 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29  te3_syscall_ptr)
e900: 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73  (void);.struct s
e910: 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69  qlite3_vfs {.  i
e920: 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20  nt iVersion;    
e930: 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63          /* Struc
e940: 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d  ture version num
e950: 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33  ber (currently 3
e960: 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46  ) */.  int szOsF
e970: 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20  ile;            
e980: 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c  /* Size of subcl
e990: 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69  assed sqlite3_fi
e9a0: 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61  le */.  int mxPa
e9b0: 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20  thname;         
e9c0: 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65   /* Maximum file
e9d0: 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68   pathname length
e9e0: 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66   */.  sqlite3_vf
e9f0: 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f  s *pNext;      /
ea00: 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65  * Next registere
ea10: 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74  d VFS */.  const
ea20: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20   char *zName;   
ea30: 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74      /* Name of t
ea40: 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65  his virtual file
ea50: 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69   system */.  voi
ea60: 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20  d *pAppData;    
ea70: 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72        /* Pointer
ea80: 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   to application-
ea90: 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f  specific data */
eaa0: 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28  .  int (*xOpen)(
eab0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
eac0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
ead0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a   sqlite3_file*,.
eae0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69                 i
eaf0: 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70  nt flags, int *p
eb00: 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74  OutFlags);.  int
eb10: 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69   (*xDelete)(sqli
eb20: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
eb30: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
eb40: 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74   syncDir);.  int
eb50: 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69   (*xAccess)(sqli
eb60: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
eb70: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
eb80: 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65   flags, int *pRe
eb90: 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sOut);.  int (*x
eba0: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71  FullPathname)(sq
ebb0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
ebc0: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
ebd0: 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a  nt nOut, char *z
ebe0: 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a  Out);.  void *(*
ebf0: 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33  xDlOpen)(sqlite3
ec00: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
ec10: 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20  r *zFilename);. 
ec20: 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72   void (*xDlError
ec30: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
ec40: 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20  int nByte, char 
ec50: 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69  *zErrMsg);.  voi
ec60: 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71  d (*(*xDlSym)(sq
ec70: 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a  lite3_vfs*,void*
ec80: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53  , const char *zS
ec90: 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20  ymbol))(void);. 
eca0: 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65   void (*xDlClose
ecb0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
ecc0: 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  void*);.  int (*
ecd0: 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c  xRandomness)(sql
ece0: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e  ite3_vfs*, int n
ecf0: 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74  Byte, char *zOut
ed00: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65  );.  int (*xSlee
ed10: 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  p)(sqlite3_vfs*,
ed20: 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64   int microsecond
ed30: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72  s);.  int (*xCur
ed40: 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65  rentTime)(sqlite
ed50: 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29  3_vfs*, double*)
ed60: 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61  ;.  int (*xGetLa
ed70: 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33  stError)(sqlite3
ed80: 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72  _vfs*, int, char
ed90: 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54   *);.  /*.  ** T
eda0: 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  he methods above
edb0: 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20   are in version 
edc0: 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f  1 of the sqlite_
edd0: 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20  vfs object.  ** 
ede0: 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f  definition.  Tho
edf0: 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61  se that follow a
ee00: 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 72 73  re added in vers
ee10: 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20  ion 2 or later. 
ee20: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72   */.  int (*xCur
ee30: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73  rentTimeInt64)(s
ee40: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c  qlite3_vfs*, sql
ee50: 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20  ite3_int64*);.  
ee60: 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68  /*.  ** The meth
ee70: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
ee80: 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20   versions 1 and 
ee90: 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f  2 of the sqlite_
eea0: 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a  vfs object..  **
eeb0: 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65   Those below are
eec0: 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61   for version 3 a
eed0: 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f  nd greater..  */
eee0: 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73  .  int (*xSetSys
eef0: 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33  temCall)(sqlite3
ef00: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
ef10: 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65  r *zName, sqlite
ef20: 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a  3_syscall_ptr);.
ef30: 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c    sqlite3_syscal
ef40: 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73 74  l_ptr (*xGetSyst
ef50: 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f  emCall)(sqlite3_
ef60: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
ef70: 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73   *zName);.  cons
ef80: 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53  t char *(*xNextS
ef90: 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74  ystemCall)(sqlit
efa0: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
efb0: 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f  har *zName);.  /
efc0: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
efd0: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
efe0: 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75  versions 1 throu
eff0: 67 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69  gh 3 of the sqli
f000: 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20  te_vfs object.. 
f010: 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d   ** New fields m
f020: 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69  ay be appended i
f030: 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e  n future version
f040: 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e  s.  The iVersion
f050: 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c  .  ** value will
f060: 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65   increment whene
f070: 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73  ver this happens
f080: 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  . .  */.};../*.*
f090: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67  * CAPI3REF: Flag
f0a0: 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73  s for the xAcces
f0b0: 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a  s VFS method.**.
f0c0: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72  ** These integer
f0d0: 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62   constants can b
f0e0: 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68  e used as the th
f0f0: 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
f100: 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20  .** the xAccess 
f110: 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71  method of an [sq
f120: 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
f130: 74 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d 69  t.  They determi
f140: 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20  ne.** what kind 
f150: 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74  of permissions t
f160: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
f170: 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72  d is looking for
f180: 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45  ..** With SQLITE
f190: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20  _ACCESS_EXISTS, 
f1a0: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
f1b0: 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65  od.** simply che
f1c0: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
f1d0: 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20  file exists..** 
f1e0: 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45  With SQLITE_ACCE
f1f0: 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68  SS_READWRITE, th
f200: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
f210: 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68  .** checks wheth
f220: 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72  er the named dir
f230: 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72  ectory is both r
f240: 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74  eadable and writ
f250: 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65  able.** (in othe
f260: 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65  r words, if file
f270: 73 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20  s can be added, 
f280: 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e  removed, and ren
f290: 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74  amed within.** t
f2a0: 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a  he directory)..*
f2b0: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43  * The SQLITE_ACC
f2c0: 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f  ESS_READWRITE co
f2d0: 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e  nstant is curren
f2e0: 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79  tly used only by
f2f0: 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74   the.** [temp_st
f300: 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
f310: 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68  agma], though th
f320: 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20  is could change 
f330: 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72  in a future.** r
f340: 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
f350: 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45  ..** With SQLITE
f360: 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68  _ACCESS_READ, th
f370: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
f380: 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68  .** checks wheth
f390: 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72  er the file is r
f3a0: 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51  eadable.  The SQ
f3b0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
f3c0: 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20   constant is.** 
f3d0: 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64  currently unused
f3e0: 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68  , though it migh
f3f0: 74 20 62 65 20 75 73 65 64 20 69 6e 20 61 20 66  t be used in a f
f400: 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66  uture release of
f410: 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23  .** SQLite..*/.#
f420: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
f430: 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 30  CESS_EXISTS    0
f440: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
f450: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
f460: 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20   1   /* Used by 
f470: 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72  PRAGMA temp_stor
f480: 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23  e_directory */.#
f490: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
f4a0: 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32  CESS_READ      2
f4b0: 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a     /* Unused */.
f4c0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
f4d0: 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78   Flags for the x
f4e0: 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68  ShmLock VFS meth
f4f0: 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69  od.**.** These i
f500: 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
f510: 20 64 65 66 69 6e 65 20 74 68 65 20 76 61 72 69   define the vari
f520: 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72  ous locking oper
f530: 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65  ations.** allowe
f540: 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63  d by the xShmLoc
f550: 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c  k method of [sql
f560: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
f570: 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77  .  The.** follow
f580: 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79  ing are the only
f590: 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69   legal combinati
f5a0: 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20  ons of flags to 
f5b0: 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20  the.** xShmLock 
f5c0: 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  method:.**.** <u
f5d0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  l>.** <li>  SQLI
f5e0: 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51  TE_SHM_LOCK | SQ
f5f0: 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a  LITE_SHM_SHARED.
f600: 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
f610: 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  SHM_LOCK | SQLIT
f620: 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a  E_SHM_EXCLUSIVE.
f630: 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
f640: 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c  SHM_UNLOCK | SQL
f650: 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a  ITE_SHM_SHARED.*
f660: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
f670: 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49  HM_UNLOCK | SQLI
f680: 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
f690: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
f6a0: 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20  When unlocking, 
f6b0: 74 68 65 20 73 61 6d 65 20 53 48 41 52 45 44 20  the same SHARED 
f6c0: 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61  or EXCLUSIVE fla
f6d0: 67 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69  g must be suppli
f6e0: 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76  ed as.** was giv
f6f0: 65 6e 20 6f 6e 20 74 68 65 20 63 6f 72 72 65 73  en on the corres
f700: 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a  ponding lock.  .
f710: 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f  **.** The xShmLo
f720: 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72  ck method can tr
f730: 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e  ansition between
f740: 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48   unlocked and SH
f750: 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65  ARED or.** betwe
f760: 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20  en unlocked and 
f770: 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63  EXCLUSIVE.  It c
f780: 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e  annot transition
f790: 20 62 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a   between SHARED.
f7a0: 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45  ** and EXCLUSIVE
f7b0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
f7c0: 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20  ITE_SHM_UNLOCK  
f7d0: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
f7e0: 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20  QLITE_SHM_LOCK  
f7f0: 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
f800: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52   SQLITE_SHM_SHAR
f810: 45 44 20 20 20 20 20 20 20 34 0a 23 64 65 66 69  ED       4.#defi
f820: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58  ne SQLITE_SHM_EX
f830: 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a  CLUSIVE    8../*
f840: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61  .** CAPI3REF: Ma
f850: 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69  ximum xShmLock i
f860: 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ndex.**.** The x
f870: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f  ShmLock method o
f880: 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  n [sqlite3_io_me
f890: 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76  thods] may use v
f8a0: 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e  alues.** between
f8b0: 20 30 20 61 6e 64 20 74 68 69 73 20 75 70 70 65   0 and this uppe
f8c0: 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22  r bound as its "
f8d0: 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74  offset" argument
f8e0: 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20  ..** The SQLite 
f8f0: 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  core will never 
f900: 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69  attempt to acqui
f910: 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a  re or release a.
f920: 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20  ** lock outside 
f930: 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f  of this range.*/
f940: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
f950: 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20  SHM_NLOCK       
f960: 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   8.../*.** CAPI3
f970: 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20  REF: Initialize 
f980: 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61  The SQLite Libra
f990: 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ry.**.** ^The sq
f9a0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f9b0: 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69  () routine initi
f9c0: 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51  alizes the.** SQ
f9d0: 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e  Lite library.  ^
f9e0: 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74  The sqlite3_shut
f9f0: 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a  down() routine.*
fa00: 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e  * deallocates an
fa10: 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 74  y resources that
fa20: 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20   were allocated 
fa30: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  by sqlite3_initi
fa40: 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73  alize()..** Thes
fa50: 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64  e routines are d
fa60: 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69  esigned to aid i
fa70: 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61  n process initia
fa80: 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20  lization and.** 
fa90: 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65  shutdown on embe
faa0: 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57  dded systems.  W
fab0: 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69  orkstation appli
fac0: 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a  cations using.**
fad0: 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79   SQLite normally
fae0: 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20   do not need to 
faf0: 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66  invoke either of
fb00: 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
fb10: 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f  .**.** A call to
fb20: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
fb30: 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66  ize() is an "eff
fb40: 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20  ective" call if 
fb50: 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72  it is.** the fir
fb60: 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f  st time sqlite3_
fb70: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
fb80: 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74  invoked during t
fb90: 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a  he lifetime of.*
fba0: 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f  * the process, o
fbb0: 72 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66  r if it is the f
fbc0: 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65  irst time sqlite
fbd0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
fbe0: 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c  s invoked.** fol
fbf0: 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f  lowing a call to
fc00: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
fc10: 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20  n().  ^(Only an 
fc20: 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a  effective call.*
fc30: 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69  * of sqlite3_ini
fc40: 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61  tialize() does a
fc50: 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ny initializatio
fc60: 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61  n.  All other ca
fc70: 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c  lls.** are harml
fc80: 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a  ess no-ops.)^.**
fc90: 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71  .** A call to sq
fca0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
fcb0: 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76   is an "effectiv
fcc0: 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73  e" call if it is
fcd0: 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61   the first.** ca
fce0: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
fcf0: 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74  utdown() since t
fd00: 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f  he last sqlite3_
fd10: 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e  initialize().  ^
fd20: 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65  (Only.** an effe
fd30: 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71  ctive call to sq
fd40: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
fd50: 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74   does any deinit
fd60: 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41  ialization..** A
fd70: 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63  ll other valid c
fd80: 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
fd90: 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68  shutdown() are h
fda0: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29  armless no-ops.)
fdb0: 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ^.**.** The sqli
fdc0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
fdd0: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68   interface is th
fde0: 72 65 61 64 73 61 66 65 2c 20 62 75 74 20 73 71  readsafe, but sq
fdf0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
fe00: 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65  .** is not.  The
fe10: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
fe20: 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75  n() interface mu
fe30: 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65  st only be calle
fe40: 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67  d from a.** sing
fe50: 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20  le thread.  All 
fe60: 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63  open [database c
fe70: 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74  onnections] must
fe80: 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61   be closed and a
fe90: 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69  ll.** other SQLi
fea0: 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73  te resources mus
feb0: 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  t be deallocated
fec0: 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69   prior to invoki
fed0: 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68  ng.** sqlite3_sh
fee0: 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20  utdown()..**.** 
fef0: 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e  Among other thin
ff00: 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69  gs, ^sqlite3_ini
ff10: 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69  tialize() will i
ff20: 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33  nvoke.** sqlite3
ff30: 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d  _os_init().  Sim
ff40: 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33  ilarly, ^sqlite3
ff50: 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77  _shutdown().** w
ff60: 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  ill invoke sqlit
ff70: 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a  e3_os_end()..**.
ff80: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
ff90: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
ffa0: 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51  tine returns [SQ
ffb0: 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
ffc0: 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20  ess..** ^If for 
ffd0: 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c  some reason, sql
ffe0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
fff0: 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69  ) is unable to i
10000 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65  nitialize.** the
10010 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 70   library (perhap
10020 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74  s it is unable t
10030 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65  o allocate a nee
10040 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 63  ded resource suc
10050 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29  h.** as a mutex)
10060 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b   it returns an [
10070 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65  error code] othe
10080 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f  r than [SQLITE_O
10090 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  K]..**.** ^The s
100a0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
100b0 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63  e() routine is c
100c0 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  alled internally
100d0 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a   by many other.*
100e0 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  * SQLite interfa
100f0 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61  ces so that an a
10100 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c  pplication usual
10110 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  ly does not need
10120 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71   to.** invoke sq
10130 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
10140 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f  () directly.  Fo
10150 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69  r example, [sqli
10160 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63  te3_open()].** c
10170 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69  alls sqlite3_ini
10180 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65  tialize() so the
10190 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20   SQLite library 
101a0 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69  will be automati
101b0 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c  cally.** initial
101c0 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74  ized when [sqlit
101d0 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61  e3_open()] is ca
101e0 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 6e  lled if it has n
101f0 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65  ot be initialize
10200 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e  d.** already.  ^
10210 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69  However, if SQLi
10220 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
10230 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ith the [SQLITE_
10240 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a  OMIT_AUTOINIT].*
10250 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  * compile-time o
10260 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20  ption, then the 
10270 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20  automatic calls 
10280 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  to sqlite3_initi
10290 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f  alize().** are o
102a0 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 61  mitted and the a
102b0 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
102c0 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69  call sqlite3_ini
102d0 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74  tialize() direct
102e0 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75  ly.** prior to u
102f0 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53  sing any other S
10300 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
10310 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f    For maximum po
10320 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74  rtability,.** it
10330 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
10340 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  that application
10350 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20  s always invoke 
10360 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
10370 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79  ze().** directly
10380 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20   prior to using 
10390 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65  any other SQLite
103a0 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74   interface.  Fut
103b0 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20  ure releases.** 
103c0 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65  of SQLite may re
103d0 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20  quire this.  In 
103e0 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65  other words, the
103f0 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 69   behavior exhibi
10400 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69  ted.** when SQLi
10410 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
10420 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  ith [SQLITE_OMIT
10430 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74  _AUTOINIT] might
10440 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64   become the.** d
10450 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20  efault behavior 
10460 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72  in some future r
10470 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
10480 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
10490 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f  te3_os_init() ro
104a0 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61  utine does opera
104b0 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63  ting-system spec
104c0 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69  ific.** initiali
104d0 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51  zation of the SQ
104e0 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54  Lite library.  T
104f0 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  he sqlite3_os_en
10500 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75  d().** routine u
10510 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74  ndoes the effect
10520 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69   of sqlite3_os_i
10530 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20  nit().  Typical 
10540 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d  tasks.** perform
10550 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 74  ed by these rout
10560 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c  ines include all
10570 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c  ocation or deall
10580 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74  ocation.** of st
10590 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20  atic resources, 
105a0 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f  initialization o
105b0 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c  f global variabl
105c0 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75  es,.** setting u
105d0 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  p a default [sql
105e0 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65  ite3_vfs] module
105f0 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a  , or setting up.
10600 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e  ** a default con
10610 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67  figuration using
10620 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
10630 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  ()]..**.** The a
10640 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
10650 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65  d never invoke e
10660 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73  ither sqlite3_os
10670 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71  _init().** or sq
10680 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64  lite3_os_end() d
10690 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70  irectly.  The ap
106a0 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
106b0 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20   only invoke.** 
106c0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
106d0 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  ze() and sqlite3
106e0 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68  _shutdown().  Th
106f0 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  e sqlite3_os_ini
10700 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  t().** interface
10710 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d   is called autom
10720 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69  atically by sqli
10730 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
10740 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   and.** sqlite3_
10750 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c  os_end() is call
10760 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68  ed by sqlite3_sh
10770 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f  utdown().  Appro
10780 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d  priate.** implem
10790 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71  entations for sq
107a0 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
107b0 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  and sqlite3_os_e
107c0 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c  nd().** are buil
107d0 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68  t into SQLite wh
107e0 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65  en it is compile
107f0 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64  d for Unix, Wind
10800 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a  ows, or OS/2..**
10810 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75   When [custom bu
10820 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72  ilds | built for
10830 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73   other platforms
10840 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20  ].** (using the 
10850 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52  [SQLITE_OS_OTHER
10860 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =1] compile-time
10870 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20  .** option) the 
10880 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
10890 20 73 75 70 70 6c 79 20 61 20 73 75 69 74 61 62   supply a suitab
108a0 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
108b0 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  n for.** sqlite3
108c0 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73  _os_init() and s
108d0 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e  qlite3_os_end().
108e0 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e    An application
108f0 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70  -supplied.** imp
10900 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73  lementation of s
10910 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
10920 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65   or sqlite3_os_e
10930 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74  nd().** must ret
10940 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
10950 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 73  on success and s
10960 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72  ome other [error
10970 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66   code] upon.** f
10980 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73  ailure..*/.int s
10990 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
109a0 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  e(void);.int sql
109b0 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f  ite3_shutdown(vo
109c0 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  id);.int sqlite3
109d0 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a  _os_init(void);.
109e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  int sqlite3_os_e
109f0 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a  nd(void);../*.**
10a00 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
10a10 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74  guring The SQLit
10a20 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20  e Library.**.** 
10a30 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  The sqlite3_conf
10a40 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ig() interface i
10a50 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67  s used to make g
10a60 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74  lobal configurat
10a70 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74  ion.** changes t
10a80 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65  o SQLite in orde
10a90 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65  r to tune SQLite
10aa0 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63   to the specific
10ab0 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65   needs of.** the
10ac0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54   application.  T
10ad0 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69  he default confi
10ae0 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f  guration is reco
10af0 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74  mmended for most
10b00 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  .** applications
10b10 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75   and so this rou
10b20 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20  tine is usually 
10b30 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20  not necessary.  
10b40 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65  It is.** provide
10b50 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72  d to support rar
10b60 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77  e applications w
10b70 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64  ith unusual need
10b80 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 54 68 65 20  s..**.** <b>The 
10b90 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
10ba0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f   interface is no
10bb0 74 20 74 68 72 65 61 64 73 61 66 65 2e 20 54 68  t threadsafe. Th
10bc0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a  e application.**
10bd0 20 6d 75 73 74 20 65 6e 73 75 72 65 20 74 68 61   must ensure tha
10be0 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74  t no other SQLit
10bf0 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  e interfaces are
10c00 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65   invoked by othe
10c10 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69  r.** threads whi
10c20 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  le sqlite3_confi
10c30 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 3c  g() is running.<
10c40 2f 62 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  /b>.**.** The sq
10c50 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
10c60 6e 74 65 72 66 61 63 65 0a 2a 2a 20 6d 61 79 20  nterface.** may 
10c70 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20  only be invoked 
10c80 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79  prior to library
10c90 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
10ca0 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
10cb0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20  3_initialize()] 
10cc0 6f 72 20 61 66 74 65 72 20 73 68 75 74 64 6f 77  or after shutdow
10cd0 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68  n by [sqlite3_sh
10ce0 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49  utdown()]..** ^I
10cf0 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  f sqlite3_config
10d00 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74  () is called aft
10d10 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74  er [sqlite3_init
10d20 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65  ialize()] and be
10d30 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  fore.** [sqlite3
10d40 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65  _shutdown()] the
10d50 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e  n it will return
10d60 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a   SQLITE_MISUSE..
10d70 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72  ** Note, however
10d80 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f  , that ^sqlite3_
10d90 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20  config() can be 
10da0 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f  called as part o
10db0 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  f the.** impleme
10dc0 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70  ntation of an ap
10dd0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
10de0 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  d [sqlite3_os_in
10df0 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  it()]..**.** The
10e00 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
10e10 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  to sqlite3_confi
10e20 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65  g() is an intege
10e30 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74  r.** [configurat
10e40 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74  ion option] that
10e50 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77   determines.** w
10e60 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20  hat property of 
10e70 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20  SQLite is to be 
10e80 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62  configured.  Sub
10e90 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74  sequent argument
10ea0 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64  s.** vary depend
10eb0 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66  ing on the [conf
10ec0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
10ed0 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73  ].** in the firs
10ee0 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  t argument..**.*
10ef0 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67  * ^When a config
10f00 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69  uration option i
10f10 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63  s set, sqlite3_c
10f20 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73 20  onfig() returns 
10f30 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20  [SQLITE_OK]..** 
10f40 5e 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69  ^If the option i
10f50 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c  s unknown or SQL
10f60 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ite is unable to
10f70 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a   set the option.
10f80 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75  ** then this rou
10f90 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e  tine returns a n
10fa0 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
10fb0 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ode]..*/.int sql
10fc0 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c  ite3_config(int,
10fd0 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   ...);../*.** CA
10fe0 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
10ff0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
11000 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44  ctions.** METHOD
11010 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
11020 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63  The sqlite3_db_c
11030 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
11040 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b  e is used to mak
11050 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a  e configuration.
11060 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20  ** changes to a 
11070 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
11080 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65  tion].  The inte
11090 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72  rface is similar
110a0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
110b0 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74  config()] except
110c0 20 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65   that the change
110d0 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e  s apply to a sin
110e0 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  gle.** [database
110f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70   connection] (sp
11100 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66  ecified in the f
11110 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a  irst argument)..
11120 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
11130 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
11140 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44  ite3_db_config(D
11150 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a  ,V,...)  is the.
11160 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ** [SQLITE_DBCON
11170 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20  FIG_LOOKASIDE | 
11180 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65  configuration ve
11190 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72  rb] - an integer
111a0 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69   code .** that i
111b0 6e 64 69 63 61 74 65 73 20 77 68 61 74 20 61 73  ndicates what as
111c0 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74  pect of the [dat
111d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
111e0 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69  ] is being confi
111f0 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71  gured..** Subseq
11200 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76  uent arguments v
11210 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ary depending on
11220 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
11230 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e  on verb..**.** ^
11240 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  Calls to sqlite3
11250 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74  _db_config() ret
11260 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66  urn SQLITE_OK if
11270 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
11280 74 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73  the call is cons
11290 69 64 65 72 65 64 20 73 75 63 63 65 73 73 66 75  idered successfu
112a0 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l..*/.int sqlite
112b0 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69  3_db_config(sqli
112c0 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e  te3*, int op, ..
112d0 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
112e0 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f  REF: Memory Allo
112f0 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a  cation Routines.
11300 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
11310 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
11320 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74   defines the int
11330 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53  erface between S
11340 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77  QLite.** and low
11350 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c  -level memory al
11360 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
11370 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62  s..**.** This ob
11380 6a 65 63 74 20 69 73 20 75 73 65 64 20 69 6e 20  ject is used in 
11390 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69  only one place i
113a0 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74  n the SQLite int
113b0 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69  erface..** A poi
113c0 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
113d0 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
113e0 63 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65  ct is the argume
113f0 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  nt to.** [sqlite
11400 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e  3_config()] when
11410 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
11420 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20  on option is.** 
11430 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
11440 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54  ALLOC] or [SQLIT
11450 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
11460 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65  OC].  .** By cre
11470 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63  ating an instanc
11480 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
11490 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20  .** and passing 
114a0 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  it to [sqlite3_c
114b0 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43  onfig]([SQLITE_C
114c0 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a  ONFIG_MALLOC]).*
114d0 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75  * during configu
114e0 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69  ration, an appli
114f0 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69  cation can speci
11500 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76  fy an alternativ
11510 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  e.** memory allo
11520 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d  cation subsystem
11530 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75   for SQLite to u
11540 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  se for all of it
11550 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d  s.** dynamic mem
11560 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a  ory needs..**.**
11570 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74   Note that SQLit
11580 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76  e comes with sev
11590 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d  eral [built-in m
115a0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73  emory allocators
115b0 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65  ].** that are pe
115c0 72 66 65 63 74 6c 79 20 61 64 65 71 75 61 74 65  rfectly adequate
115d0 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65   for the overwhe
115e0 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f  lming majority o
115f0 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  f applications.*
11600 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20  * and that this 
11610 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75  object is only u
11620 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20  seful to a tiny 
11630 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c  minority of appl
11640 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68  ications.** with
11650 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d   specialized mem
11660 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
11670 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68  equirements.  Th
11680 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20  is object is.** 
11690 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67  also used during
116a0 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69   testing of SQLi
116b0 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73  te in order to s
116c0 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e  pecify an altern
116d0 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ative.** memory 
116e0 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73  allocator that s
116f0 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20  imulates memory 
11700 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f  out-of-memory co
11710 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f  nditions in.** o
11720 72 64 65 72 20 74 6f 20 76 65 72 69 66 79 20 74  rder to verify t
11730 68 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76  hat SQLite recov
11740 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66  ers gracefully f
11750 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64  rom such.** cond
11760 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  itions..**.** Th
11770 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c  e xMalloc, xReal
11780 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65 65 20 6d  loc, and xFree m
11790 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b  ethods must work
117a0 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c   like the.** mal
117b0 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29  loc(), realloc()
117c0 20 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63   and free() func
117d0 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73  tions from the s
117e0 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
117f0 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75  y..** ^SQLite gu
11800 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
11810 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
11820 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63  t to.** xRealloc
11830 20 69 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c   is always a val
11840 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 61  ue returned by a
11850 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78   prior call to x
11860 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78  Roundup..**.** x
11870 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75  Size should retu
11880 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64  rn the allocated
11890 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72   size of a memor
118a0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
118b0 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69  previously obtai
118c0 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63  ned from xMalloc
118d0 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54   or xRealloc.  T
118e0 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
118f0 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61  e.** is always a
11900 74 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61  t least as big a
11910 73 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20  s the requested 
11920 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20  size but may be 
11930 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  larger..**.** Th
11940 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f  e xRoundup metho
11950 64 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 77  d returns what w
11960 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f  ould be the allo
11970 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a  cated size of.**
11980 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
11990 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72  tion given a par
119a0 74 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 65  ticular requeste
119b0 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65  d size.  Most me
119c0 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f  mory.** allocato
119d0 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f  rs round up memo
119e0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61  ry allocations a
119f0 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e  t least to the n
11a00 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20  ext multiple.** 
11a10 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f  of 8.  Some allo
11a20 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
11a30 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74  to a larger mult
11a40 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77  iple or to a pow
11a50 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72  er of 2..** Ever
11a60 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  y memory allocat
11a70 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69  ion request comi
11a80 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73  ng in through [s
11a90 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
11aa0 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
11ab0 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74  realloc()] first
11ac0 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e   calls xRoundup.
11ad0 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65    If xRoundup re
11ae0 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61  turns 0, .** tha
11af0 74 20 63 61 75 73 65 73 20 74 68 65 20 63 6f 72  t causes the cor
11b00 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72  responding memor
11b10 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20  y allocation to 
11b20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fail..**.** The 
11b30 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69  xInit method ini
11b40 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d  tializes the mem
11b50 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20  ory allocator.  
11b60 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20  For example,.** 
11b70 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74  it might allocat
11b80 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75  e any require mu
11b90 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c  texes or initial
11ba0 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  ize internal dat
11bb0 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e  a.** structures.
11bc0 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20    The xShutdown 
11bd0 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65  method is invoke
11be0 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62  d (indirectly) b
11bf0 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68  y.** [sqlite3_sh
11c00 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68  utdown()] and sh
11c10 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20  ould deallocate 
11c20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61 63  any resources ac
11c30 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e  quired.** by xIn
11c40 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 61 74  it.  The pAppDat
11c50 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65  a pointer is use
11c60 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61  d as the only pa
11c70 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49  rameter to.** xI
11c80 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77  nit and xShutdow
11c90 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  n..**.** SQLite 
11ca0 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54  holds the [SQLIT
11cb0 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d  E_MUTEX_STATIC_M
11cc0 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68 65  ASTER] mutex whe
11cd0 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20  n it invokes.** 
11ce0 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64  the xInit method
11cf0 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20 6d  , so the xInit m
11d00 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62  ethod need not b
11d10 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54  e threadsafe.  T
11d20 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20  he.** xShutdown 
11d30 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63  method is only c
11d40 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  alled from [sqli
11d50 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20  te3_shutdown()] 
11d60 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f  so it does.** no
11d70 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68 72  t need to be thr
11d80 65 61 64 73 61 66 65 20 65 69 74 68 65 72 2e 20  eadsafe either. 
11d90 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d   For all other m
11da0 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a  ethods, SQLite.*
11db0 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c  * holds the [SQL
11dc0 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
11dd0 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c  _MEM] mutex as l
11de0 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53  ong as the.** [S
11df0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
11e00 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 72  STATUS] configur
11e10 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20  ation option is 
11e20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 68  turned on (which
11e30 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65 66  .** it is by def
11e40 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 65  ault) and so the
11e50 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75 74   methods are aut
11e60 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69 61  omatically seria
11e70 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65  lized..** Howeve
11e80 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f  r, if [SQLITE_CO
11e90 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20  NFIG_MEMSTATUS] 
11ea0 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65  is disabled, the
11eb0 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d  n the other.** m
11ec0 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20 74  ethods must be t
11ed0 68 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c 73  hreadsafe or els
11ee0 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 6e  e make their own
11ef0 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f   arrangements fo
11f00 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 69  r.** serializati
11f10 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  on..**.** SQLite
11f20 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f   will never invo
11f30 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 20  ke xInit() more 
11f40 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75  than once withou
11f50 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67  t an intervening
11f60 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 75  .** call to xShu
11f70 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65  tdown()..*/.type
11f80 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
11f90 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73  e3_mem_methods s
11fa0 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
11fb0 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  ds;.struct sqlit
11fc0 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b  e3_mem_methods {
11fd0 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c  .  void *(*xMall
11fe0 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20  oc)(int);       
11ff0 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f    /* Memory allo
12000 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20  cation function 
12010 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65  */.  void (*xFre
12020 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  e)(void*);      
12030 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72      /* Free a pr
12040 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a  ior allocation *
12050 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61  /.  void *(*xRea
12060 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29  lloc)(void*,int)
12070 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20  ;  /* Resize an 
12080 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20  allocation */.  
12090 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69  int (*xSize)(voi
120a0 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f  d*);           /
120b0 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a  * Return the siz
120c0 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69  e of an allocati
120d0 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52  on */.  int (*xR
120e0 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20  oundup)(int);   
120f0 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20         /* Round 
12100 75 70 20 72 65 71 75 65 73 74 20 73 69 7a 65 20  up request size 
12110 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  to allocation si
12120 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49  ze */.  int (*xI
12130 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  nit)(void*);    
12140 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61         /* Initia
12150 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  lize the memory 
12160 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76  allocator */.  v
12170 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29  oid (*xShutdown)
12180 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a  (void*);      /*
12190 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68   Deinitialize th
121a0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
121b0 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41  or */.  void *pA
121c0 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20  ppData;         
121d0 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65         /* Argume
121e0 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e  nt to xInit() an
121f0 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f  d xShutdown() */
12200 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
12210 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69  REF: Configurati
12220 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45  on Options.** KE
12230 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75  YWORDS: {configu
12240 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a  ration option}.*
12250 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
12260 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61  ants are the ava
12270 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63  ilable integer c
12280 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
12290 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e  ions that.** can
122a0 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
122b0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
122c0 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
122d0 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
122e0 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  face..**.** New 
122f0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
12300 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64  tions may be add
12310 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
12320 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
12330 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e  .** Existing con
12340 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
12350 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63  ns might be disc
12360 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69  ontinued.  Appli
12370 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
12380 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  d check the retu
12390 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71  rn code from [sq
123a0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
123b0 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  to make sure tha
123c0 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f  t.** the call wo
123d0 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69  rked.  The [sqli
123e0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  te3_config()] in
123f0 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74  terface will ret
12400 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72  urn a.** non-zer
12410 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  o [error code] i
12420 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64  f a discontinued
12430 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20   or unsupported 
12440 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
12450 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b  tion.** is invok
12460 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  ed..**.** <dl>.*
12470 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
12480 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d  G_SINGLETHREAD]]
12490 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
124a0 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c  IG_SINGLETHREAD<
124b0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
124c0 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
124d0 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
124e0 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  n.  ^This option
124f0 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68   sets the.** [th
12500 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f  reading mode] to
12510 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20   Single-thread. 
12520 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
12530 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20   it disables.** 
12540 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64  all mutexing and
12550 20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74   puts SQLite int
12560 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69  o a mode where i
12570 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73  t can only be us
12580 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c  ed.** by a singl
12590 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20  e thread.   ^If 
125a0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
125b0 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
125c0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
125d0 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
125e0 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
125f0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
12600 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70  n.** it is not p
12610 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67  ossible to chang
12620 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67  e the [threading
12630 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20   mode] from its 
12640 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65  default.** value
12650 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61   of Single-threa
12660 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65  d and so [sqlite
12670 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c  3_config()] will
12680 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c   return .** [SQL
12690 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61  ITE_ERROR] if ca
126a0 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51  lled with the SQ
126b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
126c0 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66  LETHREAD.** conf
126d0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
126e0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
126f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
12700 54 49 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53  TITHREAD]] <dt>S
12710 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
12720 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a  TITHREAD</dt>.**
12730 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
12740 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
12750 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
12760 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
12770 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
12780 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d   mode] to Multi-
12790 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65  thread.  In othe
127a0 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61  r words, it disa
127b0 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67  bles.** mutexing
127c0 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
127d0 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70  nnection] and [p
127e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
127f0 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54  t] objects..** T
12800 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  he application i
12810 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
12820 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63  r serializing ac
12830 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61  cess to.** [data
12840 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
12850 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
12860 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75  statements].  Bu
12870 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a  t other mutexes.
12880 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73  ** are enabled s
12890 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  o that SQLite wi
128a0 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 73  ll be safe to us
128b0 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72  e in a multi-thr
128c0 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e  eaded.** environ
128d0 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20  ment as long as 
128e0 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 61  no two threads a
128f0 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68  ttempt to use th
12900 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62  e same.** [datab
12910 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
12920 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
12930 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73  .  ^If SQLite is
12940 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
12950 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
12960 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
12970 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
12980 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
12990 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69  ion then.** it i
129a0 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74  s not possible t
129b0 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d  o set the Multi-
129c0 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e  thread [threadin
129d0 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b  g mode] and.** [
129e0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
129f0 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  ] will return [S
12a00 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
12a10 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a  called with the.
12a20 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ** SQLITE_CONFIG
12a30 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e  _MULTITHREAD con
12a40 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
12a50 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  n.</dd>.**.** [[
12a60 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
12a70 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53  RIALIZED]] <dt>S
12a80 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
12a90 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20  IALIZED</dt>.** 
12aa0 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f  <dd>There are no
12ab0 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
12ac0 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69  is option.  ^Thi
12ad0 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68  s option sets th
12ae0 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20  e.** [threading 
12af0 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69  mode] to Seriali
12b00 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f  zed. In other wo
12b10 72 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e  rds, this option
12b20 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20   enables.** all 
12b30 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e  mutexes includin
12b40 67 20 74 68 65 20 72 65 63 75 72 73 69 76 65 0a  g the recursive.
12b50 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64  ** mutexes on [d
12b60 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
12b70 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  on] and [prepare
12b80 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a  d statement] obj
12b90 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73  ects..** In this
12ba0 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73 20   mode (which is 
12bb0 74 68 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e  the default when
12bc0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
12bd0 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c  led with.** [SQL
12be0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31  ITE_THREADSAFE=1
12bf0 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  ]) the SQLite li
12c00 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c  brary will itsel
12c10 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65  f serialize acce
12c20 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61  ss.** to [databa
12c30 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
12c40 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
12c50 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61  atements] so tha
12c60 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61  t the.** applica
12c70 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20  tion is free to 
12c80 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61  use the same [da
12c90 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
12ca0 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d  n] or the.** sam
12cb0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
12cc0 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72  ement] in differ
12cd0 65 6e 74 20 74 68 72 65 61 64 73 20 61 74 20 74  ent threads at t
12ce0 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a  he same time..**
12cf0 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
12d00 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
12d10 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
12d20 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
12d30 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
12d40 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
12d50 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20  n then.** it is 
12d60 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
12d70 73 65 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a  set the Serializ
12d80 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ed [threading mo
12d90 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  de] and.** [sqli
12da0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
12db0 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
12dc0 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c  E_ERROR] if call
12dd0 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53  ed with the.** S
12de0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
12df0 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72  IALIZED configur
12e00 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64  ation option.</d
12e10 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
12e20 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
12e30 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
12e40 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a  FIG_MALLOC</dt>.
12e50 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51  ** <dd> ^(The SQ
12e60 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
12e70 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  OC option takes 
12e80 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
12e90 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 61  t which is .** a
12ea0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
12eb0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
12ec0 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
12ed0 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a  ods] structure..
12ee0 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  ** The argument 
12ef0 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74  specifies.** alt
12f00 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76  ernative low-lev
12f10 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  el memory alloca
12f20 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f  tion routines to
12f30 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63   be used in plac
12f40 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f  e of.** the memo
12f50 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
12f60 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74  utines built int
12f70 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c  o SQLite.)^ ^SQL
12f80 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73  ite makes.** its
12f90 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70   own private cop
12fa0 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74  y of the content
12fb0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
12fc0 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
12fd0 72 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72  ructure.** befor
12fe0 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  e the [sqlite3_c
12ff0 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65  onfig()] call re
13000 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  turns.</dd>.**.*
13010 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
13020 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64  G_GETMALLOC]] <d
13030 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
13040 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a  GETMALLOC</dt>.*
13050 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c  * <dd> ^(The SQL
13060 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
13070 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65  LLOC option take
13080 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
13090 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ent which.** is 
130a0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
130b0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
130c0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
130d0 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
130e0 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
130f0 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  _mem_methods].**
13100 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69   structure is fi
13110 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75  lled with the cu
13120 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20  rrently defined 
13130 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
13140 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a  n routines.)^.**
13150 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e   This option can
13160 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72   be used to over
13170 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74  load the default
13180 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
13190 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77  on.** routines w
131a0 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74 68  ith a wrapper th
131b0 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d  at simulations m
131c0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
131d0 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74   failure or.** t
131e0 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61  racks memory usa
131f0 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e  ge, for example.
13200 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
13210 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
13220 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c  STATUS]] <dt>SQL
13230 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
13240 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATUS</dt>.** <dd
13250 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  > ^The SQLITE_CO
13260 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 6f  NFIG_MEMSTATUS o
13270 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67  ption takes sing
13280 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74  le argument of t
13290 79 70 65 20 69 6e 74 2c 0a 2a 2a 20 69 6e 74 65  ype int,.** inte
132a0 72 70 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f  rpreted as a boo
132b0 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62  lean, which enab
132c0 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
132d0 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f  the collection o
132e0 66 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  f.** memory allo
132f0 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
13300 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79  s. ^(When memory
13310 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74   allocation stat
13320 69 73 74 69 63 73 20 61 72 65 0a 2a 2a 20 64 69  istics are.** di
13330 73 61 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c 6c  sabled, the foll
13340 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74  owing SQLite int
13350 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e  erfaces become n
13360 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a  on-operational:.
13370 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c  **   <ul>.**   <
13380 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  li> [sqlite3_mem
13390 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20  ory_used()].**  
133a0 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d   <li> [sqlite3_m
133b0 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
133c0 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  )].**   <li> [sq
133d0 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f  lite3_soft_heap_
133e0 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20  limit64()].**   
133f0 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74  <li> [sqlite3_st
13400 61 74 75 73 36 34 28 29 5d 0a 2a 2a 20 20 20 3c  atus64()].**   <
13410 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72  /ul>)^.** ^Memor
13420 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  y allocation sta
13430 74 69 73 74 69 63 73 20 61 72 65 20 65 6e 61 62  tistics are enab
13440 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 75  led by default u
13450 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a  nless SQLite is.
13460 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  ** compiled with
13470 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54   [SQLITE_DEFAULT
13480 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e  _MEMSTATUS]=0 in
13490 20 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f   which case memo
134a0 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  ry.** allocation
134b0 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20   statistics are 
134c0 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
134d0 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ult..** </dd>.**
134e0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
134f0 46 49 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64  FIG_SCRATCH]] <d
13500 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
13510 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20  SCRATCH</dt>.** 
13520 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45  <dd> ^The SQLITE
13530 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20  _CONFIG_SCRATCH 
13540 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73  option specifies
13550 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79   a static memory
13560 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20   buffer.** that 
13570 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66  SQLite can use f
13580 6f 72 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72  or scratch memor
13590 79 2e 20 20 5e 28 54 68 65 72 65 20 61 72 65 20  y.  ^(There are 
135a0 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 0a  three arguments.
135b0 2a 2a 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e  ** to SQLITE_CON
135c0 46 49 47 5f 53 43 52 41 54 43 48 3a 20 20 41 20  FIG_SCRATCH:  A 
135d0 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79 74  pointer an 8-byt
135e0 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d  e.** aligned mem
135f0 6f 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d 20  ory buffer from 
13600 77 68 69 63 68 20 74 68 65 20 73 63 72 61 74 63  which the scratc
13610 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69  h allocations wi
13620 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20  ll be.** drawn, 
13630 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68  the size of each
13640 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
13650 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64  ion (sz),.** and
13660 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   the maximum num
13670 62 65 72 20 6f 66 20 73 63 72 61 74 63 68 20 61  ber of scratch a
13680 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e 29  llocations (N).)
13690 5e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ^.** The first a
136a0 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20  rgument must be 
136b0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
136c0 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62  8-byte aligned b
136d0 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c  uffer.** of at l
136e0 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20  east sz*N bytes 
136f0 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53  of memory..** ^S
13700 51 4c 69 74 65 20 77 69 6c 6c 20 6e 6f 74 20 75  QLite will not u
13710 73 65 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65  se more than one
13720 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 73   scratch buffers
13730 20 70 65 72 20 74 68 72 65 61 64 2e 0a 2a 2a 20   per thread..** 
13740 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76  ^SQLite will nev
13750 65 72 20 72 65 71 75 65 73 74 20 61 20 73 63 72  er request a scr
13760 61 74 63 68 20 62 75 66 66 65 72 20 74 68 61 74  atch buffer that
13770 20 69 73 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a   is more than 6.
13780 2a 2a 20 74 69 6d 65 73 20 74 68 65 20 64 61 74  ** times the dat
13790 61 62 61 73 65 20 70 61 67 65 20 73 69 7a 65 2e  abase page size.
137a0 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 6e  .** ^If SQLite n
137b0 65 65 64 73 20 6e 65 65 64 73 20 61 64 64 69 74  eeds needs addit
137c0 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68  ional.** scratch
137d0 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77   memory beyond w
137e0 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20  hat is provided 
137f0 62 79 20 74 68 69 73 20 63 6f 6e 66 69 67 75 72  by this configur
13800 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68  ation option, th
13810 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  en .** [sqlite3_
13820 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62  malloc()] will b
13830 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  e used to obtain
13840 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64   the memory need
13850 65 64 2e 3c 70 3e 0a 2a 2a 20 5e 57 68 65 6e 20  ed.<p>.** ^When 
13860 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
13870 70 72 6f 76 69 64 65 73 20 61 6e 79 20 61 6d 6f  provides any amo
13880 75 6e 74 20 6f 66 20 73 63 72 61 74 63 68 20 6d  unt of scratch m
13890 65 6d 6f 72 79 20 75 73 69 6e 67 0a 2a 2a 20 53  emory using.** S
138a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
138b0 41 54 43 48 2c 20 53 51 4c 69 74 65 20 61 76 6f  ATCH, SQLite avo
138c0 69 64 73 20 75 6e 6e 65 63 65 73 73 61 72 79 20  ids unnecessary 
138d0 6c 61 72 67 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  large.** [sqlite
138e0 33 5f 6d 61 6c 6c 6f 63 7c 68 65 61 70 20 61 6c  3_malloc|heap al
138f0 6c 6f 63 61 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54  locations]..** T
13900 68 69 73 20 63 61 6e 20 68 65 6c 70 20 5b 52 6f  his can help [Ro
13910 62 73 6f 6e 20 70 72 6f 6f 66 7c 70 72 65 76 65  bson proof|preve
13920 6e 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  nt memory alloca
13930 74 69 6f 6e 20 66 61 69 6c 75 72 65 73 5d 20 64  tion failures] d
13940 75 65 20 74 6f 20 68 65 61 70 0a 2a 2a 20 66 72  ue to heap.** fr
13950 61 67 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 20 6c  agmentation in l
13960 6f 77 2d 6d 65 6d 6f 72 79 20 65 6d 62 65 64 64  ow-memory embedd
13970 65 64 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 20 3c  ed systems..** <
13980 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
13990 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
139a0 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  ACHE]] <dt>SQLIT
139b0 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
139c0 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  HE</dt>.** <dd> 
139d0 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
139e0 49 47 5f 50 41 47 45 43 41 43 48 45 20 6f 70 74  IG_PAGECACHE opt
139f0 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20  ion specifies a 
13a00 6d 65 6d 6f 72 79 20 70 6f 6f 6c 0a 2a 2a 20 74  memory pool.** t
13a10 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75  hat SQLite can u
13a20 73 65 20 66 6f 72 20 74 68 65 20 64 61 74 61 62  se for the datab
13a30 61 73 65 20 70 61 67 65 20 63 61 63 68 65 20 77  ase page cache w
13a40 69 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 20  ith the default 
13a50 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d  page.** cache im
13a60 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a  plementation.  .
13a70 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72  ** This configur
13a80 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20  ation option is 
13a90 61 20 6e 6f 2d 6f 70 20 69 66 20 61 6e 20 61 70  a no-op if an ap
13aa0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
13ab0 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69   page.** cache i
13ac0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73  mplementation is
13ad0 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68   loaded using th
13ae0 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  e [SQLITE_CONFIG
13af0 5f 50 43 41 43 48 45 32 5d 2e 0a 2a 2a 20 5e 54  _PCACHE2]..** ^T
13b00 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
13b10 72 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49  rguments to SQLI
13b20 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
13b30 43 48 45 3a 20 41 20 70 6f 69 6e 74 65 72 20 74  CHE: A pointer t
13b40 6f 0a 2a 2a 20 38 2d 62 79 74 65 20 61 6c 69 67  o.** 8-byte alig
13b50 6e 65 64 20 6d 65 6d 6f 72 79 20 28 70 4d 65 6d  ned memory (pMem
13b60 29 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65  ), the size of e
13b70 61 63 68 20 70 61 67 65 20 63 61 63 68 65 20 6c  ach page cache l
13b80 69 6e 65 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64  ine (sz),.** and
13b90 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
13ba0 61 63 68 65 20 6c 69 6e 65 73 20 28 4e 29 2e 0a  ache lines (N)..
13bb0 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65  ** The sz argume
13bc0 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65  nt should be the
13bd0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72   size of the lar
13be0 67 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61  gest database pa
13bf0 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f  ge.** (a power o
13c00 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31  f two between 51
13c10 32 20 61 6e 64 20 36 35 35 33 36 29 20 70 6c 75  2 and 65536) plu
13c20 73 20 73 6f 6d 65 20 65 78 74 72 61 20 62 79 74  s some extra byt
13c30 65 73 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70  es for each.** p
13c40 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68  age header.  ^Th
13c50 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72  e number of extr
13c60 61 20 62 79 74 65 73 20 6e 65 65 64 65 64 20 62  a bytes needed b
13c70 79 20 74 68 65 20 70 61 67 65 20 68 65 61 64 65  y the page heade
13c80 72 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65  r.** can be dete
13c90 72 6d 69 6e 65 64 20 75 73 69 6e 67 20 5b 53 51  rmined using [SQ
13ca0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
13cb0 48 45 5f 48 44 52 53 5a 5d 2e 0a 2a 2a 20 5e 49  HE_HDRSZ]..** ^I
13cc0 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61  t is harmless, a
13cd0 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61  part from the wa
13ce0 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20  sted memory,.** 
13cf0 66 6f 72 20 74 68 65 20 73 7a 20 70 61 72 61 6d  for the sz param
13d00 65 74 65 72 20 74 6f 20 62 65 20 6c 61 72 67 65  eter to be large
13d10 72 20 74 68 61 6e 20 6e 65 63 65 73 73 61 72 79  r than necessary
13d20 2e 20 20 54 68 65 20 70 4d 65 6d 0a 2a 2a 20 61  .  The pMem.** a
13d30 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20  rgument must be 
13d40 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f  either a NULL po
13d50 69 6e 74 65 72 20 6f 72 20 61 20 70 6f 69 6e 74  inter or a point
13d60 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a  er to an 8-byte.
13d70 2a 2a 20 61 6c 69 67 6e 65 64 20 62 6c 6f 63 6b  ** aligned block
13d80 20 6f 66 20 6d 65 6d 6f 72 79 20 6f 66 20 61 74   of memory of at
13d90 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65   least sz*N byte
13da0 73 2c 20 6f 74 68 65 72 77 69 73 65 0a 2a 2a 20  s, otherwise.** 
13db0 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76  subsequent behav
13dc0 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
13dd0 2e 0a 2a 2a 20 5e 57 68 65 6e 20 70 4d 65 6d 20  ..** ^When pMem 
13de0 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c  is not NULL, SQL
13df0 69 74 65 20 77 69 6c 6c 20 73 74 72 69 76 65 20  ite will strive 
13e00 74 6f 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72  to use the memor
13e10 79 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 74 6f  y provided.** to
13e20 20 73 61 74 69 73 66 79 20 70 61 67 65 20 63 61   satisfy page ca
13e30 63 68 65 20 6e 65 65 64 73 2c 20 66 61 6c 6c 69  che needs, falli
13e40 6e 67 20 62 61 63 6b 20 74 6f 20 5b 73 71 6c 69  ng back to [sqli
13e50 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 66  te3_malloc()] if
13e60 0a 2a 2a 20 61 20 70 61 67 65 20 63 61 63 68 65  .** a page cache
13e70 20 6c 69 6e 65 20 69 73 20 6c 61 72 67 65 72 20   line is larger 
13e80 74 68 61 6e 20 73 7a 20 62 79 74 65 73 20 6f 72  than sz bytes or
13e90 20 69 66 20 61 6c 6c 20 6f 66 20 74 68 65 20 70   if all of the p
13ea0 4d 65 6d 20 62 75 66 66 65 72 0a 2a 2a 20 69 73  Mem buffer.** is
13eb0 20 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 5e   exhausted..** ^
13ec0 49 66 20 70 4d 65 6d 20 69 73 20 4e 55 4c 4c 20  If pMem is NULL 
13ed0 61 6e 64 20 4e 20 69 73 20 6e 6f 6e 2d 7a 65 72  and N is non-zer
13ee0 6f 2c 20 74 68 65 6e 20 65 61 63 68 20 64 61 74  o, then each dat
13ef0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
13f00 0a 2a 2a 20 64 6f 65 73 20 61 6e 20 69 6e 69 74  .** does an init
13f10 69 61 6c 20 62 75 6c 6b 20 61 6c 6c 6f 63 61 74  ial bulk allocat
13f20 69 6f 6e 20 66 6f 72 20 70 61 67 65 20 63 61 63  ion for page cac
13f30 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 66 72 6f  he memory.** fro
13f40 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
13f50 63 28 29 5d 20 73 75 66 66 69 63 69 65 6e 74 20  c()] sufficient 
13f60 66 6f 72 20 4e 20 63 61 63 68 65 20 6c 69 6e 65  for N cache line
13f70 73 20 69 66 20 4e 20 69 73 20 70 6f 73 69 74 69  s if N is positi
13f80 76 65 20 6f 72 0a 2a 2a 20 6f 66 20 2d 31 30 32  ve or.** of -102
13f90 34 2a 4e 20 62 79 74 65 73 20 69 66 20 4e 20 69  4*N bytes if N i
13fa0 73 20 6e 65 67 61 74 69 76 65 2c 20 2e 20 5e 49  s negative, . ^I
13fb0 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  f additional.** 
13fc0 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72  page cache memor
13fd0 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f  y is needed beyo
13fe0 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69  nd what is provi
13ff0 64 65 64 20 62 79 20 74 68 65 20 69 6e 69 74 69  ded by the initi
14000 61 6c 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  al.** allocation
14010 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 67 6f  , then SQLite go
14020 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d  es to [sqlite3_m
14030 61 6c 6c 6f 63 28 29 5d 20 73 65 70 61 72 61 74  alloc()] separat
14040 65 6c 79 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20  ely for each.** 
14050 61 64 64 69 74 69 6f 6e 61 6c 20 63 61 63 68 65  additional cache
14060 20 6c 69 6e 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a   line. </dd>.**.
14070 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
14080 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51  IG_HEAP]] <dt>SQ
14090 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
140a0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
140b0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
140c0 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20 73 70 65  _HEAP option spe
140d0 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
140e0 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 0a 2a  memory buffer .*
140f0 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  * that SQLite wi
14100 6c 6c 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f  ll use for all o
14110 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65  f its dynamic me
14120 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
14130 6e 65 65 64 73 0a 2a 2a 20 62 65 79 6f 6e 64 20  needs.** beyond 
14140 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64 20 66  those provided f
14150 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f  or by [SQLITE_CO
14160 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e  NFIG_SCRATCH] an
14170 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  d.** [SQLITE_CON
14180 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a  FIG_PAGECACHE]..
14190 2a 2a 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  ** ^The SQLITE_C
141a0 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 69 6f  ONFIG_HEAP optio
141b0 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61  n is only availa
141c0 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 73  ble if SQLite is
141d0 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74   compiled.** wit
141e0 68 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  h either [SQLITE
141f0 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d  _ENABLE_MEMSYS3]
14200 20 6f 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42   or [SQLITE_ENAB
14210 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 6e 64 20  LE_MEMSYS5] and 
14220 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49  returns.** [SQLI
14230 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 69 6e 76  TE_ERROR] if inv
14240 6f 6b 65 64 20 6f 74 68 65 72 77 69 73 65 2e 0a  oked otherwise..
14250 2a 2a 20 5e 54 68 65 72 65 20 61 72 65 20 74 68  ** ^There are th
14260 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  ree arguments to
14270 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48   SQLITE_CONFIG_H
14280 45 41 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79 74  EAP:.** An 8-byt
14290 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65  e aligned pointe
142a0 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c  r to the memory,
142b0 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
142c0 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d  f bytes in the m
142d0 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e  emory buffer, an
142e0 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c  d the minimum al
142f0 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a  location size..*
14300 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73 74 20  * ^If the first 
14310 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d  pointer (the mem
14320 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20  ory pointer) is 
14330 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74  NULL, then SQLit
14340 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20  e reverts.** to 
14350 75 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c  using its defaul
14360 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  t memory allocat
14370 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d  or (the system m
14380 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e  alloc() implemen
14390 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f  tation),.** undo
143a0 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e  ing any prior in
143b0 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c  vocation of [SQL
143c0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
143d0 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  C].  ^If the.** 
143e0 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69  memory pointer i
143f0 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20  s not NULL then 
14400 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20  the alternative 
14410 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
14420 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20 74  tor is engaged t
14430 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20  o handle all of 
14440 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61  SQLites memory a
14450 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e  llocation needs.
14460 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f  .** The first po
14470 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72  inter (the memor
14480 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20  y pointer) must 
14490 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  be aligned to an
144a0 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64   8-byte.** bound
144b0 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e  ary or subsequen
144c0 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51  t behavior of SQ
144d0 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64  Lite will be und
144e0 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d  efined..** The m
144f0 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f  inimum allocatio
14500 6e 20 73 69 7a 65 20 69 73 20 63 61 70 70 65 64  n size is capped
14510 20 61 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f   at 2**12. Reaso
14520 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20  nable values.** 
14530 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20  for the minimum 
14540 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20  allocation size 
14550 61 72 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 68  are 2**5 through
14560 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a   2**8.</dd>.**.*
14570 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
14580 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51  G_MUTEX]] <dt>SQ
14590 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
145a0 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  X</dt>.** <dd> ^
145b0 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
145c0 49 47 5f 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20  IG_MUTEX option 
145d0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
145e0 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
145f0 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f   a.** pointer to
14600 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
14610 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
14620 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  ex_methods] stru
14630 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72  cture..** The ar
14640 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73  gument specifies
14650 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77   alternative low
14660 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75  -level mutex rou
14670 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64  tines to be used
14680 0a 2a 2a 20 69 6e 20 70 6c 61 63 65 20 74 68 65  .** in place the
14690 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20   mutex routines 
146a0 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
146b0 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61  e.)^  ^SQLite ma
146c0 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a  kes a copy of.**
146d0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
146e0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
146f0 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  ex_methods] stru
14700 63 74 75 72 65 20 62 65 66 6f 72 65 20 74 68 65  cture before the
14710 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
14720 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72  ite3_config()] r
14730 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69  eturns. ^If SQLi
14740 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
14750 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
14760 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
14770 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
14780 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
14790 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
147a0 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65   the entire mute
147b0 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69  xing subsystem i
147c0 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74  s omitted from t
147d0 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e  he build and hen
147e0 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b  ce calls to.** [
147f0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
14800 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54  ] with the SQLIT
14810 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63  E_CONFIG_MUTEX c
14820 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
14830 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75  ion will.** retu
14840 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
14850 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ].</dd>.**.** [[
14860 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
14870 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c  TMUTEX]] <dt>SQL
14880 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
14890 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TEX</dt>.** <dd>
148a0 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
148b0 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 6f 70  NFIG_GETMUTEX op
148c0 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
148d0 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
148e0 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74  ch.** is a point
148f0 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
14900 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
14910 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
14920 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65   structure.  The
14930 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  .** [sqlite3_mut
14940 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73  ex_methods].** s
14950 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c  tructure is fill
14960 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72  ed with the curr
14970 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75  ently defined mu
14980 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a  tex routines.)^.
14990 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63  ** This option c
149a0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76  an be used to ov
149b0 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75  erload the defau
149c0 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74  lt mutex allocat
149d0 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ion.** routines 
149e0 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20 75  with a wrapper u
149f0 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74  sed to track mut
14a00 65 78 20 75 73 61 67 65 20 66 6f 72 20 70 65 72  ex usage for per
14a10 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66  formance.** prof
14a20 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67  iling or testing
14a30 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20  , for example.  
14a40 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
14a50 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
14a60 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
14a70 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
14a80 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
14a90 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
14aa0 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e  n then.** the en
14ab0 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75  tire mutexing su
14ac0 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74  bsystem is omitt
14ad0 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c  ed from the buil
14ae0 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c  d and hence call
14af0 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s to.** [sqlite3
14b00 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20  _config()] with 
14b10 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  the SQLITE_CONFI
14b20 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69  G_GETMUTEX confi
14b30 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
14b40 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  will.** return [
14b50 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f  SQLITE_ERROR].</
14b60 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
14b70 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
14b80 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  IDE]] <dt>SQLITE
14b90 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
14ba0 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
14bb0 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
14bc0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f 70 74  IG_LOOKASIDE opt
14bd0 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72  ion takes two ar
14be0 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74  guments that det
14bf0 65 72 6d 69 6e 65 0a 2a 2a 20 74 68 65 20 64 65  ermine.** the de
14c00 66 61 75 6c 74 20 73 69 7a 65 20 6f 66 20 6c 6f  fault size of lo
14c10 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 6f  okaside memory o
14c20 6e 20 65 61 63 68 20 5b 64 61 74 61 62 61 73 65  n each [database
14c30 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a   connection]..**
14c40 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
14c50 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69  ent is the.** si
14c60 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61  ze of each looka
14c70 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74  side buffer slot
14c80 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
14c90 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
14ca0 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61  .** slots alloca
14cb0 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 74 61  ted to each data
14cc0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  base connection.
14cd0 29 5e 20 20 5e 28 53 51 4c 49 54 45 5f 43 4f 4e  )^  ^(SQLITE_CON
14ce0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a 2a  FIG_LOOKASIDE.**
14cf0 20 73 65 74 73 20 74 68 65 20 3c 69 3e 64 65 66   sets the <i>def
14d00 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69  ault</i> lookasi
14d10 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51  de size. The [SQ
14d20 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
14d30 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 6f 70 74 69  OKASIDE].** opti
14d40 6f 6e 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64  on to [sqlite3_d
14d50 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20  b_config()] can 
14d60 62 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67  be used to chang
14d70 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a  e the lookaside.
14d80 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
14d90 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63   on individual c
14da0 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f  onnections.)^ </
14db0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
14dc0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
14dd0 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  2]] <dt>SQLITE_C
14de0 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 3c 2f 64  ONFIG_PCACHE2</d
14df0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
14e00 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
14e10 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61  CACHE2 option ta
14e20 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
14e30 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a  ument which is .
14e40 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** a pointer to 
14e50 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63  an [sqlite3_pcac
14e60 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a  he_methods2] obj
14e70 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63  ect.  This objec
14e80 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74  t specifies.** t
14e90 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20  he interface to 
14ea0 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61  a custom page ca
14eb0 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
14ec0 6f 6e 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74 65  on.)^.** ^SQLite
14ed0 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
14ee0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 63   the [sqlite3_pc
14ef0 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f  ache_methods2] o
14f00 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  bject.</dd>.**.*
14f10 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
14f20 47 5f 47 45 54 50 43 41 43 48 45 32 5d 5d 20 3c  G_GETPCACHE2]] <
14f30 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
14f40 5f 47 45 54 50 43 41 43 48 45 32 3c 2f 64 74 3e  _GETPCACHE2</dt>
14f50 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
14f60 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
14f70 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74  PCACHE2 option t
14f80 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
14f90 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20  gument which.** 
14fa0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
14fb0 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63  an [sqlite3_pcac
14fc0 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a  he_methods2] obj
14fd0 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70  ect.  SQLite cop
14fe0 69 65 73 20 6f 66 0a 2a 2a 20 74 68 65 20 63 75  ies of.** the cu
14ff0 72 72 65 6e 74 20 70 61 67 65 20 63 61 63 68 65  rrent page cache
15000 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
15010 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74  into that object
15020 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .)^ </dd>.**.** 
15030 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
15040 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  LOG]] <dt>SQLITE
15050 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e  _CONFIG_LOG</dt>
15060 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 4c  .** <dd> The SQL
15070 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f  ITE_CONFIG_LOG o
15080 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f  ption is used to
15090 20 63 6f 6e 66 69 67 75 72 65 20 74 68 65 20 53   configure the S
150a0 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20  QLite.** global 
150b0 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20  [error log]..** 
150c0 28 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  (^The SQLITE_CON
150d0 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74  FIG_LOG option t
150e0 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e  akes two argumen
150f0 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  ts: a pointer to
15100 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77   a.** function w
15110 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61  ith a call signa
15120 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28  ture of void(*)(
15130 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
15140 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20  char*), .** and 
15150 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69  a pointer to voi
15160 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74  d. ^If the funct
15170 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e  ion pointer is n
15180 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a  ot NULL, it is.*
15190 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71  * invoked by [sq
151a0 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20  lite3_log()] to 
151b0 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67  process each log
151c0 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66  ging event.  ^If
151d0 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   the.** function
151e0 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c   pointer is NULL
151f0 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  , the [sqlite3_l
15200 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  og()] interface 
15210 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e  becomes a no-op.
15220 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f  .** ^The void po
15230 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 74 68  inter that is th
15240 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
15250 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46  t to SQLITE_CONF
15260 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73  IG_LOG is.** pas
15270 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74  sed through as t
15280 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
15290 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63  er to the applic
152a0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f  ation-defined lo
152b0 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  gger.** function
152c0 20 77 68 65 6e 65 76 65 72 20 74 68 61 74 20 66   whenever that f
152d0 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b  unction is invok
152e0 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64  ed.  ^The second
152f0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
15300 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63   the logger func
15310 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f  tion is a copy o
15320 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  f the first para
15330 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72  meter to the cor
15340 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73  responding.** [s
15350 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61  qlite3_log()] ca
15360 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64  ll and is intend
15370 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75  ed to be a [resu
15380 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a  lt code] or an.*
15390 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
153a0 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20  lt code].  ^The 
153b0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
153c0 70 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f  passed to the lo
153d0 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d  gger is.** log m
153e0 65 73 73 61 67 65 20 61 66 74 65 72 20 66 6f 72  essage after for
153f0 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c  matting via [sql
15400 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
15410 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20  ..** The SQLite 
15420 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63  logging interfac
15430 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61  e is not reentra
15440 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66  nt; the logger f
15450 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c  unction.** suppl
15460 69 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69  ied by the appli
15470 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  cation must not 
15480 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74  invoke any SQLit
15490 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20  e interface..** 
154a0 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61  In a multi-threa
154b0 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c  ded application,
154c0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
154d0 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a  -defined logger.
154e0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ** function must
154f0 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20   be threadsafe. 
15500 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
15510 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d  LITE_CONFIG_URI]
15520 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
15530 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e  FIG_URI.** <dd>^
15540 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
15550 49 47 5f 55 52 49 20 6f 70 74 69 6f 6e 20 74 61  IG_URI option ta
15560 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
15570 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e  ument of type in
15580 74 2e 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65 72  t..** If non-zer
15590 6f 2c 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64  o, then URI hand
155a0 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79  ling is globally
155b0 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 65   enabled. If the
155c0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 7a 65   parameter is ze
155d0 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 55 52 49 20  ro,.** then URI 
155e0 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62  handling is glob
155f0 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e 29 5e  ally disabled.)^
15600 20 5e 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e   ^If URI handlin
15610 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a  g is globally.**
15620 20 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69   enabled, all fi
15630 6c 65 6e 61 6d 65 73 20 70 61 73 73 65 64 20 74  lenames passed t
15640 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  o [sqlite3_open(
15650 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
15660 6e 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  n_v2()],.** [sql
15670 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f  ite3_open16()] o
15680 72 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20 61  r.** specified a
15690 73 20 70 61 72 74 20 6f 66 20 5b 41 54 54 41 43  s part of [ATTAC
156a0 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20  H] commands are 
156b0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55  interpreted as U
156c0 52 49 73 2c 20 72 65 67 61 72 64 6c 65 73 73 0a  RIs, regardless.
156d0 2a 2a 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ** of whether or
156e0 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45   not the [SQLITE
156f0 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20  _OPEN_URI] flag 
15700 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20  is set when the 
15710 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
15720 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64  ection is opened
15730 2e 20 5e 49 66 20 69 74 20 69 73 20 67 6c 6f 62  . ^If it is glob
15740 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 66  ally disabled, f
15750 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20  ilenames are.** 
15760 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65 74 65 64  only interpreted
15770 20 61 73 20 55 52 49 73 20 69 66 20 74 68 65 20   as URIs if the 
15780 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20  SQLITE_OPEN_URI 
15790 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e  flag is set when
157a0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
157b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
157c0 70 65 6e 65 64 2e 20 5e 28 42 79 20 64 65 66 61  pened. ^(By defa
157d0 75 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e  ult, URI handlin
157e0 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a  g is globally.**
157f0 20 64 69 73 61 62 6c 65 64 2e 20 54 68 65 20 64   disabled. The d
15800 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6d 61 79  efault value may
15810 20 62 65 20 63 68 61 6e 67 65 64 20 62 79 20 63   be changed by c
15820 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 74 68  ompiling with th
15830 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45  e.** [SQLITE_USE
15840 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66  _URI] symbol def
15850 69 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  ined.)^.**.** [[
15860 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f  SQLITE_CONFIG_CO
15870 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
15880 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  N]] <dt>SQLITE_C
15890 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49  ONFIG_COVERING_I
158a0 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64  NDEX_SCAN.** <dd
158b0 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  >^The SQLITE_CON
158c0 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  FIG_COVERING_IND
158d0 45 58 5f 53 43 41 4e 20 6f 70 74 69 6f 6e 20 74  EX_SCAN option t
158e0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 69 6e  akes a single in
158f0 74 65 67 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e  teger.** argumen
15900 74 20 77 68 69 63 68 20 69 73 20 69 6e 74 65 72  t which is inter
15910 70 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c  preted as a bool
15920 65 61 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ean in order to 
15930 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c  enable or disabl
15940 65 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20  e.** the use of 
15950 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73  covering indices
15960 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20   for full table 
15970 73 63 61 6e 73 20 69 6e 20 74 68 65 20 71 75 65  scans in the que
15980 72 79 20 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a 2a  ry optimizer..**
15990 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73 65   ^The default se
159a0 74 74 69 6e 67 20 69 73 20 64 65 74 65 72 6d 69  tting is determi
159b0 6e 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53  ned.** by the [S
159c0 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45  QLITE_ALLOW_COVE
159d0 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d  RING_INDEX_SCAN]
159e0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
159f0 74 69 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22  tion, or is "on"
15a00 0a 2a 2a 20 69 66 20 74 68 61 74 20 63 6f 6d 70  .** if that comp
15a10 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
15a20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54  is omitted..** T
15a30 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 64 69  he ability to di
15a40 73 61 62 6c 65 20 74 68 65 20 75 73 65 20 6f 66  sable the use of
15a50 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65   covering indice
15a60 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65  s for full table
15a70 20 73 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63   scans.** is bec
15a80 61 75 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72  ause some incorr
15a90 65 63 74 6c 79 20 63 6f 64 65 64 20 6c 65 67 61  ectly coded lega
15aa0 63 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  cy applications 
15ab0 6d 69 67 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f  might malfunctio
15ac0 6e 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 6f 70  n.** when the op
15ad0 74 69 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e  timization is en
15ae0 61 62 6c 65 64 2e 20 20 50 72 6f 76 69 64 69 6e  abled.  Providin
15af0 67 20 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f  g the ability to
15b00 0a 2a 2a 20 64 69 73 61 62 6c 65 20 74 68 65 20  .** disable the 
15b10 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c  optimization all
15b20 6f 77 73 20 74 68 65 20 6f 6c 64 65 72 2c 20 62  ows the older, b
15b30 75 67 67 79 20 61 70 70 6c 69 63 61 74 69 6f 6e  uggy application
15b40 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a   code to work.**
15b50 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 65 20   without change 
15b60 65 76 65 6e 20 77 69 74 68 20 6e 65 77 65 72 20  even with newer 
15b70 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
15b80 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  te..**.** [[SQLI
15b90 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
15ba0 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ]] [[SQLITE_CONF
15bb0 49 47 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a  IG_GETPCACHE]].*
15bc0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
15bd0 46 49 47 5f 50 43 41 43 48 45 20 61 6e 64 20 53  FIG_PCACHE and S
15be0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
15bf0 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54  PCACHE.** <dd> T
15c00 68 65 73 65 20 6f 70 74 69 6f 6e 73 20 61 72 65  hese options are
15c10 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20 73 68   obsolete and sh
15c20 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64  ould not be used
15c30 20 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a   by new code..**
15c40 20 54 68 65 79 20 61 72 65 20 72 65 74 61 69 6e   They are retain
15c50 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ed for backwards
15c60 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 62   compatibility b
15c70 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70  ut are now no-op
15c80 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  s..** </dd>.**.*
15c90 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
15ca0 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64  G_SQLLOG]].** <d
15cb0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
15cc0 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68  SQLLOG.** <dd>Th
15cd0 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c  is option is onl
15ce0 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 73  y available if s
15cf0 71 6c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  qlite is compile
15d00 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53  d with the.** [S
15d10 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c  QLITE_ENABLE_SQL
15d20 4c 4f 47 5d 20 70 72 65 2d 70 72 6f 63 65 73 73  LOG] pre-process
15d30 6f 72 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64  or macro defined
15d40 2e 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  . The first argu
15d50 6d 65 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62  ment should.** b
15d60 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  e a pointer to a
15d70 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70   function of typ
15d80 65 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c  e void(*)(void*,
15d90 73 71 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63  sqlite3*,const c
15da0 68 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54  har*, int)..** T
15db0 68 65 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64  he second should
15dc0 20 62 65 20 6f 66 20 74 79 70 65 20 28 76 6f 69   be of type (voi
15dd0 64 2a 29 2e 20 54 68 65 20 63 61 6c 6c 62 61 63  d*). The callbac
15de0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20  k is invoked by 
15df0 74 68 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69  the library.** i
15e00 6e 20 74 68 72 65 65 20 73 65 70 61 72 61 74 65  n three separate
15e10 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20   circumstances, 
15e20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68  identified by th
15e30 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61  e value passed a
15e40 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20  s the.** fourth 
15e50 70 61 72 61 6d 65 74 65 72 2e 20 49 66 20 74 68  parameter. If th
15e60 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
15e70 65 72 20 69 73 20 30 2c 20 74 68 65 6e 20 74 68  er is 0, then th
15e80 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
15e90 63 74 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20  ction.** passed 
15ea0 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  as the second ar
15eb0 67 75 6d 65 6e 74 20 68 61 73 20 6a 75 73 74 20  gument has just 
15ec0 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65  been opened. The
15ed0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a   third argument.
15ee0 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 62  ** points to a b
15ef0 75 66 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67  uffer containing
15f00 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
15f10 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66   main database f
15f20 69 6c 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66  ile. If the.** f
15f30 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
15f40 69 73 20 31 2c 20 74 68 65 6e 20 74 68 65 20 53  is 1, then the S
15f50 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  QL statement tha
15f60 74 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  t the third para
15f70 6d 65 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20  meter.** points 
15f80 74 6f 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e  to has just been
15f90 20 65 78 65 63 75 74 65 64 2e 20 4f 72 2c 20 69   executed. Or, i
15fa0 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
15fb0 61 6d 65 74 65 72 20 69 73 20 32 2c 20 74 68 65  ameter is 2, the
15fc0 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74  n.** the connect
15fd0 69 6f 6e 20 62 65 69 6e 67 20 70 61 73 73 65 64  ion being passed
15fe0 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
15ff0 61 72 61 6d 65 74 65 72 20 69 73 20 62 65 69 6e  arameter is bein
16000 67 20 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a  g closed. The.**
16010 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
16020 20 69 73 20 70 61 73 73 65 64 20 4e 55 4c 4c 20   is passed NULL 
16030 49 6e 20 74 68 69 73 20 63 61 73 65 2e 20 20 41  In this case.  A
16040 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 75 73 69  n example of usi
16050 6e 67 20 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69  ng this.** confi
16060 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
16070 63 61 6e 20 62 65 20 73 65 65 6e 20 69 6e 20 74  can be seen in t
16080 68 65 20 22 74 65 73 74 5f 73 71 6c 6c 6f 67 2e  he "test_sqllog.
16090 63 22 20 73 6f 75 72 63 65 20 66 69 6c 65 20 69  c" source file i
160a0 6e 0a 2a 2a 20 74 68 65 20 63 61 6e 6f 6e 69 63  n.** the canonic
160b0 61 6c 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65  al SQLite source
160c0 20 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a   tree.</dd>.**.*
160d0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
160e0 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a  G_MMAP_SIZE]].**
160f0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
16100 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20  IG_MMAP_SIZE.** 
16110 3c 64 64 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e 46  <dd>^SQLITE_CONF
16120 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 74 61 6b  IG_MMAP_SIZE tak
16130 65 73 20 74 77 6f 20 36 34 2d 62 69 74 20 69 6e  es two 64-bit in
16140 74 65 67 65 72 20 28 73 71 6c 69 74 65 33 5f 69  teger (sqlite3_i
16150 6e 74 36 34 29 20 76 61 6c 75 65 73 0a 2a 2a 20  nt64) values.** 
16160 74 68 61 74 20 61 72 65 20 74 68 65 20 64 65 66  that are the def
16170 61 75 6c 74 20 6d 6d 61 70 20 73 69 7a 65 20 6c  ault mmap size l
16180 69 6d 69 74 20 28 74 68 65 20 64 65 66 61 75 6c  imit (the defaul
16190 74 20 73 65 74 74 69 6e 67 20 66 6f 72 0a 2a 2a  t setting for.**
161a0 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69   [PRAGMA mmap_si
161b0 7a 65 5d 29 20 61 6e 64 20 74 68 65 20 6d 61 78  ze]) and the max
161c0 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61  imum allowed mma
161d0 70 20 73 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a  p size limit..**
161e0 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73 65   ^The default se
161f0 74 74 69 6e 67 20 63 61 6e 20 62 65 20 6f 76 65  tting can be ove
16200 72 72 69 64 64 65 6e 20 62 79 20 65 61 63 68 20  rridden by each 
16210 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
16220 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 65 69 74  ion using.** eit
16230 68 65 72 20 74 68 65 20 5b 50 52 41 47 4d 41 20  her the [PRAGMA 
16240 6d 6d 61 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61  mmap_size] comma
16250 6e 64 2c 20 6f 72 20 62 79 20 75 73 69 6e 67 20  nd, or by using 
16260 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46  the.** [SQLITE_F
16270 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20  CNTL_MMAP_SIZE] 
16280 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e  file control.  ^
16290 28 54 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c  (The maximum all
162a0 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a  owed mmap size.*
162b0 2a 20 77 69 6c 6c 20 62 65 20 73 69 6c 65 6e 74  * will be silent
162c0 6c 79 20 74 72 75 6e 63 61 74 65 64 20 69 66 20  ly truncated if 
162d0 6e 65 63 65 73 73 61 72 79 20 73 6f 20 74 68 61  necessary so tha
162e0 74 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 65 78  t it does not ex
162f0 63 65 65 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70  ceed the.** comp
16300 69 6c 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d  ile-time maximum
16310 20 6d 6d 61 70 20 73 69 7a 65 20 73 65 74 20 62   mmap size set b
16320 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  y the.** [SQLITE
16330 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20  _MAX_MMAP_SIZE] 
16340 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
16350 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69  ion.)^.** ^If ei
16360 74 68 65 72 20 61 72 67 75 6d 65 6e 74 20 74 6f  ther argument to
16370 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20   this option is 
16380 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74  negative, then t
16390 68 61 74 20 61 72 67 75 6d 65 6e 74 20 69 73 0a  hat argument is.
163a0 2a 2a 20 63 68 61 6e 67 65 64 20 74 6f 20 69 74  ** changed to it
163b0 73 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64  s compile-time d
163c0 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  efault..**.** [[
163d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49  SQLITE_CONFIG_WI
163e0 4e 33 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a  N32_HEAPSIZE]].*
163f0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
16400 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49  FIG_WIN32_HEAPSI
16410 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53  ZE.** <dd>^The S
16420 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e  QLITE_CONFIG_WIN
16430 33 32 5f 48 45 41 50 53 49 5a 45 20 6f 70 74 69  32_HEAPSIZE opti
16440 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c  on is only avail
16450 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69  able if SQLite i
16460 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 66 6f  s.** compiled fo
16470 72 20 57 69 6e 64 6f 77 73 20 77 69 74 68 20 74  r Windows with t
16480 68 65 20 5b 53 51 4c 49 54 45 5f 57 49 4e 33 32  he [SQLITE_WIN32
16490 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d 70 72 6f  _MALLOC] pre-pro
164a0 63 65 73 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a 20  cessor macro.** 
164b0 64 65 66 69 6e 65 64 2e 20 5e 53 51 4c 49 54 45  defined. ^SQLITE
164c0 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45  _CONFIG_WIN32_HE
164d0 41 50 53 49 5a 45 20 74 61 6b 65 73 20 61 20 33  APSIZE takes a 3
164e0 32 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69  2-bit unsigned i
164f0 6e 74 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a 20  nteger value.** 
16500 74 68 61 74 20 73 70 65 63 69 66 69 65 73 20 74  that specifies t
16510 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20  he maximum size 
16520 6f 66 20 74 68 65 20 63 72 65 61 74 65 64 20 68  of the created h
16530 65 61 70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  eap..**.** [[SQL
16540 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
16550 45 5f 48 44 52 53 5a 5d 5d 0a 2a 2a 20 3c 64 74  E_HDRSZ]].** <dt
16560 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
16570 43 41 43 48 45 5f 48 44 52 53 5a 0a 2a 2a 20 3c  CACHE_HDRSZ.** <
16580 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  dd>^The SQLITE_C
16590 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52  ONFIG_PCACHE_HDR
165a0 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  SZ option takes 
165b0 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74  a single paramet
165c0 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61  er which.** is a
165d0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
165e0 6e 74 65 67 65 72 20 61 6e 64 20 77 72 69 74 65  nteger and write
165f0 73 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65  s into that inte
16600 67 65 72 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ger the number o
16610 66 20 65 78 74 72 61 0a 2a 2a 20 62 79 74 65 73  f extra.** bytes
16620 20 70 65 72 20 70 61 67 65 20 72 65 71 75 69 72   per page requir
16630 65 64 20 66 6f 72 20 65 61 63 68 20 70 61 67 65  ed for each page
16640 20 69 6e 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   in [SQLITE_CONF
16650 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a  IG_PAGECACHE]..*
16660 2a 20 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20  * The amount of 
16670 65 78 74 72 61 20 73 70 61 63 65 20 72 65 71 75  extra space requ
16680 69 72 65 64 20 63 61 6e 20 63 68 61 6e 67 65 20  ired can change 
16690 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
166a0 20 63 6f 6d 70 69 6c 65 72 2c 0a 2a 2a 20 74 61   compiler,.** ta
166b0 72 67 65 74 20 70 6c 61 74 66 6f 72 6d 2c 20 61  rget platform, a
166c0 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  nd SQLite versio
166d0 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  n..**.** [[SQLIT
166e0 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 5d 5d  E_CONFIG_PMASZ]]
166f0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
16700 4f 4e 46 49 47 5f 50 4d 41 53 5a 0a 2a 2a 20 3c  ONFIG_PMASZ.** <
16710 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  dd>^The SQLITE_C
16720 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 6f 70 74 69  ONFIG_PMASZ opti
16730 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
16740 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63  e parameter whic
16750 68 0a 2a 2a 20 69 73 20 61 6e 20 75 6e 73 69 67  h.** is an unsig
16760 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20  ned integer and 
16770 73 65 74 73 20 74 68 65 20 22 4d 69 6e 69 6d 75  sets the "Minimu
16780 6d 20 50 4d 41 20 53 69 7a 65 22 20 66 6f 72 20  m PMA Size" for 
16790 74 68 65 20 6d 75 6c 74 69 74 68 72 65 61 64 65  the multithreade
167a0 64 0a 2a 2a 20 73 6f 72 74 65 72 20 74 6f 20 74  d.** sorter to t
167b0 68 61 74 20 69 6e 74 65 67 65 72 2e 20 20 54 68  hat integer.  Th
167c0 65 20 64 65 66 61 75 6c 74 20 6d 69 6e 69 6d 75  e default minimu
167d0 6d 20 50 4d 41 20 53 69 7a 65 20 69 73 20 73 65  m PMA Size is se
167e0 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  t by the.** [SQL
167f0 49 54 45 5f 53 4f 52 54 45 52 5f 50 4d 41 53 5a  ITE_SORTER_PMASZ
16800 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
16810 70 74 69 6f 6e 2e 20 20 4e 65 77 20 74 68 72 65  ption.  New thre
16820 61 64 73 20 61 72 65 20 6c 61 75 6e 63 68 65 64  ads are launched
16830 0a 2a 2a 20 74 6f 20 68 65 6c 70 20 77 69 74 68  .** to help with
16840 20 73 6f 72 74 20 6f 70 65 72 61 74 69 6f 6e 73   sort operations
16850 20 77 68 65 6e 20 6d 75 6c 74 69 74 68 72 65 61   when multithrea
16860 64 65 64 20 73 6f 72 74 69 6e 67 0a 2a 2a 20 69  ded sorting.** i
16870 73 20 65 6e 61 62 6c 65 64 20 28 75 73 69 6e 67  s enabled (using
16880 20 74 68 65 20 5b 50 52 41 47 4d 41 20 74 68 72   the [PRAGMA thr
16890 65 61 64 73 5d 20 63 6f 6d 6d 61 6e 64 29 20 61  eads] command) a
168a0 6e 64 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66  nd the amount of
168b0 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 74 6f 20 62   content.** to b
168c0 65 20 73 6f 72 74 65 64 20 65 78 63 65 65 64 73  e sorted exceeds
168d0 20 74 68 65 20 70 61 67 65 20 73 69 7a 65 20 74   the page size t
168e0 69 6d 65 73 20 74 68 65 20 6d 69 6e 69 6d 75 6d  imes the minimum
168f0 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 50 52 41 47   of the.** [PRAG
16900 4d 41 20 63 61 63 68 65 5f 73 69 7a 65 5d 20 73  MA cache_size] s
16910 65 74 74 69 6e 67 20 61 6e 64 20 74 68 69 73 20  etting and this 
16920 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  value..**.** [[S
16930 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d  QLITE_CONFIG_STM
16940 54 4a 52 4e 4c 5f 53 50 49 4c 4c 5d 5d 0a 2a 2a  TJRNL_SPILL]].**
16950 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
16960 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c  IG_STMTJRNL_SPIL
16970 4c 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51  L.** <dd>^The SQ
16980 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54  LITE_CONFIG_STMT
16990 4a 52 4e 4c 5f 53 50 49 4c 4c 20 6f 70 74 69 6f  JRNL_SPILL optio
169a0 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
169b0 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68   parameter which
169c0 0a 2a 2a 20 62 65 63 6f 6d 65 73 20 74 68 65 20  .** becomes the 
169d0 5b 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e  [statement journ
169e0 61 6c 5d 20 73 70 69 6c 6c 2d 74 6f 2d 64 69 73  al] spill-to-dis
169f0 6b 20 74 68 72 65 73 68 6f 6c 64 2e 20 20 0a 2a  k threshold.  .*
16a00 2a 20 5b 53 74 61 74 65 6d 65 6e 74 20 6a 6f 75  * [Statement jou
16a10 72 6e 61 6c 73 5d 20 61 72 65 20 68 65 6c 64 20  rnals] are held 
16a20 69 6e 20 6d 65 6d 6f 72 79 20 75 6e 74 69 6c 20  in memory until 
16a30 74 68 65 69 72 20 73 69 7a 65 20 28 69 6e 20 62  their size (in b
16a40 79 74 65 73 29 0a 2a 2a 20 65 78 63 65 65 64 73  ytes).** exceeds
16a50 20 74 68 69 73 20 74 68 72 65 73 68 6f 6c 64 2c   this threshold,
16a60 20 61 74 20 77 68 69 63 68 20 70 6f 69 6e 74 20   at which point 
16a70 74 68 65 79 20 61 72 65 20 77 72 69 74 74 65 6e  they are written
16a80 20 74 6f 20 64 69 73 6b 2e 0a 2a 2a 20 4f 72 20   to disk..** Or 
16a90 69 66 20 74 68 65 20 74 68 72 65 73 68 6f 6c 64  if the threshold
16aa0 20 69 73 20 2d 31 2c 20 73 74 61 74 65 6d 65 6e   is -1, statemen
16ab0 74 20 6a 6f 75 72 6e 61 6c 73 20 61 72 65 20 61  t journals are a
16ac0 6c 77 61 79 73 20 68 65 6c 64 0a 2a 2a 20 65 78  lways held.** ex
16ad0 63 6c 75 73 69 76 65 6c 79 20 69 6e 20 6d 65 6d  clusively in mem
16ae0 6f 72 79 2e 0a 2a 2a 20 53 69 6e 63 65 20 6d 61  ory..** Since ma
16af0 6e 79 20 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75  ny statement jou
16b00 72 6e 61 6c 73 20 6e 65 76 65 72 20 62 65 63 6f  rnals never beco
16b10 6d 65 20 6c 61 72 67 65 2c 20 73 65 74 74 69 6e  me large, settin
16b20 67 20 74 68 65 20 73 70 69 6c 6c 0a 2a 2a 20 74  g the spill.** t
16b30 68 72 65 73 68 6f 6c 64 20 74 6f 20 61 20 76 61  hreshold to a va
16b40 6c 75 65 20 73 75 63 68 20 61 73 20 36 34 4b 69  lue such as 64Ki
16b50 42 20 63 61 6e 20 67 72 65 61 74 6c 79 20 72 65  B can greatly re
16b60 64 75 63 65 20 74 68 65 20 61 6d 6f 75 6e 74 20  duce the amount 
16b70 6f 66 0a 2a 2a 20 49 2f 4f 20 72 65 71 75 69 72  of.** I/O requir
16b80 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 73 74  ed to support st
16b90 61 74 65 6d 65 6e 74 20 72 6f 6c 6c 62 61 63 6b  atement rollback
16ba0 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74  ..** The default
16bb0 20 76 61 6c 75 65 20 66 6f 72 20 74 68 69 73 20   value for this 
16bc0 73 65 74 74 69 6e 67 20 69 73 20 63 6f 6e 74 72  setting is contr
16bd0 6f 6c 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  olled by the.** 
16be0 5b 53 51 4c 49 54 45 5f 53 54 4d 54 4a 52 4e 4c  [SQLITE_STMTJRNL
16bf0 5f 53 50 49 4c 4c 5d 20 63 6f 6d 70 69 6c 65 2d  _SPILL] compile-
16c00 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20  time option..** 
16c10 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
16c20 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
16c30 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 20  INGLETHREAD  1  
16c40 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
16c50 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16c60 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 20  MULTITHREAD   2 
16c70 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
16c80 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
16c90 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33  _SERIALIZED    3
16ca0 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66    /* nil */.#def
16cb0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
16cc0 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20  G_MALLOC        
16cd0 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65  4  /* sqlite3_me
16ce0 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  m_methods* */.#d
16cf0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
16d00 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20  FIG_GETMALLOC   
16d10 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f    5  /* sqlite3_
16d20 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  mem_methods* */.
16d30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16d40 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 20  ONFIG_SCRATCH   
16d50 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c      6  /* void*,
16d60 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a   int sz, int N *
16d70 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16d80 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
16d90 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64  E     7  /* void
16da0 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e  *, int sz, int N
16db0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16dc0 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20  TE_CONFIG_HEAP  
16dd0 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f          8  /* vo
16de0 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20  id*, int nByte, 
16df0 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69  int min */.#defi
16e00 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
16e10 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 39  _MEMSTATUS     9
16e20 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a    /* boolean */.
16e30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16e40 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20  ONFIG_MUTEX     
16e50 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65     10  /* sqlite
16e60 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a  3_mutex_methods*
16e70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16e80 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
16e90 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71  EX     11  /* sq
16ea0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
16eb0 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69  ods* */./* previ
16ec0 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e  ously SQLITE_CON
16ed0 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31  FIG_CHUNKALLOC 1
16ee0 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75  2 which is now u
16ef0 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69  nused. */ .#defi
16f00 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
16f10 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33  _LOOKASIDE    13
16f20 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a    /* int int */.
16f30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16f40 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20 20  ONFIG_PCACHE    
16f50 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20     14  /* no-op 
16f60 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16f70 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
16f80 48 45 20 20 20 20 31 35 20 20 2f 2a 20 6e 6f 2d  HE    15  /* no-
16f90 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  op */.#define SQ
16fa0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
16fb0 20 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a 20           16  /* 
16fc0 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a  xFunc, void* */.
16fd0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16fe0 4f 4e 46 49 47 5f 55 52 49 20 20 20 20 20 20 20  ONFIG_URI       
16ff0 20 20 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a 2f     17  /* int */
17000 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17010 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 20  CONFIG_PCACHE2  
17020 20 20 20 20 31 38 20 20 2f 2a 20 73 71 6c 69 74      18  /* sqlit
17030 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
17040 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  s2* */.#define S
17050 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
17060 50 43 41 43 48 45 32 20 20 20 31 39 20 20 2f 2a  PCACHE2   19  /*
17070 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f   sqlite3_pcache_
17080 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65  methods2* */.#de
17090 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
170a0 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45  IG_COVERING_INDE
170b0 58 5f 53 43 41 4e 20 32 30 20 20 2f 2a 20 69 6e  X_SCAN 20  /* in
170c0 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
170d0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f  ITE_CONFIG_SQLLO
170e0 47 20 20 20 20 20 20 20 32 31 20 20 2f 2a 20 78  G       21  /* x
170f0 53 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20 2a 2f  Sqllog, void* */
17100 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17110 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45  CONFIG_MMAP_SIZE
17120 20 20 20 20 32 32 20 20 2f 2a 20 73 71 6c 69 74      22  /* sqlit
17130 65 33 5f 69 6e 74 36 34 2c 20 73 71 6c 69 74 65  e3_int64, sqlite
17140 33 5f 69 6e 74 36 34 20 2a 2f 0a 23 64 65 66 69  3_int64 */.#defi
17150 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
17160 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20  _WIN32_HEAPSIZE 
17170 20 20 20 20 20 32 33 20 20 2f 2a 20 69 6e 74 20       23  /* int 
17180 6e 42 79 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65  nByte */.#define
17190 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
171a0 43 41 43 48 45 5f 48 44 52 53 5a 20 20 20 20 20  CACHE_HDRSZ     
171b0 20 20 20 32 34 20 20 2f 2a 20 69 6e 74 20 2a 70     24  /* int *p
171c0 73 7a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  sz */.#define SQ
171d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53  LITE_CONFIG_PMAS
171e0 5a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  Z               
171f0 32 35 20 20 2f 2a 20 75 6e 73 69 67 6e 65 64 20  25  /* unsigned 
17200 69 6e 74 20 73 7a 50 6d 61 20 2a 2f 0a 23 64 65  int szPma */.#de
17210 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
17220 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c  IG_STMTJRNL_SPIL
17230 4c 20 20 20 20 20 20 32 36 20 20 2f 2a 20 69 6e  L      26  /* in
17240 74 20 6e 42 79 74 65 20 2a 2f 0a 0a 2f 2a 0a 2a  t nByte */../*.*
17250 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61  * CAPI3REF: Data
17260 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20  base Connection 
17270 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70  Configuration Op
17280 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
17290 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
172a0 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  the available in
172b0 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74  teger configurat
172c0 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  ion options that
172d0 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65  .** can be passe
172e0 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
172f0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
17300 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
17310 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ig()] interface.
17320 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69  .**.** New confi
17330 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
17340 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
17350 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
17360 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45   of SQLite..** E
17370 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72  xisting configur
17380 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69  ation options mi
17390 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e  ght be discontin
173a0 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ued.  Applicatio
173b0 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65  ns.** should che
173c0 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f  ck the return co
173d0 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  de from [sqlite3
173e0 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f  _db_config()] to
173f0 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a   make sure that.
17400 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b  ** the call work
17410 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74  ed.  ^The [sqlit
17420 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
17430 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72  interface will r
17440 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a  eturn a.** non-z
17450 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
17460 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75   if a discontinu
17470 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65  ed or unsupporte
17480 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  d configuration 
17490 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76  option.** is inv
174a0 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  oked..**.** <dl>
174b0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
174c0 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
174d0 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
174e0 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
174f0 73 20 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e  s three addition
17500 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  al arguments tha
17510 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  t determine the 
17520 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d  .** [lookaside m
17530 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d  emory allocator]
17540 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66   configuration f
17550 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  or the [database
17560 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a   connection]..**
17570 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
17580 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72 64 20  ment (the third 
17590 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
175a0 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
175b0 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74  )] is a.** point
175c0 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62  er to a memory b
175d0 75 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72  uffer to use for
175e0 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
175f0 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  y..** ^The first
17600 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20   argument after 
17610 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  the SQLITE_DBCON
17620 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65  FIG_LOOKASIDE ve
17630 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c  rb.** may be NUL
17640 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  L in which case 
17650 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f  SQLite will allo
17660 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b  cate the.** look
17670 61 73 69 64 65 20 62 75 66 66 65 72 20 69 74 73  aside buffer its
17680 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  elf using [sqlit
17690 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54  e3_malloc()]. ^T
176a0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
176b0 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a  nt is the.** siz
176c0 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73  e of each lookas
176d0 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e  ide buffer slot.
176e0 20 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67    ^The third arg
176f0 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d  ument is the num
17700 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e  ber of.** slots.
17710 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68    The size of th
17720 65 20 62 75 66 66 65 72 20 69 6e 20 74 68 65 20  e buffer in the 
17730 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d  first argument m
17740 75 73 74 20 62 65 20 67 72 65 61 74 65 72 20 74  ust be greater t
17750 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20  han.** or equal 
17760 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f  to the product o
17770 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64  f the second and
17780 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73   third arguments
17790 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a  .  The buffer.**
177a0 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64   must be aligned
177b0 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f   to an 8-byte bo
177c0 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65  undary.  ^If the
177d0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
177e0 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42   to.** SQLITE_DB
177f0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
17800 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70   is not a multip
17810 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69  le of 8, it is i
17820 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75  nternally.** rou
17830 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65  nded down to the
17840 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75   next smaller mu
17850 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28  ltiple of 8.  ^(
17860 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  The lookaside me
17870 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  mory.** configur
17880 61 74 69 6f 6e 20 66 6f 72 20 61 20 64 61 74 61  ation for a data
17890 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
178a0 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e  can only be chan
178b0 67 65 64 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a  ged when that.**
178c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e   connection is n
178d0 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69  ot currently usi
178e0 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  ng lookaside mem
178f0 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72  ory, or in other
17900 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74   words.** when t
17910 68 65 20 22 63 75 72 72 65 6e 74 20 76 61 6c 75  he "current valu
17920 65 22 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  e" returned by.*
17930 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74  * [sqlite3_db_st
17940 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f  atus](D,[SQLITE_
17950 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
17960 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a  ],...) is zero..
17970 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74  ** Any attempt t
17980 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f  o change the loo
17990 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f  kaside memory co
179a0 6e 66 69 67 75 72 61 74 69 6f 6e 20 77 68 65 6e  nfiguration when
179b0 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65   lookaside.** me
179c0 6d 6f 72 79 20 69 73 20 69 6e 20 75 73 65 20 6c  mory is in use l
179d0 65 61 76 65 73 20 74 68 65 20 63 6f 6e 66 69 67  eaves the config
179e0 75 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65  uration unchange
179f0 64 20 61 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a  d and returns .*
17a00 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e  * [SQLITE_BUSY].
17a10 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  )^</dd>.**.** <d
17a20 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
17a30 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64  G_ENABLE_FKEY</d
17a40 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
17a50 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
17a60 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73  to enable or dis
17a70 61 62 6c 65 20 74 68 65 20 65 6e 66 6f 72 63 65  able the enforce
17a80 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65  ment of.** [fore
17a90 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69  ign key constrai
17aa0 6e 74 73 5d 2e 20 20 54 68 65 72 65 20 73 68 6f  nts].  There sho
17ab0 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74  uld be two addit
17ac0 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e  ional arguments.
17ad0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
17ae0 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74  gument is an int
17af0 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20  eger which is 0 
17b00 74 6f 20 64 69 73 61 62 6c 65 20 46 4b 20 65 6e  to disable FK en
17b10 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f  forcement,.** po
17b20 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65  sitive to enable
17b30 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20   FK enforcement 
17b40 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c  or negative to l
17b50 65 61 76 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d  eave FK enforcem
17b60 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64  ent.** unchanged
17b70 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  .  The second pa
17b80 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
17b90 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
17ba0 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a  er into which.**
17bb0 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72   is written 0 or
17bc0 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77   1 to indicate w
17bd0 68 65 74 68 65 72 20 46 4b 20 65 6e 66 6f 72 63  hether FK enforc
17be0 65 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f 72 20  ement is off or 
17bf0 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  on.** following 
17c00 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20  this call.  The 
17c10 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
17c20 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70   may be a NULL p
17c30 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68  ointer, in.** wh
17c40 69 63 68 20 63 61 73 65 20 74 68 65 20 46 4b 20  ich case the FK 
17c50 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65 74 74  enforcement sett
17c60 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72  ing is not repor
17c70 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a  ted back. </dd>.
17c80 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
17c90 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
17ca0 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a  _TRIGGER</dt>.**
17cb0 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
17cc0 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e  on is used to en
17cd0 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20  able or disable 
17ce0 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20  [CREATE TRIGGER 
17cf0 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20  | triggers]..** 
17d00 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20  There should be 
17d10 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61  two additional a
17d20 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65  rguments..** The
17d30 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
17d40 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  is an integer wh
17d50 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61  ich is 0 to disa
17d60 62 6c 65 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a  ble triggers,.**
17d70 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61   positive to ena
17d80 62 6c 65 20 74 72 69 67 67 65 72 73 20 6f 72 20  ble triggers or 
17d90 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76  negative to leav
17da0 65 20 74 68 65 20 73 65 74 74 69 6e 67 20 75 6e  e the setting un
17db0 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20  changed..** The 
17dc0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
17dd0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
17de0 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f   an integer into
17df0 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69   which.** is wri
17e00 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69  tten 0 or 1 to i
17e10 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20  ndicate whether 
17e20 74 72 69 67 67 65 72 73 20 61 72 65 20 64 69 73  triggers are dis
17e30 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64  abled or enabled
17e40 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  .** following th
17e50 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65  is call.  The se
17e60 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d  cond parameter m
17e70 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69  ay be a NULL poi
17e80 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63  nter, in.** whic
17e90 68 20 63 61 73 65 20 74 68 65 20 74 72 69 67 67  h case the trigg
17ea0 65 72 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f  er setting is no
17eb0 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e  t reported back.
17ec0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74   </dd>.**.** <dt
17ed0 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
17ee0 5f 45 4e 41 42 4c 45 5f 46 54 53 33 5f 54 4f 4b  _ENABLE_FTS3_TOK
17ef0 45 4e 49 5a 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c  ENIZER</dt>.** <
17f00 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
17f10 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62   is used to enab
17f20 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68  le or disable th
17f30 65 20 74 77 6f 2d 61 72 67 75 6d 65 6e 74 0a 2a  e two-argument.*
17f40 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65  * version of the
17f50 20 5b 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72   [fts3_tokenizer
17f60 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 77 68 69  ()] function whi
17f70 63 68 20 69 73 20 70 61 72 74 20 6f 66 20 74 68  ch is part of th
17f80 65 0a 2a 2a 20 5b 46 54 53 33 5d 20 66 75 6c 6c  e.** [FTS3] full
17f90 2d 74 65 78 74 20 73 65 61 72 63 68 20 65 6e 67  -text search eng
17fa0 69 6e 65 20 65 78 74 65 6e 73 69 6f 6e 2e 0a 2a  ine extension..*
17fb0 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62  * There should b
17fc0 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c  e two additional
17fd0 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54   arguments..** T
17fe0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
17ff0 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  t is an integer 
18000 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69  which is 0 to di
18010 73 61 62 6c 65 20 66 74 73 33 5f 74 6f 6b 65 6e  sable fts3_token
18020 69 7a 65 72 28 29 20 6f 72 0a 2a 2a 20 70 6f 73  izer() or.** pos
18030 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20  itive to enable 
18040 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28 29  fts3_tokenizer()
18050 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20   or negative to 
18060 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e  leave the settin
18070 67 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 0a  g.** unchanged..
18080 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  ** The second pa
18090 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
180a0 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
180b0 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a  er into which.**
180c0 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72   is written 0 or
180d0 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77   1 to indicate w
180e0 68 65 74 68 65 72 20 66 74 73 33 5f 74 6f 6b 65  hether fts3_toke
180f0 6e 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65  nizer is disable
18100 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20  d or enabled.** 
18110 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63  following this c
18120 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  all.  The second
18130 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
18140 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  e a NULL pointer
18150 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61  , in.** which ca
18160 73 65 20 74 68 65 20 6e 65 77 20 73 65 74 74 69  se the new setti
18170 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74  ng is not report
18180 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a  ed back. </dd>.*
18190 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
181a0 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
181b0 4c 4f 41 44 5f 45 58 54 45 4e 53 49 4f 4e 3c 2f  LOAD_EXTENSION</
181c0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
181d0 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  s option is used
181e0 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69   to enable or di
181f0 73 61 62 6c 65 20 74 68 65 20 5b 73 71 6c 69 74  sable the [sqlit
18200 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  e3_load_extensio
18210 6e 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  n()].** interfac
18220 65 20 69 6e 64 65 70 65 6e 64 65 6e 74 6c 79 20  e independently 
18230 6f 66 20 74 68 65 20 5b 6c 6f 61 64 5f 65 78 74  of the [load_ext
18240 65 6e 73 69 6f 6e 28 29 5d 20 53 51 4c 20 66 75  ension()] SQL fu
18250 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20 5b  nction..** The [
18260 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c  sqlite3_enable_l
18270 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d  oad_extension()]
18280 20 41 50 49 20 65 6e 61 62 6c 65 73 20 6f 72 20   API enables or 
18290 64 69 73 61 62 6c 65 73 20 62 6f 74 68 20 74 68  disables both th
182a0 65 0a 2a 2a 20 43 2d 41 50 49 20 5b 73 71 6c 69  e.** C-API [sqli
182b0 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  te3_load_extensi
182c0 6f 6e 28 29 5d 20 61 6e 64 20 74 68 65 20 53 51  on()] and the SQ
182d0 4c 20 66 75 6e 63 74 69 6f 6e 20 5b 6c 6f 61 64  L function [load
182e0 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 2e 0a 2a  _extension()]..*
182f0 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62  * There should b
18300 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c  e two additional
18310 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 57   arguments..** W
18320 68 65 6e 20 74 68 65 20 66 69 72 73 74 20 61 72  hen the first ar
18330 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 69  gument to this i
18340 6e 74 65 72 66 61 63 65 20 69 73 20 31 2c 20 74  nterface is 1, t
18350 68 65 6e 20 6f 6e 6c 79 20 74 68 65 20 43 2d 41  hen only the C-A
18360 50 49 20 69 73 0a 2a 2a 20 65 6e 61 62 6c 65 64  PI is.** enabled
18370 20 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75 6e   and the SQL fun
18380 63 74 69 6f 6e 20 72 65 6d 61 69 6e 73 20 64 69  ction remains di
18390 73 61 62 6c 65 64 2e 20 20 49 66 20 74 68 65 20  sabled.  If the 
183a0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
183b0 6f 0a 2a 2a 20 74 68 69 73 20 69 6e 74 65 72 66  o.** this interf
183c0 61 63 65 20 69 73 20 30 2c 20 74 68 65 6e 20 62  ace is 0, then b
183d0 6f 74 68 20 74 68 65 20 43 2d 41 50 49 20 61 6e  oth the C-API an
183e0 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  d the SQL functi
183f0 6f 6e 20 61 72 65 20 64 69 73 61 62 6c 65 64 2e  on are disabled.
18400 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 72 73 74  .** If the first
18410 20 61 72 67 75 6d 65 6e 74 20 69 73 20 2d 31 2c   argument is -1,
18420 20 74 68 65 6e 20 6e 6f 20 63 68 61 6e 67 65 73   then no changes
18430 20 61 72 65 20 6d 61 64 65 20 74 6f 20 73 74 61   are made to sta
18440 74 65 20 6f 66 20 65 69 74 68 65 72 20 74 68 65  te of either the
18450 0a 2a 2a 20 43 2d 41 50 49 20 6f 72 20 74 68 65  .** C-API or the
18460 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a   SQL function..*
18470 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * The second par
18480 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
18490 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
184a0 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20  r into which.** 
184b0 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20  is written 0 or 
184c0 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  1 to indicate wh
184d0 65 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 6c  ether [sqlite3_l
184e0 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d  oad_extension()]
184f0 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 73   interface.** is
18500 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61   disabled or ena
18510 62 6c 65 64 20 66 6f 6c 6c 6f 77 69 6e 67 20 74  bled following t
18520 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73  his call.  The s
18530 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
18540 6d 61 79 0a 2a 2a 20 62 65 20 61 20 4e 55 4c 4c  may.** be a NULL
18550 20 70 6f 69 6e 74 65 72 2c 20 69 6e 20 77 68 69   pointer, in whi
18560 63 68 20 63 61 73 65 20 74 68 65 20 6e 65 77 20  ch case the new 
18570 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72  setting is not r
18580 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 0a 2a 2a  eported back..**
18590 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74   </dd>.**.** <dt
185a0 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
185b0 5f 4d 41 49 4e 44 42 4e 41 4d 45 3c 2f 64 74 3e  _MAINDBNAME</dt>
185c0 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
185d0 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f  ption is used to
185e0 20 63 68 61 6e 67 65 20 74 68 65 20 6e 61 6d 65   change the name
185f0 20 6f 66 20 74 68 65 20 22 6d 61 69 6e 22 20 64   of the "main" d
18600 61 74 61 62 61 73 65 0a 2a 2a 20 73 63 68 65 6d  atabase.** schem
18610 61 2e 20 20 5e 54 68 65 20 73 6f 6c 65 20 61 72  a.  ^The sole ar
18620 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
18630 74 65 72 20 74 6f 20 61 20 63 6f 6e 73 74 61 6e  ter to a constan
18640 74 20 55 54 46 38 20 73 74 72 69 6e 67 0a 2a 2a  t UTF8 string.**
18650 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65 63 6f   which will beco
18660 6d 65 20 74 68 65 20 6e 65 77 20 73 63 68 65 6d  me the new schem
18670 61 20 6e 61 6d 65 20 69 6e 20 70 6c 61 63 65 20  a name in place 
18680 6f 66 20 22 6d 61 69 6e 22 2e 20 20 5e 53 51 4c  of "main".  ^SQL
18690 69 74 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  ite.** does not 
186a0 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f 66 20 74  make a copy of t
186b0 68 65 20 6e 65 77 20 6d 61 69 6e 20 73 63 68 65  he new main sche
186c0 6d 61 20 6e 61 6d 65 20 73 74 72 69 6e 67 2c 20  ma name string, 
186d0 73 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  so the applicati
186e0 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e 73 75 72  on.** must ensur
186f0 65 20 74 68 61 74 20 74 68 65 20 61 72 67 75 6d  e that the argum
18700 65 6e 74 20 70 61 73 73 65 64 20 69 6e 74 6f 20  ent passed into 
18710 74 68 69 73 20 44 42 43 4f 4e 46 49 47 20 6f 70  this DBCONFIG op
18720 74 69 6f 6e 20 69 73 20 75 6e 63 68 61 6e 67 65  tion is unchange
18730 64 0a 2a 2a 20 75 6e 74 69 6c 20 61 66 74 65 72  d.** until after
18740 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
18750 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e  nnection closes.
18760 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .** </dd>.**.** 
18770 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
18780 46 49 47 5f 4e 4f 5f 43 4b 50 54 5f 4f 4e 5f 43  FIG_NO_CKPT_ON_C
18790 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LOSE</dt>.** <dd
187a0 3e 20 55 73 75 61 6c 6c 79 2c 20 77 68 65 6e 20  > Usually, when 
187b0 61 20 64 61 74 61 62 61 73 65 20 69 6e 20 77 61  a database in wa
187c0 6c 20 6d 6f 64 65 20 69 73 20 63 6c 6f 73 65 64  l mode is closed
187d0 20 6f 72 20 64 65 74 61 63 68 65 64 20 66 72 6f   or detached fro
187e0 6d 20 61 20 0a 2a 2a 20 64 61 74 61 62 61 73 65  m a .** database
187f0 20 68 61 6e 64 6c 65 2c 20 53 51 4c 69 74 65 20   handle, SQLite 
18800 63 68 65 63 6b 73 20 69 66 20 74 68 69 73 20 77  checks if this w
18810 69 6c 6c 20 6d 65 61 6e 20 74 68 61 74 20 74 68  ill mean that th
18820 65 72 65 20 61 72 65 20 6e 6f 77 20 6e 6f 20 0a  ere are now no .
18830 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 61  ** connections a
18840 74 20 61 6c 6c 20 74 6f 20 74 68 65 20 64 61 74  t all to the dat
18850 61 62 61 73 65 2e 20 49 66 20 73 6f 2c 20 69 74  abase. If so, it
18860 20 70 65 72 66 6f 72 6d 73 20 61 20 63 68 65 63   performs a chec
18870 6b 70 6f 69 6e 74 20 0a 2a 2a 20 6f 70 65 72 61  kpoint .** opera
18880 74 69 6f 6e 20 62 65 66 6f 72 65 20 63 6c 6f 73  tion before clos
18890 69 6e 67 20 74 68 65 20 63 6f 6e 6e 65 63 74 69  ing the connecti
188a0 6f 6e 2e 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  on. This option 
188b0 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f 0a 2a  may be used to.*
188c0 2a 20 6f 76 65 72 72 69 64 65 20 74 68 69 73 20  * override this 
188d0 62 65 68 61 76 69 6f 75 72 2e 20 54 68 65 20 66  behaviour. The f
188e0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 70  irst parameter p
188f0 61 73 73 65 64 20 74 6f 20 74 68 69 73 20 6f 70  assed to this op
18900 65 72 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 61 6e  eration.** is an
18910 20 69 6e 74 65 67 65 72 20 2d 20 6e 6f 6e 2d 7a   integer - non-z
18920 65 72 6f 20 74 6f 20 64 69 73 61 62 6c 65 20 63  ero to disable c
18930 68 65 63 6b 70 6f 69 6e 74 73 2d 6f 6e 2d 63 6c  heckpoints-on-cl
18940 6f 73 65 2c 20 6f 72 20 7a 65 72 6f 20 28 74 68  ose, or zero (th
18950 65 0a 2a 2a 20 64 65 66 61 75 6c 74 29 20 74 6f  e.** default) to
18960 20 65 6e 61 62 6c 65 20 74 68 65 6d 2e 20 54 68   enable them. Th
18970 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
18980 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  er is a pointer 
18990 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  to an integer.**
189a0 20 69 6e 74 6f 20 77 68 69 63 68 20 69 73 20 77   into which is w
189b0 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f  ritten 0 or 1 to
189c0 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65   indicate whethe
189d0 72 20 63 68 65 63 6b 70 6f 69 6e 74 73 2d 6f 6e  r checkpoints-on
189e0 2d 63 6c 6f 73 65 0a 2a 2a 20 68 61 76 65 20 62  -close.** have b
189f0 65 65 6e 20 64 69 73 61 62 6c 65 64 20 2d 20 30  een disabled - 0
18a00 20 69 66 20 74 68 65 79 20 61 72 65 20 6e 6f 74   if they are not
18a10 20 64 69 73 61 62 6c 65 64 2c 20 31 20 69 66 20   disabled, 1 if 
18a20 74 68 65 79 20 61 72 65 2e 0a 2a 2a 20 3c 2f 64  they are..** </d
18a30 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
18a40 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
18a50 42 4c 45 5f 51 50 53 47 3c 2f 64 74 3e 0a 2a 2a  BLE_QPSG</dt>.**
18a60 20 3c 64 64 3e 54 68 65 20 53 51 4c 49 54 45 5f   <dd>The SQLITE_
18a70 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
18a80 51 50 53 47 20 6f 70 74 69 6f 6e 20 61 63 74 69  QPSG option acti
18a90 76 61 74 65 73 20 6f 72 20 64 65 61 63 74 69 76  vates or deactiv
18aa0 61 74 65 73 0a 2a 2a 20 74 68 65 20 5b 71 75 65  ates.** the [que
18ab0 72 79 20 70 6c 61 6e 6e 65 72 20 73 74 61 62 69  ry planner stabi
18ac0 6c 69 74 79 20 67 75 61 72 61 6e 74 65 65 5d 20  lity guarantee] 
18ad0 28 51 50 53 47 29 2e 20 20 57 68 65 6e 20 74 68  (QPSG).  When th
18ae0 65 20 51 50 53 47 20 69 73 20 61 63 74 69 76 65  e QPSG is active
18af0 2c 0a 2a 2a 20 61 20 73 69 6e 67 6c 65 20 53 51  ,.** a single SQ
18b00 4c 20 71 75 65 72 79 20 73 74 61 74 65 6d 65 6e  L query statemen
18b10 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 75 73  t will always us
18b20 65 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72  e the same algor
18b30 69 74 68 6d 20 72 65 67 61 72 64 6c 65 73 73 0a  ithm regardless.
18b40 2a 2a 20 6f 66 20 76 61 6c 75 65 73 20 6f 66 20  ** of values of 
18b50 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72  [bound parameter
18b60 73 5d 2e 20 20 54 68 65 20 51 50 53 47 20 64 69  s].  The QPSG di
18b70 73 61 62 6c 65 73 20 73 6f 6d 65 20 71 75 65 72  sables some quer
18b80 79 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 0a  y optimizations.
18b90 2a 2a 20 74 68 61 74 20 6c 6f 6f 6b 20 61 74 20  ** that look at 
18ba0 74 68 65 20 76 61 6c 75 65 73 20 6f 66 20 62 6f  the values of bo
18bb0 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 2c 20  und parameters, 
18bc0 77 68 69 63 68 20 63 61 6e 20 6d 61 6b 65 20 73  which can make s
18bd0 6f 6d 65 20 71 75 65 72 69 65 73 0a 2a 2a 20 73  ome queries.** s
18be0 6c 6f 77 65 72 2e 20 20 42 75 74 20 74 68 65 20  lower.  But the 
18bf0 51 50 53 47 20 68 61 73 20 74 68 65 20 61 64 76  QPSG has the adv
18c00 61 6e 74 61 67 65 20 6f 66 20 6d 6f 72 65 20 70  antage of more p
18c10 72 65 64 69 63 74 61 62 6c 65 20 62 65 68 61 76  redictable behav
18c20 69 6f 72 2e 20 20 57 69 74 68 0a 2a 2a 20 74 68  ior.  With.** th
18c30 65 20 51 50 53 47 20 61 63 74 69 76 65 2c 20 53  e QPSG active, S
18c40 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79  QLite will alway
18c50 73 20 75 73 65 20 74 68 65 20 73 61 6d 65 20 71  s use the same q
18c60 75 65 72 79 20 70 6c 61 6e 20 69 6e 20 74 68 65  uery plan in the
18c70 20 66 69 65 6c 64 20 61 73 0a 2a 2a 20 77 61 73   field as.** was
18c80 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73   used during tes
18c90 74 69 6e 67 20 69 6e 20 74 68 65 20 6c 61 62 2e  ting in the lab.
18ca0 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .** </dd>.**.** 
18cb0 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
18cc0 46 49 47 5f 50 52 45 50 41 52 45 5f 46 4c 41 47  FIG_PREPARE_FLAG
18cd0 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  S</dt>.** <dd>Th
18ce0 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
18cf0 47 5f 50 52 45 50 41 52 45 5f 46 4c 41 47 53 20  G_PREPARE_FLAGS 
18d00 6f 62 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20  obption takes a 
18d10 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 0a  single argument.
18d20 2a 2a 20 77 68 69 63 68 20 69 73 20 61 20 62 69  ** which is a bi
18d30 74 6d 61 73 6b 20 6f 66 20 7a 65 72 6f 20 6f 72  tmask of zero or
18d40 20 6d 6f 72 65 20 5b 53 51 4c 49 54 45 5f 50 52   more [SQLITE_PR
18d50 45 50 41 52 45 5f 50 45 52 53 49 53 54 45 4e 54  EPARE_PERSISTENT
18d60 7c 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5d  |SQLITE_PREPARE]
18d70 0a 2a 2a 20 6f 70 74 69 6f 6e 73 2e 20 20 54 68  .** options.  Th
18d80 65 20 73 65 6c 65 63 74 65 64 20 6f 70 74 69 6f  e selected optio
18d90 6e 73 20 61 72 65 20 61 70 70 6c 69 65 64 20 74  ns are applied t
18da0 6f 20 74 68 65 20 6e 65 78 74 20 5b 73 71 6c 69  o the next [sqli
18db0 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 2c 0a  te3_prepare()],.
18dc0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
18dd0 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69  are_v2()], [sqli
18de0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
18df0 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  , or [sqlite3_pr
18e00 65 70 61 72 65 31 36 5f 76 32 28 29 5d 0a 2a 2a  epare16_v2()].**
18e10 20 63 61 6c 6c 20 6f 6e 20 74 68 65 20 73 61 6d   call on the sam
18e20 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
18e30 63 74 69 6f 6e 2e 20 20 54 68 65 20 70 72 65 70  ction.  The prep
18e40 61 72 65 20 66 6c 61 67 73 20 61 72 65 20 72 65  are flags are re
18e50 73 65 74 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 61  set to zero.** a
18e60 66 74 65 72 20 61 20 73 69 6e 67 6c 65 20 75 73  fter a single us
18e70 65 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  e..** </dd>.**.*
18e80 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </dl>.*/.#defi
18e90 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
18ea0 49 47 5f 4d 41 49 4e 44 42 4e 41 4d 45 20 20 20  IG_MAINDBNAME   
18eb0 20 20 20 20 20 20 20 20 20 31 30 30 30 20 2f 2a           1000 /*
18ec0 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 2a 2f 0a   const char* */.
18ed0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
18ee0 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
18ef0 45 20 20 20 20 20 20 20 20 20 20 20 20 20 31 30  E             10
18f00 30 31 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20  01 /* void* int 
18f10 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  int */.#define S
18f20 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
18f30 4e 41 42 4c 45 5f 46 4b 45 59 20 20 20 20 20 20  NABLE_FKEY      
18f40 20 20 20 20 20 31 30 30 32 20 2f 2a 20 69 6e 74       1002 /* int
18f50 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65   int* */.#define
18f60 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
18f70 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 20  _ENABLE_TRIGGER 
18f80 20 20 20 20 20 20 20 31 30 30 33 20 2f 2a 20 69         1003 /* i
18f90 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69  nt int* */.#defi
18fa0 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
18fb0 49 47 5f 45 4e 41 42 4c 45 5f 46 54 53 33 5f 54  IG_ENABLE_FTS3_T
18fc0 4f 4b 45 4e 49 5a 45 52 20 31 30 30 34 20 2f 2a  OKENIZER 1004 /*
18fd0 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65   int int* */.#de
18fe0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
18ff0 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 4c 4f 41 44  NFIG_ENABLE_LOAD
19000 5f 45 58 54 45 4e 53 49 4f 4e 20 31 30 30 35 20  _EXTENSION 1005 
19010 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23  /* int int* */.#
19020 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
19030 43 4f 4e 46 49 47 5f 4e 4f 5f 43 4b 50 54 5f 4f  CONFIG_NO_CKPT_O
19040 4e 5f 43 4c 4f 53 45 20 20 20 20 20 20 31 30 30  N_CLOSE      100
19050 36 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f  6 /* int int* */
19060 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
19070 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
19080 51 50 53 47 20 20 20 20 20 20 20 20 20 20 20 31  QPSG           1
19090 30 30 37 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20  007 /* int int* 
190a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
190b0 45 5f 44 42 43 4f 4e 46 49 47 5f 50 52 45 50 41  E_DBCONFIG_PREPA
190c0 52 45 5f 46 4c 41 47 53 20 20 20 20 20 20 20 20  RE_FLAGS        
190d0 20 31 30 30 38 20 2f 2a 20 69 6e 74 20 2a 2f 0a   1008 /* int */.
190e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
190f0 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61  : Enable Or Disa
19100 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65 73  ble Extended Res
19110 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4d 45 54  ult Codes.** MET
19120 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
19130 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
19140 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
19150 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20  codes() routine 
19160 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
19170 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65  les the.** [exte
19180 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
19190 73 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53 51  s] feature of SQ
191a0 4c 69 74 65 2e 20 5e 54 68 65 20 65 78 74 65 6e  Lite. ^The exten
191b0 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f  ded result.** co
191c0 64 65 73 20 61 72 65 20 64 69 73 61 62 6c 65 64  des are disabled
191d0 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20   by default for 
191e0 68 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61  historical compa
191f0 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74  tibility..*/.int
19200 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
19210 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73  d_result_codes(s
19220 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f  qlite3*, int ono
19230 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ff);../*.** CAPI
19240 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72  3REF: Last Inser
19250 74 20 52 6f 77 69 64 0a 2a 2a 20 4d 45 54 48 4f  t Rowid.** METHO
19260 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
19270 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20   ^Each entry in 
19280 6d 6f 73 74 20 53 51 4c 69 74 65 20 74 61 62 6c  most SQLite tabl
19290 65 73 20 28 65 78 63 65 70 74 20 66 6f 72 20 5b  es (except for [
192a0 57 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74  WITHOUT ROWID] t
192b0 61 62 6c 65 73 29 0a 2a 2a 20 68 61 73 20 61 20  ables).** has a 
192c0 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73 69  unique 64-bit si
192d0 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20  gned.** integer 
192e0 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b  key called the [
192f0 52 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d  ROWID | "rowid"]
19300 2e 20 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20  . ^The rowid is 
19310 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65  always available
19320 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c  .** as an undecl
19330 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65  ared column name
19340 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72  d ROWID, OID, or
19350 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67   _ROWID_ as long
19360 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d   as those.** nam
19370 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20  es are not also 
19380 75 73 65 64 20 62 79 20 65 78 70 6c 69 63 69 74  used by explicit
19390 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75  ly declared colu
193a0 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20  mns. ^If.** the 
193b0 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75  table has a colu
193c0 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45  mn of type [INTE
193d0 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d  GER PRIMARY KEY]
193e0 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d   then that colum
193f0 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20  n.** is another 
19400 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f  alias for the ro
19410 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  wid..**.** ^The 
19420 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
19430 65 72 74 5f 72 6f 77 69 64 28 44 29 20 69 6e 74  ert_rowid(D) int
19440 65 72 66 61 63 65 20 75 73 75 61 6c 6c 79 20 72  erface usually r
19450 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69  eturns the [rowi
19460 64 5d 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 6f 73  d] of.** the mos
19470 74 20 72 65 63 65 6e 74 20 73 75 63 63 65 73 73  t recent success
19480 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74  ful [INSERT] int
19490 6f 20 61 20 72 6f 77 69 64 20 74 61 62 6c 65 20  o a rowid table 
194a0 6f 72 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  or [virtual tabl
194b0 65 5d 0a 2a 2a 20 6f 6e 20 64 61 74 61 62 61 73  e].** on databas
194c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20  e connection D. 
194d0 5e 49 6e 73 65 72 74 73 20 69 6e 74 6f 20 5b 57  ^Inserts into [W
194e0 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61  ITHOUT ROWID] ta
194f0 62 6c 65 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20  bles are not.** 
19500 72 65 63 6f 72 64 65 64 2e 20 5e 49 66 20 6e 6f  recorded. ^If no
19510 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53   successful [INS
19520 45 52 54 5d 73 20 69 6e 74 6f 20 72 6f 77 69 64  ERT]s into rowid
19530 20 74 61 62 6c 65 73 20 68 61 76 65 20 65 76 65   tables have eve
19540 72 20 6f 63 63 75 72 72 65 64 20 0a 2a 2a 20 6f  r occurred .** o
19550 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
19560 6f 6e 6e 65 63 74 69 6f 6e 20 44 2c 20 74 68 65  onnection D, the
19570 6e 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69  n sqlite3_last_i
19580 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20 72  nsert_rowid(D) r
19590 65 74 75 72 6e 73 20 0a 2a 2a 20 7a 65 72 6f 2e  eturns .** zero.
195a0 0a 2a 2a 0a 2a 2a 20 41 73 20 77 65 6c 6c 20 61  .**.** As well a
195b0 73 20 62 65 69 6e 67 20 73 65 74 20 61 75 74 6f  s being set auto
195c0 6d 61 74 69 63 61 6c 6c 79 20 61 73 20 72 6f 77  matically as row
195d0 73 20 61 72 65 20 69 6e 73 65 72 74 65 64 20 69  s are inserted i
195e0 6e 74 6f 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  nto database.** 
195f0 74 61 62 6c 65 73 2c 20 74 68 65 20 76 61 6c 75  tables, the valu
19600 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  e returned by th
19610 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20  is function may 
19620 62 65 20 73 65 74 20 65 78 70 6c 69 63 69 74 6c  be set explicitl
19630 79 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  y by.** [sqlite3
19640 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72 74  _set_last_insert
19650 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 0a 2a 2a 20  _rowid()].**.** 
19660 53 6f 6d 65 20 76 69 72 74 75 61 6c 20 74 61 62  Some virtual tab
19670 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
19680 6e 73 20 6d 61 79 20 49 4e 53 45 52 54 20 72 6f  ns may INSERT ro
19690 77 73 20 69 6e 74 6f 20 72 6f 77 69 64 20 74 61  ws into rowid ta
196a0 62 6c 65 73 20 61 73 0a 2a 2a 20 70 61 72 74 20  bles as.** part 
196b0 6f 66 20 63 6f 6d 6d 69 74 74 69 6e 67 20 61 20  of committing a 
196c0 74 72 61 6e 73 61 63 74 69 6f 6e 20 28 65 2e 67  transaction (e.g
196d0 2e 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20  . to flush data 
196e0 61 63 63 75 6d 75 6c 61 74 65 64 20 69 6e 20 6d  accumulated in m
196f0 65 6d 6f 72 79 0a 2a 2a 20 74 6f 20 64 69 73 6b  emory.** to disk
19700 29 2e 20 49 6e 20 74 68 69 73 20 63 61 73 65 20  ). In this case 
19710 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
19720 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f   to this functio
19730 6e 20 72 65 74 75 72 6e 20 74 68 65 20 72 6f 77  n return the row
19740 69 64 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  id.** associated
19750 20 77 69 74 68 20 74 68 65 73 65 20 69 6e 74 65   with these inte
19760 72 6e 61 6c 20 49 4e 53 45 52 54 20 6f 70 65 72  rnal INSERT oper
19770 61 74 69 6f 6e 73 2c 20 77 68 69 63 68 20 6c 65  ations, which le
19780 61 64 73 20 74 6f 20 0a 2a 2a 20 75 6e 69 6e 74  ads to .** unint
19790 75 69 74 69 76 65 20 72 65 73 75 6c 74 73 2e 20  uitive results. 
197a0 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d  Virtual table im
197b0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 68  plementations th
197c0 61 74 20 64 6f 20 77 72 69 74 65 20 74 6f 20 72  at do write to r
197d0 6f 77 69 64 0a 2a 2a 20 74 61 62 6c 65 73 20 69  owid.** tables i
197e0 6e 20 74 68 69 73 20 77 61 79 20 63 61 6e 20 61  n this way can a
197f0 76 6f 69 64 20 74 68 69 73 20 70 72 6f 62 6c 65  void this proble
19800 6d 20 62 79 20 72 65 73 74 6f 72 69 6e 67 20 74  m by restoring t
19810 68 65 20 6f 72 69 67 69 6e 61 6c 20 0a 2a 2a 20  he original .** 
19820 72 6f 77 69 64 20 76 61 6c 75 65 20 75 73 69 6e  rowid value usin
19830 67 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c  g [sqlite3_set_l
19840 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
19850 28 29 5d 20 62 65 66 6f 72 65 20 72 65 74 75 72  ()] before retur
19860 6e 69 6e 67 20 0a 2a 2a 20 63 6f 6e 74 72 6f 6c  ning .** control
19870 20 74 6f 20 74 68 65 20 75 73 65 72 2e 0a 2a 2a   to the user..**
19880 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53  .** ^(If an [INS
19890 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68  ERT] occurs with
198a0 69 6e 20 61 20 74 72 69 67 67 65 72 20 74 68 65  in a trigger the
198b0 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  n this routine w
198c0 69 6c 6c 20 0a 2a 2a 20 72 65 74 75 72 6e 20 74  ill .** return t
198d0 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68  he [rowid] of th
198e0 65 20 69 6e 73 65 72 74 65 64 20 72 6f 77 20 61  e inserted row a
198f0 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72  s long as the tr
19900 69 67 67 65 72 20 69 73 20 0a 2a 2a 20 72 75 6e  igger is .** run
19910 6e 69 6e 67 2e 20 4f 6e 63 65 20 74 68 65 20 74  ning. Once the t
19920 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 65  rigger program e
19930 6e 64 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72  nds, the value r
19940 65 74 75 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74  eturned .** by t
19950 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 76 65  his routine reve
19960 72 74 73 20 74 6f 20 77 68 61 74 20 69 74 20 77  rts to what it w
19970 61 73 20 62 65 66 6f 72 65 20 74 68 65 20 74 72  as before the tr
19980 69 67 67 65 72 20 77 61 73 20 66 69 72 65 64 2e  igger was fired.
19990 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e  )^.**.** ^An [IN
199a0 53 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73  SERT] that fails
199b0 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72   due to a constr
199c0 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69  aint violation i
199d0 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65  s not a.** succe
199e0 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61  ssful [INSERT] a
199f0 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  nd does not chan
19a00 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ge the value ret
19a10 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a  urned by this.**
19a20 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 73   routine.  ^Thus
19a30 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c   INSERT OR FAIL,
19a40 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52   INSERT OR IGNOR
19a50 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c  E, INSERT OR ROL
19a60 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e  LBACK,.** and IN
19a70 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61  SERT OR ABORT ma
19a80 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f  ke no changes to
19a90 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
19aa0 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75  e of this.** rou
19ab0 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20  tine when their 
19ac0 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e  insertion fails.
19ad0 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 20    ^(When INSERT 
19ae0 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e  OR REPLACE.** en
19af0 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74  counters a const
19b00 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c  raint violation,
19b10 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69   it does not fai
19b20 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52  l.  The.** INSER
19b30 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63  T continues to c
19b40 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20  ompletion after 
19b50 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68  deleting rows th
19b60 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65  at caused.** the
19b70 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62   constraint prob
19b80 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52  lem so INSERT OR
19b90 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c   REPLACE will al
19ba0 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74  ways change.** t
19bb0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
19bc0 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  of this interfac
19bd0 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20  e.)^.**.** ^For 
19be0 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20  the purposes of 
19bf0 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e  this routine, an
19c00 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e   [INSERT] is con
19c10 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65  sidered to.** be
19c20 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e   successful even
19c30 20 69 66 20 69 74 20 69 73 20 73 75 62 73 65 71   if it is subseq
19c40 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61  uently rolled ba
19c50 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66  ck..**.** This f
19c60 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65 73  unction is acces
19c70 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 61  sible to SQL sta
19c80 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65 0a  tements via the.
19c90 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f  ** [last_insert_
19ca0 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e 63  rowid() SQL func
19cb0 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  tion]..**.** If 
19cc0 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
19cd0 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77  d performs a new
19ce0 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65   [INSERT] on the
19cf0 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73   same.** databas
19d00 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69  e connection whi
19d10 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  le the [sqlite3_
19d20 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
19d30 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  d()].** function
19d40 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20   is running and 
19d50 74 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 65  thus changes the
19d60 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f   last insert [ro
19d70 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  wid],.** then th
19d80 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
19d90 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73   by [sqlite3_las
19da0 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
19db0 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63  ] is.** unpredic
19dc0 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20  table and might 
19dd0 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65 72  not equal either
19de0 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20   the old or the 
19df0 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65  new.** last inse
19e00 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73  rt [rowid]..*/.s
19e10 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
19e20 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
19e30 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29  _rowid(sqlite3*)
19e40 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
19e50 46 3a 20 53 65 74 20 74 68 65 20 4c 61 73 74 20  F: Set the Last 
19e60 49 6e 73 65 72 74 20 52 6f 77 69 64 20 76 61 6c  Insert Rowid val
19e70 75 65 2e 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ue..** METHOD: s
19e80 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65  qlite3.**.** The
19e90 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73   sqlite3_set_las
19ea0 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44  t_insert_rowid(D
19eb0 2c 20 52 29 20 6d 65 74 68 6f 64 20 61 6c 6c 6f  , R) method allo
19ec0 77 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ws the applicati
19ed0 6f 6e 20 74 6f 0a 2a 2a 20 73 65 74 20 74 68 65  on to.** set the
19ee0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
19ef0 62 79 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74  by calling sqlit
19f00 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
19f10 6f 77 69 64 28 44 29 20 74 6f 20 52 20 0a 2a 2a  owid(D) to R .**
19f20 20 77 69 74 68 6f 75 74 20 69 6e 73 65 72 74 69   without inserti
19f30 6e 67 20 61 20 72 6f 77 20 69 6e 74 6f 20 74 68  ng a row into th
19f40 65 20 64 61 74 61 62 61 73 65 2e 0a 2a 2f 0a 76  e database..*/.v
19f50 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  oid sqlite3_set_
19f60 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
19f70 64 28 73 71 6c 69 74 65 33 2a 2c 73 71 6c 69 74  d(sqlite3*,sqlit
19f80 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a  e3_int64);../*.*
19f90 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e  * CAPI3REF: Coun
19fa0 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20  t The Number Of 
19fb0 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a  Rows Modified.**
19fc0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
19fd0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
19fe0 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
19ff0 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  e number of rows
1a000 20 6d 6f 64 69 66 69 65 64 2c 20 69 6e 73 65 72   modified, inser
1a010 74 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 65  ted or.** delete
1a020 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65  d by the most re
1a030 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64  cently completed
1a040 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20   INSERT, UPDATE 
1a050 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61  or DELETE.** sta
1a060 74 65 6d 65 6e 74 20 6f 6e 20 74 68 65 20 64 61  tement on the da
1a070 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1a080 6e 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  n specified by t
1a090 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65  he only paramete
1a0a0 72 2e 0a 2a 2a 20 5e 45 78 65 63 75 74 69 6e 67  r..** ^Executing
1a0b0 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20   any other type 
1a0c0 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  of SQL statement
1a0d0 20 64 6f 65 73 20 6e 6f 74 20 6d 6f 64 69 66 79   does not modify
1a0e0 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65   the value.** re
1a0f0 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 66  turned by this f
1a100 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  unction..**.** ^
1a110 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61 64  Only changes mad
1a120 65 20 64 69 72 65 63 74 6c 79 20 62 79 20 74 68  e directly by th
1a130 65 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  e INSERT, UPDATE
1a140 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65   or DELETE state
1a150 6d 65 6e 74 20 61 72 65 0a 2a 2a 20 63 6f 6e 73  ment are.** cons
1a160 69 64 65 72 65 64 20 2d 20 61 75 78 69 6c 69 61  idered - auxilia
1a170 72 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65  ry changes cause
1a180 64 20 62 79 20 5b 43 52 45 41 54 45 20 54 52 49  d by [CREATE TRI
1a190 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d  GGER | triggers]
1a1a0 2c 20 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b  , .** [foreign k
1a1b0 65 79 20 61 63 74 69 6f 6e 73 5d 20 6f 72 20 5b  ey actions] or [
1a1c0 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61  REPLACE] constra
1a1d0 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61  int resolution a
1a1e0 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a  re not counted..
1a1f0 2a 2a 20 0a 2a 2a 20 43 68 61 6e 67 65 73 20 74  ** .** Changes t
1a200 6f 20 61 20 76 69 65 77 20 74 68 61 74 20 61 72  o a view that ar
1a210 65 20 69 6e 74 65 72 63 65 70 74 65 64 20 62 79  e intercepted by
1a220 20 0a 2a 2a 20 5b 49 4e 53 54 45 41 44 20 4f 46   .** [INSTEAD OF
1a230 20 74 72 69 67 67 65 72 20 7c 20 49 4e 53 54 45   trigger | INSTE
1a240 41 44 20 4f 46 20 74 72 69 67 67 65 72 73 5d 20  AD OF triggers] 
1a250 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e  are not counted.
1a260 20 5e 54 68 65 20 76 61 6c 75 65 20 0a 2a 2a 20   ^The value .** 
1a270 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
1a280 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6d  te3_changes() im
1a290 6d 65 64 69 61 74 65 6c 79 20 61 66 74 65 72 20  mediately after 
1a2a0 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  an INSERT, UPDAT
1a2b0 45 20 6f 72 20 0a 2a 2a 20 44 45 4c 45 54 45 20  E or .** DELETE 
1a2c0 73 74 61 74 65 6d 65 6e 74 20 72 75 6e 20 6f 6e  statement run on
1a2d0 20 61 20 76 69 65 77 20 69 73 20 61 6c 77 61 79   a view is alway
1a2e0 73 20 7a 65 72 6f 2e 20 4f 6e 6c 79 20 63 68 61  s zero. Only cha
1a2f0 6e 67 65 73 20 6d 61 64 65 20 74 6f 20 72 65 61  nges made to rea
1a300 6c 20 0a 2a 2a 20 74 61 62 6c 65 73 20 61 72 65  l .** tables are
1a310 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20   counted..**.** 
1a320 54 68 69 6e 67 73 20 61 72 65 20 6d 6f 72 65 20  Things are more 
1a330 63 6f 6d 70 6c 69 63 61 74 65 64 20 69 66 20 74  complicated if t
1a340 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  he sqlite3_chang
1a350 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  es() function is
1a360 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 77 68 69  .** executed whi
1a370 6c 65 20 61 20 74 72 69 67 67 65 72 20 70 72 6f  le a trigger pro
1a380 67 72 61 6d 20 69 73 20 72 75 6e 6e 69 6e 67 2e  gram is running.
1a390 20 54 68 69 73 20 6d 61 79 20 68 61 70 70 65 6e   This may happen
1a3a0 20 69 66 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72   if the.** progr
1a3b0 61 6d 20 75 73 65 73 20 74 68 65 20 5b 63 68 61  am uses the [cha
1a3c0 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74  nges() SQL funct
1a3d0 69 6f 6e 5d 2c 20 6f 72 20 69 66 20 73 6f 6d 65  ion], or if some
1a3e0 20 6f 74 68 65 72 20 63 61 6c 6c 62 61 63 6b 0a   other callback.
1a3f0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 6e 76 6f  ** function invo
1a400 6b 65 73 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  kes sqlite3_chan
1a410 67 65 73 28 29 20 64 69 72 65 63 74 6c 79 2e 20  ges() directly. 
1a420 45 73 73 65 6e 74 69 61 6c 6c 79 3a 0a 2a 2a 20  Essentially:.** 
1a430 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  .** <ul>.**   <l
1a440 69 3e 20 5e 28 42 65 66 6f 72 65 20 65 6e 74 65  i> ^(Before ente
1a450 72 69 6e 67 20 61 20 74 72 69 67 67 65 72 20 70  ring a trigger p
1a460 72 6f 67 72 61 6d 20 74 68 65 20 76 61 6c 75 65  rogram the value
1a470 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
1a480 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63         sqlite3_c
1a490 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f  hanges() functio
1a4a0 6e 20 69 73 20 73 61 76 65 64 2e 20 41 66 74 65  n is saved. Afte
1a4b0 72 20 74 68 65 20 74 72 69 67 67 65 72 20 70 72  r the trigger pr
1a4c0 6f 67 72 61 6d 20 0a 2a 2a 20 20 20 20 20 20 20  ogram .**       
1a4d0 20 68 61 73 20 66 69 6e 69 73 68 65 64 2c 20 74   has finished, t
1a4e0 68 65 20 6f 72 69 67 69 6e 61 6c 20 76 61 6c 75  he original valu
1a4f0 65 20 69 73 20 72 65 73 74 6f 72 65 64 2e 29 5e  e is restored.)^
1a500 0a 2a 2a 20 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e  .** .**   <li> ^
1a510 28 57 69 74 68 69 6e 20 61 20 74 72 69 67 67 65  (Within a trigge
1a520 72 20 70 72 6f 67 72 61 6d 20 65 61 63 68 20 49  r program each I
1a530 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 61 6e  NSERT, UPDATE an
1a540 64 20 44 45 4c 45 54 45 20 0a 2a 2a 20 20 20 20  d DELETE .**    
1a550 20 20 20 20 73 74 61 74 65 6d 65 6e 74 20 73 65      statement se
1a560 74 73 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ts the value ret
1a570 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
1a580 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20  _changes() .**  
1a590 20 20 20 20 20 20 75 70 6f 6e 20 63 6f 6d 70 6c        upon compl
1a5a0 65 74 69 6f 6e 20 61 73 20 6e 6f 72 6d 61 6c 2e  etion as normal.
1a5b0 20 4f 66 20 63 6f 75 72 73 65 2c 20 74 68 69 73   Of course, this
1a5c0 20 76 61 6c 75 65 20 77 69 6c 6c 20 6e 6f 74 20   value will not 
1a5d0 69 6e 63 6c 75 64 65 20 0a 2a 2a 20 20 20 20 20  include .**     
1a5e0 20 20 20 61 6e 79 20 63 68 61 6e 67 65 73 20 70     any changes p
1a5f0 65 72 66 6f 72 6d 65 64 20 62 79 20 73 75 62 2d  erformed by sub-
1a600 74 72 69 67 67 65 72 73 2c 20 61 73 20 74 68 65  triggers, as the
1a610 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
1a620 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 76 61  () .**        va
1a630 6c 75 65 20 77 69 6c 6c 20 62 65 20 73 61 76 65  lue will be save
1a640 64 20 61 6e 64 20 72 65 73 74 6f 72 65 64 20 61  d and restored a
1a650 66 74 65 72 20 65 61 63 68 20 73 75 62 2d 74 72  fter each sub-tr
1a660 69 67 67 65 72 20 68 61 73 20 72 75 6e 2e 29 5e  igger has run.)^
1a670 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a  .** </ul>.** .**
1a680 20 5e 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61   ^This means tha
1a690 74 20 69 66 20 74 68 65 20 63 68 61 6e 67 65 73  t if the changes
1a6a0 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  () SQL function 
1a6b0 28 6f 72 20 73 69 6d 69 6c 61 72 29 20 69 73 20  (or similar) is 
1a6c0 75 73 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 66  used.** by the f
1a6d0 69 72 73 74 20 49 4e 53 45 52 54 2c 20 55 50 44  irst INSERT, UPD
1a6e0 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74  ATE or DELETE st
1a6f0 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61  atement within a
1a700 20 74 72 69 67 67 65 72 2c 20 69 74 20 0a 2a 2a   trigger, it .**
1a710 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c   returns the val
1a720 75 65 20 61 73 20 73 65 74 20 77 68 65 6e 20 74  ue as set when t
1a730 68 65 20 63 61 6c 6c 69 6e 67 20 73 74 61 74 65  he calling state
1a740 6d 65 6e 74 20 62 65 67 61 6e 20 65 78 65 63 75  ment began execu
1a750 74 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 69 74 20  ting..** ^If it 
1a760 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20 73  is used by the s
1a770 65 63 6f 6e 64 20 6f 72 20 73 75 62 73 65 71 75  econd or subsequ
1a780 65 6e 74 20 73 75 63 68 20 73 74 61 74 65 6d 65  ent such stateme
1a790 6e 74 20 77 69 74 68 69 6e 20 61 20 74 72 69 67  nt within a trig
1a7a0 67 65 72 20 0a 2a 2a 20 70 72 6f 67 72 61 6d 2c  ger .** program,
1a7b0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
1a7c0 6e 65 64 20 72 65 66 6c 65 63 74 73 20 74 68 65  ned reflects the
1a7d0 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
1a7e0 6d 6f 64 69 66 69 65 64 20 62 79 20 74 68 65 20  modified by the 
1a7f0 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 49 4e 53  .** previous INS
1a800 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44  ERT, UPDATE or D
1a810 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20  ELETE statement 
1a820 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20  within the same 
1a830 74 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 53  trigger..**.** S
1a840 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c  ee also the [sql
1a850 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
1a860 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c  es()] interface,
1a870 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63   the.** [count_c
1a880 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20  hanges pragma], 
1a890 61 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 65 73  and the [changes
1a8a0 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
1a8b0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70  ..**.** If a sep
1a8c0 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b  arate thread mak
1a8d0 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68  es changes on th
1a8e0 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
1a8f0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68  connection.** wh
1a900 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61  ile [sqlite3_cha
1a910 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69  nges()] is runni
1a920 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ng then the valu
1a930 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73  e returned.** is
1a940 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
1a950 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75  nd not meaningfu
1a960 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l..*/.int sqlite
1a970 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65  3_changes(sqlite
1a980 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
1a990 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62  3REF: Total Numb
1a9a0 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66  er Of Rows Modif
1a9b0 69 65 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ied.** METHOD: s
1a9c0 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
1a9d0 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
1a9e0 72 6e 73 20 74 68 65 20 74 6f 74 61 6c 20 6e 75  rns the total nu
1a9f0 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 69 6e 73  mber of rows ins
1aa00 65 72 74 65 64 2c 20 6d 6f 64 69 66 69 65 64 20  erted, modified 
1aa10 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79  or.** deleted by
1aa20 20 61 6c 6c 20 5b 49 4e 53 45 52 54 5d 2c 20 5b   all [INSERT], [
1aa30 55 50 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45  UPDATE] or [DELE
1aa40 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 63  TE] statements c
1aa50 6f 6d 70 6c 65 74 65 64 0a 2a 2a 20 73 69 6e 63  ompleted.** sinc
1aa60 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  e the database c
1aa70 6f 6e 6e 65 63 74 69 6f 6e 20 77 61 73 20 6f 70  onnection was op
1aa80 65 6e 65 64 2c 20 69 6e 63 6c 75 64 69 6e 67 20  ened, including 
1aa90 74 68 6f 73 65 20 65 78 65 63 75 74 65 64 20 61  those executed a
1aaa0 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 72 69  s.** part of tri
1aab0 67 67 65 72 20 70 72 6f 67 72 61 6d 73 2e 20 5e  gger programs. ^
1aac0 45 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f 74  Executing any ot
1aad0 68 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c 20  her type of SQL 
1aae0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 64 6f 65  statement.** doe
1aaf0 73 20 6e 6f 74 20 61 66 66 65 63 74 20 74 68 65  s not affect the
1ab00 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
1ab10 62 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  by sqlite3_total
1ab20 5f 63 68 61 6e 67 65 73 28 29 2e 0a 2a 2a 20 0a  _changes()..** .
1ab30 2a 2a 20 5e 43 68 61 6e 67 65 73 20 6d 61 64 65  ** ^Changes made
1ab40 20 61 73 20 70 61 72 74 20 6f 66 20 5b 66 6f 72   as part of [for
1ab50 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73  eign key actions
1ab60 5d 20 61 72 65 20 69 6e 63 6c 75 64 65 64 20 69  ] are included i
1ab70 6e 20 74 68 65 0a 2a 2a 20 63 6f 75 6e 74 2c 20  n the.** count, 
1ab80 62 75 74 20 74 68 6f 73 65 20 6d 61 64 65 20 61  but those made a
1ab90 73 20 70 61 72 74 20 6f 66 20 52 45 50 4c 41 43  s part of REPLAC
1aba0 45 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73  E constraint res
1abb0 6f 6c 75 74 69 6f 6e 20 61 72 65 0a 2a 2a 20 6e  olution are.** n
1abc0 6f 74 2e 20 5e 43 68 61 6e 67 65 73 20 74 6f 20  ot. ^Changes to 
1abd0 61 20 76 69 65 77 20 74 68 61 74 20 61 72 65 20  a view that are 
1abe0 69 6e 74 65 72 63 65 70 74 65 64 20 62 79 20 49  intercepted by I
1abf0 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65  NSTEAD OF trigge
1ac00 72 73 20 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63  rs .** are not c
1ac10 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 53  ounted..** .** S
1ac20 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c  ee also the [sql
1ac30 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20  ite3_changes()] 
1ac40 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a  interface, the.*
1ac50 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73  * [count_changes
1ac60 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68   pragma], and th
1ac70 65 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e [total_changes
1ac80 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
1ac90 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70  ..**.** If a sep
1aca0 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b  arate thread mak
1acb0 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68  es changes on th
1acc0 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
1acd0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68  connection.** wh
1ace0 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74  ile [sqlite3_tot
1acf0 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73  al_changes()] is
1ad00 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68   running then th
1ad10 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72  e value.** retur
1ad20 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69 63 74  ned is unpredict
1ad30 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61  able and not mea
1ad40 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20  ningful..*/.int 
1ad50 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
1ad60 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b  anges(sqlite3*);
1ad70 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1ad80 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f  : Interrupt A Lo
1ad90 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79  ng-Running Query
1ada0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
1adb0 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  te3.**.** ^This 
1adc0 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20  function causes 
1add0 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61  any pending data
1ade0 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74  base operation t
1adf0 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72  o abort and.** r
1ae00 65 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 72  eturn at its ear
1ae10 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74  liest opportunit
1ae20 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  y. This routine 
1ae30 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20  is typically.** 
1ae40 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e  called in respon
1ae50 73 65 20 74 6f 20 61 20 75 73 65 72 20 61 63 74  se to a user act
1ae60 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 73  ion such as pres
1ae70 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a  sing "Cancel".**
1ae80 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65   or Ctrl-C where
1ae90 20 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 20   the user wants 
1aea0 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65  a long query ope
1aeb0 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a  ration to halt.*
1aec0 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a  * immediately..*
1aed0 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 65  *.** ^It is safe
1aee0 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f   to call this ro
1aef0 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72  utine from a thr
1af00 65 61 64 20 64 69 66 66 65 72 65 6e 74 20 66 72  ead different fr
1af10 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64  om the.** thread
1af20 20 74 68 61 74 20 69 73 20 63 75 72 72 65 6e 74   that is current
1af30 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64  ly running the d
1af40 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f  atabase operatio
1af50 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73  n.  But it.** is
1af60 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c   not safe to cal
1af70 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  l this routine w
1af80 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20  ith a [database 
1af90 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74  connection] that
1afa0 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72  .** is closed or
1afb0 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66   might close bef
1afc0 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  ore sqlite3_inte
1afd0 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e  rrupt() returns.
1afe0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51  .**.** ^If an SQ
1aff0 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76  L operation is v
1b000 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73  ery nearly finis
1b010 68 65 64 20 61 74 20 74 68 65 20 74 69 6d 65 20  hed at the time 
1b020 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  when.** sqlite3_
1b030 69 6e 74 65 72 72 75 70 74 28 29 20 69 73 20 63  interrupt() is c
1b040 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d  alled, then it m
1b050 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e  ight not have an
1b060 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20   opportunity.** 
1b070 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74 65  to be interrupte
1b080 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74  d and might cont
1b090 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69  inue to completi
1b0a0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51  on..**.** ^An SQ
1b0b0 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74  L operation that
1b0c0 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20   is interrupted 
1b0d0 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
1b0e0 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a  ITE_INTERRUPT]..
1b0f0 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65 72  ** ^If the inter
1b100 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61  rupted SQL opera
1b110 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52  tion is an INSER
1b120 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
1b130 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20  LETE.** that is 
1b140 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63  inside an explic
1b150 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20  it transaction, 
1b160 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20  then the entire 
1b170 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77  transaction.** w
1b180 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61  ill be rolled ba
1b190 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ck automatically
1b1a0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1b1b0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44  ite3_interrupt(D
1b1c0 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66  ) call is in eff
1b1d0 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75  ect until all cu
1b1e0 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a  rrently running.
1b1f0 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
1b200 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  s on [database c
1b210 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d  onnection] D com
1b220 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77  plete.  ^Any new
1b230 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
1b240 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72  ** that are star
1b250 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71  ted after the sq
1b260 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1b270 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72  ) call and befor
1b280 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e  e the .** runnin
1b290 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61  g statements rea
1b2a0 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e  ches zero are in
1b2b0 74 65 72 72 75 70 74 65 64 20 61 73 20 69 66 20  terrupted as if 
1b2c0 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a  they had been.**
1b2d0 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74   running prior t
1b2e0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  o the sqlite3_in
1b2f0 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20  terrupt() call. 
1b300 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d   ^New SQL statem
1b310 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ents.** that are
1b320 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74   started after t
1b330 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65  he running state
1b340 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68  ment count reach
1b350 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e  es zero are.** n
1b360 6f 74 20 65 66 66 65 63 74 65 64 20 62 79 20 74  ot effected by t
1b370 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
1b380 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61  rupt()..** ^A ca
1b390 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ll to sqlite3_in
1b3a0 74 65 72 72 75 70 74 28 44 29 20 74 68 61 74 20  terrupt(D) that 
1b3b0 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68 65 72  occurs when ther
1b3c0 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67  e are no running
1b3d0 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
1b3e0 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e  ts is a no-op an
1b3f0 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20  d has no effect 
1b400 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  on SQL statement
1b410 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74  s.** that are st
1b420 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20  arted after the 
1b430 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1b440 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73  t() call returns
1b450 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
1b460 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69  3_interrupt(sqli
1b470 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
1b480 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e  PI3REF: Determin
1b490 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74  e If An SQL Stat
1b4a0 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74  ement Is Complet
1b4b0 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  e.**.** These ro
1b4c0 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66 75  utines are usefu
1b4d0 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64  l during command
1b4e0 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64  -line input to d
1b4f0 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a  etermine if the.
1b500 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74  ** currently ent
1b510 65 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20  ered text seems 
1b520 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65  to form a comple
1b530 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  te SQL statement
1b540 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69   or.** if additi
1b550 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65  onal input is ne
1b560 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64  eded before send
1b570 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74  ing the text int
1b580 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20  o.** SQLite for 
1b590 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65  parsing.  ^These
1b5a0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
1b5b0 20 31 20 69 66 20 74 68 65 20 69 6e 70 75 74 20   1 if the input 
1b5c0 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72  string.** appear
1b5d0 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65  s to be a comple
1b5e0 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  te SQL statement
1b5f0 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20  .  ^A statement 
1b600 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a  is judged to be.
1b610 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69  ** complete if i
1b620 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 65  t ends with a se
1b630 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e  micolon token an
1b640 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69  d is not a prefi
1b650 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66  x of a.** well-f
1b660 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54 52 49  ormed CREATE TRI
1b670 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20  GGER statement. 
1b680 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61   ^Semicolons tha
1b690 74 20 61 72 65 20 65 6d 62 65 64 64 65 64 20 77  t are embedded w
1b6a0 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20  ithin.** string 
1b6b0 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74  literals or quot
1b6c0 65 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61  ed identifier na
1b6d0 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20  mes or comments 
1b6e0 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70  are not.** indep
1b6f0 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74  endent tokens (t
1b700 68 65 79 20 61 72 65 20 70 61 72 74 20 6f 66 20  hey are part of 
1b710 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69  the token in whi
1b720 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65  ch they are.** e
1b730 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74 68 75  mbedded) and thu
1b740 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61  s do not count a
1b750 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65  s a statement te
1b760 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74  rminator.  ^Whit
1b770 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f  espace.** and co
1b780 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c  mments that foll
1b790 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d  ow the final sem
1b7a0 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72  icolon are ignor
1b7b0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ed..**.** ^These
1b7c0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
1b7d0 20 30 20 69 66 20 74 68 65 20 73 74 61 74 65 6d   0 if the statem
1b7e0 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74  ent is incomplet
1b7f0 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d  e.  ^If a.** mem
1b800 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
1b810 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54  ails, then SQLIT
1b820 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72  E_NOMEM is retur
1b830 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ned..**.** ^Thes
1b840 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f  e routines do no
1b850 74 20 70 61 72 73 65 20 74 68 65 20 53 51 4c 20  t parse the SQL 
1b860 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a  statements thus.
1b870 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65  ** will not dete
1b880 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79  ct syntactically
1b890 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a   incorrect SQL..
1b8a0 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74  **.** ^(If SQLit
1b8b0 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69  e has not been i
1b8c0 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67  nitialized using
1b8d0 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
1b8e0 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a  lize()] prior .*
1b8f0 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71  * to invoking sq
1b900 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
1b910 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  () then sqlite3_
1b920 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
1b930 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d  invoked.** autom
1b940 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69  atically by sqli
1b950 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
1b960 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69 74 69  .  If that initi
1b970 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c  alization fails,
1b980 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74  .** then the ret
1b990 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  urn value from s
1b9a0 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
1b9b0 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d  6() will be non-
1b9c0 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65  zero.** regardle
1b9d0 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
1b9e0 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53   not the input S
1b9f0 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29  QL is complete.)
1ba00 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75  ^.**.** The inpu
1ba10 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
1ba20 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62  mplete()] must b
1ba30 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  e a zero-termina
1ba40 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72  ted.** UTF-8 str
1ba50 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  ing..**.** The i
1ba60 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  nput to [sqlite3
1ba70 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d  _complete16()] m
1ba80 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65  ust be a zero-te
1ba90 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d  rminated.** UTF-
1baa0 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74  16 string in nat
1bab0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
1bac0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
1bad0 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68  omplete(const ch
1bae0 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71  ar *sql);.int sq
1baf0 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
1bb00 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  (const void *sql
1bb10 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1bb20 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 43  EF: Register A C
1bb30 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c  allback To Handl
1bb40 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72  e SQLITE_BUSY Er
1bb50 72 6f 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  rors.** KEYWORDS
1bb60 3a 20 7b 62 75 73 79 2d 68 61 6e 64 6c 65 72 20  : {busy-handler 
1bb70 63 61 6c 6c 62 61 63 6b 7d 20 7b 62 75 73 79 20  callback} {busy 
1bb80 68 61 6e 64 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48  handler}.** METH
1bb90 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
1bba0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62  * ^The sqlite3_b
1bbb0 75 73 79 5f 68 61 6e 64 6c 65 72 28 44 2c 58 2c  usy_handler(D,X,
1bbc0 50 29 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20  P) routine sets 
1bbd0 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
1bbe0 69 6f 6e 20 58 0a 2a 2a 20 74 68 61 74 20 6d 69  ion X.** that mi
1bbf0 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  ght be invoked w
1bc00 69 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77  ith argument P w
1bc10 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74  henever.** an at
1bc20 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f  tempt is made to
1bc30 20 61 63 63 65 73 73 20 61 20 64 61 74 61 62 61   access a databa
1bc40 73 65 20 74 61 62 6c 65 20 61 73 73 6f 63 69 61  se table associa
1bc50 74 65 64 20 77 69 74 68 0a 2a 2a 20 5b 64 61 74  ted with.** [dat
1bc60 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1bc70 5d 20 44 20 77 68 65 6e 20 61 6e 6f 74 68 65 72  ] D when another
1bc80 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72   thread.** or pr
1bc90 6f 63 65 73 73 20 68 61 73 20 74 68 65 20 74 61  ocess has the ta
1bca0 62 6c 65 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20 54  ble locked..** T
1bcb0 68 65 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  he sqlite3_busy_
1bcc0 68 61 6e 64 6c 65 72 28 29 20 69 6e 74 65 72 66  handler() interf
1bcd0 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 69  ace is used to i
1bce0 6d 70 6c 65 6d 65 6e 74 0a 2a 2a 20 5b 73 71 6c  mplement.** [sql
1bcf0 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
1bd00 74 28 29 5d 20 61 6e 64 20 5b 50 52 41 47 4d 41  t()] and [PRAGMA
1bd10 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 2e 0a   busy_timeout]..
1bd20 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75  **.** ^If the bu
1bd30 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e  sy callback is N
1bd40 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54  ULL, then [SQLIT
1bd50 45 5f 42 55 53 59 5d 0a 2a 2a 20 69 73 20 72 65  E_BUSY].** is re
1bd60 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65  turned immediate
1bd70 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65  ly upon encounte
1bd80 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20  ring the lock.  
1bd90 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c  ^If the busy cal
1bda0 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20  lback.** is not 
1bdb0 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63  NULL, then the c
1bdc0 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62 65  allback might be
1bdd0 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77   invoked with tw
1bde0 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a  o arguments..**.
1bdf0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
1be00 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62 75  gument to the bu
1be10 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20  sy handler is a 
1be20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64  copy of the void
1be30 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a  * pointer which.
1be40 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72 64 20  ** is the third 
1be50 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
1be60 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
1be70 28 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64  ().  ^The second
1be80 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
1be90 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
1bea0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65   callback is the
1beb0 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73   number of times
1bec0 20 74 68 61 74 20 74 68 65 20 62 75 73 79 20 68   that the busy h
1bed0 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65  andler has.** be
1bee0 65 6e 20 69 6e 76 6f 6b 65 64 20 70 72 65 76 69  en invoked previ
1bef0 6f 75 73 6c 79 20 66 6f 72 20 74 68 65 20 73 61  ously for the sa
1bf00 6d 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74  me locking event
1bf10 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75  .  ^If the.** bu
1bf20 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  sy callback retu
1bf30 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61  rns 0, then no a
1bf40 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70  dditional attemp
1bf50 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a  ts are made to.*
1bf60 2a 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74  * access the dat
1bf70 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54  abase and [SQLIT
1bf80 45 5f 42 55 53 59 5d 20 69 73 20 72 65 74 75 72  E_BUSY] is retur
1bf90 6e 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70  ned.** to the ap
1bfa0 70 6c 69 63 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49  plication..** ^I
1bfb0 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  f the callback r
1bfc0 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
1bfd0 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74   then another at
1bfe0 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65  tempt.** is made
1bff0 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64   to access the d
1c000 61 74 61 62 61 73 65 20 61 6e 64 20 74 68 65 20  atabase and the 
1c010 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a  cycle repeats..*
1c020 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63  *.** The presenc
1c030 65 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64  e of a busy hand
1c040 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61  ler does not gua
1c050 72 61 6e 74 65 65 20 74 68 61 74 20 69 74 20 77  rantee that it w
1c060 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a  ill be invoked.*
1c070 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69 73 20  * when there is 
1c080 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e  lock contention.
1c090 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74 65   ^If SQLite dete
1c0a0 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f  rmines that invo
1c0b0 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a  king the busy.**
1c0c0 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72   handler could r
1c0d0 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c  esult in a deadl
1c0e0 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20  ock, it will go 
1c0f0 61 68 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e  ahead and return
1c100 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a   [SQLITE_BUSY].*
1c110 2a 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  * to the applica
1c120 74 69 6f 6e 20 69 6e 73 74 65 61 64 20 6f 66 20  tion instead of 
1c130 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 0a 2a 2a  invoking the .**
1c140 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a   busy handler..*
1c150 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65  * Consider a sce
1c160 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20  nario where one 
1c170 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69  process is holdi
1c180 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74  ng a read lock t
1c190 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79  hat.** it is try
1c1a0 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  ing to promote t
1c1b0 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63  o a reserved loc
1c1c0 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e  k and.** a secon
1c1d0 64 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c  d process is hol
1c1e0 64 69 6e 67 20 61 20 72 65 73 65 72 76 65 64 20  ding a reserved 
1c1f0 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73 20  lock that it is 
1c200 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f  trying.** to pro
1c210 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75  mote to an exclu
1c220 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20  sive lock.  The 
1c230 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 63 61  first process ca
1c240 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20  nnot proceed.** 
1c250 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c  because it is bl
1c260 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73 65 63  ocked by the sec
1c270 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f  ond and the seco
1c280 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f  nd process canno
1c290 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63  t.** proceed bec
1c2a0 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b  ause it is block
1c2b0 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 2e  ed by the first.
1c2c0 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73    If both proces
1c2d0 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68  ses.** invoke th
1c2e0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c  e busy handlers,
1c2f0 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61   neither will ma
1c300 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e  ke any progress.
1c310 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20    Therefore,.** 
1c320 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b  SQLite returns [
1c330 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72  SQLITE_BUSY] for
1c340 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   the first proce
1c350 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20  ss, hoping that 
1c360 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64  this.** will ind
1c370 75 63 65 20 74 68 65 20 66 69 72 73 74 20 70 72  uce the first pr
1c380 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65  ocess to release
1c390 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61   its read lock a
1c3a0 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20  nd allow.** the 
1c3b0 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74  second process t
1c3c0 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a  o proceed..**.**
1c3d0 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 75   ^The default bu
1c3e0 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e  sy callback is N
1c3f0 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ULL..**.** ^(The
1c400 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61  re can only be a
1c410 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e   single busy han
1c420 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72  dler defined for
1c430 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61   each.** [databa
1c440 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
1c450 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62   Setting a new b
1c460 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61  usy handler clea
1c470 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f  rs any.** previo
1c480 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72  usly set handler
1c490 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20  .)^  ^Note that 
1c4a0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
1c4b0 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
1c4c0 0a 2a 2a 20 6f 72 20 65 76 61 6c 75 61 74 69 6e  .** or evaluatin
1c4d0 67 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74  g [PRAGMA busy_t
1c4e0 69 6d 65 6f 75 74 3d 4e 5d 20 77 69 6c 6c 20 63  imeout=N] will c
1c4f0 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 62 75 73  hange the.** bus
1c500 79 20 68 61 6e 64 6c 65 72 20 61 6e 64 20 74 68  y handler and th
1c510 75 73 20 63 6c 65 61 72 20 61 6e 79 20 70 72 65  us clear any pre
1c520 76 69 6f 75 73 6c 79 20 73 65 74 20 62 75 73 79  viously set busy
1c530 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20   handler..**.** 
1c540 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63  The busy callbac
1c550 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b  k should not tak
1c560 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68  e any actions wh
1c570 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a  ich modify the.*
1c580 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
1c590 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
1c5a0 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ed the busy hand
1c5b0 6c 65 72 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  ler.  In other w
1c5c0 6f 72 64 73 2c 0a 2a 2a 20 74 68 65 20 62 75 73  ords,.** the bus
1c5d0 79 20 68 61 6e 64 6c 65 72 20 69 73 20 6e 6f 74  y handler is not
1c5e0 20 72 65 65 6e 74 72 61 6e 74 2e 20 20 41 6e 79   reentrant.  Any
1c5f0 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a   such actions.**
1c600 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66   result in undef
1c610 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a  ined behavior..*
1c620 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e  * .** A busy han
1c630 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c  dler must not cl
1c640 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ose the database
1c650 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f   connection.** o
1c660 72 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  r [prepared stat
1c670 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f  ement] that invo
1c680 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e  ked the busy han
1c690 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  dler..*/.int sql
1c6a0 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
1c6b0 72 28 73 71 6c 69 74 65 33 2a 2c 69 6e 74 28 2a  r(sqlite3*,int(*
1c6c0 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 76 6f 69  )(void*,int),voi
1c6d0 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
1c6e0 33 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 79  3REF: Set A Busy
1c6f0 20 54 69 6d 65 6f 75 74 0a 2a 2a 20 4d 45 54 48   Timeout.** METH
1c700 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
1c710 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
1c720 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f  sets a [sqlite3_
1c730 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62  busy_handler | b
1c740 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61  usy handler] tha
1c750 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20  t sleeps.** for 
1c760 61 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75  a specified amou
1c770 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20  nt of time when 
1c780 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65  a table is locke
1c790 64 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72  d.  ^The handler
1c7a0 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d  .** will sleep m
1c7b0 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e  ultiple times un
1c7c0 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73  til at least "ms
1c7d0 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  " milliseconds o
1c7e0 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61  f sleeping.** ha
1c7f0 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20  ve accumulated. 
1c800 20 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73 74   ^After at least
1c810 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e   "ms" millisecon
1c820 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a  ds of sleeping,.
1c830 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72  ** the handler r
1c840 65 74 75 72 6e 73 20 30 20 77 68 69 63 68 20 63  eturns 0 which c
1c850 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73  auses [sqlite3_s
1c860 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e  tep()] to return
1c870 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  .** [SQLITE_BUSY
1c880 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e  ]..**.** ^Callin
1c890 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  g this routine w
1c8a0 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20  ith an argument 
1c8b0 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75  less than or equ
1c8c0 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75  al to zero.** tu
1c8d0 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79  rns off all busy
1c8e0 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a   handlers..**.**
1c8f0 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c   ^(There can onl
1c900 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75  y be a single bu
1c910 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61  sy handler for a
1c920 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b   particular.** [
1c930 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1c940 69 6f 6e 5d 20 61 74 20 61 6e 79 20 67 69 76 65  ion] at any give
1c950 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e  n moment.  If an
1c960 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c  other busy handl
1c970 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65  er.** was define
1c980 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74  d  (using [sqlit
1c990 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
1c9a0 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c  )]) prior to cal
1c9b0 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75  ling.** this rou
1c9c0 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72  tine, that other
1c9d0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
1c9e0 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2a 0a 2a   cleared.)^.**.*
1c9f0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 50 52  * See also:  [PR
1ca00 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75  AGMA busy_timeou
1ca10 74 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  t].*/.int sqlite
1ca20 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73  3_busy_timeout(s
1ca30 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29  qlite3*, int ms)
1ca40 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1ca50 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52  F: Convenience R
1ca60 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e  outines For Runn
1ca70 69 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 20 4d  ing Queries.** M
1ca80 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
1ca90 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 6c  *.** This is a l
1caa0 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 20  egacy interface 
1cab0 74 68 61 74 20 69 73 20 70 72 65 73 65 72 76 65  that is preserve
1cac0 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20  d for backwards 
1cad0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
1cae0 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20 69 6e  * Use of this in
1caf0 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72  terface is not r
1cb00 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a  ecommended..**.*
1cb10 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20  * Definition: A 
1cb20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c  <b>result table<
1cb30 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61  /b> is memory da
1cb40 74 61 20 73 74 72 75 63 74 75 72 65 20 63 72 65  ta structure cre
1cb50 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b  ated by the.** [
1cb60 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1cb70 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20  e()] interface. 
1cb80 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
1cb90 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63  records the.** c
1cba0 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72 65  omplete query re
1cbb0 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f  sults from one o
1cbc0 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a  r more queries..
1cbd0 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20  **.** The table 
1cbe0 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73  conceptually has
1cbf0 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77   a number of row
1cc00 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20  s and columns.  
1cc10 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d  But.** these num
1cc20 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72  bers are not par
1cc30 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  t of the result 
1cc40 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54  table itself.  T
1cc50 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20  hese.** numbers 
1cc60 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70  are obtained sep
1cc70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20  arately.  Let N 
1cc80 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  be the number of
1cc90 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62   rows.** and M b
1cca0 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  e the number of 
1ccb0 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41  columns..**.** A
1ccc0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73   result table is
1ccd0 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
1cce0 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65  nters to zero-te
1ccf0 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
1cd00 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65  trings..** There
1cd10 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65   are (N+1)*M ele
1cd20 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72  ments in the arr
1cd30 61 79 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d  ay.  The first M
1cd40 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a   pointers point.
1cd50 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69  ** to zero-termi
1cd60 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68  nated strings th
1cd70 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20  at  contain the 
1cd80 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c  names of the col
1cd90 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d  umns..** The rem
1cda0 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61  aining entries a
1cdb0 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72  ll point to quer
1cdc0 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c  y results.  NULL
1cdd0 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a   values result.*
1cde0 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  * in NULL pointe
1cdf0 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76  rs.  All other v
1ce00 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68 65  alues are in the
1ce10 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65  ir UTF-8 zero-te
1ce20 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69  rminated.** stri
1ce30 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  ng representatio
1ce40 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 62 79  n as returned by
1ce50 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
1ce60 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _text()]..**.** 
1ce70 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d  A result table m
1ce80 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20  ight consist of 
1ce90 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f  one or more memo
1cea0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a  ry allocations..
1ceb0 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66  ** It is not saf
1cec0 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 73 75  e to pass a resu
1ced0 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c  lt table directl
1cee0 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72  y to [sqlite3_fr
1cef0 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75  ee()]..** A resu
1cf00 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20  lt table should 
1cf10 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75  be deallocated u
1cf20 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72  sing [sqlite3_fr
1cf30 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a  ee_table()]..**.
1cf40 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 6d 70  ** ^(As an examp
1cf50 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  le of the result
1cf60 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73   table format, s
1cf70 75 70 70 6f 73 65 20 61 20 71 75 65 72 79 20 72  uppose a query r
1cf80 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66  esult.** is as f
1cf90 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
1cfa0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1cfb0 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20  **        Name  
1cfc0 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20        | Age.**  
1cfd0 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d        ----------
1cfe0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a  -------------.**
1cff0 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 20 20          Alice   
1d000 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20      | 43.**     
1d010 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c     Bob         |
1d020 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69   28.**        Ci
1d030 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a  ndy       | 21.*
1d040 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1d050 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72  uote>.**.** Ther
1d060 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e  e are two column
1d070 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65   (M==2) and thre
1d080 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20  e rows (N==3).  
1d090 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75  Thus the.** resu
1d0a0 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38 20 65  lt table has 8 e
1d0b0 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65  ntries.  Suppose
1d0c0 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
1d0d0 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69  e is stored.** i
1d0e0 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73  n an array names
1d0f0 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e   azResult.  Then
1d100 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20   azResult holds 
1d110 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a  this content:.**
1d120 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1d130 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20  <pre>.**        
1d140 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20  azResult&#91;0] 
1d150 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20  = "Name";.**    
1d160 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1d170 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20  ;1] = "Age";.** 
1d180 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1d190 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22  #91;2] = "Alice"
1d1a0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1d1b0 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34  sult&#91;3] = "4
1d1c0 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  3";.**        az
1d1d0 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20  Result&#91;4] = 
1d1e0 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20  "Bob";.**       
1d1f0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d   azResult&#91;5]
1d200 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20   = "28";.**     
1d210 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1d220 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a  6] = "Cindy";.**
1d230 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1d240 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a  &#91;7] = "21";.
1d250 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1d260 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  quote>)^.**.** ^
1d270 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
1d280 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e  table() function
1d290 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f   evaluates one o
1d2a0 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f  r more.** semico
1d2b0 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51  lon-separated SQ
1d2c0 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20  L statements in 
1d2d0 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  the zero-termina
1d2e0 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72  ted UTF-8.** str
1d2f0 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70  ing of its 2nd p
1d300 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74  arameter and ret
1d310 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61  urns a result ta
1d320 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f  ble to the.** po
1d330 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69  inter given in i
1d340 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  ts 3rd parameter
1d350 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68  ..**.** After th
1d360 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68 61  e application ha
1d370 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
1d380 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 20  the result from 
1d390 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1d3a0 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20  e(),.** it must 
1d3b0 70 61 73 73 20 74 68 65 20 72 65 73 75 6c 74 20  pass the result 
1d3c0 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f  table pointer to
1d3d0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61   sqlite3_free_ta
1d3e0 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74  ble() in order t
1d3f0 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65  o.** release the
1d400 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73   memory that was
1d410 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61   malloced.  Beca
1d420 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 74  use of the way t
1d430 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  he.** [sqlite3_m
1d440 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73  alloc()] happens
1d450 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f   within sqlite3_
1d460 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65  get_table(), the
1d470 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63   calling.** func
1d480 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72  tion must not tr
1d490 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74  y to call [sqlit
1d4a0 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63  e3_free()] direc
1d4b0 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73  tly.  Only.** [s
1d4c0 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
1d4d0 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20  e()] is able to 
1d4e0 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f  release the memo
1d4f0 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20  ry properly and 
1d500 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68  safely..**.** Th
1d510 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  e sqlite3_get_ta
1d520 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ble() interface 
1d530 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61  is implemented a
1d540 73 20 61 20 77 72 61 70 70 65 72 20 61 72 6f 75  s a wrapper arou
1d550 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  nd.** [sqlite3_e
1d560 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c  xec()].  The sql
1d570 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1d580 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f   routine does no
1d590 74 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a  t have access.**
1d5a0 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c   to any internal
1d5b0 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73   data structures
1d5c0 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20   of SQLite.  It 
1d5d0 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75  uses only the pu
1d5e0 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63  blic.** interfac
1d5f0 65 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20  e defined here. 
1d600 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63   As a consequenc
1d610 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f  e, errors that o
1d620 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77  ccur in the.** w
1d630 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74  rapper layer out
1d640 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65  side of the inte
1d650 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78  rnal [sqlite3_ex
1d660 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e  ec()] call are n
1d670 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20  ot.** reflected 
1d680 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  in subsequent ca
1d690 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
1d6a0 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a  errcode()] or.**
1d6b0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
1d6c0 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
1d6d0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20  te3_get_table(. 
1d6e0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
1d6f0 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65         /* An ope
1d700 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20  n database */.  
1d710 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
1d720 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20  ,     /* SQL to 
1d730 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a  be evaluated */.
1d740 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73    char ***pazRes
1d750 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c  ult,    /* Resul
1d760 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20  ts of the query 
1d770 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c  */.  int *pnRow,
1d780 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75             /* Nu
1d790 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72  mber of result r
1d7a0 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65  ows written here
1d7b0 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c   */.  int *pnCol
1d7c0 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e  umn,        /* N
1d7d0 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20  umber of result 
1d7e0 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20  columns written 
1d7f0 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a  here */.  char *
1d800 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20  *pzErrmsg       
1d810 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69  /* Error msg wri
1d820 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a  tten here */.);.
1d830 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65  void sqlite3_fre
1d840 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72  e_table(char **r
1d850 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  esult);../*.** C
1d860 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74  API3REF: Formatt
1d870 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69  ed String Printi
1d880 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a  ng Functions.**.
1d890 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
1d8a0 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65  s are work-alike
1d8b0 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66  s of the "printf
1d8c0 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75  ()" family of fu
1d8d0 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20  nctions.** from 
1d8e0 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
1d8f0 69 62 72 61 72 79 2e 0a 2a 2a 20 54 68 65 73 65  ibrary..** These
1d900 20 72 6f 75 74 69 6e 65 73 20 75 6e 64 65 72 73   routines unders
1d910 74 61 6e 64 20 6d 6f 73 74 20 6f 66 20 74 68 65  tand most of the
1d920 20 63 6f 6d 6d 6f 6e 20 4b 26 52 20 66 6f 72 6d   common K&R form
1d930 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 2c 0a  atting options,.
1d940 2a 2a 20 70 6c 75 73 20 73 6f 6d 65 20 61 64 64  ** plus some add
1d950 69 74 69 6f 6e 61 6c 20 6e 6f 6e 2d 73 74 61 6e  itional non-stan
1d960 64 61 72 64 20 66 6f 72 6d 61 74 73 2c 20 64 65  dard formats, de
1d970 74 61 69 6c 65 64 20 62 65 6c 6f 77 2e 0a 2a 2a  tailed below..**
1d980 20 4e 6f 74 65 20 74 68 61 74 20 73 6f 6d 65 20   Note that some 
1d990 6f 66 20 74 68 65 20 6d 6f 72 65 20 6f 62 73 63  of the more obsc
1d9a0 75 72 65 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f  ure formatting o
1d9b0 70 74 69 6f 6e 73 20 66 72 6f 6d 20 72 65 63 65  ptions from rece
1d9c0 6e 74 0a 2a 2a 20 43 2d 6c 69 62 72 61 72 79 20  nt.** C-library 
1d9d0 73 74 61 6e 64 61 72 64 73 20 61 72 65 20 6f 6d  standards are om
1d9e0 69 74 74 65 64 20 66 72 6f 6d 20 74 68 69 73 20  itted from this 
1d9f0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a  implementation..
1da00 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1da10 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64  e3_mprintf() and
1da20 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74   sqlite3_vmprint
1da30 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69  f() routines wri
1da40 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75  te their.** resu
1da50 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20  lts into memory 
1da60 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
1da70 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1da80 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73  ..** The strings
1da90 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
1daa0 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20  se two routines 
1dab0 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c  should be.** rel
1dac0 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65  eased by [sqlite
1dad0 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74  3_free()].  ^Bot
1dae0 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  h routines retur
1daf0 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e  n a.** NULL poin
1db00 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f  ter if [sqlite3_
1db10 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61  malloc()] is una
1db20 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
1db30 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79  enough.** memory
1db40 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73   to hold the res
1db50 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a  ulting string..*
1db60 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74  *.** ^(The sqlit
1db70 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f  e3_snprintf() ro
1db80 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72  utine is similar
1db90 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22   to "snprintf()"
1dba0 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61   from.** the sta
1dbb0 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
1dbc0 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20    The result is 
1dbd0 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65  written into the
1dbe0 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c  .** buffer suppl
1dbf0 69 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ied as the secon
1dc00 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73  d parameter whos
1dc10 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20  e size is given 
1dc20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  by.** the first 
1dc30 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20  parameter. Note 
1dc40 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f  that the order o
1dc50 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74  f the.** first t
1dc60 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73  wo parameters is
1dc70 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73   reversed from s
1dc80 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68  nprintf().)^  Th
1dc90 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74  is is an.** hist
1dca0 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20  orical accident 
1dcb0 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66  that cannot be f
1dcc0 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 65  ixed without bre
1dcd0 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72  aking.** backwar
1dce0 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
1dcf0 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74  .  ^(Note also t
1dd00 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72  hat sqlite3_snpr
1dd10 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e  intf().** return
1dd20 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69  s a pointer to i
1dd30 74 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61  ts buffer instea
1dd40 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20  d of the number 
1dd50 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73  of.** characters
1dd60 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65   actually writte
1dd70 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65  n into the buffe
1dd80 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74  r.)^  We admit t
1dd90 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  hat.** the numbe
1dda0 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20  r of characters 
1ddb0 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65  written would be
1ddc0 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72   a more useful r
1ddd0 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62  eturn.** value b
1dde0 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61  ut we cannot cha
1ddf0 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  nge the implemen
1de00 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65  tation of sqlite
1de10 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
1de20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61  now without brea
1de30 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69  king compatibili
1de40 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f  ty..**.** ^As lo
1de50 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72  ng as the buffer
1de60 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72   size is greater
1de70 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69   than zero, sqli
1de80 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
1de90 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  * guarantees tha
1dea0 74 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20  t the buffer is 
1deb0 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d  always zero-term
1dec0 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69  inated.  ^The fi
1ded0 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  rst.** parameter
1dee0 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61   "n" is the tota
1def0 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75  l size of the bu
1df00 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20  ffer, including 
1df10 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65  space for.** the
1df20 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
1df30 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73  .  So the longes
1df40 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61  t string that ca
1df50 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a  n be completely.
1df60 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20  ** written will 
1df70 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72  be n-1 character
1df80 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  s..**.** ^The sq
1df90 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28  lite3_vsnprintf(
1dfa0 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76  ) routine is a v
1dfb0 61 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f  arargs version o
1dfc0 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  f sqlite3_snprin
1dfd0 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tf()..**.** Thes
1dfe0 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69  e routines all i
1dff0 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64  mplement some ad
1e000 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74  ditional formatt
1e010 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74  ing.** options t
1e020 68 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66  hat are useful f
1e030 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20  or constructing 
1e040 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
1e050 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73  ** All of the us
1e060 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72  ual printf() for
1e070 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20  matting options 
1e080 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74  apply.  In addit
1e090 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73  ion, there.** is
1e0a0 20 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c   are "%q", "%Q",
1e0b0 20 22 25 77 22 20 61 6e 64 20 22 25 7a 22 20 6f   "%w" and "%z" o
1e0c0 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ptions..**.** ^(
1e0d0 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f  The %q option wo
1e0e0 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74  rks like %s in t
1e0f0 68 61 74 20 69 74 20 73 75 62 73 74 69 74 75 74  hat it substitut
1e100 65 73 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61  es a nul-termina
1e110 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72  ted.** string fr
1e120 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  om the argument 
1e130 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c  list.  But %q al
1e140 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79  so doubles every
1e150 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e   '\'' character.
1e160 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e  .** %q is design
1e170 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64  ed for use insid
1e180 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72  e a string liter
1e190 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c 69  al.)^  By doubli
1e1a0 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20  ng each '\''.** 
1e1b0 63 68 61 72 61 63 74 65 72 20 69 74 20 65 73 63  character it esc
1e1c0 61 70 65 73 20 74 68 61 74 20 63 68 61 72 61 63  apes that charac
1e1d0 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69  ter and allows i
1e1e0 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64  t to be inserted
1e1f0 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72   into.** the str
1e200 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65  ing..**.** For e
1e210 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74  xample, assume t
1e220 68 65 20 73 74 72 69 6e 67 20 76 61 72 69 61 62  he string variab
1e230 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e  le zText contain
1e240 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77  s text as follow
1e250 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
1e260 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
1e270 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74  har *zText = "It
1e280 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 22  's a happy day!"
1e290 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
1e2a0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f  ckquote>.**.** O
1e2b0 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69 73 20  ne can use this 
1e2c0 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73  text in an SQL s
1e2d0 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c  tatement as foll
1e2e0 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
1e2f0 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1e300 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71   char *zSQL = sq
1e310 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49  lite3_mprintf("I
1e320 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
1e330 20 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20   VALUES('%q')", 
1e340 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69  zText);.**  sqli
1e350 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51  te3_exec(db, zSQ
1e360 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20  L, 0, 0, 0);.** 
1e370 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53   sqlite3_free(zS
1e380 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  QL);.** </pre></
1e390 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
1e3a0 2a 20 42 65 63 61 75 73 65 20 74 68 65 20 25 71  * Because the %q
1e3b0 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69   format string i
1e3c0 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27  s used, the '\''
1e3d0 20 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54   character in zT
1e3e0 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65  ext.** is escape
1e3f0 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65  d and the SQL ge
1e400 6e 65 72 61 74 65 64 20 69 73 20 61 73 20 66 6f  nerated is as fo
1e410 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
1e420 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1e430 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  *  INSERT INTO t
1e440 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74  able1 VALUES('It
1e450 27 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21  ''s a happy day!
1e460 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  ').** </pre></bl
1e470 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
1e480 54 68 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e  This is correct.
1e490 20 20 48 61 64 20 77 65 20 75 73 65 64 20 25 73    Had we used %s
1e4a0 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20   instead of %q, 
1e4b0 74 68 65 20 67 65 6e 65 72 61 74 65 64 20 53 51  the generated SQ
1e4c0 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20  L.** would have 
1e4d0 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73  looked like this
1e4e0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1e4f0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e  ote><pre>.**  IN
1e500 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31  SERT INTO table1
1e510 20 56 41 4c 55 45 53 28 27 49 74 27 73 20 61 20   VALUES('It's a 
1e520 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a  happy day!');.**
1e530 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1e540 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ote>.**.** This 
1e550 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69  second example i
1e560 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20  s an SQL syntax 
1e570 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e  error.  As a gen
1e580 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68  eral rule you sh
1e590 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75  ould.** always u
1e5a0 73 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66  se %q instead of
1e5b0 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69   %s when inserti
1e5c0 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73  ng text into a s
1e5d0 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a  tring literal..*
1e5e0 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f 70  *.** ^(The %Q op
1e5f0 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20  tion works like 
1e600 25 71 20 65 78 63 65 70 74 20 69 74 20 61 6c 73  %q except it als
1e610 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75  o adds single qu
1e620 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74  otes around.** t
1e630 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68  he outside of th
1e640 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20  e total string. 
1e650 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69   Additionally, i
1e660 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
1e670 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65  in the.** argume
1e680 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c  nt list is a NUL
1e690 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75  L pointer, %Q su
1e6a0 62 73 74 69 74 75 74 65 73 20 74 68 65 20 74 65  bstitutes the te
1e6b0 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f  xt "NULL" (witho
1e6c0 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f  ut.** single quo
1e6d0 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72  tes).)^  So, for
1e6e0 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f   example, one co
1e6f0 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c  uld say:.**.** <
1e700 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1e710 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20  .**  char *zSQL 
1e720 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  = sqlite3_mprint
1e730 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  f("INSERT INTO t
1e740 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22  able VALUES(%Q)"
1e750 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71  , zText);.**  sq
1e760 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a  lite3_exec(db, z
1e770 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a  SQL, 0, 0, 0);.*
1e780 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  *  sqlite3_free(
1e790 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  zSQL);.** </pre>
1e7a0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1e7b0 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f  .** The code abo
1e7c0 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61  ve will render a
1e7d0 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61   correct SQL sta
1e7e0 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53  tement in the zS
1e7f0 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65  QL.** variable e
1e800 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74  ven if the zText
1e810 20 76 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e   variable is a N
1e820 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
1e830 2a 2a 20 5e 28 54 68 65 20 22 25 77 22 20 66 6f  ** ^(The "%w" fo
1e840 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20  rmatting option 
1e850 69 73 20 6c 69 6b 65 20 22 25 71 22 20 65 78 63  is like "%q" exc
1e860 65 70 74 20 74 68 61 74 20 69 74 20 65 78 70 65  ept that it expe
1e870 63 74 73 20 74 6f 0a 2a 2a 20 62 65 20 63 6f 6e  cts to.** be con
1e880 74 61 69 6e 65 64 20 77 69 74 68 69 6e 20 64 6f  tained within do
1e890 75 62 6c 65 2d 71 75 6f 74 65 73 20 69 6e 73 74  uble-quotes inst
1e8a0 65 61 64 20 6f 66 20 73 69 6e 67 6c 65 20 71 75  ead of single qu
1e8b0 6f 74 65 73 2c 20 61 6e 64 20 69 74 0a 2a 2a 20  otes, and it.** 
1e8c0 65 73 63 61 70 65 73 20 74 68 65 20 64 6f 75 62  escapes the doub
1e8d0 6c 65 2d 71 75 6f 74 65 20 63 68 61 72 61 63 74  le-quote charact
1e8e0 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68  er instead of th
1e8f0 65 20 73 69 6e 67 6c 65 2d 71 75 6f 74 65 0a 2a  e single-quote.*
1e900 2a 20 63 68 61 72 61 63 74 65 72 2e 29 5e 20 20  * character.)^  
1e910 54 68 65 20 22 25 77 22 20 66 6f 72 6d 61 74 74  The "%w" formatt
1e920 69 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20 69 6e  ing option is in
1e930 74 65 6e 64 65 64 20 66 6f 72 20 73 61 66 65 6c  tended for safel
1e940 79 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74  y inserting.** t
1e950 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20  able and column 
1e960 6e 61 6d 65 73 20 69 6e 74 6f 20 61 20 63 6f 6e  names into a con
1e970 73 74 72 75 63 74 65 64 20 53 51 4c 20 73 74 61  structed SQL sta
1e980 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28  tement..**.** ^(
1e990 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74  The "%z" formatt
1e9a0 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73  ing option works
1e9b0 20 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20 77   like "%s" but w
1e9c0 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74  ith the.** addit
1e9d0 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 74  ion that after t
1e9e0 68 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 65  he string has be
1e9f0 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69  en read and copi
1ea00 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72  ed into.** the r
1ea10 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f  esult, [sqlite3_
1ea20 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65  free()] is calle
1ea30 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73  d on the input s
1ea40 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72  tring.)^.*/.char
1ea50 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74   *sqlite3_mprint
1ea60 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e  f(const char*,..
1ea70 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  .);.char *sqlite
1ea80 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74  3_vmprintf(const
1ea90 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29   char*, va_list)
1eaa0 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  ;.char *sqlite3_
1eab0 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61  snprintf(int,cha
1eac0 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  r*,const char*, 
1ead0 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69  ...);.char *sqli
1eae0 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e  te3_vsnprintf(in
1eaf0 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t,char*,const ch
1eb00 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a  ar*, va_list);..
1eb10 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1eb20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f  Memory Allocatio
1eb30 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a  n Subsystem.**.*
1eb40 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72  * The SQLite cor
1eb50 65 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72  e uses these thr
1eb60 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20  ee routines for 
1eb70 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a  all of its own.*
1eb80 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72  * internal memor
1eb90 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
1eba0 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68  ds. "Core" in th
1ebb0 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65  e previous sente
1ebc0 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  nce.** does not 
1ebd0 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e  include operatin
1ebe0 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69  g-system specifi
1ebf0 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  c VFS implementa
1ec00 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69  tion.  The.** Wi
1ec10 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e  ndows VFS uses n
1ec20 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61  ative malloc() a
1ec30 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f  nd free() for so
1ec40 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a  me operations..*
1ec50 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1ec60 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69  3_malloc() routi
1ec70 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ne returns a poi
1ec80 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a  nter to a block.
1ec90 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20  ** of memory at 
1eca0 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e  least N bytes in
1ecb0 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e   length, where N
1ecc0 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65   is the paramete
1ecd0 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  r..** ^If sqlite
1ece0 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e  3_malloc() is un
1ecf0 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73  able to obtain s
1ed00 75 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a  ufficient free.*
1ed10 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74  * memory, it ret
1ed20 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
1ed30 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61  ter.  ^If the pa
1ed40 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20  rameter N to.** 
1ed50 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1ed60 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61   is zero or nega
1ed70 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65  tive then sqlite
1ed80 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72  3_malloc() retur
1ed90 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69  ns.** a NULL poi
1eda0 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nter..**.** ^The
1edb0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36   sqlite3_malloc6
1edc0 34 28 4e 29 20 72 6f 75 74 69 6e 65 20 77 6f 72  4(N) routine wor
1edd0 6b 73 20 6a 75 73 74 20 6c 69 6b 65 0a 2a 2a 20  ks just like.** 
1ede0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e  sqlite3_malloc(N
1edf0 29 20 65 78 63 65 70 74 20 74 68 61 74 20 4e 20  ) except that N 
1ee00 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 36  is an unsigned 6
1ee10 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 69 6e  4-bit integer in
1ee20 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 73 69  stead.** of a si
1ee30 67 6e 65 64 20 33 32 2d 62 69 74 20 69 6e 74 65  gned 32-bit inte
1ee40 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c  ger..**.** ^Call
1ee50 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65  ing sqlite3_free
1ee60 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65  () with a pointe
1ee70 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74  r previously ret
1ee80 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69  urned.** by sqli
1ee90 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20  te3_malloc() or 
1eea0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1eeb0 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 20  ) releases that 
1eec0 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61  memory so.** tha
1eed0 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 65  t it might be re
1eee0 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69  used.  ^The sqli
1eef0 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69  te3_free() routi
1ef00 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70  ne is.** a no-op
1ef10 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69   if is called wi
1ef20 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
1ef30 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55  r.  Passing a NU
1ef40 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f  LL pointer.** to
1ef50 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
1ef60 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66  is harmless.  Af
1ef70 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c  ter being freed,
1ef80 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c   memory.** shoul
1ef90 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 61  d neither be rea
1efa0 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20  d nor written.  
1efb0 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65  Even reading pre
1efc0 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a  viously freed.**
1efd0 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65   memory might re
1efe0 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e  sult in a segmen
1eff0 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20  tation fault or 
1f000 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72  other severe err
1f010 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f  or..** Memory co
1f020 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d  rruption, a segm
1f030 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20  entation fault, 
1f040 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20  or other severe 
1f050 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72  error.** might r
1f060 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33  esult if sqlite3
1f070 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65  _free() is calle
1f080 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c  d with a non-NUL
1f090 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a  L pointer that.*
1f0a0 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e  * was not obtain
1f0b0 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ed from sqlite3_
1f0c0 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69  malloc() or sqli
1f0d0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a  te3_realloc()..*
1f0e0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1f0f0 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69  3_realloc(X,N) i
1f100 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
1f110 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a  s to resize a.**
1f120 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c   prior memory al
1f130 6c 6f 63 61 74 69 6f 6e 20 58 20 74 6f 20 62 65  location X to be
1f140 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
1f150 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 58 20  s..** ^If the X 
1f160 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
1f170 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e  ite3_realloc(X,N
1f180 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70  ).** is a NULL p
1f190 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20  ointer then its 
1f1a0 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e  behavior is iden
1f1b0 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67  tical to calling
1f1c0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
1f1d0 6f 63 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20 74 68  oc(N)..** ^If th
1f1e0 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e N parameter to
1f1f0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1f200 28 58 2c 4e 29 20 69 73 20 7a 65 72 6f 20 6f 72  (X,N) is zero or
1f210 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65  .** negative the
1f220 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
1f230 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61  s exactly the sa
1f240 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a  me as calling.**
1f250 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 58 29   sqlite3_free(X)
1f260 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65  ..** ^sqlite3_re
1f270 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72  alloc(X,N) retur
1f280 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
1f290 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
1f2a0 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61  ion.** of at lea
1f2b0 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69  st N bytes in si
1f2c0 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 69 6e  ze or NULL if in
1f2d0 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72  sufficient memor
1f2e0 79 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a  y is available..
1f2f0 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20  ** ^If M is the 
1f300 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f  size of the prio
1f310 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68  r allocation, th
1f320 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65  en min(N,M) byte
1f330 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f  s.** of the prio
1f340 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65  r allocation are
1f350 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65   copied into the
1f360 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75   beginning of bu
1f370 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ffer returned.**
1f380 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   by sqlite3_real
1f390 6c 6f 63 28 58 2c 4e 29 20 61 6e 64 20 74 68 65  loc(X,N) and the
1f3a0 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
1f3b0 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e  n is freed..** ^
1f3c0 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  If sqlite3_reall
1f3d0 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 20  oc(X,N) returns 
1f3e0 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20 70 6f  NULL and N is po
1f3f0 73 69 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65  sitive, then the
1f400 0a 2a 2a 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  .** prior alloca
1f410 74 69 6f 6e 20 69 73 20 6e 6f 74 20 66 72 65 65  tion is not free
1f420 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
1f430 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28  lite3_realloc64(
1f440 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 73 20  X,N) interfaces 
1f450 77 6f 72 6b 73 20 74 68 65 20 73 61 6d 65 20 61  works the same a
1f460 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 61  s.** sqlite3_rea
1f470 6c 6c 6f 63 28 58 2c 4e 29 20 65 78 63 65 70 74  lloc(X,N) except
1f480 20 74 68 61 74 20 4e 20 69 73 20 61 20 36 34 2d   that N is a 64-
1f490 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74  bit unsigned int
1f4a0 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20  eger instead.** 
1f4b0 6f 66 20 61 20 33 32 2d 62 69 74 20 73 69 67 6e  of a 32-bit sign
1f4c0 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a  ed integer..**.*
1f4d0 2a 20 5e 49 66 20 58 20 69 73 20 61 20 6d 65 6d  * ^If X is a mem
1f4e0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 70  ory allocation p
1f4f0 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e  reviously obtain
1f500 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ed from sqlite3_
1f510 6d 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c  malloc(),.** sql
1f520 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c  ite3_malloc64(),
1f530 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1f540 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  (), or sqlite3_r
1f550 65 61 6c 6c 6f 63 36 34 28 29 2c 20 74 68 65 6e  ealloc64(), then
1f560 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a  .** sqlite3_msiz
1f570 65 28 58 29 20 72 65 74 75 72 6e 73 20 74 68 65  e(X) returns the
1f580 20 73 69 7a 65 20 6f 66 20 74 68 61 74 20 6d 65   size of that me
1f590 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1f5a0 69 6e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 54 68  in bytes..** ^Th
1f5b0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
1f5c0 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a   by sqlite3_msiz
1f5d0 65 28 58 29 20 6d 69 67 68 74 20 62 65 20 6c 61  e(X) might be la
1f5e0 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 6e 75  rger than the nu
1f5f0 6d 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74 65 73  mber.** of bytes
1f600 20 72 65 71 75 65 73 74 65 64 20 77 68 65 6e 20   requested when 
1f610 58 20 77 61 73 20 61 6c 6c 6f 63 61 74 65 64 2e  X was allocated.
1f620 20 20 5e 49 66 20 58 20 69 73 20 61 20 4e 55 4c    ^If X is a NUL
1f630 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a 2a  L pointer then.*
1f640 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28  * sqlite3_msize(
1f650 58 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e  X) returns zero.
1f660 20 20 49 66 20 58 20 70 6f 69 6e 74 73 20 74 6f    If X points to
1f670 20 73 6f 6d 65 74 68 69 6e 67 20 74 68 61 74 20   something that 
1f680 69 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 62 65  is not.** the be
1f690 67 69 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d 6f 72  ginning of memor
1f6a0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 6f 72  y allocation, or
1f6b0 20 69 66 20 69 74 20 70 6f 69 6e 74 73 20 74 6f   if it points to
1f6c0 20 61 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a 20 76   a formerly.** v
1f6d0 61 6c 69 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  alid memory allo
1f6e0 63 61 74 69 6f 6e 20 74 68 61 74 20 68 61 73 20  cation that has 
1f6f0 6e 6f 77 20 62 65 65 6e 20 66 72 65 65 64 2c 20  now been freed, 
1f700 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
1f710 72 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  r.** of sqlite3_
1f720 6d 73 69 7a 65 28 58 29 20 69 73 20 75 6e 64 65  msize(X) is unde
1f730 66 69 6e 65 64 20 61 6e 64 20 70 6f 73 73 69 62  fined and possib
1f740 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a  ly harmful..**.*
1f750 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65  * ^The memory re
1f760 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
1f770 33 5f 6d 61 6c 6c 6f 63 28 29 2c 20 73 71 6c 69  3_malloc(), sqli
1f780 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 0a 2a  te3_realloc(),.*
1f790 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
1f7a0 36 34 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65  64(), and sqlite
1f7b0 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29 0a 2a 2a  3_realloc64().**
1f7c0 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e   is always align
1f7d0 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61  ed to at least a
1f7e0 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72  n 8 byte boundar
1f7f0 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20  y, or to a.** 4 
1f800 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69 66  byte boundary if
1f810 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42   the [SQLITE_4_B
1f820 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c  YTE_ALIGNED_MALL
1f830 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  OC] compile-time
1f840 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  .** option is us
1f850 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c  ed..**.** In SQL
1f860 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
1f870 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20  0 and 3.5.1, it 
1f880 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  was possible to 
1f890 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51  define.** the SQ
1f8a0 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59  LITE_OMIT_MEMORY
1f8b0 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63  _ALLOCATION whic
1f8c0 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68  h would cause th
1f8d0 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d  e built-in.** im
1f8e0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
1f8f0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74  these routines t
1f900 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54  o be omitted.  T
1f910 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a  hat capability.*
1f920 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70  * is no longer p
1f930 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62  rovided.  Only b
1f940 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
1f950 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65  llocators can be
1f960 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69   used..**.** Pri
1f970 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72  or to SQLite ver
1f980 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68 65  sion 3.7.10, the
1f990 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65   Windows OS inte
1f9a0 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c  rface layer call
1f9b0 65 64 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d  ed.** the system
1f9c0 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72   malloc() and fr
1f9d0 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 68  ee() directly wh
1f9e0 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a  en converting.**
1f9f0 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65   filenames betwe
1fa00 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63  en the UTF-8 enc
1fa10 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 51  oding used by SQ
1fa20 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74  Lite.** and what
1fa30 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e  ever filename en
1fa40 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 62  coding is used b
1fa50 79 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72  y the particular
1fa60 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74   Windows.** inst
1fa70 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72  allation.  Memor
1fa80 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
1fa90 6f 72 73 20 77 65 72 65 20 64 65 74 65 63 74 65  ors were detecte
1faa0 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 77  d, but.** they w
1fab0 65 72 65 20 72 65 70 6f 72 74 65 64 20 62 61 63  ere reported bac
1fac0 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e  k as [SQLITE_CAN
1fad0 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51  TOPEN] or.** [SQ
1fae0 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68  LITE_IOERR] rath
1faf0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
1fb00 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  NOMEM]..**.** Th
1fb10 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65  e pointer argume
1fb20 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  nts to [sqlite3_
1fb30 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  free()] and [sql
1fb40 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a  ite3_realloc()].
1fb50 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 65  ** must be eithe
1fb60 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70  r NULL or else p
1fb70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64  ointers obtained
1fb80 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a   from a prior.**
1fb90 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b   invocation of [
1fba0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1fbb0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
1fbc0 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61  alloc()] that ha
1fbd0 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65  ve.** not yet be
1fbe0 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a  en released..**.
1fbf0 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
1fc00 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64  on must not read
1fc10 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70 61   or write any pa
1fc20 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b  rt of.** a block
1fc30 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72   of memory after
1fc40 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c   it has been rel
1fc50 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b  eased using.** [
1fc60 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
1fc70 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
1fc80 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20  loc()]..*/.void 
1fc90 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  *sqlite3_malloc(
1fca0 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69  int);.void *sqli
1fcb0 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 73 71 6c  te3_malloc64(sql
1fcc0 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 76 6f  ite3_uint64);.vo
1fcd0 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c  id *sqlite3_real
1fce0 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b  loc(void*, int);
1fcf0 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72  .void *sqlite3_r
1fd00 65 61 6c 6c 6f 63 36 34 28 76 6f 69 64 2a 2c 20  ealloc64(void*, 
1fd10 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b  sqlite3_uint64);
1fd20 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72  .void sqlite3_fr
1fd30 65 65 28 76 6f 69 64 2a 29 3b 0a 73 71 6c 69 74  ee(void*);.sqlit
1fd40 65 33 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65  e3_uint64 sqlite
1fd50 33 5f 6d 73 69 7a 65 28 76 6f 69 64 2a 29 3b 0a  3_msize(void*);.
1fd60 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1fd70 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f   Memory Allocato
1fd80 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a  r Statistics.**.
1fd90 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64  ** SQLite provid
1fda0 65 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74  es these two int
1fdb0 65 72 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f  erfaces for repo
1fdc0 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61  rting on the sta
1fdd0 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  tus.** of the [s
1fde0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1fdf0 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  , [sqlite3_free(
1fe00 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
1fe10 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72  _realloc()].** r
1fe20 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66  outines, which f
1fe30 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e  orm the built-in
1fe40 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1fe50 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a  on subsystem..**
1fe60 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
1fe70 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
1fe80 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
1fe90 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
1fea0 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72  ytes.** of memor
1feb0 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73  y currently outs
1fec0 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65  tanding (malloce
1fed0 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29  d but not freed)
1fee0 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  ..** ^The [sqlit
1fef0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
1ff00 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72  ter()] routine r
1ff10 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d  eturns the maxim
1ff20 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b  um.** value of [
1ff30 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
1ff40 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65  sed()] since the
1ff50 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b   high-water mark
1ff60 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73  .** was last res
1ff70 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73  et.  ^The values
1ff80 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
1ff90 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
1ffa0 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  d()] and.** [sql
1ffb0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
1ffc0 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65  water()] include
1ffd0 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a   any overhead.**
1ffe0 20 61 64 64 65 64 20 62 79 20 53 51 4c 69 74 65   added by SQLite
1fff0 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e   in its implemen
20000 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  tation of [sqlit
20010 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a  e3_malloc()],.**
20020 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61   but not overhea
20030 64 20 61 64 64 65 64 20 62 79 20 74 68 65 20 61  d added by the a
20040 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79  ny underlying sy
20050 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20  stem library.** 
20060 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73  routines that [s
20070 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
20080 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a   may call..**.**
20090 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67   ^The memory hig
200a0 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20  h-water mark is 
200b0 72 65 73 65 74 20 74 6f 20 74 68 65 20 63 75 72  reset to the cur
200c0 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a  rent value of.**
200d0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
200e0 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20  _used()] if and 
200f0 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72 61  only if the para
20100 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c  meter to.** [sql
20110 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
20120 77 61 74 65 72 28 29 5d 20 69 73 20 74 72 75 65  water()] is true
20130 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65  .  ^The value re
20140 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71  turned.** by [sq
20150 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
20160 68 77 61 74 65 72 28 31 29 5d 20 69 73 20 74 68  hwater(1)] is th
20170 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72  e high-water mar
20180 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68  k.** prior to th
20190 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69  e reset..*/.sqli
201a0 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
201b0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f  3_memory_used(vo
201c0 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74  id);.sqlite3_int
201d0 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  64 sqlite3_memor
201e0 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 20  y_highwater(int 
201f0 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a  resetFlag);../*.
20200 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 65  ** CAPI3REF: Pse
20210 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65  udo-Random Numbe
20220 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a  r Generator.**.*
20230 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e  * SQLite contain
20240 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79  s a high-quality
20250 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e   pseudo-random n
20260 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20  umber generator 
20270 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a  (PRNG) used to.*
20280 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20  * select random 
20290 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d  [ROWID | ROWIDs]
202a0 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20   when inserting 
202b0 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f  new records into
202c0 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a   a table that.**
202d0 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 68   already uses th
202e0 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62  e largest possib
202f0 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65  le [ROWID].  The
20300 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73   PRNG is also us
20310 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75  ed for.** the bu
20320 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20  ild-in random() 
20330 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29  and randomblob()
20340 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20   SQL functions. 
20350 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
20360 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63  allows.** applic
20370 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73  ations to access
20380 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66   the same PRNG f
20390 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65  or other purpose
203a0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c  s..**.** ^A call
203b0 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   to this routine
203c0 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20   stores N bytes 
203d0 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e  of randomness in
203e0 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 20  to buffer P..** 
203f0 5e 54 68 65 20 50 20 70 61 72 61 6d 65 74 65 72  ^The P parameter
20400 20 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c 20 70   can be a NULL p
20410 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ointer..**.** ^I
20420 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68  f this routine h
20430 61 73 20 6e 6f 74 20 62 65 65 6e 20 70 72 65 76  as not been prev
20440 69 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20 6f 72  iously called or
20450 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 73   if the previous
20460 0a 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e 20 6c  .** call had N l
20470 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 6f 72 20  ess than one or 
20480 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66  a NULL pointer f
20490 6f 72 20 50 2c 20 74 68 65 6e 20 74 68 65 20 50  or P, then the P
204a0 52 4e 47 20 69 73 0a 2a 2a 20 73 65 65 64 65 64  RNG is.** seeded
204b0 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73   using randomnes
204c0 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  s obtained from 
204d0 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20  the xRandomness 
204e0 6d 65 74 68 6f 64 20 6f 66 0a 2a 2a 20 74 68 65  method of.** the
204f0 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
20500 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a  3_vfs] object..*
20510 2a 20 5e 49 66 20 74 68 65 20 70 72 65 76 69 6f  * ^If the previo
20520 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20  us call to this 
20530 72 6f 75 74 69 6e 65 20 68 61 64 20 61 6e 20 4e  routine had an N
20540 20 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20 61 6e   of 1 or more an
20550 64 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c 20  d a.** non-NULL 
20560 50 20 74 68 65 6e 20 74 68 65 20 70 73 65 75 64  P then the pseud
20570 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20  o-randomness is 
20580 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74  generated.** int
20590 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68  ernally and with
205a0 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20  out recourse to 
205b0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
205c0 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a  ] xRandomness.**
205d0 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64   method..*/.void
205e0 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e   sqlite3_randomn
205f0 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20  ess(int N, void 
20600 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  *P);../*.** CAPI
20610 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69  3REF: Compile-Ti
20620 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e  me Authorization
20630 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45   Callbacks.** ME
20640 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
20650 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 75 74 68   KEYWORDS: {auth
20660 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 7d  orizer callback}
20670 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
20680 74 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61  tine registers a
20690 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  n authorizer cal
206a0 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70 61 72  lback with a par
206b0 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61  ticular.** [data
206c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
206d0 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68  , supplied in th
206e0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
206f0 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72  ..** ^The author
20700 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
20710 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20   invoked as SQL 
20720 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62  statements are b
20730 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a  eing compiled.**
20740 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   by [sqlite3_pre
20750 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76  pare()] or its v
20760 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33  ariants [sqlite3
20770 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a  _prepare_v2()],.
20780 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
20790 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71  are16()] and [sq
207a0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
207b0 76 32 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69  v2()].  ^At vari
207c0 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75  ous.** points du
207d0 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61  ring the compila
207e0 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73  tion process, as
207f0 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20   logic is being 
20800 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65  created.** to pe
20810 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63  rform various ac
20820 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f  tions, the autho
20830 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
20840 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20  s invoked to.** 
20850 73 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74  see if those act
20860 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64  ions are allowed
20870 2e 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a  .  ^The authoriz
20880 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75  er callback shou
20890 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ld.** return [SQ
208a0 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f  LITE_OK] to allo
208b0 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53  w the action, [S
208c0 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f  QLITE_IGNORE] to
208d0 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a   disallow the.**
208e0 20 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e   specific action
208f0 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53   but allow the S
20900 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  QL statement to 
20910 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a  continue to be.*
20920 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b  * compiled, or [
20930 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20  SQLITE_DENY] to 
20940 63 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65  cause the entire
20950 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
20960 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64  o be.** rejected
20970 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20   with an error. 
20980 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69   ^If the authori
20990 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  zer callback ret
209a0 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75  urns.** any valu
209b0 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  e other than [SQ
209c0 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53  LITE_IGNORE], [S
209d0 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53  QLITE_OK], or [S
209e0 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74  QLITE_DENY].** t
209f0 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hen the [sqlite3
20a00 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
20a10 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c  r equivalent cal
20a20 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64  l that triggered
20a30 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a  .** the authoriz
20a40 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74  er will fail wit
20a50 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  h an error messa
20a60 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  ge..**.** When t
20a70 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
20a80 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  rns [SQLITE_OK],
20a90 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20   that means the 
20aa0 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71  operation.** req
20ab0 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e  uested is ok.  ^
20ac0 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  When the callbac
20ad0 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
20ae0 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20  E_DENY], the.** 
20af0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
20b00 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61  _v2()] or equiva
20b10 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74  lent call that t
20b20 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20  riggered the.** 
20b30 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20  authorizer will 
20b40 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72  fail with an err
20b50 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61  or message expla
20b60 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63  ining that.** ac
20b70 63 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20  cess is denied. 
20b80 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
20b90 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  t parameter to t
20ba0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
20bb0 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79  llback is a copy
20bc0 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a   of the third.**
20bd0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
20be0 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
20bf0 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72  thorizer() inter
20c00 66 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e  face. ^The secon
20c10 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74  d parameter.** t
20c20 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
20c30 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51  s an integer [SQ
20c40 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69  LITE_COPY | acti
20c50 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70  on code] that sp
20c60 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70  ecifies.** the p
20c70 61 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e  articular action
20c80 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65   to be authorize
20c90 64 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74 68  d. ^The third th
20ca0 72 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 61  rough sixth para
20cb0 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65  meters.** to the
20cc0 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 65 69   callback are ei
20cd0 74 68 65 72 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ther NULL pointe
20ce0 72 73 20 6f 72 20 7a 65 72 6f 2d 74 65 72 6d 69  rs or zero-termi
20cf0 6e 61 74 65 64 20 73 74 72 69 6e 67 73 0a 2a 2a  nated strings.**
20d00 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64   that contain ad
20d10 64 69 74 69 6f 6e 61 6c 20 64 65 74 61 69 6c 73  ditional details
20d20 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f   about the actio
20d30 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a  n to be authoriz
20d40 65 64 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  ed..** Applicati
20d50 6f 6e 73 20 6d 75 73 74 20 61 6c 77 61 79 73 20  ons must always 
20d60 62 65 20 70 72 65 70 61 72 65 64 20 74 6f 20 65  be prepared to e
20d70 6e 63 6f 75 6e 74 65 72 20 61 20 4e 55 4c 4c 20  ncounter a NULL 
20d80 70 6f 69 6e 74 65 72 20 69 6e 20 61 6e 79 0a 2a  pointer in any.*
20d90 2a 20 6f 66 20 74 68 65 20 74 68 69 72 64 20 74  * of the third t
20da0 68 72 6f 75 67 68 20 74 68 65 20 73 69 78 74 68  hrough the sixth
20db0 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74   parameters of t
20dc0 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e  he authorization
20dd0 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   callback..**.**
20de0 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20   ^If the action 
20df0 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  code is [SQLITE_
20e00 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65  READ].** and the
20e10 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
20e20 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  s [SQLITE_IGNORE
20e30 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70  ] then the.** [p
20e40 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
20e50 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  t] statement is 
20e60 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73  constructed to s
20e70 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e  ubstitute.** a N
20e80 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61  ULL value in pla
20e90 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20  ce of the table 
20ea0 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c  column that woul
20eb0 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72  d have.** been r
20ec0 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f  ead if [SQLITE_O
20ed0 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75  K] had been retu
20ee0 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49  rned.  The [SQLI
20ef0 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65  TE_IGNORE].** re
20f00 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64  turn can be used
20f10 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72   to deny an untr
20f20 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73  usted user acces
20f30 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a  s to individual.
20f40 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20  ** columns of a 
20f50 74 61 62 6c 65 2e 0a 2a 2a 20 5e 57 68 65 6e 20  table..** ^When 
20f60 61 20 74 61 62 6c 65 20 69 73 20 72 65 66 65 72  a table is refer
20f70 65 6e 63 65 64 20 62 79 20 61 20 5b 53 45 4c 45  enced by a [SELE
20f80 43 54 5d 20 62 75 74 20 6e 6f 20 63 6f 6c 75 6d  CT] but no colum
20f90 6e 20 76 61 6c 75 65 73 20 61 72 65 0a 2a 2a 20  n values are.** 
20fa0 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 20 74  extracted from t
20fb0 68 61 74 20 74 61 62 6c 65 20 28 66 6f 72 20 65  hat table (for e
20fc0 78 61 6d 70 6c 65 20 69 6e 20 61 20 71 75 65 72  xample in a quer
20fd0 79 20 6c 69 6b 65 0a 2a 2a 20 22 53 45 4c 45 43  y like.** "SELEC
20fe0 54 20 63 6f 75 6e 74 28 2a 29 20 46 52 4f 4d 20  T count(*) FROM 
20ff0 74 61 62 22 29 20 74 68 65 6e 20 74 68 65 20 5b  tab") then the [
21000 53 51 4c 49 54 45 5f 52 45 41 44 5d 20 61 75 74  SQLITE_READ] aut
21010 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
21020 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  .** is invoked o
21030 6e 63 65 20 66 6f 72 20 74 68 61 74 20 74 61 62  nce for that tab
21040 6c 65 20 77 69 74 68 20 61 20 63 6f 6c 75 6d 6e  le with a column
21050 20 6e 61 6d 65 20 74 68 61 74 20 69 73 20 61 6e   name that is an
21060 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a   empty string..*
21070 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e  * ^If the action
21080 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45   code is [SQLITE
21090 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65  _DELETE] and the
210a0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
210b0 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e  s.** [SQLITE_IGN
210c0 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44  ORE] then the [D
210d0 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e  ELETE] operation
210e0 20 70 72 6f 63 65 65 64 73 20 62 75 74 20 74 68   proceeds but th
210f0 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f  e.** [truncate o
21100 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20  ptimization] is 
21110 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c  disabled and all
21120 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65   rows are delete
21130 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a  d individually..
21140 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69  **.** An authori
21150 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 65 6e  zer is used when
21160 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
21170 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a  e | preparing].*
21180 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
21190 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74   from an untrust
211a0 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e  ed source, to en
211b0 73 75 72 65 20 74 68 61 74 20 74 68 65 20 53 51  sure that the SQ
211c0 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
211d0 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63  do not try to ac
211e0 63 65 73 73 20 64 61 74 61 20 74 68 65 79 20 61  cess data they a
211f0 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74  re not allowed t
21200 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74  o see, or that t
21210 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72  hey do not.** tr
21220 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c  y to execute mal
21230 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74  icious statement
21240 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 68  s that damage th
21250 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72  e database.  For
21260 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20  .** example, an 
21270 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20  application may 
21280 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20  allow a user to 
21290 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 0a  enter arbitrary.
212a0 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 66  ** SQL queries f
212b0 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79  or evaluation by
212c0 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 75   a database.  Bu
212d0 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
212e0 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61  n does.** not wa
212f0 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 62  nt the user to b
21300 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61  e able to make a
21310 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 73  rbitrary changes
21320 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62   to the.** datab
21330 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69  ase.  An authori
21340 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62  zer could then b
21350 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77  e put in place w
21360 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72  hile the.** user
21370 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20  -entered SQL is 
21380 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  being [sqlite3_p
21390 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 65  repare | prepare
213a0 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c  d] that.** disal
213b0 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67 20  lows everything 
213c0 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20  except [SELECT] 
213d0 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
213e0 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * Applications t
213f0 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63  hat need to proc
21400 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74  ess SQL from unt
21410 72 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a  rusted sources.*
21420 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e  * might also con
21430 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72  sider lowering r
21440 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75  esource limits u
21450 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69  sing [sqlite3_li
21460 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69  mit()].** and li
21470 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73 65 20  miting database 
21480 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b  size using the [
21490 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20  max_page_count] 
214a0 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61  [PRAGMA].** in a
214b0 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67  ddition to using
214c0 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a   an authorizer..
214d0 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73  **.** ^(Only a s
214e0 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72  ingle authorizer
214f0 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65   can be in place
21500 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 63   on a database c
21510 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20  onnection.** at 
21520 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61  a time.  Each ca
21530 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65  ll to sqlite3_se
21540 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65  t_authorizer ove
21550 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72  rrides the.** pr
21560 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20  evious call.)^  
21570 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61 75 74  ^Disable the aut
21580 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61  horizer by insta
21590 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c  lling a NULL cal
215a0 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75  lback..** The au
215b0 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61  thorizer is disa
215c0 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e  bled by default.
215d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  .**.** The autho
215e0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d  rizer callback m
215f0 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68  ust not do anyth
21600 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f  ing that will mo
21610 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61  dify.** the data
21620 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
21630 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
21640 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
21650 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  back..** Note th
21660 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  at [sqlite3_prep
21670 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
21680 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62  qlite3_step()] b
21690 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72  oth modify their
216a0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
216b0 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  nections for the
216c0 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64   meaning of "mod
216d0 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72  ify" in this par
216e0 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57  agraph..**.** ^W
216f0 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hen [sqlite3_pre
21700 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73  pare_v2()] is us
21710 65 64 20 74 6f 20 70 72 65 70 61 72 65 20 61 20  ed to prepare a 
21720 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a  statement, the.*
21730 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68  * statement migh
21740 74 20 62 65 20 72 65 2d 70 72 65 70 61 72 65 64  t be re-prepared
21750 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33   during [sqlite3
21760 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20  _step()] due to 
21770 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61  a .** schema cha
21780 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65  nge.  Hence, the
21790 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
217a0 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74 20  uld ensure that 
217b0 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61  the.** correct a
217c0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
217d0 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c  ck remains in pl
217e0 61 63 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b  ace during the [
217f0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
21800 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61  .**.** ^Note tha
21810 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  t the authorizer
21820 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
21830 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67  oked only during
21840 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
21850 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76  pare()] or its v
21860 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72  ariants.  Author
21870 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a  ization is not.*
21880 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69  * performed duri
21890 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61  ng statement eva
218a0 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69  luation in [sqli
218b0 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c  te3_step()], unl
218c0 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64  ess.** as stated
218d0 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73   in the previous
218e0 20 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69   paragraph, sqli
218f0 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b  te3_step() invok
21900 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72  es.** sqlite3_pr
21910 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65  epare_v2() to re
21920 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d  prepare a statem
21930 65 6e 74 20 61 66 74 65 72 20 61 20 73 63 68 65  ent after a sche
21940 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e  ma change..*/.in
21950 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  t sqlite3_set_au
21960 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69  thorizer(.  sqli
21970 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41  te3*,.  int (*xA
21980 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  uth)(void*,int,c
21990 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
219a0 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
219b0 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  r*,const char*),
219c0 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61  .  void *pUserDa
219d0 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ta.);../*.** CAP
219e0 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65  I3REF: Authorize
219f0 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a  r Return Codes.*
21a00 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  *.** The [sqlite
21a10 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
21a20 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61   | authorizer ca
21a30 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d  llback function]
21a40 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20   must.** return 
21a50 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f  either [SQLITE_O
21a60 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65  K] or one of the
21a70 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73  se two constants
21a80 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20   in order.** to 
21a90 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68  signal SQLite wh
21aa0 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
21ab0 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69   action is permi
21ac0 74 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a  tted.  See the.*
21ad0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  * [sqlite3_set_a
21ae0 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68  uthorizer | auth
21af0 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61  orizer documenta
21b00 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69  tion] for additi
21b10 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  onal.** informat
21b20 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  ion..**.** Note 
21b30 74 68 61 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f  that SQLITE_IGNO
21b40 52 45 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20  RE is also used 
21b50 61 73 20 61 20 5b 63 6f 6e 66 6c 69 63 74 20 72  as a [conflict r
21b60 65 73 6f 6c 75 74 69 6f 6e 20 6d 6f 64 65 5d 0a  esolution mode].
21b70 2a 2a 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  ** returned from
21b80 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 74   the [sqlite3_vt
21b90 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29  ab_on_conflict()
21ba0 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a  ] interface..*/.
21bb0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
21bc0 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f  ENY   1   /* Abo
21bd0 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  rt the SQL state
21be0 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72  ment with an err
21bf0 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  or */.#define SQ
21c00 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20  LITE_IGNORE 2   
21c10 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61  /* Don't allow a
21c20 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74  ccess, but don't
21c30 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72   generate an err
21c40 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  or */../*.** CAP
21c50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65  I3REF: Authorize
21c60 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a  r Action Codes.*
21c70 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  *.** The [sqlite
21c80 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
21c90 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  ()] interface re
21ca0 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61  gisters a callba
21cb0 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74  ck function.** t
21cc0 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74  hat is invoked t
21cd0 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74  o authorize cert
21ce0 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ain SQL statemen
21cf0 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a  t actions.  The.
21d00 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
21d10 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ter to the callb
21d20 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ack is an intege
21d30 72 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 63  r code that spec
21d40 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63  ifies.** what ac
21d50 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75  tion is being au
21d60 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65  thorized.  These
21d70 20 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 72   are the integer
21d80 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68   action codes th
21d90 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72  at.** the author
21da0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61  izer callback ma
21db0 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a  y be passed..**.
21dc0 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20  ** These action 
21dd0 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e  code values sign
21de0 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66  ify what kind of
21df0 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f   operation is to
21e00 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65   be.** authorize
21e10 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20  d.  The 3rd and 
21e20 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74  4th parameters t
21e30 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74  o the authorizat
21e40 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  ion.** callback 
21e50 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65  function will be
21e60 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e   parameters or N
21e70 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ULL depending on
21e80 20 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a   which of these.
21e90 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64  ** codes is used
21ea0 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
21eb0 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65  arameter.  ^(The
21ec0 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
21ed0 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69  o the.** authori
21ee0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
21ef0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
21f00 64 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22  database ("main"
21f10 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63  , "temp",.** etc
21f20 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65  .) if applicable
21f30 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61  .)^  ^The 6th pa
21f40 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
21f50 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
21f60 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d  ck.** is the nam
21f70 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d  e of the inner-m
21f80 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76  ost trigger or v
21f90 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70  iew that is resp
21fa0 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74  onsible for.** t
21fb0 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70  he access attemp
21fc0 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69  t or NULL if thi
21fd0 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  s access attempt
21fe0 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f   is directly fro
21ff0 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53  m.** top-level S
22000 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a  QL code..*/./***
22010 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
22020 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
22030 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a  ******** 3rd ***
22040 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a  ********* 4th **
22050 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69  *********/.#defi
22060 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
22070 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  _INDEX          
22080 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  1   /* Index Nam
22090 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
220a0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
220b0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
220c0 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32  TABLE          2
220d0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
220e0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
220f0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
22100 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
22110 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20  EMP_INDEX     3 
22120 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
22130 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
22140 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
22150 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
22160 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20  MP_TABLE     4  
22170 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
22180 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
22190 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
221a0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
221b0 50 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 20  P_TRIGGER   5   
221c0 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
221d0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
221e0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
221f0 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
22200 5f 56 49 45 57 20 20 20 20 20 20 36 20 20 20 2f  _VIEW      6   /
22210 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
22220 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
22230 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22240 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47  ITE_CREATE_TRIGG
22250 45 52 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a  ER        7   /*
22260 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
22270 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
22280 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
22290 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20  TE_CREATE_VIEW  
222a0 20 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20           8   /* 
222b0 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
222c0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
222d0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
222e0 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20  E_DELETE        
222f0 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54          9   /* T
22300 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
22310 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
22320 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22330 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20  _DROP_INDEX     
22340 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e        10   /* In
22350 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
22360 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
22370 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22380 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20  DROP_TABLE      
22390 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62       11   /* Tab
223a0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
223b0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
223c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
223d0 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20  ROP_TEMP_INDEX  
223e0 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65      12   /* Inde
223f0 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
22400 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
22410 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
22420 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20  OP_TEMP_TABLE   
22430 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65     13   /* Table
22440 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
22450 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
22460 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
22470 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20  P_TEMP_TRIGGER  
22480 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65    14   /* Trigge
22490 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
224a0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
224b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
224c0 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20  _TEMP_VIEW      
224d0 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61   15   /* View Na
224e0 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
224f0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
22500 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
22510 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 20  TRIGGER         
22520 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20  16   /* Trigger 
22530 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
22540 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
22550 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56  ne SQLITE_DROP_V
22560 49 45 57 20 20 20 20 20 20 20 20 20 20 20 20 31  IEW            1
22570 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  7   /* View Name
22580 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
22590 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
225a0 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20  e SQLITE_INSERT 
225b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38                18
225c0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
225d0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
225e0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
225f0 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20   SQLITE_PRAGMA  
22600 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39 20               19 
22610 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65    /* Pragma Name
22620 20 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 20       1st arg or 
22630 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20  NULL */.#define 
22640 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20  SQLITE_READ     
22650 20 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20              20  
22660 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
22670 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20      Column Name 
22680 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
22690 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20  QLITE_SELECT    
226a0 20 20 20 20 20 20 20 20 20 20 20 32 31 20 20 20             21   
226b0 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
226c0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
226d0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
226e0 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e  LITE_TRANSACTION
226f0 20 20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f            22   /
22700 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20  * Operation     
22710 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
22720 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22730 49 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 20  ITE_UPDATE      
22740 20 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a           23   /*
22750 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
22760 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20   Column Name    
22770 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
22780 54 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 20  TE_ATTACH       
22790 20 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20          24   /* 
227a0 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20  Filename        
227b0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
227c0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
227d0 45 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 20  E_DETACH        
227e0 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44         25   /* D
227f0 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e  atabase Name   N
22800 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
22810 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22820 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20  _ALTER_TABLE    
22830 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61        26   /* Da
22840 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61  tabase Name   Ta
22850 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
22860 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22870 52 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  REINDEX         
22880 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64       27   /* Ind
22890 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  ex Name      NUL
228a0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
228b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
228c0 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20  NALYZE          
228d0 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c      28   /* Tabl
228e0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
228f0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
22900 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
22910 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20  EATE_VTABLE     
22920 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65     29   /* Table
22930 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c   Name      Modul
22940 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  e Name     */.#d
22950 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
22960 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20  P_VTABLE        
22970 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20    30   /* Table 
22980 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65  Name      Module
22990 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
229a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43  fine SQLITE_FUNC
229b0 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20  TION            
229c0 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20   31   /* NULL   
229d0 20 20 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f           Functio
229e0 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66  n Name   */.#def
229f0 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50  ine SQLITE_SAVEP
22a00 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20  OINT            
22a10 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f  32   /* Operatio
22a20 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e  n       Savepoin
22a30 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69  t Name  */.#defi
22a40 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20  ne SQLITE_COPY  
22a50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
22a60 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72  0   /* No longer
22a70 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65   used */.#define
22a80 20 53 51 4c 49 54 45 5f 52 45 43 55 52 53 49 56   SQLITE_RECURSIV
22a90 45 20 20 20 20 20 20 20 20 20 20 20 20 33 33 20  E            33 
22aa0 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20    /* NULL       
22ab0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
22ac0 20 20 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43       */../*.** C
22ad0 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67  API3REF: Tracing
22ae0 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46   And Profiling F
22af0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48  unctions.** METH
22b00 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
22b10 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
22b20 20 61 72 65 20 64 65 70 72 65 63 61 74 65 64 2e   are deprecated.
22b30 20 55 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65   Use the [sqlite
22b40 33 5f 74 72 61 63 65 5f 76 32 28 29 5d 20 69 6e  3_trace_v2()] in
22b50 74 65 72 66 61 63 65 0a 2a 2a 20 69 6e 73 74 65  terface.** inste
22b60 61 64 20 6f 66 20 74 68 65 20 72 6f 75 74 69 6e  ad of the routin
22b70 65 73 20 64 65 73 63 72 69 62 65 64 20 68 65 72  es described her
22b80 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  e..**.** These r
22b90 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 72  outines register
22ba0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
22bb0 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 20  ons that can be 
22bc0 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63  used for.** trac
22bd0 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e  ing and profilin
22be0 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20  g the execution 
22bf0 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  of SQL statement
22c00 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61  s..**.** ^The ca
22c10 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
22c20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71  registered by sq
22c30 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 69 73  lite3_trace() is
22c40 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76   invoked at.** v
22c50 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65  arious times whe
22c60 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
22c70 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20  nt is being run 
22c80 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  by [sqlite3_step
22c90 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ()]..** ^The sql
22ca0 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c  ite3_trace() cal
22cb0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
22cc0 20 77 69 74 68 20 61 20 55 54 46 2d 38 20 72 65   with a UTF-8 re
22cd0 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a  ndering of the.*
22ce0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  * SQL statement 
22cf0 74 65 78 74 20 61 73 20 74 68 65 20 73 74 61 74  text as the stat
22d00 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67 69  ement first begi
22d10 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a  ns executing..**
22d20 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20 73 71   ^(Additional sq
22d30 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61  lite3_trace() ca
22d40 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 20 6f 63  llbacks might oc
22d50 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74  cur.** as each t
22d60 72 69 67 67 65 72 65 64 20 73 75 62 70 72 6f 67  riggered subprog
22d70 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20  ram is entered. 
22d80 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66   The callbacks f
22d90 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63  or triggers.** c
22da0 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53  ontain a UTF-8 S
22db0 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20  QL comment that 
22dc0 69 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 74  identifies the t
22dd0 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20  rigger.)^.**.** 
22de0 54 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43  The [SQLITE_TRAC
22df0 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f  E_SIZE_LIMIT] co
22e00 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
22e10 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
22e20 20 6c 69 6d 69 74 0a 2a 2a 20 74 68 65 20 6c 65   limit.** the le
22e30 6e 67 74 68 20 6f 66 20 5b 62 6f 75 6e 64 20 70  ngth of [bound p
22e40 61 72 61 6d 65 74 65 72 5d 20 65 78 70 61 6e 73  arameter] expans
22e50 69 6f 6e 20 69 6e 20 74 68 65 20 6f 75 74 70 75  ion in the outpu
22e60 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 74 72 61  t of sqlite3_tra
22e70 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ce()..**.** ^The
22e80 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
22e90 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
22ea0 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65   sqlite3_profile
22eb0 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
22ec0 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61   as each SQL sta
22ed0 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e  tement finishes.
22ee0 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63    ^The profile c
22ef0 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73  allback contains
22f00 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  .** the original
22f10 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
22f20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20  and an estimate 
22f30 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69  of wall-clock ti
22f40 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e  me.** of how lon
22f50 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74  g that statement
22f60 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e   took to run.  ^
22f70 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c  The profile call
22f80 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20  back.** time is 
22f90 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f  in units of nano
22fa0 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72  seconds, however
22fb0 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70   the current imp
22fc0 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69  lementation.** i
22fd0 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f  s only capable o
22fe0 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65  f millisecond re
22ff0 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65 20  solution so the 
23000 73 69 78 20 6c 65 61 73 74 20 73 69 67 6e 69 66  six least signif
23010 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20  icant.** digits 
23020 69 6e 20 74 68 65 20 74 69 6d 65 20 61 72 65 20  in the time are 
23030 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75  meaningless.  Fu
23040 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
23050 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74   SQLite.** might
23060 20 70 72 6f 76 69 64 65 20 67 72 65 61 74 65 72   provide greater
23070 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74   resolution on t
23080 68 65 20 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c  he profiler call
23090 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71  back.  The.** sq
230a0 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20  lite3_profile() 
230b0 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73  function is cons
230c0 69 64 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e  idered experimen
230d0 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75  tal and is.** su
230e0 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20  bject to change 
230f0 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f  in future versio
23100 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  ns of SQLite..*/
23110 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
23120 45 44 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  ED void *sqlite3
23130 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c  _trace(sqlite3*,
23140 0a 20 20 20 76 6f 69 64 28 2a 78 54 72 61 63 65  .   void(*xTrace
23150 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68  )(void*,const ch
23160 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51  ar*), void*);.SQ
23170 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
23180 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72  void *sqlite3_pr
23190 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a  ofile(sqlite3*,.
231a0 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c     void(*xProfil
231b0 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63  e)(void*,const c
231c0 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e  har*,sqlite3_uin
231d0 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  t64), void*);../
231e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
231f0 51 4c 20 54 72 61 63 65 20 45 76 65 6e 74 20 43  QL Trace Event C
23200 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  odes.** KEYWORDS
23210 3a 20 53 51 4c 49 54 45 5f 54 52 41 43 45 0a 2a  : SQLITE_TRACE.*
23220 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
23230 61 6e 74 73 20 69 64 65 6e 74 69 66 79 20 63 6c  ants identify cl
23240 61 73 73 65 73 20 6f 66 20 65 76 65 6e 74 73 20  asses of events 
23250 74 68 61 74 20 63 61 6e 20 62 65 20 6d 6f 6e 69  that can be moni
23260 74 6f 72 65 64 0a 2a 2a 20 75 73 69 6e 67 20 74  tored.** using t
23270 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63  he [sqlite3_trac
23280 65 5f 76 32 28 29 5d 20 74 72 61 63 69 6e 67 20  e_v2()] tracing 
23290 6c 6f 67 69 63 2e 20 20 54 68 65 20 74 68 69 72  logic.  The thir
232a0 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  d argument.** to
232b0 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f   [sqlite3_trace_
232c0 76 32 28 29 5d 20 69 73 20 61 6e 20 4f 52 2d 65  v2()] is an OR-e
232d0 64 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66  d combination of
232e0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 0a   one or more of.
232f0 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ** the following
23300 20 63 6f 6e 73 74 61 6e 74 73 2e 20 20 5e 54 68   constants.  ^Th
23310 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
23320 20 74 6f 20 74 68 65 20 74 72 61 63 65 20 63 61   to the trace ca
23330 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6f 6e 65  llback.** is one
23340 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
23350 67 20 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a  g constants..**.
23360 2a 2a 20 4e 65 77 20 74 72 61 63 69 6e 67 20 63  ** New tracing c
23370 6f 6e 73 74 61 6e 74 73 20 6d 61 79 20 62 65 20  onstants may be 
23380 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
23390 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20  releases..**.** 
233a0 5e 41 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63  ^A trace callbac
233b0 6b 20 68 61 73 20 66 6f 75 72 20 61 72 67 75 6d  k has four argum
233c0 65 6e 74 73 3a 20 78 43 61 6c 6c 62 61 63 6b 28  ents: xCallback(
233d0 54 2c 43 2c 50 2c 58 29 2e 0a 2a 2a 20 5e 54 68  T,C,P,X)..** ^Th
233e0 65 20 54 20 61 72 67 75 6d 65 6e 74 20 69 73 20  e T argument is 
233f0 6f 6e 65 20 6f 66 20 74 68 65 20 69 6e 74 65 67  one of the integ
23400 65 72 20 74 79 70 65 20 63 6f 64 65 73 20 61 62  er type codes ab
23410 6f 76 65 2e 0a 2a 2a 20 5e 54 68 65 20 43 20 61  ove..** ^The C a
23420 72 67 75 6d 65 6e 74 20 69 73 20 61 20 63 6f 70  rgument is a cop
23430 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 78 74  y of the context
23440 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20   pointer passed 
23450 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75  in as the.** fou
23460 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rth argument to 
23470 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76  [sqlite3_trace_v
23480 32 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 50 20 61  2()]..** The P a
23490 6e 64 20 58 20 61 72 67 75 6d 65 6e 74 73 20 61  nd X arguments a
234a0 72 65 20 70 6f 69 6e 74 65 72 73 20 77 68 6f 73  re pointers whos
234b0 65 20 6d 65 61 6e 69 6e 67 73 20 64 65 70 65 6e  e meanings depen
234c0 64 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20 3c 64  d on T..**.** <d
234d0 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54  l>.** [[SQLITE_T
234e0 52 41 43 45 5f 53 54 4d 54 5d 5d 20 3c 64 74 3e  RACE_STMT]] <dt>
234f0 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d  SQLITE_TRACE_STM
23500 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41  T</dt>.** <dd>^A
23510 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53  n SQLITE_TRACE_S
23520 54 4d 54 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  TMT callback is 
23530 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61 20 70  invoked when a p
23540 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
23550 74 0a 2a 2a 20 66 69 72 73 74 20 62 65 67 69 6e  t.** first begin
23560 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 70 6f  s running and po
23570 73 73 69 62 6c 79 20 61 74 20 6f 74 68 65 72 20  ssibly at other 
23580 74 69 6d 65 73 20 64 75 72 69 6e 67 20 74 68 65  times during the
23590 0a 2a 2a 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  .** execution of
235a0 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
235b0 61 74 65 6d 65 6e 74 2c 20 73 75 63 68 20 61 73  atement, such as
235c0 20 61 74 20 74 68 65 20 73 74 61 72 74 20 6f 66   at the start of
235d0 20 65 61 63 68 0a 2a 2a 20 74 72 69 67 67 65 72   each.** trigger
235e0 20 73 75 62 70 72 6f 67 72 61 6d 2e 20 5e 54 68   subprogram. ^Th
235f0 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20  e P argument is 
23600 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
23610 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
23620 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 65 20 58  atement]. ^The X
23630 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
23640 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69  ointer to a stri
23650 6e 67 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74  ng which.** is t
23660 68 65 20 75 6e 65 78 70 61 6e 64 65 64 20 53 51  he unexpanded SQ
23670 4c 20 74 65 78 74 20 6f 66 20 74 68 65 20 70 72  L text of the pr
23680 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
23690 20 6f 72 20 61 6e 20 53 51 4c 20 63 6f 6d 6d 65   or an SQL comme
236a0 6e 74 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69  nt .** that indi
236b0 63 61 74 65 73 20 74 68 65 20 69 6e 76 6f 63 61  cates the invoca
236c0 74 69 6f 6e 20 6f 66 20 61 20 74 72 69 67 67 65  tion of a trigge
236d0 72 2e 20 20 5e 54 68 65 20 63 61 6c 6c 62 61 63  r.  ^The callbac
236e0 6b 20 63 61 6e 20 63 6f 6d 70 75 74 65 0a 2a 2a  k can compute.**
236f0 20 74 68 65 20 73 61 6d 65 20 74 65 78 74 20 74   the same text t
23700 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 20 62  hat would have b
23710 65 65 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20  een returned by 
23720 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69  the legacy [sqli
23730 74 65 33 5f 74 72 61 63 65 28 29 5d 0a 2a 2a 20  te3_trace()].** 
23740 69 6e 74 65 72 66 61 63 65 20 62 79 20 75 73 69  interface by usi
23750 6e 67 20 74 68 65 20 58 20 61 72 67 75 6d 65 6e  ng the X argumen
23760 74 20 77 68 65 6e 20 58 20 62 65 67 69 6e 73 20  t when X begins 
23770 77 69 74 68 20 22 2d 2d 22 20 61 6e 64 20 69 6e  with "--" and in
23780 76 6f 6b 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74  voking.** [sqlit
23790 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28  e3_expanded_sql(
237a0 50 29 5d 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a  P)] otherwise..*
237b0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52  *.** [[SQLITE_TR
237c0 41 43 45 5f 50 52 4f 46 49 4c 45 5d 5d 20 3c 64  ACE_PROFILE]] <d
237d0 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50  t>SQLITE_TRACE_P
237e0 52 4f 46 49 4c 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  ROFILE</dt>.** <
237f0 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52  dd>^An SQLITE_TR
23800 41 43 45 5f 50 52 4f 46 49 4c 45 20 63 61 6c 6c  ACE_PROFILE call
23810 62 61 63 6b 20 70 72 6f 76 69 64 65 73 20 61 70  back provides ap
23820 70 72 6f 78 69 6d 61 74 65 6c 79 20 74 68 65 20  proximately the 
23830 73 61 6d 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  same.** informat
23840 69 6f 6e 20 61 73 20 69 73 20 70 72 6f 76 69 64  ion as is provid
23850 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
23860 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 20 63 61  e3_profile()] ca
23870 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20  llback..** ^The 
23880 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  P argument is a 
23890 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
238a0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
238b0 6e 74 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 58  nt] and the.** X
238c0 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73   argument points
238d0 20 74 6f 20 61 20 36 34 2d 62 69 74 20 69 6e 74   to a 64-bit int
238e0 65 67 65 72 20 77 68 69 63 68 20 69 73 20 74 68  eger which is th
238f0 65 20 65 73 74 69 6d 61 74 65 64 20 6f 66 0a 2a  e estimated of.*
23900 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
23910 6e 61 6e 6f 73 65 63 6f 6e 64 20 74 68 61 74 20  nanosecond that 
23920 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
23930 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72  tement took to r
23940 75 6e 2e 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49  un..** ^The SQLI
23950 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45  TE_TRACE_PROFILE
23960 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
23970 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20 73 74  oked when the st
23980 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73  atement finishes
23990 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
239a0 5f 54 52 41 43 45 5f 52 4f 57 5d 5d 20 3c 64 74  _TRACE_ROW]] <dt
239b0 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f  >SQLITE_TRACE_RO
239c0 57 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41  W</dt>.** <dd>^A
239d0 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52  n SQLITE_TRACE_R
239e0 4f 57 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  OW callback is i
239f0 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20  nvoked whenever 
23a00 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  a prepared.** st
23a10 61 74 65 6d 65 6e 74 20 67 65 6e 65 72 61 74 65  atement generate
23a20 73 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f  s a single row o
23a30 66 20 72 65 73 75 6c 74 2e 20 20 0a 2a 2a 20 5e  f result.  .** ^
23a40 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69  The P argument i
23a50 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
23a60 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
23a70 74 65 6d 65 6e 74 5d 20 61 6e 64 20 74 68 65 0a  tement] and the.
23a80 2a 2a 20 58 20 61 72 67 75 6d 65 6e 74 20 69 73  ** X argument is
23a90 20 75 6e 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b   unused..**.** [
23aa0 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c  [SQLITE_TRACE_CL
23ab0 4f 53 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  OSE]] <dt>SQLITE
23ac0 5f 54 52 41 43 45 5f 43 4c 4f 53 45 3c 2f 64 74  _TRACE_CLOSE</dt
23ad0 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c  >.** <dd>^An SQL
23ae0 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 20  ITE_TRACE_CLOSE 
23af0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
23b00 6b 65 64 20 77 68 65 6e 20 61 20 64 61 74 61 62  ked when a datab
23b10 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
23b20 6e 20 63 6c 6f 73 65 73 2e 0a 2a 2a 20 5e 54 68  n closes..** ^Th
23b30 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20  e P argument is 
23b40 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
23b50 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
23b60 63 74 69 6f 6e 5d 20 6f 62 6a 65 63 74 0a 2a 2a  ction] object.**
23b70 20 61 6e 64 20 74 68 65 20 58 20 61 72 67 75 6d   and the X argum
23b80 65 6e 74 20 69 73 20 75 6e 75 73 65 64 2e 0a 2a  ent is unused..*
23b90 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </dl>.*/.#defi
23ba0 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  ne SQLITE_TRACE_
23bb0 53 54 4d 54 20 20 20 20 20 20 20 30 78 30 31 0a  STMT       0x01.
23bc0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
23bd0 52 41 43 45 5f 50 52 4f 46 49 4c 45 20 20 20 20  RACE_PROFILE    
23be0 30 78 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c  0x02.#define SQL
23bf0 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 20 20 20  ITE_TRACE_ROW   
23c00 20 20 20 20 20 30 78 30 34 0a 23 64 65 66 69 6e       0x04.#defin
23c10 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43  e SQLITE_TRACE_C
23c20 4c 4f 53 45 20 20 20 20 20 20 30 78 30 38 0a 0a  LOSE      0x08..
23c30 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
23c40 53 51 4c 20 54 72 61 63 65 20 48 6f 6f 6b 0a 2a  SQL Trace Hook.*
23c50 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
23c60 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  3.**.** ^The sql
23c70 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 44 2c  ite3_trace_v2(D,
23c80 4d 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65  M,X,P) interface
23c90 20 72 65 67 69 73 74 65 72 73 20 61 20 74 72 61   registers a tra
23ca0 63 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66  ce callback.** f
23cb0 75 6e 63 74 69 6f 6e 20 58 20 61 67 61 69 6e 73  unction X agains
23cc0 74 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  t [database conn
23cd0 65 63 74 69 6f 6e 5d 20 44 2c 20 75 73 69 6e 67  ection] D, using
23ce0 20 70 72 6f 70 65 72 74 79 20 6d 61 73 6b 20 4d   property mask M
23cf0 0a 2a 2a 20 61 6e 64 20 63 6f 6e 74 65 78 74 20  .** and context 
23d00 70 6f 69 6e 74 65 72 20 50 2e 20 20 5e 49 66 20  pointer P.  ^If 
23d10 74 68 65 20 58 20 63 61 6c 6c 62 61 63 6b 20 69  the X callback i
23d20 73 0a 2a 2a 20 4e 55 4c 4c 20 6f 72 20 69 66 20  s.** NULL or if 
23d30 74 68 65 20 4d 20 6d 61 73 6b 20 69 73 20 7a 65  the M mask is ze
23d40 72 6f 2c 20 74 68 65 6e 20 74 72 61 63 69 6e 67  ro, then tracing
23d50 20 69 73 20 64 69 73 61 62 6c 65 64 2e 20 20 54   is disabled.  T
23d60 68 65 0a 2a 2a 20 4d 20 61 72 67 75 6d 65 6e 74  he.** M argument
23d70 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20 62   should be the b
23d80 69 74 77 69 73 65 20 4f 52 2d 65 64 20 63 6f 6d  itwise OR-ed com
23d90 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 7a  bination of.** z
23da0 65 72 6f 20 6f 72 20 6d 6f 72 65 20 5b 53 51 4c  ero or more [SQL
23db0 49 54 45 5f 54 52 41 43 45 5d 20 63 6f 6e 73 74  ITE_TRACE] const
23dc0 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 45 61 63  ants..**.** ^Eac
23dd0 68 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72  h call to either
23de0 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
23df0 20 6f 72 20 73 71 6c 69 74 65 33 5f 74 72 61 63   or sqlite3_trac
23e00 65 5f 76 32 28 29 20 6f 76 65 72 72 69 64 65 73  e_v2() overrides
23e10 20 0a 2a 2a 20 28 63 61 6e 63 65 6c 73 29 20 61   .** (cancels) a
23e20 6e 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 20 74  ny prior calls t
23e30 6f 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  o sqlite3_trace(
23e40 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 74 72 61  ) or sqlite3_tra
23e50 63 65 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  ce_v2()..**.** ^
23e60 54 68 65 20 58 20 63 61 6c 6c 62 61 63 6b 20 69  The X callback i
23e70 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  s invoked whenev
23e80 65 72 20 61 6e 79 20 6f 66 20 74 68 65 20 65 76  er any of the ev
23e90 65 6e 74 73 20 69 64 65 6e 74 69 66 69 65 64 20  ents identified 
23ea0 62 79 20 0a 2a 2a 20 6d 61 73 6b 20 4d 20 6f 63  by .** mask M oc
23eb0 63 75 72 2e 20 20 5e 54 68 65 20 69 6e 74 65 67  cur.  ^The integ
23ec0 65 72 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  er return value 
23ed0 66 72 6f 6d 20 74 68 65 20 63 61 6c 6c 62 61 63  from the callbac
23ee0 6b 20 69 73 20 63 75 72 72 65 6e 74 6c 79 0a 2a  k is currently.*
23ef0 2a 20 69 67 6e 6f 72 65 64 2c 20 74 68 6f 75 67  * ignored, thoug
23f00 68 20 74 68 69 73 20 6d 61 79 20 63 68 61 6e 67  h this may chang
23f10 65 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  e in future rele
23f20 61 73 65 73 2e 20 20 43 61 6c 6c 62 61 63 6b 0a  ases.  Callback.
23f30 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
23f40 6e 73 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e  ns should return
23f50 20 7a 65 72 6f 20 74 6f 20 65 6e 73 75 72 65 20   zero to ensure 
23f60 66 75 74 75 72 65 20 63 6f 6d 70 61 74 69 62 69  future compatibi
23f70 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 74  lity..**.** ^A t
23f80 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 69 73  race callback is
23f90 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 66 6f   invoked with fo
23fa0 75 72 20 61 72 67 75 6d 65 6e 74 73 3a 20 63 61  ur arguments: ca
23fb0 6c 6c 62 61 63 6b 28 54 2c 43 2c 50 2c 58 29 2e  llback(T,C,P,X).
23fc0 0a 2a 2a 20 5e 54 68 65 20 54 20 61 72 67 75 6d  .** ^The T argum
23fd0 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 74 68  ent is one of th
23fe0 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5d  e [SQLITE_TRACE]
23ff0 0a 2a 2a 20 63 6f 6e 73 74 61 6e 74 73 20 74 6f  .** constants to
24000 20 69 6e 64 69 63 61 74 65 20 77 68 79 20 74 68   indicate why th
24010 65 20 63 61 6c 6c 62 61 63 6b 20 77 61 73 20 69  e callback was i
24020 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  nvoked..** ^The 
24030 43 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  C argument is a 
24040 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74  copy of the cont
24050 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20  ext pointer..** 
24060 54 68 65 20 50 20 61 6e 64 20 58 20 61 72 67 75  The P and X argu
24070 6d 65 6e 74 73 20 61 72 65 20 70 6f 69 6e 74 65  ments are pointe
24080 72 73 20 77 68 6f 73 65 20 6d 65 61 6e 69 6e 67  rs whose meaning
24090 73 20 64 65 70 65 6e 64 20 6f 6e 20 54 2e 0a 2a  s depend on T..*
240a0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
240b0 5f 74 72 61 63 65 5f 76 32 28 29 20 69 6e 74 65  _trace_v2() inte
240c0 72 66 61 63 65 20 69 73 20 69 6e 74 65 6e 64 65  rface is intende
240d0 64 20 74 6f 20 72 65 70 6c 61 63 65 20 74 68 65  d to replace the
240e0 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
240f0 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 74  faces [sqlite3_t
24100 72 61 63 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  race()] and [sql
24110 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 2c  ite3_profile()],
24120 20 62 6f 74 68 20 6f 66 20 77 68 69 63 68 0a 2a   both of which.*
24130 2a 20 61 72 65 20 64 65 70 72 65 63 61 74 65 64  * are deprecated
24140 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
24150 5f 74 72 61 63 65 5f 76 32 28 0a 20 20 73 71 6c  _trace_v2(.  sql
24160 69 74 65 33 2a 2c 0a 20 20 75 6e 73 69 67 6e 65  ite3*,.  unsigne
24170 64 20 75 4d 61 73 6b 2c 0a 20 20 69 6e 74 28 2a  d uMask,.  int(*
24180 78 43 61 6c 6c 62 61 63 6b 29 28 75 6e 73 69 67  xCallback)(unsig
24190 6e 65 64 2c 76 6f 69 64 2a 2c 76 6f 69 64 2a 2c  ned,void*,void*,
241a0 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 20 2a  void*),.  void *
241b0 70 43 74 78 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pCtx.);../*.** C
241c0 41 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50  API3REF: Query P
241d0 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b  rogress Callback
241e0 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
241f0 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ite3.**.** ^The 
24200 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
24210 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50  _handler(D,N,X,P
24220 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73  ) interface caus
24230 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a  es the callback.
24240 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f  ** function X to
24250 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 65 72 69   be invoked peri
24260 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20  odically during 
24270 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c  long running cal
24280 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ls to.** [sqlite
24290 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69  3_exec()], [sqli
242a0 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 20  te3_step()] and 
242b0 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
242c0 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74  le()] for.** dat
242d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
242e0 20 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20   D.  An example 
242f0 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20  use for this.** 
24300 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f 20  interface is to 
24310 6b 65 65 70 20 61 20 47 55 49 20 75 70 64 61 74  keep a GUI updat
24320 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67  ed during a larg
24330 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e  e query..**.** ^
24340 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 50 20  The parameter P 
24350 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67  is passed throug
24360 68 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61  h as the only pa
24370 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 0a  rameter to the .
24380 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  ** callback func
24390 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70 61  tion X.  ^The pa
243a0 72 61 6d 65 74 65 72 20 4e 20 69 73 20 74 68 65  rameter N is the
243b0 20 61 70 70 72 6f 78 69 6d 61 74 65 20 6e 75 6d   approximate num
243c0 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74  ber of .** [virt
243d0 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73 74  ual machine inst
243e0 72 75 63 74 69 6f 6e 73 5d 20 74 68 61 74 20 61  ructions] that a
243f0 72 65 20 65 76 61 6c 75 61 74 65 64 20 62 65 74  re evaluated bet
24400 77 65 65 6e 20 73 75 63 63 65 73 73 69 76 65 0a  ween successive.
24410 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  ** invocations o
24420 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 58  f the callback X
24430 2e 20 20 5e 49 66 20 4e 20 69 73 20 6c 65 73 73  .  ^If N is less
24440 20 74 68 61 6e 20 6f 6e 65 20 74 68 65 6e 20 74   than one then t
24450 68 65 20 70 72 6f 67 72 65 73 73 0a 2a 2a 20 68  he progress.** h
24460 61 6e 64 6c 65 72 20 69 73 20 64 69 73 61 62 6c  andler is disabl
24470 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20  ed..**.** ^Only 
24480 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65 73  a single progres
24490 73 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 62 65  s handler may be
244a0 20 64 65 66 69 6e 65 64 20 61 74 20 6f 6e 65 20   defined at one 
244b0 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74  time per.** [dat
244c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
244d0 5d 3b 20 73 65 74 74 69 6e 67 20 61 20 6e 65 77  ]; setting a new
244e0 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
244f0 72 20 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a  r cancels the.**
24500 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74   old one.  ^Sett
24510 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 58 20  ing parameter X 
24520 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73  to NULL disables
24530 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61   the progress ha
24540 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70  ndler..** ^The p
24550 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
24560 69 73 20 61 6c 73 6f 20 64 69 73 61 62 6c 65 64  is also disabled
24570 20 62 79 20 73 65 74 74 69 6e 67 20 4e 20 74 6f   by setting N to
24580 20 61 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a   a value less.**
24590 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e   than 1..**.** ^
245a0 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  If the progress 
245b0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
245c0 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f   non-zero, the o
245d0 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69  peration is.** i
245e0 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54 68 69  nterrupted.  Thi
245f0 73 20 66 65 61 74 75 72 65 20 63 61 6e 20 62 65  s feature can be
24600 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
24610 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22  nt a.** "Cancel"
24620 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49   button on a GUI
24630 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67   progress dialog
24640 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20   box..**.** The 
24650 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
24660 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e   callback must n
24670 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74  ot do anything t
24680 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a  hat will modify.
24690 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
246a0 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
246b0 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67  invoked the prog
246c0 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  ress handler..**
246d0 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
246e0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
246f0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
24700 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
24710 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
24720 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
24730 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
24740 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
24750 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
24760 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  **.*/.void sqlit
24770 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
24780 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  ler(sqlite3*, in
24790 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29  t, int(*)(void*)
247a0 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
247b0 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69   CAPI3REF: Openi
247c0 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62 61 73  ng A New Databas
247d0 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e Connection.** 
247e0 43 4f 4e 53 54 52 55 43 54 4f 52 3a 20 73 71 6c  CONSTRUCTOR: sql
247f0 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ite3.**.** ^Thes
24800 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20  e routines open 
24810 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61  an SQLite databa
24820 73 65 20 66 69 6c 65 20 61 73 20 73 70 65 63 69  se file as speci
24830 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20  fied by the .** 
24840 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
24850 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65  t. ^The filename
24860 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74   argument is int
24870 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d  erpreted as UTF-
24880 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  8 for.** sqlite3
24890 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
248a0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e  te3_open_v2() an
248b0 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74  d as UTF-16 in t
248c0 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a  he native byte.*
248d0 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69  * order for sqli
248e0 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28  te3_open16(). ^(
248f0 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  A [database conn
24900 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69  ection] handle i
24910 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74  s usually.** ret
24920 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20  urned in *ppDb, 
24930 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72  even if an error
24940 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e   occurs.  The on
24950 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20  ly exception is 
24960 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74  that.** if SQLit
24970 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61  e is unable to a
24980 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74  llocate memory t
24990 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69  o hold the [sqli
249a0 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20  te3] object,.** 
249b0 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77  a NULL will be w
249c0 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44  ritten into *ppD
249d0 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70  b instead of a p
249e0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
249f0 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63  qlite3].** objec
24a00 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61  t.)^ ^(If the da
24a10 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
24a20 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64   (and/or created
24a30 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20  ) successfully, 
24a40 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  then.** [SQLITE_
24a50 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  OK] is returned.
24a60 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b    Otherwise an [
24a70 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
24a80 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a  eturned.)^ ^The.
24a90 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ** [sqlite3_errm
24aa0 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  sg()] or [sqlite
24ab0 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f  3_errmsg16()] ro
24ac0 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73  utines can be us
24ad0 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20  ed to obtain.** 
24ae0 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75  an English langu
24af0 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20  age description 
24b00 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c  of the error fol
24b10 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65  lowing a failure
24b20 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68   of any.** of th
24b30 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  e sqlite3_open()
24b40 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
24b50 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e   ^The default en
24b60 63 6f 64 69 6e 67 20 77 69 6c 6c 20 62 65 20 55  coding will be U
24b70 54 46 2d 38 20 66 6f 72 20 64 61 74 61 62 61 73  TF-8 for databas
24b80 65 73 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  es created using
24b90 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
24ba0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  () or sqlite3_op
24bb0 65 6e 5f 76 32 28 29 2e 20 20 5e 54 68 65 20 64  en_v2().  ^The d
24bc0 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20  efault encoding 
24bd0 66 6f 72 20 64 61 74 61 62 61 73 65 73 0a 2a 2a  for databases.**
24be0 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 73   created using s
24bf0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20  qlite3_open16() 
24c00 77 69 6c 6c 20 62 65 20 55 54 46 2d 31 36 20 69  will be UTF-16 i
24c10 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
24c20 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 57  e order..**.** W
24c30 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e  hether or not an
24c40 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68   error occurs wh
24c50 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c  en it is opened,
24c60 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73   resources.** as
24c70 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
24c80 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
24c90 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73  ection] handle s
24ca0 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65  hould be release
24cb0 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20  d by.** passing 
24cc0 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  it to [sqlite3_c
24cd0 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20  lose()] when it 
24ce0 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71  is no longer req
24cf0 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  uired..**.** The
24d00 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
24d10 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72  () interface wor
24d20 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f  ks like sqlite3_
24d30 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74  open().** except
24d40 20 74 68 61 74 20 69 74 20 61 63 63 65 70 74 73   that it accepts
24d50 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
24d60 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61  parameters for a
24d70 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f  dditional contro
24d80 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65  l.** over the ne
24d90 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  w database conne
24da0 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c  ction.  ^(The fl
24db0 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ags parameter to
24dc0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
24dd0 5f 76 32 28 29 20 63 61 6e 20 74 61 6b 65 20 6f  _v2() can take o
24de0 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c  ne of.** the fol
24df0 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c  lowing three val
24e00 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20  ues, optionally 
24e10 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68  combined with th
24e20 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  e .** [SQLITE_OP
24e30 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51  EN_NOMUTEX], [SQ
24e40 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55  LITE_OPEN_FULLMU
24e50 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50  TEX], [SQLITE_OP
24e60 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 2c  EN_SHAREDCACHE],
24e70 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
24e80 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 2c 20  _PRIVATECACHE], 
24e90 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f  and/or [SQLITE_O
24ea0 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 73 3a 29  PEN_URI] flags:)
24eb0 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ^.**.** <dl>.** 
24ec0 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50  ^(<dt>[SQLITE_OP
24ed0 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74  EN_READONLY]</dt
24ee0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
24ef0 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
24f00 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64  in read-only mod
24f10 65 2e 20 20 49 66 20 74 68 65 20 64 61 74 61 62  e.  If the datab
24f20 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  ase does not.** 
24f30 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 61  already exist, a
24f40 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  n error is retur
24f50 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ned.</dd>)^.**.*
24f60 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f  * ^(<dt>[SQLITE_
24f70 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c  OPEN_READWRITE]<
24f80 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
24f90 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
24fa0 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61  ed for reading a
24fb0 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f  nd writing if po
24fc0 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69  ssible, or readi
24fd0 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68  ng.** only if th
24fe0 65 20 66 69 6c 65 20 69 73 20 77 72 69 74 65 20  e file is write 
24ff0 70 72 6f 74 65 63 74 65 64 20 62 79 20 74 68 65  protected by the
25000 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
25010 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a  m.  In either.**
25020 20 63 61 73 65 20 74 68 65 20 64 61 74 61 62 61   case the databa
25030 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20  se must already 
25040 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65  exist, otherwise
25050 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74   an error is ret
25060 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  urned.</dd>)^.**
25070 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54  .** ^(<dt>[SQLIT
25080 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
25090 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ] | [SQLITE_OPEN
250a0 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a  _CREATE]</dt>.**
250b0 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73   <dd>The databas
250c0 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
250d0 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74  reading and writ
250e0 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61  ing, and is crea
250f0 74 65 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65  ted if.** it doe
25100 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78  s not already ex
25110 69 73 74 2e 20 54 68 69 73 20 69 73 20 74 68 65  ist. This is the
25120 20 62 65 68 61 76 69 6f 72 20 74 68 61 74 20 69   behavior that i
25130 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f  s always used fo
25140 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  r.** sqlite3_ope
25150 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
25160 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e  open16().</dd>)^
25170 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </dl>.**.** 
25180 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
25190 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
251a0 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74  open_v2() is not
251b0 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63   one of the.** c
251c0 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77  ombinations show
251d0 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f 6e 61 6c  n above optional
251e0 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68  ly combined with
251f0 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 54   other.** [SQLIT
25200 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20  E_OPEN_READONLY 
25210 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20  | SQLITE_OPEN_* 
25220 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 68  bits].** then th
25230 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
25240 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
25250 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  If the [SQLITE_O
25260 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61  PEN_NOMUTEX] fla
25270 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20 74  g is set, then t
25280 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
25290 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20  ection.** opens 
252a0 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72  in the multi-thr
252b0 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  ead [threading m
252c0 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20  ode] as long as 
252d0 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61  the single-threa
252e0 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f  d.** mode has no
252f0 74 20 62 65 65 6e 20 73 65 74 20 61 74 20 63 6f  t been set at co
25300 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74  mpile-time or st
25310 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74  art-time.  ^If t
25320 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  he.** [SQLITE_OP
25330 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c  EN_FULLMUTEX] fl
25340 61 67 20 69 73 20 73 65 74 20 74 68 65 6e 20 74  ag is set then t
25350 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
25360 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20  ection opens.** 
25370 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65  in the serialize
25380 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
25390 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65  e] unless single
253a0 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 70  -thread was.** p
253b0 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 74  reviously select
253c0 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  ed at compile-ti
253d0 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65  me or start-time
253e0 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ..** ^The [SQLIT
253f0 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
25400 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20  HE] flag causes 
25410 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
25420 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a  nection to be.**
25430 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 75 73 65   eligible to use
25440 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d   [shared cache m
25450 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c 65 73 73  ode], regardless
25460 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
25470 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63  ot shared.** cac
25480 68 65 20 69 73 20 65 6e 61 62 6c 65 64 20 75 73  he is enabled us
25490 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61  ing [sqlite3_ena
254a0 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65  ble_shared_cache
254b0 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53  ()].  ^The.** [S
254c0 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
254d0 54 45 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61  TECACHE] flag ca
254e0 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73  uses the databas
254f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  e connection to 
25500 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69 70 61  not.** participa
25510 74 65 20 69 6e 20 5b 73 68 61 72 65 64 20 63 61  te in [shared ca
25520 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69  che mode] even i
25530 66 20 69 74 20 69 73 20 65 6e 61 62 6c 65 64 2e  f it is enabled.
25540 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72  .**.** ^The four
25550 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
25560 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
25570 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  ) is the name of
25580 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
25590 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61  _vfs] object tha
255a0 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70  t defines the op
255b0 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69  erating system i
255c0 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a 2a  nterface that.**
255d0 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73   the new databas
255e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f  e connection sho
255f0 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 74 68  uld use.  ^If th
25600 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
25610 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20  er is.** a NULL 
25620 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65  pointer then the
25630 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
25640 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 73  3_vfs] object is
25650 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66   used..**.** ^If
25660 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
25670 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65   ":memory:", the
25680 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d  n a private, tem
25690 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79  porary in-memory
256a0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20   database.** is 
256b0 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 20  created for the 
256c0 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68  connection.  ^Th
256d0 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74  is in-memory dat
256e0 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73  abase will vanis
256f0 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61  h when.** the da
25700 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
25710 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75  n is closed.  Fu
25720 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
25730 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a   SQLite might.**
25740 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64   make use of add
25750 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20  itional special 
25760 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62  filenames that b
25770 65 67 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a  egin with the ":
25780 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  " character..** 
25790 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  It is recommende
257a0 64 20 74 68 61 74 20 77 68 65 6e 20 61 20 64 61  d that when a da
257b0 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
257c0 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65  actually does be
257d0 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a  gin with.** a ":
257e0 22 20 63 68 61 72 61 63 74 65 72 20 79 6f 75 20  " character you 
257f0 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68  should prefix th
25800 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20  e filename with 
25810 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20  a pathname such 
25820 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76  as.** "./" to av
25830 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a  oid ambiguity..*
25840 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c  *.** ^If the fil
25850 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74  ename is an empt
25860 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61  y string, then a
25870 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72   private, tempor
25880 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64  ary.** on-disk d
25890 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20  atabase will be 
258a0 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69 73 20  created.  ^This 
258b0 70 72 69 76 61 74 65 20 64 61 74 61 62 61 73 65  private database
258c0 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f   will be.** auto
258d0 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65  matically delete
258e0 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65  d as soon as the
258f0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
25900 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a  tion is closed..
25910 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65  **.** [[URI file
25920 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69 74 65 33  names in sqlite3
25930 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 52  _open()]] <h3>UR
25940 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e  I Filenames</h3>
25950 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 20  .**.** ^If [URI 
25960 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 65 72 70  filename] interp
25970 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62  retation is enab
25980 6c 65 64 2c 20 61 6e 64 20 74 68 65 20 66 69 6c  led, and the fil
25990 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a  ename argument.*
259a0 2a 20 62 65 67 69 6e 73 20 77 69 74 68 20 22 66  * begins with "f
259b0 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74 68 65 20  ile:", then the 
259c0 66 69 6c 65 6e 61 6d 65 20 69 73 20 69 6e 74 65  filename is inte
259d0 72 70 72 65 74 65 64 20 61 73 20 61 20 55 52 49  rpreted as a URI
259e0 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 6e 61  . ^URI.** filena
259f0 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f  me interpretatio
25a00 6e 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20  n is enabled if 
25a10 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
25a20 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 0a 2a 2a  _URI] flag is.**
25a30 20 73 65 74 20 69 6e 20 74 68 65 20 66 6f 75 72   set in the four
25a40 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  th argument to s
25a50 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
25a60 2c 20 6f 72 20 69 66 20 69 74 20 68 61 73 0a 2a  , or if it has.*
25a70 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65 64 20 67  * been enabled g
25a80 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20 74 68  lobally using th
25a90 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  e [SQLITE_CONFIG
25aa0 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74  _URI] option wit
25ab0 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  h the.** [sqlite
25ac0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68  3_config()] meth
25ad0 6f 64 20 6f 72 20 62 79 20 74 68 65 20 5b 53 51  od or by the [SQ
25ae0 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f  LITE_USE_URI] co
25af0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
25b00 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20 53 51 4c 69  n..** As of SQLi
25b10 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37  te version 3.7.7
25b20 2c 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 69  , URI filename i
25b30 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73  nterpretation is
25b40 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62   turned off.** b
25b50 79 20 64 65 66 61 75 6c 74 2c 20 62 75 74 20 66  y default, but f
25b60 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
25b70 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 65  f SQLite might e
25b80 6e 61 62 6c 65 20 55 52 49 20 66 69 6c 65 6e 61  nable URI filena
25b90 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 61  me.** interpreta
25ba0 74 69 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e  tion by default.
25bb0 20 20 53 65 65 20 22 5b 55 52 49 20 66 69 6c 65    See "[URI file
25bc0 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61 64 64 69  names]" for addi
25bd0 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d  tional.** inform
25be0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49  ation..**.** URI
25bf0 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 20 70   filenames are p
25c00 61 72 73 65 64 20 61 63 63 6f 72 64 69 6e 67 20  arsed according 
25c10 74 6f 20 52 46 43 20 33 39 38 36 2e 20 5e 49 66  to RFC 3986. ^If
25c20 20 74 68 65 20 55 52 49 20 63 6f 6e 74 61 69 6e   the URI contain
25c30 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74  s an.** authorit
25c40 79 2c 20 74 68 65 6e 20 69 74 20 6d 75 73 74 20  y, then it must 
25c50 62 65 20 65 69 74 68 65 72 20 61 6e 20 65 6d 70  be either an emp
25c60 74 79 20 73 74 72 69 6e 67 20 6f 72 20 74 68 65  ty string or the
25c70 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63   string .** "loc
25c80 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74 68 65  alhost". ^If the
25c90 20 61 75 74 68 6f 72 69 74 79 20 69 73 20 6e 6f   authority is no
25ca0 74 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  t an empty strin
25cb0 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22  g or "localhost"
25cc0 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69  , an .** error i
25cd0 73 20 72 65 74 75 72 6e 65 64 20 74 6f 20 74 68  s returned to th
25ce0 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66  e caller. ^The f
25cf0 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e  ragment componen
25d00 74 20 6f 66 20 61 20 55 52 49 2c 20 69 66 20 0a  t of a URI, if .
25d10 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69 73 20 69  ** present, is i
25d20 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53  gnored..**.** ^S
25d30 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 70  QLite uses the p
25d40 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  ath component of
25d50 20 74 68 65 20 55 52 49 20 61 73 20 74 68 65 20   the URI as the 
25d60 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 69 73 6b  name of the disk
25d70 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63   file.** which c
25d80 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74 61  ontains the data
25d90 62 61 73 65 2e 20 5e 49 66 20 74 68 65 20 70 61  base. ^If the pa
25da0 74 68 20 62 65 67 69 6e 73 20 77 69 74 68 20 61  th begins with a
25db0 20 27 2f 27 20 63 68 61 72 61 63 74 65 72 2c 20   '/' character, 
25dc0 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 69  .** then it is i
25dd0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 6e  nterpreted as an
25de0 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 2e 20   absolute path. 
25df0 5e 49 66 20 74 68 65 20 70 61 74 68 20 64 6f 65  ^If the path doe
25e00 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20  s not begin .** 
25e10 77 69 74 68 20 61 20 27 2f 27 20 28 6d 65 61 6e  with a '/' (mean
25e20 69 6e 67 20 74 68 61 74 20 74 68 65 20 61 75 74  ing that the aut
25e30 68 6f 72 69 74 79 20 73 65 63 74 69 6f 6e 20 69  hority section i
25e40 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74  s omitted from t
25e50 68 65 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20  he URI).** then 
25e60 74 68 65 20 70 61 74 68 20 69 73 20 69 6e 74 65  the path is inte
25e70 72 70 72 65 74 65 64 20 61 73 20 61 20 72 65 6c  rpreted as a rel
25e80 61 74 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20  ative path. .** 
25e90 5e 28 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68  ^(On windows, th
25ea0 65 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e  e first componen
25eb0 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74 65  t of an absolute
25ec0 20 70 61 74 68 20 0a 2a 2a 20 69 73 20 61 20 64   path .** is a d
25ed0 72 69 76 65 20 73 70 65 63 69 66 69 63 61 74 69  rive specificati
25ee0 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e 29  on (e.g. "C:").)
25ef0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55  ^.**.** [[core U
25f00 52 49 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  RI query paramet
25f10 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65  ers]].** The que
25f20 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  ry component of 
25f30 61 20 55 52 49 20 6d 61 79 20 63 6f 6e 74 61 69  a URI may contai
25f40 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74 68 61  n parameters tha
25f50 74 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  t are interprete
25f60 64 0a 2a 2a 20 65 69 74 68 65 72 20 62 79 20 53  d.** either by S
25f70 51 4c 69 74 65 20 69 74 73 65 6c 66 2c 20 6f 72  QLite itself, or
25f80 20 62 79 20 61 20 5b 56 46 53 20 7c 20 63 75 73   by a [VFS | cus
25f90 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  tom VFS implemen
25fa0 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69  tation]..** SQLi
25fb0 74 65 20 61 6e 64 20 69 74 73 20 62 75 69 6c 74  te and its built
25fc0 2d 69 6e 20 5b 56 46 53 65 73 5d 20 69 6e 74 65  -in [VFSes] inte
25fd0 72 70 72 65 74 20 74 68 65 0a 2a 2a 20 66 6f 6c  rpret the.** fol
25fe0 6c 6f 77 69 6e 67 20 71 75 65 72 79 20 70 61 72  lowing query par
25ff0 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ameters:.**.** <
26000 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62  ul>.**   <li> <b
26010 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22  >vfs</b>: ^The "
26020 76 66 73 22 20 70 61 72 61 6d 65 74 65 72 20 6d  vfs" parameter m
26030 61 79 20 62 65 20 75 73 65 64 20 74 6f 20 73 70  ay be used to sp
26040 65 63 69 66 79 20 74 68 65 20 6e 61 6d 65 20 6f  ecify the name o
26050 66 0a 2a 2a 20 20 20 20 20 61 20 56 46 53 20 6f  f.**     a VFS o
26060 62 6a 65 63 74 20 74 68 61 74 20 70 72 6f 76 69  bject that provi
26070 64 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e  des the operatin
26080 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61  g system interfa
26090 63 65 20 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a  ce that should.*
260a0 2a 20 20 20 20 20 62 65 20 75 73 65 64 20 74 6f  *     be used to
260b0 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61   access the data
260c0 62 61 73 65 20 66 69 6c 65 20 6f 6e 20 64 69 73  base file on dis
260d0 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f 70 74 69  k. ^If this opti
260e0 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20  on is set to.** 
260f0 20 20 20 20 61 6e 20 65 6d 70 74 79 20 73 74 72      an empty str
26100 69 6e 67 20 74 68 65 20 64 65 66 61 75 6c 74 20  ing the default 
26110 56 46 53 20 6f 62 6a 65 63 74 20 69 73 20 75 73  VFS object is us
26120 65 64 2e 20 5e 53 70 65 63 69 66 79 69 6e 67 20  ed. ^Specifying 
26130 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20  an unknown.**   
26140 20 20 56 46 53 20 69 73 20 61 6e 20 65 72 72 6f    VFS is an erro
26150 72 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f  r. ^If sqlite3_o
26160 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64  pen_v2() is used
26170 20 61 6e 64 20 74 68 65 20 76 66 73 20 6f 70 74   and the vfs opt
26180 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70 72  ion is.**     pr
26190 65 73 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20  esent, then the 
261a0 56 46 53 20 73 70 65 63 69 66 69 65 64 20 62 79  VFS specified by
261b0 20 74 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65   the option take
261c0 73 20 70 72 65 63 65 64 65 6e 63 65 20 6f 76 65  s precedence ove
261d0 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 76 61 6c  r.**     the val
261e0 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ue passed as the
261f0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
26200 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
26210 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20  n_v2()..**.**   
26220 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e  <li> <b>mode</b>
26230 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20 70 61 72  : ^(The mode par
26240 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65  ameter may be se
26250 74 20 74 6f 20 65 69 74 68 65 72 20 22 72 6f 22  t to either "ro"
26260 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22  , "rw",.**     "
26270 72 77 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79  rwc", or "memory
26280 22 2e 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f  ". Attempting to
26290 20 73 65 74 20 69 74 20 74 6f 20 61 6e 79 20 6f   set it to any o
262a0 74 68 65 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a  ther value is.**
262b0 20 20 20 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e       an error)^.
262c0 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22 72 6f   .**     ^If "ro
262d0 22 20 69 73 20 73 70 65 63 69 66 69 65 64 2c 20  " is specified, 
262e0 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
262f0 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
26300 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20  read-only .**   
26310 20 20 61 63 63 65 73 73 2c 20 6a 75 73 74 20 61    access, just a
26320 73 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45  s if the [SQLITE
26330 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20  _OPEN_READONLY] 
26340 66 6c 61 67 20 68 61 64 20 62 65 65 6e 20 73 65  flag had been se
26350 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20  t in the .**    
26360 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
26370 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
26380 76 32 28 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f  v2(). ^If the mo
26390 64 65 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74  de option is set
263a0 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77 22   to .**     "rw"
263b0 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
263c0 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
263d0 72 20 72 65 61 64 2d 77 72 69 74 65 20 28 62 75  r read-write (bu
263e0 74 20 6e 6f 74 20 63 72 65 61 74 65 29 20 0a 2a  t not create) .*
263f0 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 61 73  *     access, as
26400 20 69 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   if SQLITE_OPEN_
26410 52 45 41 44 57 52 49 54 45 20 28 62 75 74 20 6e  READWRITE (but n
26420 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  ot SQLITE_OPEN_C
26430 52 45 41 54 45 29 20 68 61 64 20 0a 2a 2a 20 20  REATE) had .**  
26440 20 20 20 62 65 65 6e 20 73 65 74 2e 20 5e 56 61     been set. ^Va
26450 6c 75 65 20 22 72 77 63 22 20 69 73 20 65 71 75  lue "rwc" is equ
26460 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69  ivalent to setti
26470 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20  ng both .**     
26480 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
26490 57 52 49 54 45 20 61 6e 64 20 53 51 4c 49 54 45  WRITE and SQLITE
264a0 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e  _OPEN_CREATE.  ^
264b0 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69  If the mode opti
264c0 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 73 65 74  on is.**     set
264d0 20 74 6f 20 22 6d 65 6d 6f 72 79 22 20 74 68 65   to "memory" the
264e0 6e 20 61 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d  n a pure [in-mem
264f0 6f 72 79 20 64 61 74 61 62 61 73 65 5d 20 74 68  ory database] th
26500 61 74 20 6e 65 76 65 72 20 72 65 61 64 73 0a 2a  at never reads.*
26510 2a 20 20 20 20 20 6f 72 20 77 72 69 74 65 73 20  *     or writes 
26520 66 72 6f 6d 20 64 69 73 6b 20 69 73 20 75 73 65  from disk is use
26530 64 2e 20 5e 49 74 20 69 73 20 61 6e 20 65 72 72  d. ^It is an err
26540 6f 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 20  or to specify a 
26550 76 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20  value for.**    
26560 20 74 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65   the mode parame
26570 74 65 72 20 74 68 61 74 20 69 73 20 6c 65 73 73  ter that is less
26580 20 72 65 73 74 72 69 63 74 69 76 65 20 74 68 61   restrictive tha
26590 6e 20 74 68 61 74 20 73 70 65 63 69 66 69 65 64  n that specified
265a0 20 62 79 0a 2a 2a 20 20 20 20 20 74 68 65 20 66   by.**     the f
265b0 6c 61 67 73 20 70 61 73 73 65 64 20 69 6e 20 74  lags passed in t
265c0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
265d0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
265e0 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20  en_v2()..**.**  
265f0 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f   <li> <b>cache</
26600 62 3e 3a 20 5e 54 68 65 20 63 61 63 68 65 20 70  b>: ^The cache p
26610 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
26620 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 73  set to either "s
26630 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20  hared" or.**    
26640 20 22 70 72 69 76 61 74 65 22 2e 20 5e 53 65 74   "private". ^Set
26650 74 69 6e 67 20 69 74 20 74 6f 20 22 73 68 61 72  ting it to "shar
26660 65 64 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e  ed" is equivalen
26670 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65  t to setting the
26680 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f  .**     SQLITE_O
26690 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20  PEN_SHAREDCACHE 
266a0 62 69 74 20 69 6e 20 74 68 65 20 66 6c 61 67 73  bit in the flags
266b0 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64   argument passed
266c0 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74   to.**     sqlit
266d0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53  e3_open_v2(). ^S
266e0 65 74 74 69 6e 67 20 74 68 65 20 63 61 63 68 65  etting the cache
266f0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 22 70   parameter to "p
26700 72 69 76 61 74 65 22 20 69 73 20 0a 2a 2a 20 20  rivate" is .**  
26710 20 20 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f     equivalent to
26720 20 73 65 74 74 69 6e 67 20 74 68 65 20 53 51 4c   setting the SQL
26730 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
26740 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20  CACHE bit..**   
26750 20 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70    ^If sqlite3_op
26760 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20  en_v2() is used 
26770 61 6e 64 20 74 68 65 20 22 63 61 63 68 65 22 20  and the "cache" 
26780 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 65  parameter is pre
26790 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61  sent in.**     a
267a0 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69   URI filename, i
267b0 74 73 20 76 61 6c 75 65 20 6f 76 65 72 72 69 64  ts value overrid
267c0 65 73 20 61 6e 79 20 62 65 68 61 76 69 6f 72 20  es any behavior 
267d0 72 65 71 75 65 73 74 65 64 20 62 79 20 73 65 74  requested by set
267e0 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49  ting.**     SQLI
267f0 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
26800 41 43 48 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f  ACHE or SQLITE_O
26810 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20  PEN_SHAREDCACHE 
26820 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69  flag..**.**  <li
26830 3e 20 3c 62 3e 70 73 6f 77 3c 2f 62 3e 3a 20 5e  > <b>psow</b>: ^
26840 54 68 65 20 70 73 6f 77 20 70 61 72 61 6d 65 74  The psow paramet
26850 65 72 20 69 6e 64 69 63 61 74 65 73 20 77 68 65  er indicates whe
26860 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 0a  ther or not the.
26870 2a 2a 20 20 20 20 20 5b 70 6f 77 65 72 73 61 66  **     [powersaf
26880 65 20 6f 76 65 72 77 72 69 74 65 5d 20 70 72 6f  e overwrite] pro
26890 70 65 72 74 79 20 64 6f 65 73 20 6f 72 20 64 6f  perty does or do
268a0 65 73 20 6e 6f 74 20 61 70 70 6c 79 20 74 6f 20  es not apply to 
268b0 74 68 65 0a 2a 2a 20 20 20 20 20 73 74 6f 72 61  the.**     stora
268c0 67 65 20 6d 65 64 69 61 20 6f 6e 20 77 68 69 63  ge media on whic
268d0 68 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  h the database f
268e0 69 6c 65 20 72 65 73 69 64 65 73 2e 0a 2a 2a 0a  ile resides..**.
268f0 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f  **  <li> <b>nolo
26900 63 6b 3c 2f 62 3e 3a 20 5e 54 68 65 20 6e 6f 6c  ck</b>: ^The nol
26910 6f 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73  ock parameter is
26920 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79   a boolean query
26930 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20   parameter.**   
26940 20 20 77 68 69 63 68 20 69 66 20 73 65 74 20 64    which if set d
26950 69 73 61 62 6c 65 73 20 66 69 6c 65 20 6c 6f 63  isables file loc
26960 6b 69 6e 67 20 69 6e 20 72 6f 6c 6c 62 61 63 6b  king in rollback
26970 20 6a 6f 75 72 6e 61 6c 20 6d 6f 64 65 73 2e 20   journal modes. 
26980 20 54 68 69 73 0a 2a 2a 20 20 20 20 20 69 73 20   This.**     is 
26990 75 73 65 66 75 6c 20 66 6f 72 20 61 63 63 65 73  useful for acces
269a0 73 69 6e 67 20 61 20 64 61 74 61 62 61 73 65 20  sing a database 
269b0 6f 6e 20 61 20 66 69 6c 65 73 79 73 74 65 6d 20  on a filesystem 
269c0 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a  that does not.**
269d0 20 20 20 20 20 73 75 70 70 6f 72 74 20 6c 6f 63       support loc
269e0 6b 69 6e 67 2e 20 20 43 61 75 74 69 6f 6e 3a 20  king.  Caution: 
269f0 20 44 61 74 61 62 61 73 65 20 63 6f 72 72 75 70   Database corrup
26a00 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 73 75 6c  tion might resul
26a10 74 20 69 66 20 74 77 6f 0a 2a 2a 20 20 20 20 20  t if two.**     
26a20 6f 72 20 6d 6f 72 65 20 70 72 6f 63 65 73 73 65  or more processe
26a30 73 20 77 72 69 74 65 20 74 6f 20 74 68 65 20 73  s write to the s
26a40 61 6d 65 20 64 61 74 61 62 61 73 65 20 61 6e 64  ame database and
26a50 20 61 6e 79 20 6f 6e 65 20 6f 66 20 74 68 6f 73   any one of thos
26a60 65 0a 2a 2a 20 20 20 20 20 70 72 6f 63 65 73 73  e.**     process
26a70 65 73 20 75 73 65 73 20 6e 6f 6c 6f 63 6b 3d 31  es uses nolock=1
26a80 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62  ..**.**  <li> <b
26a90 3e 69 6d 6d 75 74 61 62 6c 65 3c 2f 62 3e 3a 20  >immutable</b>: 
26aa0 5e 54 68 65 20 69 6d 6d 75 74 61 62 6c 65 20 70  ^The immutable p
26ab0 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f  arameter is a bo
26ac0 6f 6c 65 61 6e 20 71 75 65 72 79 0a 2a 2a 20 20  olean query.**  
26ad0 20 20 20 70 61 72 61 6d 65 74 65 72 20 74 68 61     parameter tha
26ae0 74 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74  t indicates that
26af0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
26b00 6c 65 20 69 73 20 73 74 6f 72 65 64 20 6f 6e 0a  le is stored on.
26b10 2a 2a 20 20 20 20 20 72 65 61 64 2d 6f 6e 6c 79  **     read-only
26b20 20 6d 65 64 69 61 2e 20 20 5e 57 68 65 6e 20 69   media.  ^When i
26b30 6d 6d 75 74 61 62 6c 65 20 69 73 20 73 65 74 2c  mmutable is set,
26b40 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20   SQLite assumes 
26b50 74 68 61 74 20 74 68 65 0a 2a 2a 20 20 20 20 20  that the.**     
26b60 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 63 61  database file ca
26b70 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 2c  nnot be changed,
26b80 20 65 76 65 6e 20 62 79 20 61 20 70 72 6f 63 65   even by a proce
26b90 73 73 20 77 69 74 68 20 68 69 67 68 65 72 0a 2a  ss with higher.*
26ba0 2a 20 20 20 20 20 70 72 69 76 69 6c 65 67 65 2c  *     privilege,
26bb0 20 61 6e 64 20 73 6f 20 74 68 65 20 64 61 74 61   and so the data
26bc0 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 72  base is opened r
26bd0 65 61 64 2d 6f 6e 6c 79 20 61 6e 64 20 61 6c 6c  ead-only and all
26be0 20 6c 6f 63 6b 69 6e 67 0a 2a 2a 20 20 20 20 20   locking.**     
26bf0 61 6e 64 20 63 68 61 6e 67 65 20 64 65 74 65 63  and change detec
26c00 74 69 6f 6e 20 69 73 20 64 69 73 61 62 6c 65 64  tion is disabled
26c10 2e 20 20 43 61 75 74 69 6f 6e 3a 20 53 65 74 74  .  Caution: Sett
26c20 69 6e 67 20 74 68 65 20 69 6d 6d 75 74 61 62 6c  ing the immutabl
26c30 65 0a 2a 2a 20 20 20 20 20 70 72 6f 70 65 72 74  e.**     propert
26c40 79 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20  y on a database 
26c50 66 69 6c 65 20 74 68 61 74 20 64 6f 65 73 20 69  file that does i
26c60 6e 20 66 61 63 74 20 63 68 61 6e 67 65 20 63 61  n fact change ca
26c70 6e 20 72 65 73 75 6c 74 0a 2a 2a 20 20 20 20 20  n result.**     
26c80 69 6e 20 69 6e 63 6f 72 72 65 63 74 20 71 75 65  in incorrect que
26c90 72 79 20 72 65 73 75 6c 74 73 20 61 6e 64 2f 6f  ry results and/o
26ca0 72 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  r [SQLITE_CORRUP
26cb0 54 5d 20 65 72 72 6f 72 73 2e 0a 2a 2a 20 20 20  T] errors..**   
26cc0 20 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c    See also: [SQL
26cd0 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41  ITE_IOCAP_IMMUTA
26ce0 42 4c 45 5d 2e 0a 2a 2a 20 20 20 20 20 20 20 0a  BLE]..**       .
26cf0 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e  ** </ul>.**.** ^
26d00 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e  Specifying an un
26d10 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 20  known parameter 
26d20 69 6e 20 74 68 65 20 71 75 65 72 79 20 63 6f 6d  in the query com
26d30 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20  ponent of a URI 
26d40 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72  is not an.** err
26d50 6f 72 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  or.  Future vers
26d60 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
26d70 69 67 68 74 20 75 6e 64 65 72 73 74 61 6e 64 20  ight understand 
26d80 61 64 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 79  additional query
26d90 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20  .** parameters. 
26da0 20 53 65 65 20 22 5b 71 75 65 72 79 20 70 61 72   See "[query par
26db0 61 6d 65 74 65 72 73 20 77 69 74 68 20 73 70 65  ameters with spe
26dc0 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20  cial meaning to 
26dd0 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20  SQLite]" for.** 
26de0 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
26df0 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  mation..**.** [[
26e00 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61  URI filename exa
26e10 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20  mples]] <h3>URI 
26e20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65  filename example
26e30 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61  s</h3>.**.** <ta
26e40 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 20 61  ble border="1" a
26e50 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c  lign=center cell
26e60 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74  padding=5>.** <t
26e70 72 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 6e  r><th> URI filen
26e80 61 6d 65 73 20 3c 74 68 3e 20 52 65 73 75 6c 74  ames <th> Result
26e90 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  s.** <tr><td> fi
26ea0 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e 20  le:data.db <td> 
26eb0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65  .**          Ope
26ec0 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61  n the file "data
26ed0 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72  .db" in the curr
26ee0 65 6e 74 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a  ent directory..*
26ef0 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
26f00 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
26f10 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20  db<br>.**       
26f20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f     file:///home/
26f30 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72  fred/data.db <br
26f40 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  > .**          f
26f50 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f  ile://localhost/
26f60 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
26f70 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20  b <br> <td> .** 
26f80 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68           Open th
26f90 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
26fa0 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  "/home/fred/data
26fb0 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  .db"..** <tr><td
26fc0 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61  > file://darksta
26fd0 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  r/home/fred/data
26fe0 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  .db <td> .**    
26ff0 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20        An error. 
27000 22 64 61 72 6b 73 74 61 72 22 20 69 73 20 6e 6f  "darkstar" is no
27010 74 20 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 61  t a recognized a
27020 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72  uthority..** <tr
27030 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77 68 69 74  ><td style="whit
27040 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e  e-space:nowrap">
27050 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69   .**          fi
27060 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e  le:///C:/Documen
27070 74 73 25 32 30 61 6e 64 25 32 30 53 65 74 74 69  ts%20and%20Setti
27080 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70  ngs/fred/Desktop
27090 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20  /data.db.**     
270a0 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c  <td> Windows onl
270b0 79 3a 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65  y: Open the file
270c0 20 22 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 72   "data.db" on fr
270d0 65 64 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20  ed's desktop on 
270e0 64 72 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20  drive.**        
270f0 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20    C:. Note that 
27100 74 68 65 20 25 32 30 20 65 73 63 61 70 69 6e 67  the %20 escaping
27110 20 69 6e 20 74 68 69 73 20 65 78 61 6d 70 6c 65   in this example
27120 20 69 73 20 6e 6f 74 20 73 74 72 69 63 74 6c 79   is not strictly
27130 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65   .**          ne
27140 63 65 73 73 61 72 79 20 2d 20 73 70 61 63 65 20  cessary - space 
27150 63 68 61 72 61 63 74 65 72 73 20 63 61 6e 20 62  characters can b
27160 65 20 75 73 65 64 20 6c 69 74 65 72 61 6c 6c 79  e used literally
27170 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20  .**          in 
27180 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a  URI filenames..*
27190 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
271a0 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26  data.db?mode=ro&
271b0 63 61 63 68 65 3d 70 72 69 76 61 74 65 20 3c 74  cache=private <t
271c0 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
271d0 4f 70 65 6e 20 66 69 6c 65 20 22 64 61 74 61 2e  Open file "data.
271e0 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65  db" in the curre
271f0 6e 74 20 64 69 72 65 63 74 6f 72 79 20 66 6f 72  nt directory for
27200 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73   read-only acces
27210 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 52  s..**          R
27220 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
27230 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72  ther or not shar
27240 65 64 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 73  ed-cache mode is
27250 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20   enabled by.**  
27260 20 20 20 20 20 20 20 20 64 65 66 61 75 6c 74 2c          default,
27270 20 75 73 65 20 61 20 70 72 69 76 61 74 65 20 63   use a private c
27280 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  ache..** <tr><td
27290 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65  > file:/home/fre
272a0 64 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e  d/data.db?vfs=un
272b0 69 78 2d 64 6f 74 66 69 6c 65 20 3c 74 64 3e 0a  ix-dotfile <td>.
272c0 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
272d0 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65   file "/home/fre
272e0 64 2f 64 61 74 61 2e 64 62 22 2e 20 55 73 65 20  d/data.db". Use 
272f0 74 68 65 20 73 70 65 63 69 61 6c 20 56 46 53 20  the special VFS 
27300 22 75 6e 69 78 2d 64 6f 74 66 69 6c 65 22 0a 2a  "unix-dotfile".*
27310 2a 20 20 20 20 20 20 20 20 20 20 74 68 61 74 20  *          that 
27320 75 73 65 73 20 64 6f 74 2d 66 69 6c 65 73 20 69  uses dot-files i
27330 6e 20 70 6c 61 63 65 20 6f 66 20 70 6f 73 69 78  n place of posix
27340 20 61 64 76 69 73 6f 72 79 20 6c 6f 63 6b 69 6e   advisory lockin
27350 67 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  g..** <tr><td> f
27360 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65  ile:data.db?mode
27370 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a  =readonly <td> .
27380 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65  **          An e
27390 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22  rror. "readonly"
273a0 20 69 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20   is not a valid 
273b0 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22  option for the "
273c0 6d 6f 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e  mode" parameter.
273d0 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a  .** </table>.**.
273e0 2a 2a 20 5e 55 52 49 20 68 65 78 61 64 65 63 69  ** ^URI hexadeci
273f0 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65  mal escape seque
27400 6e 63 65 73 20 28 25 48 48 29 20 61 72 65 20 73  nces (%HH) are s
27410 75 70 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20  upported within 
27420 74 68 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20  the path and.** 
27430 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73  query components
27440 20 6f 66 20 61 20 55 52 49 2e 20 41 20 68 65 78   of a URI. A hex
27450 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20  adecimal escape 
27460 73 65 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74  sequence consist
27470 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e  s of a.** percen
27480 74 20 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66  t sign - "%" - f
27490 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74  ollowed by exact
274a0 6c 79 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d  ly two hexadecim
274b0 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70  al digits .** sp
274c0 65 63 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65  ecifying an octe
274d0 74 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65  t value. ^Before
274e0 20 74 68 65 20 70 61 74 68 20 6f 72 20 71 75 65   the path or que
274f0 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66  ry components of
27500 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61   a.** URI filena
27510 6d 65 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  me are interpret
27520 65 64 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63  ed, they are enc
27530 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38  oded using UTF-8
27540 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78   and all .** hex
27550 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20  adecimal escape 
27560 73 65 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63  sequences replac
27570 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62  ed by a single b
27580 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  yte containing t
27590 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64  he.** correspond
275a0 69 6e 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68  ing octet. If th
275b0 69 73 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72  is process gener
275c0 61 74 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20  ates an invalid 
275d0 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a  UTF-8 encoding,.
275e0 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  ** the results a
275f0 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  re undefined..**
27600 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57  .** <b>Note to W
27610 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62  indows users:</b
27620 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20  >  The encoding 
27630 75 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c  used for the fil
27640 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a  ename argument.*
27650 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65  * of sqlite3_ope
27660 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
27670 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62  open_v2() must b
27680 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61  e UTF-8, not wha
27690 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67  tever.** codepag
276a0 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64  e is currently d
276b0 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d  efined.  Filenam
276c0 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e  es containing in
276d0 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63  ternational.** c
276e0 68 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 62  haracters must b
276f0 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55  e converted to U
27700 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61  TF-8 prior to pa
27710 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a  ssing them into.
27720 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
27730 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  ) or sqlite3_ope
27740 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62  n_v2()..**.** <b
27750 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73  >Note to Windows
27760 20 52 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c   Runtime users:<
27770 2f 62 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61  /b>  The tempora
27780 72 79 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73  ry directory mus
27790 74 20 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f  t be set.** prio
277a0 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c  r to calling sql
277b0 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73  ite3_open() or s
277c0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
277d0 2e 20 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61  .  Otherwise, va
277e0 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65  rious.** feature
277f0 73 20 74 68 61 74 20 72 65 71 75 69 72 65 20 74  s that require t
27800 68 65 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72  he use of tempor
27810 61 72 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61  ary files may fa
27820 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  il..**.** See al
27830 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d  so: [sqlite3_tem
27840 70 5f 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a  p_directory].*/.
27850 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
27860 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
27870 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
27880 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
27890 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
278a0 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20  lite3 **ppDb    
278b0 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
278c0 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
278d0 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
278e0 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74  _open16(.  const
278f0 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c   void *filename,
27900 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
27910 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29  ilename (UTF-16)
27920 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
27930 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a  ppDb          /*
27940 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
27950 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74  handle */.);.int
27960 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
27970 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
27980 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
27990 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
279a0 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
279b0 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20  lite3 **ppDb,   
279c0 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
279d0 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
279e0 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20  /.  int flags,  
279f0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46              /* F
27a00 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  lags */.  const 
27a10 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20  char *zVfs      
27a20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53    /* Name of VFS
27a30 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a   module to use *
27a40 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
27a50 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c  3REF: Obtain Val
27a60 75 65 73 20 46 6f 72 20 55 52 49 20 50 61 72 61  ues For URI Para
27a70 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65  meters.**.** The
27a80 73 65 20 61 72 65 20 75 74 69 6c 69 74 79 20 72  se are utility r
27a90 6f 75 74 69 6e 65 73 2c 20 75 73 65 66 75 6c 20  outines, useful 
27aa0 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  to VFS implement
27ab0 61 74 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65  ations, that che
27ac0 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20  ck.** to see if 
27ad0 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
27ae0 77 61 73 20 61 20 55 52 49 20 74 68 61 74 20 63  was a URI that c
27af0 6f 6e 74 61 69 6e 65 64 20 61 20 73 70 65 63 69  ontained a speci
27b00 66 69 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 61  fic query .** pa
27b10 72 61 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 20  rameter, and if 
27b20 73 6f 20 6f 62 74 61 69 6e 73 20 74 68 65 20 76  so obtains the v
27b30 61 6c 75 65 20 6f 66 20 74 68 61 74 20 71 75 65  alue of that que
27b40 72 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  ry parameter..**
27b50 0a 2a 2a 20 49 66 20 46 20 69 73 20 74 68 65 20  .** If F is the 
27b60 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  database filenam
27b70 65 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64  e pointer passed
27b80 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 28   into the xOpen(
27b90 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20  ) method of .** 
27ba0 61 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  a VFS implementa
27bb0 74 69 6f 6e 20 77 68 65 6e 20 74 68 65 20 66 6c  tion when the fl
27bc0 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ags parameter to
27bd0 20 78 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e 65   xOpen() has one
27be0 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20   or .** more of 
27bf0 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
27c00 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45  _URI] or [SQLITE
27c10 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62  _OPEN_MAIN_DB] b
27c20 69 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50  its set and.** P
27c30 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
27c40 74 68 65 20 71 75 65 72 79 20 70 61 72 61 6d 65  the query parame
27c50 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c  ter, then.** sql
27c60 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
27c70 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20  er(F,P) returns 
27c80 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
27c90 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20   P.** parameter 
27ca0 69 66 20 69 74 20 65 78 69 73 74 73 20 6f 72 20  if it exists or 
27cb0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
27cc0 66 20 50 20 64 6f 65 73 20 6e 6f 74 20 61 70 70  f P does not app
27cd0 65 61 72 20 61 73 20 61 20 0a 2a 2a 20 71 75 65  ear as a .** que
27ce0 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20  ry parameter on 
27cf0 46 2e 20 20 49 66 20 50 20 69 73 20 61 20 71 75  F.  If P is a qu
27d00 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 66  ery parameter of
27d10 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70   F.** has no exp
27d20 6c 69 63 69 74 20 76 61 6c 75 65 2c 20 74 68 65  licit value, the
27d30 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61  n sqlite3_uri_pa
27d40 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74  rameter(F,P) ret
27d50 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65  urns.** a pointe
27d60 72 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74  r to an empty st
27d70 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ring..**.** The 
27d80 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
27d90 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69  ean(F,P,B) routi
27da0 6e 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  ne assumes that 
27db0 50 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a  P is a boolean.*
27dc0 2a 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20  * parameter and 
27dd0 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29  returns true (1)
27de0 20 6f 72 20 66 61 6c 73 65 20 28 30 29 20 61 63   or false (0) ac
27df0 63 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 20 76  cording to the v
27e00 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54  alue.** of P.  T
27e10 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  he sqlite3_uri_b
27e20 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f  oolean(F,P,B) ro
27e30 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 72  utine returns tr
27e40 75 65 20 28 31 29 20 69 66 20 74 68 65 0a 2a 2a  ue (1) if the.**
27e50 20 76 61 6c 75 65 20 6f 66 20 71 75 65 72 79 20   value of query 
27e60 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f  parameter P is o
27e70 6e 65 20 6f 66 20 22 79 65 73 22 2c 20 22 74 72  ne of "yes", "tr
27e80 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20  ue", or "on" in 
27e90 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69  any.** case or i
27ea0 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69  f the value begi
27eb0 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65  ns with a non-ze
27ec0 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20  ro number.  The 
27ed0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  .** sqlite3_uri_
27ee0 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
27ef0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 73 20  outines returns 
27f00 66 61 6c 73 65 20 28 30 29 20 69 66 20 74 68 65  false (0) if the
27f10 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65   value of.** que
27f20 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69  ry parameter P i
27f30 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22  s one of "no", "
27f40 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66 22  false", or "off"
27f50 20 69 6e 20 61 6e 79 20 63 61 73 65 20 6f 72 0a   in any case or.
27f60 2a 2a 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  ** if the value 
27f70 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 75  begins with a nu
27f80 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20 49 66 20  meric zero.  If 
27f90 50 20 69 73 20 6e 6f 74 20 61 20 71 75 65 72 79  P is not a query
27fa0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 6e  .** parameter on
27fb0 20 46 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c   F or if the val
27fc0 75 65 20 6f 66 20 50 20 69 73 20 64 6f 65 73 20  ue of P is does 
27fd0 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79 20 6f 66  not match any of
27fe0 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74   the.** above, t
27ff0 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  hen sqlite3_uri_
28000 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
28010 65 74 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a  eturns (B!=0)..*
28020 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
28030 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44  _uri_int64(F,P,D
28040 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72  ) routine conver
28050 74 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ts the value of 
28060 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62  P into a.** 64-b
28070 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
28080 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 68  r and returns th
28090 61 74 20 69 6e 74 65 67 65 72 2c 20 6f 72 20 44  at integer, or D
280a0 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a   if P does not.*
280b0 2a 20 65 78 69 73 74 2e 20 20 49 66 20 74 68 65  * exist.  If the
280c0 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 73   value of P is s
280d0 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74  omething other t
280e0 68 61 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c 20  han an integer, 
280f0 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20  then.** zero is 
28100 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a  returned..** .**
28110 20 49 66 20 46 20 69 73 20 61 20 4e 55 4c 4c 20   If F is a NULL 
28120 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 73 71  pointer, then sq
28130 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65  lite3_uri_parame
28140 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73  ter(F,P) returns
28150 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c   NULL and.** sql
28160 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
28170 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20  (F,P,B) returns 
28180 42 2e 20 20 49 66 20 46 20 69 73 20 6e 6f 74 20  B.  If F is not 
28190 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61  a NULL pointer a
281a0 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64  nd.** is not a d
281b0 61 74 61 62 61 73 65 20 66 69 6c 65 20 70 61 74  atabase file pat
281c0 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 74 68  hname pointer th
281d0 61 74 20 53 51 4c 69 74 65 20 70 61 73 73 65 64  at SQLite passed
281e0 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a   into the xOpen.
281f0 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 74  ** VFS method, t
28200 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
28210 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
28220 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
28230 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e  d probably.** un
28240 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 63 6f  desirable..*/.co
28250 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
28260 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28  3_uri_parameter(
28270 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
28280 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61  ename, const cha
28290 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 69 6e 74 20  r *zParam);.int 
282a0 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
282b0 65 61 6e 28 63 6f 6e 73 74 20 63 68 61 72 20 2a  ean(const char *
282c0 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61  zFile, const cha
282d0 72 20 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62  r *zParam, int b
282e0 44 65 66 61 75 6c 74 29 3b 0a 73 71 6c 69 74 65  Default);.sqlite
282f0 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
28300 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20  uri_int64(const 
28310 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61  char*, const cha
28320 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  r*, sqlite3_int6
28330 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  4);.../*.** CAPI
28340 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65  3REF: Error Code
28350 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a  s And Messages.*
28360 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
28370 33 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  3.**.** ^If the 
28380 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 71 6c 69  most recent sqli
28390 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 20 61  te3_* API call a
283a0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 0a  ssociated with .
283b0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
283c0 6e 65 63 74 69 6f 6e 5d 20 44 20 66 61 69 6c 65  nection] D faile
283d0 64 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69  d, then the sqli
283e0 74 65 33 5f 65 72 72 63 6f 64 65 28 44 29 20 69  te3_errcode(D) i
283f0 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 74 75  nterface.** retu
28400 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20  rns the numeric 
28410 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72  [result code] or
28420 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
28430 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 61 74  t code] for that
28440 0a 2a 2a 20 41 50 49 20 63 61 6c 6c 2e 0a 2a 2a  .** API call..**
28450 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63   If the most rec
28460 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 77 61 73  ent API call was
28470 20 73 75 63 63 65 73 73 66 75 6c 2c 0a 2a 2a 20   successful,.** 
28480 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20  then the return 
28490 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74  value from sqlit
284a0 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20  e3_errcode() is 
284b0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 54  undefined..** ^T
284c0 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  he sqlite3_exten
284d0 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a  ded_errcode().**
284e0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68   interface is th
284f0 65 20 73 61 6d 65 20 65 78 63 65 70 74 20 74 68  e same except th
28500 61 74 20 69 74 20 61 6c 77 61 79 73 20 72 65 74  at it always ret
28510 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78  urns the .** [ex
28520 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
28530 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78  de] even when ex
28540 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
28550 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62  des are.** disab
28560 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  led..**.** ^The 
28570 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
28580 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72   and sqlite3_err
28590 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e 20 45  msg16() return E
285a0 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a  nglish-language.
285b0 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64 65 73  ** text that des
285c0 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72  cribes the error
285d0 2c 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d  , as either UTF-
285e0 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70  8 or UTF-16 resp
285f0 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d  ectively..** ^(M
28600 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
28610 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
28620 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65  string is manage
28630 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a  d internally..**
28640 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
28650 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
28660 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72  o worry about fr
28670 65 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74  eeing the result
28680 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68  ..** However, th
28690 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d  e error string m
286a0 69 67 68 74 20 62 65 20 6f 76 65 72 77 72 69 74  ight be overwrit
286b0 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74  ten or deallocat
286c0 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75  ed by.** subsequ
286d0 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68  ent calls to oth
286e0 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
286f0 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e  ace functions.)^
28700 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
28710 74 65 33 5f 65 72 72 73 74 72 28 29 20 69 6e 74  te3_errstr() int
28720 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
28730 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75  he English-langu
28740 61 67 65 20 74 65 78 74 0a 2a 2a 20 74 68 61 74  age text.** that
28750 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 5b   describes the [
28760 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61 73  result code], as
28770 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d   UTF-8..** ^(Mem
28780 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
28790 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
287a0 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20  ring is managed 
287b0 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e  internally.** an
287c0 64 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 66 72  d must not be fr
287d0 65 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69  eed by the appli
287e0 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20  cation)^..**.** 
287f0 57 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69  When the seriali
28800 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  zed [threading m
28810 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20  ode] is in use, 
28820 69 74 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a  it might be the.
28830 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61 20 73  ** case that a s
28840 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75  econd error occu
28850 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65  rs on a separate
28860 20 74 68 72 65 61 64 20 69 6e 20 62 65 74 77 65   thread in betwe
28870 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f  en.** the time o
28880 66 20 74 68 65 20 66 69 72 73 74 20 65 72 72 6f  f the first erro
28890 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74  r and the call t
288a0 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  o these interfac
288b0 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74  es..** When that
288c0 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65   happens, the se
288d0 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20  cond error will 
288e0 62 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63  be reported sinc
288f0 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72  e these.** inter
28900 66 61 63 65 73 20 61 6c 77 61 79 73 20 72 65 70  faces always rep
28910 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ort the most rec
28920 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20  ent result.  To 
28930 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65  avoid.** this, e
28940 61 63 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f  ach thread can o
28950 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20  btain exclusive 
28960 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61  use of the [data
28970 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
28980 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e   D.** by invokin
28990 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  g [sqlite3_mutex
289a0 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33  _enter]([sqlite3
289b0 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62  _db_mutex](D)) b
289c0 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a  efore beginning.
289d0 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20  ** to use D and 
289e0 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65  invoking [sqlite
289f0 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b  3_mutex_leave]([
28a00 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78  sqlite3_db_mutex
28a10 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61  ](D)) after.** a
28a20 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20  ll calls to the 
28a30 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74 65  interfaces liste
28a40 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c  d here are compl
28a50 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  eted..**.** If a
28a60 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c  n interface fail
28a70 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49  s with SQLITE_MI
28a80 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73  SUSE, that means
28a90 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a   the interface.*
28aa0 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e  * was invoked in
28ab0 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68 65  correctly by the
28ac0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49   application.  I
28ad0 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74 68 65  n that case, the
28ae0 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61  .** error code a
28af0 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f  nd message may o
28b00 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74  r may not be set
28b10 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
28b20 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33  _errcode(sqlite3
28b30 20 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74   *db);.int sqlit
28b40 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63  e3_extended_errc
28b50 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29  ode(sqlite3 *db)
28b60 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
28b70 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c  lite3_errmsg(sql
28b80 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f  ite3*);.const vo
28b90 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d  id *sqlite3_errm
28ba0 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a  sg16(sqlite3*);.
28bb0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
28bc0 74 65 33 5f 65 72 72 73 74 72 28 69 6e 74 29 3b  te3_errstr(int);
28bd0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
28be0 3a 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  : Prepared State
28bf0 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b  ment Object.** K
28c00 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72  EYWORDS: {prepar
28c10 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70  ed statement} {p
28c20 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
28c30 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  ts}.**.** An ins
28c40 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
28c50 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20  ject represents 
28c60 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61  a single SQL sta
28c70 74 65 6d 65 6e 74 20 74 68 61 74 0a 2a 2a 20 68  tement that.** h
28c80 61 73 20 62 65 65 6e 20 63 6f 6d 70 69 6c 65 64  as been compiled
28c90 20 69 6e 74 6f 20 62 69 6e 61 72 79 20 66 6f 72   into binary for
28ca0 6d 20 61 6e 64 20 69 73 20 72 65 61 64 79 20 74  m and is ready t
28cb0 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 2e 0a  o be evaluated..
28cc0 2a 2a 0a 2a 2a 20 54 68 69 6e 6b 20 6f 66 20 65  **.** Think of e
28cd0 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ach SQL statemen
28ce0 74 20 61 73 20 61 20 73 65 70 61 72 61 74 65 20  t as a separate 
28cf0 63 6f 6d 70 75 74 65 72 20 70 72 6f 67 72 61 6d  computer program
28d00 2e 20 20 54 68 65 0a 2a 2a 20 6f 72 69 67 69 6e  .  The.** origin
28d10 61 6c 20 53 51 4c 20 74 65 78 74 20 69 73 20 73  al SQL text is s
28d20 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 41 20 70  ource code.  A p
28d30 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
28d40 74 20 6f 62 6a 65 63 74 20 0a 2a 2a 20 69 73 20  t object .** is 
28d50 74 68 65 20 63 6f 6d 70 69 6c 65 64 20 6f 62 6a  the compiled obj
28d60 65 63 74 20 63 6f 64 65 2e 20 20 41 6c 6c 20 53  ect code.  All S
28d70 51 4c 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  QL must be conve
28d80 72 74 65 64 20 69 6e 74 6f 20 61 0a 2a 2a 20 70  rted into a.** p
28d90 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
28da0 74 20 62 65 66 6f 72 65 20 69 74 20 63 61 6e 20  t before it can 
28db0 62 65 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  be run..**.** Th
28dc0 65 20 6c 69 66 65 2d 63 79 63 6c 65 20 6f 66 20  e life-cycle of 
28dd0 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  a prepared state
28de0 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75 73 75 61  ment object usua
28df0 6c 6c 79 20 67 6f 65 73 20 6c 69 6b 65 20 74 68  lly goes like th
28e00 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a  is:.**.** <ol>.*
28e10 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68  * <li> Create th
28e20 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
28e30 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75 73 69 6e  ment object usin
28e40 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
28e50 72 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 3c 6c 69  re_v2()]..** <li
28e60 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f  > Bind values to
28e70 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73   [parameters] us
28e80 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
28e90 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20  bind_*().**     
28ea0 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
28eb0 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c  <li> Run the SQL
28ec0 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
28ed0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65  ite3_step()] one
28ee0 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a   or more times..
28ef0 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68  ** <li> Reset th
28f00 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
28f10 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ment using [sqli
28f20 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65  te3_reset()] the
28f30 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20  n go back.**    
28f40 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f    to step 2.  Do
28f50 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f   this zero or mo
28f60 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69  re times..** <li
28f70 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62  > Destroy the ob
28f80 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ject using [sqli
28f90 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e  te3_finalize()].
28fa0 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 74 79 70  .** </ol>.*/.typ
28fb0 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
28fc0 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33  te3_stmt sqlite3
28fd0 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  _stmt;../*.** CA
28fe0 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65  PI3REF: Run-time
28ff0 20 4c 69 6d 69 74 73 0a 2a 2a 20 4d 45 54 48 4f   Limits.** METHO
29000 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
29010 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61 63   ^(This interfac
29020 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a  e allows the siz
29030 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e  e of various con
29040 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69  structs to be li
29050 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f  mited.** on a co
29060 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e  nnection by conn
29070 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54  ection basis.  T
29080 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
29090 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61  er is the.** [da
290a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
290b0 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69  n] whose limit i
290c0 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71  s to be set or q
290d0 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20  ueried.  The.** 
290e0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
290f0 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b   is one of the [
29100 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
29110 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a  ] that define a.
29120 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73  ** class of cons
29130 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a  tructs to be siz
29140 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20  e limited.  The 
29150 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
29160 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69  is the.** new li
29170 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e  mit for that con
29180 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  struct.)^.**.** 
29190 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69  ^If the new limi
291a0 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20  t is a negative 
291b0 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69  number, the limi
291c0 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a  t is unchanged..
291d0 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69  ** ^(For each li
291e0 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c  mit category SQL
291f0 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d  ITE_LIMIT_<i>NAM
29200 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61  E</i> there is a
29210 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68   .** [limits | h
29220 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d  ard upper bound]
29230 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69  .** set at compi
29240 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70  le-time by a C p
29250 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
29260 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d  o called.** [lim
29270 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58  its | SQLITE_MAX
29280 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a  _<i>NAME</i>]..*
29290 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22  * (The "_LIMIT_"
292a0 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20   in the name is 
292b0 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58  changed to "_MAX
292c0 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d  _".))^.** ^Attem
292d0 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20  pts to increase 
292e0 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74  a limit above it
292f0 73 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  s hard upper bou
29300 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74  nd are.** silent
29310 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20  ly truncated to 
29320 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20 62  the hard upper b
29330 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67  ound..**.** ^Reg
29340 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
29350 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69  er or not the li
29360 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c  mit was changed,
29370 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   the .** [sqlite
29380 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72  3_limit()] inter
29390 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
293a0 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20   prior value of 
293b0 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48  the limit..** ^H
293c0 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68  ence, to find th
293d0 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20  e current value 
293e0 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f  of a limit witho
293f0 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a  ut changing it,.
29400 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65  ** simply invoke
29410 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
29420 77 69 74 68 20 74 68 65 20 74 68 69 72 64 20 70  with the third p
29430 61 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20  arameter set to 
29440 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69  -1..**.** Run-ti
29450 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e  me limits are in
29460 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69  tended for use i
29470 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  n applications t
29480 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f  hat manage.** bo
29490 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74  th their own int
294a0 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61  ernal database a
294b0 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65  nd also database
294c0 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72  s that are contr
294d0 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72  olled.** by untr
294e0 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73  usted external s
294f0 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d  ources.  An exam
29500 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  ple application 
29510 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65  might be a.** we
29520 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 20 68  b browser that h
29530 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62  as its own datab
29540 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67  ases for storing
29550 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20   history and.** 
29560 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61 73  separate databas
29570 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79  es controlled by
29580 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 6c   JavaScript appl
29590 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61  ications downloa
295a0 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49  ded.** off the I
295b0 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e  nternet.  The in
295c0 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73  ternal databases
295d0 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68   can be given th
295e0 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61  e.** large, defa
295f0 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74  ult limits.  Dat
29600 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62  abases managed b
29610 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63  y external sourc
29620 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76  es can.** be giv
29630 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20  en much smaller 
29640 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20  limits designed 
29650 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e  to prevent a den
29660 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a  ial of service.*
29670 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c  * attack.  Devel
29680 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f  opers might also
29690 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65   want to use the
296a0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
296b0 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69  thorizer()].** i
296c0 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 74  nterface to furt
296d0 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72  her control untr
296e0 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20  usted SQL.  The 
296f0 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61  size of the data
29700 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20  base.** created 
29710 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  by an untrusted 
29720 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f  script can be co
29730 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68  ntained using th
29740 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63  e.** [max_page_c
29750 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a  ount] [PRAGMA]..
29760 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69  **.** New run-ti
29770 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  me limit categor
29780 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ies may be added
29790 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
297a0 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ses..*/.int sqli
297b0 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65  te3_limit(sqlite
297c0 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20  3*, int id, int 
297d0 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  newVal);../*.** 
297e0 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69  CAPI3REF: Run-Ti
297f0 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72  me Limit Categor
29800 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ies.** KEYWORDS:
29810 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79   {limit category
29820 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f  } {*limit catego
29830 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ries}.**.** Thes
29840 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69  e constants defi
29850 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f  ne various perfo
29860 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a  rmance limits.**
29870 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77   that can be low
29880 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65  ered at run-time
29890 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
298a0 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65  limit()]..** The
298b0 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65   synopsis of the
298c0 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65   meanings of the
298d0 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20   various limits 
298e0 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a  is shown below..
298f0 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e  ** Additional in
29900 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61  formation is ava
29910 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74  ilable at [limit
29920 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51  s | Limits in SQ
29930 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  Lite]..**.** <dl
29940 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  >.** [[SQLITE_LI
29950 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c  MIT_LENGTH]] ^(<
29960 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
29970 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
29980 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73  dd>The maximum s
29990 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e  ize of any strin
299a0 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62  g or BLOB or tab
299b0 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73  le row, in bytes
299c0 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  .<dd>)^.**.** [[
299d0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
299e0 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e  _LENGTH]] ^(<dt>
299f0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
29a00 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
29a10 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
29a20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c  length of an SQL
29a30 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62   statement, in b
29a40 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  ytes.</dd>)^.**.
29a50 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
29a60 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74  T_COLUMN]] ^(<dt
29a70 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  >SQLITE_LIMIT_CO
29a80 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LUMN</dt>.** <dd
29a90 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
29aa0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
29ab0 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69  n a table defini
29ac0 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a  tion or in the.*
29ad0 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  * result set of 
29ae0 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68  a [SELECT] or th
29af0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
29b00 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
29b10 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e  n index.** or in
29b20 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20   an ORDER BY or 
29b30 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e  GROUP BY clause.
29b40 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
29b50 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
29b60 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e  R_DEPTH]] ^(<dt>
29b70 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
29b80 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20  R_DEPTH</dt>.** 
29b90 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
29ba0 64 65 70 74 68 20 6f 66 20 74 68 65 20 70 61 72  depth of the par
29bb0 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65  se tree on any e
29bc0 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29  xpression.</dd>)
29bd0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
29be0 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
29bf0 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53  SELECT]] ^(<dt>S
29c00 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50  QLITE_LIMIT_COMP
29c10 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e  OUND_SELECT</dt>
29c20 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
29c30 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65  mum number of te
29c40 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e  rms in a compoun
29c50 64 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65  d SELECT stateme
29c60 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  nt.</dd>)^.**.**
29c70 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
29c80 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e  VDBE_OP]] ^(<dt>
29c90 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
29ca0 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  E_OP</dt>.** <dd
29cb0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
29cc0 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69  ber of instructi
29cd0 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c  ons in a virtual
29ce0 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d   machine program
29cf0 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c  .** used to impl
29d00 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61  ement an SQL sta
29d10 74 65 6d 65 6e 74 2e 20 20 49 66 20 5b 73 71 6c  tement.  If [sql
29d20 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
29d30 29 5d 20 6f 72 0a 2a 2a 20 74 68 65 20 65 71 75  )] or.** the equ
29d40 69 76 61 6c 65 6e 74 20 74 72 69 65 73 20 74 6f  ivalent tries to
29d50 20 61 6c 6c 6f 63 61 74 65 20 73 70 61 63 65 20   allocate space 
29d60 66 6f 72 20 6d 6f 72 65 20 74 68 61 6e 20 74 68  for more than th
29d70 69 73 20 6d 61 6e 79 20 6f 70 63 6f 64 65 73 0a  is many opcodes.
29d80 2a 2a 20 69 6e 20 61 20 73 69 6e 67 6c 65 20 70  ** in a single p
29d90 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
29da0 74 2c 20 61 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d  t, an SQLITE_NOM
29db0 45 4d 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  EM error is retu
29dc0 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  rned.</dd>)^.**.
29dd0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
29de0 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d  T_FUNCTION_ARG]]
29df0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
29e00 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
29e10 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
29e20 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
29e30 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20  of arguments on 
29e40 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e  a function.</dd>
29e50 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
29e60 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44  E_LIMIT_ATTACHED
29e70 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
29e80 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f  LIMIT_ATTACHED</
29e90 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
29ea0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
29eb0 20 5b 41 54 54 41 43 48 20 7c 20 61 74 74 61 63   [ATTACH | attac
29ec0 68 65 64 20 64 61 74 61 62 61 73 65 73 5d 2e 29  hed databases].)
29ed0 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  ^</dd>.**.** [[S
29ee0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45  QLITE_LIMIT_LIKE
29ef0 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d  _PATTERN_LENGTH]
29f00 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  ].** ^(<dt>SQLIT
29f10 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54  E_LIMIT_LIKE_PAT
29f20 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e  TERN_LENGTH</dt>
29f30 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
29f40 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  mum length of th
29f50 65 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65  e pattern argume
29f60 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d  nt to the [LIKE]
29f70 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70   or.** [GLOB] op
29f80 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a  erators.</dd>)^.
29f90 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
29fa0 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
29fb0 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e  MBER]].** ^(<dt>
29fc0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
29fd0 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74  IABLE_NUMBER</dt
29fe0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
29ff0 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65  imum index numbe
2a000 72 20 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d 65  r of any [parame
2a010 74 65 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73  ter] in an SQL s
2a020 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a  tatement.)^.**.*
2a030 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
2a040 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 5d 5d  _TRIGGER_DEPTH]]
2a050 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
2a060 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MIT_TRIGGER_DEPT
2a070 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
2a080 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20  e maximum depth 
2a090 6f 66 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72  of recursion for
2a0a0 20 74 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29   triggers.</dd>)
2a0b0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
2a0c0 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48  _LIMIT_WORKER_TH
2a0d0 52 45 41 44 53 5d 5d 20 5e 28 3c 64 74 3e 53 51  READS]] ^(<dt>SQ
2a0e0 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45  LITE_LIMIT_WORKE
2a0f0 52 5f 54 48 52 45 41 44 53 3c 2f 64 74 3e 0a 2a  R_THREADS</dt>.*
2a100 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
2a110 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 75 78 69  m number of auxi
2a120 6c 69 61 72 79 20 77 6f 72 6b 65 72 20 74 68 72  liary worker thr
2a130 65 61 64 73 20 74 68 61 74 20 61 20 73 69 6e 67  eads that a sing
2a140 6c 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  le.** [prepared 
2a150 73 74 61 74 65 6d 65 6e 74 5d 20 6d 61 79 20 73  statement] may s
2a160 74 61 72 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20  tart.</dd>)^.** 
2a170 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
2a180 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45   SQLITE_LIMIT_LE
2a190 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20  NGTH            
2a1a0 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e          0.#defin
2a1b0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53  e SQLITE_LIMIT_S
2a1c0 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  QL_LENGTH       
2a1d0 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69           1.#defi
2a1e0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
2a1f0 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20  COLUMN          
2a200 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66            2.#def
2a210 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
2a220 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20 20 20  _EXPR_DEPTH     
2a230 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65             3.#de
2a240 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
2a250 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
2a260 54 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64  T           4.#d
2a270 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
2a280 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20  IT_VDBE_OP      
2a290 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23               5.#
2a2a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
2a2b0 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
2a2c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a                6.
2a2d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
2a2e0 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20 20  IMIT_ATTACHED   
2a2f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 37                 7
2a300 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2a310 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
2a320 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  RN_LENGTH       
2a330 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
2a340 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
2a350 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20 20 20  NUMBER          
2a360 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   9.#define SQLIT
2a370 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f  E_LIMIT_TRIGGER_
2a380 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20  DEPTH           
2a390 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   10.#define SQLI
2a3a0 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f  TE_LIMIT_WORKER_
2a3b0 54 48 52 45 41 44 53 20 20 20 20 20 20 20 20 20  THREADS         
2a3c0 20 20 31 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    11../*.** CAPI
2a3d0 33 52 45 46 3a 20 50 72 65 70 61 72 65 20 46 6c  3REF: Prepare Fl
2a3e0 61 67 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ags.** KEYWORDS:
2a3f0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
2a400 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61  stants define va
2a410 72 69 6f 75 73 20 66 6c 61 67 73 20 74 68 61 74  rious flags that
2a420 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 69   can be passed i
2a430 6e 74 6f 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  nto.** the [SQLI
2a440 54 45 5f 44 42 43 4f 4e 46 49 47 5f 50 52 45 50  TE_DBCONFIG_PREP
2a450 41 52 45 5f 46 4c 41 47 53 5d 20 69 6e 74 65 72  ARE_FLAGS] inter
2a460 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  face..**.** <dl>
2a470 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 50 52 45  .** [[SQLITE_PRE
2a480 50 41 52 45 5f 50 45 52 53 49 53 54 45 4e 54 5d  PARE_PERSISTENT]
2a490 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 50  ] ^(<dt>SQLITE_P
2a4a0 52 45 50 41 52 45 5f 50 45 52 53 49 53 54 45 4e  REPARE_PERSISTEN
2a4b0 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  T</dt>.** <dd>Th
2a4c0 65 20 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45  e SQLITE_PREPARE
2a4d0 5f 50 45 52 53 49 53 54 45 4e 54 20 66 6c 61 67  _PERSISTENT flag
2a4e0 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33   causes [sqlite3
2a4f0 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d 0a 2a  _prepare_v3()].*
2a500 2a 20 74 6f 20 6f 70 74 69 6d 69 7a 65 20 74 68  * to optimize th
2a510 65 20 72 65 73 75 6c 74 69 6e 67 20 70 72 65 70  e resulting prep
2a520 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 74  ared statement t
2a530 6f 20 62 65 20 72 65 74 61 69 6e 65 64 20 66 6f  o be retained fo
2a540 72 20 61 20 0a 2a 2a 20 72 65 6c 61 74 69 76 65  r a .** relative
2a550 6c 79 20 6c 6f 6e 67 20 61 6d 6f 75 6e 74 20 6f  ly long amount o
2a560 66 20 74 69 6d 65 2e 29 5e 20 20 5e 57 69 74 68  f time.)^  ^With
2a570 6f 75 74 20 74 68 69 73 20 66 6c 61 67 2c 0a 2a  out this flag,.*
2a580 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
2a590 72 65 5f 76 33 28 29 5d 20 61 73 73 75 6d 65 73  re_v3()] assumes
2a5a0 20 74 68 61 74 20 74 68 65 20 70 72 65 70 61 72   that the prepar
2a5b0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c  ed statement wil
2a5c0 6c 20 62 65 20 75 73 65 64 0a 2a 2a 20 6a 75 73  l be used.** jus
2a5d0 74 20 6f 6e 63 65 20 6f 72 20 61 74 20 6d 6f 73  t once or at mos
2a5e0 74 20 61 20 66 65 77 20 74 69 6d 65 73 20 61 6e  t a few times an
2a5f0 64 20 74 68 65 6e 20 64 65 73 74 72 6f 79 65 64  d then destroyed
2a600 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
2a610 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 72  e3_finalize()] r
2a620 65 6c 61 74 69 76 65 6c 79 20 73 6f 6f 6e 2e 0a  elatively soon..
2a630 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
2a640 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 45 50 41  ine SQLITE_PREPA
2a650 52 45 5f 50 45 52 53 49 53 54 45 4e 54 20 20 20  RE_PERSISTENT   
2a660 20 20 20 20 20 20 20 20 20 20 20 30 78 30 31 0a             0x01.
2a670 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2a680 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51   Compiling An SQ
2a690 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b  L Statement.** K
2a6a0 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74  EYWORDS: {SQL st
2a6b0 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72  atement compiler
2a6c0 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  }.** METHOD: sql
2a6d0 69 74 65 33 0a 2a 2a 20 43 4f 4e 53 54 52 55 43  ite3.** CONSTRUC
2a6e0 54 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  TOR: sqlite3_stm
2a6f0 74 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75  t.**.** To execu
2a700 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c  te an SQL query,
2a710 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62   it must first b
2a720 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20  e compiled into 
2a730 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70  a byte-code.** p
2a740 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65  rogram using one
2a750 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
2a760 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  es..**.** The fi
2a770 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64  rst argument, "d
2a780 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61  b", is a [databa
2a790 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f  se connection] o
2a7a0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a  btained from a.*
2a7b0 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66  * prior successf
2a7c0 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
2a7d0 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
2a7e0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
2a7f0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
2a800 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20  open16()].  The 
2a810 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2a820 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76  ion must not hav
2a830 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a  e been closed..*
2a840 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  *.** The second 
2a850 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22  argument, "zSql"
2a860 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65  , is the stateme
2a870 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65  nt to be compile
2a880 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73  d, encoded.** as
2a890 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72   either UTF-8 or
2a8a0 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71   UTF-16.  The sq
2a8b0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20  lite3_prepare() 
2a8c0 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
2a8d0 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65  are_v2().** inte
2a8e0 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38  rfaces use UTF-8
2a8f0 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  , and sqlite3_pr
2a900 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71  epare16() and sq
2a910 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2a920 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d  v2().** use UTF-
2a930 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  16..**.** ^If th
2a940 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74  e nByte argument
2a950 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
2a960 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20  en zSql is read 
2a970 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72  up to the.** fir
2a980 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  st zero terminat
2a990 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65 20 69 73  or. ^If nByte is
2a9a0 20 70 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20   positive, then 
2a9b0 69 74 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  it is the.** num
2a9c0 62 65 72 20 6f 66 20 62 79 74 65 73 20 72 65 61  ber of bytes rea
2a9d0 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 49  d from zSql.  ^I
2a9e0 66 20 6e 42 79 74 65 20 69 73 20 7a 65 72 6f 2c  f nByte is zero,
2a9f0 20 74 68 65 6e 20 6e 6f 20 70 72 65 70 61 72 65   then no prepare
2aa00 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69  d.** statement i
2aa10 73 20 67 65 6e 65 72 61 74 65 64 2e 0a 2a 2a 20  s generated..** 
2aa20 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e  If the caller kn
2aa30 6f 77 73 20 74 68 61 74 20 74 68 65 20 73 75 70  ows that the sup
2aa40 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73 20  plied string is 
2aa50 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20  nul-terminated, 
2aa60 74 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20 69 73  then.** there is
2aa70 20 61 20 73 6d 61 6c 6c 20 70 65 72 66 6f 72 6d   a small perform
2aa80 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20 74  ance advantage t
2aa90 6f 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79  o passing an nBy
2aaa0 74 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61  te parameter tha
2aab0 74 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62  t.** is the numb
2aac0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
2aad0 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20  he input string 
2aae0 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e  <i>including</i>
2aaf0 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d  .** the nul-term
2ab00 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49  inator..**.** ^I
2ab10 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20  f pzTail is not 
2ab20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69  NULL then *pzTai
2ab30 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69  l is made to poi
2ab40 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  nt to the first 
2ab50 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65  byte.** past the
2ab60 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73   end of the firs
2ab70 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  t SQL statement 
2ab80 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20  in zSql.  These 
2ab90 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a  routines only.**
2aba0 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72   compile the fir
2abb0 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  st statement in 
2abc0 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c  zSql, so *pzTail
2abd0 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e   is left pointin
2abe0 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d  g to.** what rem
2abf0 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e  ains uncompiled.
2ac00 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20  .**.** ^*ppStmt 
2ac10 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67  is left pointing
2ac20 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b   to a compiled [
2ac30 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2ac40 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a  nt] that can be.
2ac50 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e  ** executed usin
2ac60 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
2ac70 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69  )].  ^If there i
2ac80 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53  s an error, *ppS
2ac90 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f  tmt is set.** to
2aca0 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20   NULL.  ^If the 
2acb0 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61  input text conta
2acc0 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74  ins no SQL (if t
2acd0 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65  he input is an e
2ace0 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f  mpty.** string o
2acf0 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65  r a comment) the
2ad00 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74  n *ppStmt is set
2ad10 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65   to NULL..** The
2ad20 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75   calling procedu
2ad30 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  re is responsibl
2ad40 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74  e for deleting t
2ad50 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53  he compiled.** S
2ad60 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69  QL statement usi
2ad70 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
2ad80 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74  lize()] after it
2ad90 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
2ada0 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74  th it..** ppStmt
2adb0 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c   may not be NULL
2adc0 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63  ..**.** ^On succ
2add0 65 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33  ess, the sqlite3
2ade0 5f 70 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c  _prepare() famil
2adf0 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65  y of routines re
2ae00 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
2ae10 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61  ;.** otherwise a
2ae20 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
2ae30 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
2ae40 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72  * The sqlite3_pr
2ae50 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73  epare_v2() and s
2ae60 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2ae70 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 73  _v2() interfaces
2ae80 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e   are.** recommen
2ae90 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20  ded for all new 
2aea0 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77  programs. The tw
2aeb0 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63  o older interfac
2aec0 65 73 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a  es are retained.
2aed0 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ** for backwards
2aee0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20   compatibility, 
2aef0 62 75 74 20 74 68 65 69 72 20 75 73 65 20 69 73  but their use is
2af00 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a   discouraged..**
2af10 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e   ^In the "v2" in
2af20 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 72  terfaces, the pr
2af30 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2af40 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 75  .** that is retu
2af50 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74  rned (the [sqlit
2af60 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29  e3_stmt] object)
2af70 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79   contains a copy
2af80 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69   of the.** origi
2af90 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68  nal SQL text. Th
2afa0 69 73 20 63 61 75 73 65 73 20 74 68 65 20 5b 73  is causes the [s
2afb0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69  qlite3_step()] i
2afc0 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62  nterface to.** b
2afd0 65 68 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c  ehave differentl
2afe0 79 20 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a  y in three ways:
2aff0 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c  .**.** <ol>.** <
2b000 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64  li>.** ^If the d
2b010 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63  atabase schema c
2b020 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20  hanges, instead 
2b030 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51  of returning [SQ
2b040 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20  LITE_SCHEMA] as 
2b050 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65  it.** always use
2b060 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65  d to do, [sqlite
2b070 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61  3_step()] will a
2b080 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63  utomatically rec
2b090 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a  ompile the SQL.*
2b0a0 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  * statement and 
2b0b0 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67  try to run it ag
2b0c0 61 69 6e 2e 20 41 73 20 6d 61 6e 79 20 61 73 20  ain. As many as 
2b0d0 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 53 43 48 45  [SQLITE_MAX_SCHE
2b0e0 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a 20 72 65 74  MA_RETRY].** ret
2b0f0 72 69 65 73 20 77 69 6c 6c 20 6f 63 63 75 72 20  ries will occur 
2b100 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 73  before sqlite3_s
2b110 74 65 70 28 29 20 67 69 76 65 73 20 75 70 20 61  tep() gives up a
2b120 6e 64 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72  nd returns an er
2b130 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  ror..** </li>.**
2b140 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65  .** <li>.** ^Whe
2b150 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  n an error occur
2b160 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  s, [sqlite3_step
2b170 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
2b180 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 69  one of the detai
2b190 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f  led.** [error co
2b1a0 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65  des] or [extende
2b1b0 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20  d error codes]. 
2b1c0 20 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65 68   ^The legacy beh
2b1d0 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a  avior was that.*
2b1e0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
2b1f0 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65  )] would only re
2b200 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b  turn a generic [
2b210 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65  SQLITE_ERROR] re
2b220 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64  sult code.** and
2b230 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2b240 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d   would have to m
2b250 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c  ake a second cal
2b260 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  l to [sqlite3_re
2b270 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64  set()].** in ord
2b280 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75  er to find the u
2b290 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20  nderlying cause 
2b2a0 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20  of the problem. 
2b2b0 57 69 74 68 20 74 68 65 20 22 76 32 22 20 70 72  With the "v2" pr
2b2c0 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61  epare.** interfa
2b2d0 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79  ces, the underly
2b2e0 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74  ing reason for t
2b2f0 68 65 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  he error is retu
2b300 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79  rned immediately
2b310 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a  ..** </li>.**.**
2b320 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65   <li>.** ^If the
2b330 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20   specific value 
2b340 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65  bound to [parame
2b350 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d  ter | host param
2b360 65 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a  eter] in the .**
2b370 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69   WHERE clause mi
2b380 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68  ght influence th
2b390 65 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72  e choice of quer
2b3a0 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61  y plan for a sta
2b3b0 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20  tement,.** then 
2b3c0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69  the statement wi
2b3d0 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61  ll be automatica
2b3e0 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20  lly recompiled, 
2b3f0 61 73 20 69 66 20 74 68 65 72 65 20 68 61 64 20  as if there had 
2b400 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d  been .** a schem
2b410 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65  a change, on the
2b420 20 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33   first  [sqlite3
2b430 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f  _step()] call fo
2b440 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e  llowing any chan
2b450 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  ge.** to the [sq
2b460 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20  lite3_bind_text 
2b470 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74  | bindings] of t
2b480 68 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e  hat [parameter].
2b490 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66   .** ^The specif
2b4a0 69 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52  ic value of WHER
2b4b0 45 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65  E-clause [parame
2b4c0 74 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75  ter] might influ
2b4d0 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f  ence the .** cho
2b4e0 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61  ice of query pla
2b4f0 6e 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  n if the paramet
2b500 65 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68  er is the left-h
2b510 61 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c  and side of a [L
2b520 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42  IKE].** or [GLOB
2b530 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66  ] operator or if
2b540 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
2b550 73 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e  s compared to an
2b560 20 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a   indexed column.
2b570 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49  ** and the [SQLI
2b580 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d  TE_ENABLE_STAT3]
2b590 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
2b5a0 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e  tion is enabled.
2b5b0 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f  .** </li>.** </o
2b5c0 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l>.*/.int sqlite
2b5d0 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c  3_prepare(.  sql
2b5e0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
2b5f0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
2b600 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2b610 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
2b620 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
2b630 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63  ement, UTF-8 enc
2b640 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
2b650 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
2b660 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
2b670 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
2b680 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
2b690 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
2b6a0 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
2b6b0 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
2b6c0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a   const char **pz
2b6d0 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
2b6e0 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
2b6f0 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
2b700 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ql */.);.int sql
2b710 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2b720 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
2b730 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
2b740 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
2b750 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
2b760 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
2b770 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
2b780 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  -8 encoded */.  
2b790 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
2b7a0 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
2b7b0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
2b7c0 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
2b7d0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
2b7e0 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
2b7f0 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
2b800 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
2b810 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  r **pzTail     /
2b820 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
2b830 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
2b840 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
2b850 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
2b860 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20  re16(.  sqlite3 
2b870 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
2b880 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
2b890 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
2b8a0 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  id *zSql,       
2b8b0 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
2b8c0 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  , UTF-16 encoded
2b8d0 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
2b8e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2b8f0 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
2b900 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
2b910 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
2b920 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
2b930 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
2b940 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2b950 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c  st void **pzTail
2b960 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
2b970 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
2b980 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
2b990 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
2b9a0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20  _prepare16_v2(. 
2b9b0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
2b9c0 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
2b9d0 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
2b9e0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71   const void *zSq
2b9f0 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
2ba00 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31  statement, UTF-1
2ba10 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  6 encoded */.  i
2ba20 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
2ba30 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
2ba40 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
2ba50 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
2ba60 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
2ba70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
2ba80 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
2ba90 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
2baa0 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
2bab0 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
2bac0 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
2bad0 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f  of zSql */.);../
2bae0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
2baf0 65 74 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d  etrieving Statem
2bb00 65 6e 74 20 53 51 4c 0a 2a 2a 20 4d 45 54 48 4f  ent SQL.** METHO
2bb10 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
2bb20 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2bb30 65 33 5f 73 71 6c 28 50 29 20 69 6e 74 65 72 66  e3_sql(P) interf
2bb40 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
2bb50 69 6e 74 65 72 20 74 6f 20 61 20 63 6f 70 79 20  inter to a copy 
2bb60 6f 66 20 74 68 65 20 55 54 46 2d 38 0a 2a 2a 20  of the UTF-8.** 
2bb70 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f  SQL text used to
2bb80 20 63 72 65 61 74 65 20 5b 70 72 65 70 61 72 65   create [prepare
2bb90 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 20 69  d statement] P i
2bba0 66 20 50 20 77 61 73 0a 2a 2a 20 63 72 65 61 74  f P was.** creat
2bbb0 65 64 20 62 79 20 65 69 74 68 65 72 20 5b 73 71  ed by either [sq
2bbc0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2bbd0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2bbe0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
2bbf0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2bc00 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 50 29  _expanded_sql(P)
2bc10 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2bc20 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
2bc30 61 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e  a UTF-8.** strin
2bc40 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  g containing the
2bc50 20 53 51 4c 20 74 65 78 74 20 6f 66 20 70 72 65   SQL text of pre
2bc60 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2bc70 50 20 77 69 74 68 0a 2a 2a 20 5b 62 6f 75 6e 64  P with.** [bound
2bc80 20 70 61 72 61 6d 65 74 65 72 73 5d 20 65 78 70   parameters] exp
2bc90 61 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46  anded..**.** ^(F
2bca0 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61  or example, if a
2bcb0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2bcc0 65 6e 74 20 69 73 20 63 72 65 61 74 65 64 20 75  ent is created u
2bcd0 73 69 6e 67 20 74 68 65 20 53 51 4c 0a 2a 2a 20  sing the SQL.** 
2bce0 74 65 78 74 20 22 53 45 4c 45 43 54 20 24 61 62  text "SELECT $ab
2bcf0 63 2c 3a 78 79 7a 22 20 61 6e 64 20 69 66 20 70  c,:xyz" and if p
2bd00 61 72 61 6d 65 74 65 72 20 24 61 62 63 20 69 73  arameter $abc is
2bd10 20 62 6f 75 6e 64 20 74 6f 20 69 6e 74 65 67 65   bound to intege
2bd20 72 20 32 33 34 35 0a 2a 2a 20 61 6e 64 20 70 61  r 2345.** and pa
2bd30 72 61 6d 65 74 65 72 20 3a 78 79 7a 20 69 73 20  rameter :xyz is 
2bd40 75 6e 62 6f 75 6e 64 2c 20 74 68 65 6e 20 73 71  unbound, then sq
2bd50 6c 69 74 65 33 5f 73 71 6c 28 29 20 77 69 6c 6c  lite3_sql() will
2bd60 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 6f   return.** the o
2bd70 72 69 67 69 6e 61 6c 20 73 74 72 69 6e 67 2c 20  riginal string, 
2bd80 22 53 45 4c 45 43 54 20 24 61 62 63 2c 3a 78 79  "SELECT $abc,:xy
2bd90 7a 22 20 62 75 74 20 73 71 6c 69 74 65 33 5f 65  z" but sqlite3_e
2bda0 78 70 61 6e 64 65 64 5f 73 71 6c 28 29 0a 2a 2a  xpanded_sql().**
2bdb0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 22 53 45   will return "SE
2bdc0 4c 45 43 54 20 32 33 34 35 2c 4e 55 4c 4c 22 2e  LECT 2345,NULL".
2bdd0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )^.**.** ^The sq
2bde0 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73  lite3_expanded_s
2bdf0 71 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ql() interface r
2be00 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69 66 20 69  eturns NULL if i
2be10 6e 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f  nsufficient memo
2be20 72 79 0a 2a 2a 20 69 73 20 61 76 61 69 6c 61 62  ry.** is availab
2be30 6c 65 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72  le to hold the r
2be40 65 73 75 6c 74 2c 20 6f 72 20 69 66 20 74 68 65  esult, or if the
2be50 20 72 65 73 75 6c 74 20 77 6f 75 6c 64 20 65 78   result would ex
2be60 63 65 65 64 20 74 68 65 0a 2a 2a 20 74 68 65 20  ceed the.** the 
2be70 6d 61 78 69 6d 75 6d 20 73 74 72 69 6e 67 20 6c  maximum string l
2be80 65 6e 67 74 68 20 64 65 74 65 72 6d 69 6e 65 64  ength determined
2be90 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   by the [SQLITE_
2bea0 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 2e 0a 2a  LIMIT_LENGTH]..*
2beb0 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  *.** ^The [SQLIT
2bec0 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d  E_TRACE_SIZE_LIM
2bed0 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  IT] compile-time
2bee0 20 6f 70 74 69 6f 6e 20 6c 69 6d 69 74 73 20 74   option limits t
2bef0 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 62 6f  he size of.** bo
2bf00 75 6e 64 20 70 61 72 61 6d 65 74 65 72 20 65 78  und parameter ex
2bf10 70 61 6e 73 69 6f 6e 73 2e 20 20 5e 54 68 65 20  pansions.  ^The 
2bf20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 54 52 41  [SQLITE_OMIT_TRA
2bf30 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  CE] compile-time
2bf40 0a 2a 2a 20 6f 70 74 69 6f 6e 20 63 61 75 73 65  .** option cause
2bf50 73 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64  s sqlite3_expand
2bf60 65 64 5f 73 71 6c 28 29 20 74 6f 20 61 6c 77 61  ed_sql() to alwa
2bf70 79 73 20 72 65 74 75 72 6e 20 4e 55 4c 4c 2e 0a  ys return NULL..
2bf80 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 74 72 69 6e  **.** ^The strin
2bf90 67 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  g returned by sq
2bfa0 6c 69 74 65 33 5f 73 71 6c 28 50 29 20 69 73 20  lite3_sql(P) is 
2bfb0 6d 61 6e 61 67 65 64 20 62 79 20 53 51 4c 69 74  managed by SQLit
2bfc0 65 20 61 6e 64 20 69 73 0a 2a 2a 20 61 75 74 6f  e and is.** auto
2bfd0 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 64 20  matically freed 
2bfe0 77 68 65 6e 20 74 68 65 20 70 72 65 70 61 72 65  when the prepare
2bff0 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 66  d statement is f
2c000 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a 20 5e 54 68  inalized..** ^Th
2c010 65 20 73 74 72 69 6e 67 20 72 65 74 75 72 6e 65  e string returne
2c020 64 20 62 79 20 73 71 6c 69 74 65 33 5f 65 78 70  d by sqlite3_exp
2c030 61 6e 64 65 64 5f 73 71 6c 28 50 29 2c 20 6f 6e  anded_sql(P), on
2c040 20 74 68 65 20 6f 74 68 65 72 20 68 61 6e 64 2c   the other hand,
2c050 0a 2a 2a 20 69 73 20 6f 62 74 61 69 6e 65 64 20  .** is obtained 
2c060 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
2c070 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 6d 75 73 74  lloc()] and must
2c080 20 62 65 20 66 72 65 65 20 62 79 20 74 68 65 20   be free by the 
2c090 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 62  application.** b
2c0a0 79 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20  y passing it to 
2c0b0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
2c0c0 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
2c0d0 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c  *sqlite3_sql(sql
2c0e0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
2c0f0 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
2c100 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 73 71  _expanded_sql(sq
2c110 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
2c120 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2c130 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49  REF: Determine I
2c140 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  f An SQL Stateme
2c150 6e 74 20 57 72 69 74 65 73 20 54 68 65 20 44 61  nt Writes The Da
2c160 74 61 62 61 73 65 0a 2a 2a 20 4d 45 54 48 4f 44  tabase.** METHOD
2c170 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2c180 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2c190 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
2c1a0 58 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  X) interface ret
2c1b0 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a  urns true (non-z
2c1c0 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f  ero) if.** and o
2c1d0 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 72 65 70  nly if the [prep
2c1e0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2c1f0 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 63  X makes no direc
2c200 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20  t changes to.** 
2c210 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
2c220 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
2c230 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
2c240 74 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  t [application-d
2c250 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
2c260 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72  ions] or.** [vir
2c270 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67  tual tables] mig
2c280 68 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61  ht change the da
2c290 74 61 62 61 73 65 20 69 6e 64 69 72 65 63 74 6c  tabase indirectl
2c2a0 79 20 61 73 20 61 20 73 69 64 65 20 65 66 66 65  y as a side effe
2c2b0 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65  ct.  .** ^(For e
2c2c0 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 70  xample, if an ap
2c2d0 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
2c2e0 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 76  s a function "ev
2c2f0 61 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 63  al()" that .** c
2c300 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 78  alls [sqlite3_ex
2c310 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20  ec()], then the 
2c320 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74  following SQL st
2c330 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a  atement would.**
2c340 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61   change the data
2c350 62 61 73 65 20 66 69 6c 65 20 74 68 72 6f 75 67  base file throug
2c360 68 20 73 69 64 65 2d 65 66 66 65 63 74 73 3a 0a  h side-effects:.
2c370 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
2c380 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45  e><pre>.**    SE
2c390 4c 45 43 54 20 65 76 61 6c 28 27 44 45 4c 45 54  LECT eval('DELET
2c3a0 45 20 46 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d  E FROM t1') FROM
2c3b0 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f   t2;.** </pre></
2c3c0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
2c3d0 2a 20 42 75 74 20 62 65 63 61 75 73 65 20 74 68  * But because th
2c3e0 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  e [SELECT] state
2c3f0 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 68  ment does not ch
2c400 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73  ange the databas
2c410 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74  e file.** direct
2c420 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  ly, sqlite3_stmt
2c430 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c  _readonly() woul
2c440 64 20 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 74  d still return t
2c450 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72  rue.)^.**.** ^Tr
2c460 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f  ansaction contro
2c470 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 73 75 63  l statements suc
2c480 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43  h as [BEGIN], [C
2c490 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43  OMMIT], [ROLLBAC
2c4a0 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e  K],.** [SAVEPOIN
2c4b0 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 45  T], and [RELEASE
2c4c0 5d 20 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f  ] cause sqlite3_
2c4d0 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20  stmt_readonly() 
2c4e0 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 2c 0a  to return true,.
2c4f0 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 73 74 61  ** since the sta
2c500 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c 76  tements themselv
2c510 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c  es do not actual
2c520 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61  ly modify the da
2c530 74 61 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 61  tabase but.** ra
2c540 74 68 65 72 20 74 68 65 79 20 63 6f 6e 74 72 6f  ther they contro
2c550 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 20  l the timing of 
2c560 77 68 65 6e 20 6f 74 68 65 72 20 73 74 61 74 65  when other state
2c570 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 65  ments modify the
2c580 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20   .** database.  
2c590 5e 54 68 65 20 5b 41 54 54 41 43 48 5d 20 61 6e  ^The [ATTACH] an
2c5a0 64 20 5b 44 45 54 41 43 48 5d 20 73 74 61 74 65  d [DETACH] state
2c5b0 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 65  ments also cause
2c5c0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  .** sqlite3_stmt
2c5d0 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72  _readonly() to r
2c5e0 65 74 75 72 6e 20 74 72 75 65 20 73 69 6e 63 65  eturn true since
2c5f0 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 20 73 74  , while those st
2c600 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e  atements.** chan
2c610 67 65 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61  ge the configura
2c620 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 61  tion of a databa
2c630 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74  se connection, t
2c640 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20  hey do not make 
2c650 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 74  .** changes to t
2c660 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
2c670 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73  e database files
2c680 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2a 20 5e 54 68   on disk..** ^Th
2c690 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  e sqlite3_stmt_r
2c6a0 65 61 64 6f 6e 6c 79 28 29 20 69 6e 74 65 72 66  eadonly() interf
2c6b0 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65  ace returns true
2c6c0 20 66 6f 72 20 5b 42 45 47 49 4e 5d 20 73 69 6e   for [BEGIN] sin
2c6d0 63 65 0a 2a 2a 20 5b 42 45 47 49 4e 5d 20 6d 65  ce.** [BEGIN] me
2c6e0 72 65 6c 79 20 73 65 74 73 20 69 6e 74 65 72 6e  rely sets intern
2c6f0 61 6c 20 66 6c 61 67 73 2c 20 62 75 74 20 74 68  al flags, but th
2c700 65 20 5b 42 45 47 49 4e 7c 42 45 47 49 4e 20 49  e [BEGIN|BEGIN I
2c710 4d 4d 45 44 49 41 54 45 5d 20 61 6e 64 0a 2a 2a  MMEDIATE] and.**
2c720 20 5b 42 45 47 49 4e 7c 42 45 47 49 4e 20 45 58   [BEGIN|BEGIN EX
2c730 43 4c 55 53 49 56 45 5d 20 63 6f 6d 6d 61 6e 64  CLUSIVE] command
2c740 73 20 64 6f 20 74 6f 75 63 68 20 74 68 65 20 64  s do touch the d
2c750 61 74 61 62 61 73 65 20 61 6e 64 20 73 6f 0a 2a  atabase and so.*
2c760 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  * sqlite3_stmt_r
2c770 65 61 64 6f 6e 6c 79 28 29 20 72 65 74 75 72 6e  eadonly() return
2c780 73 20 66 61 6c 73 65 20 66 6f 72 20 74 68 6f 73  s false for thos
2c790 65 20 63 6f 6d 6d 61 6e 64 73 2e 0a 2a 2f 0a 69  e commands..*/.i
2c7a0 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  nt sqlite3_stmt_
2c7b0 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33  readonly(sqlite3
2c7c0 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
2c7d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2c7e0 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 20 50  Determine If A P
2c7f0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
2c800 74 20 48 61 73 20 42 65 65 6e 20 52 65 73 65 74  t Has Been Reset
2c810 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2c820 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
2c830 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  The sqlite3_stmt
2c840 5f 62 75 73 79 28 53 29 20 69 6e 74 65 72 66 61  _busy(S) interfa
2c850 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20  ce returns true 
2c860 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68  (non-zero) if th
2c870 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
2c880 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 73 20  tatement] S has 
2c890 62 65 65 6e 20 73 74 65 70 70 65 64 20 61 74 20  been stepped at 
2c8a0 6c 65 61 73 74 20 6f 6e 63 65 20 75 73 69 6e 67  least once using
2c8b0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74   .** [sqlite3_st
2c8c0 65 70 28 53 29 5d 20 62 75 74 20 68 61 73 20 6e  ep(S)] but has n
2c8d0 65 69 74 68 65 72 20 72 75 6e 20 74 6f 20 63 6f  either run to co
2c8e0 6d 70 6c 65 74 69 6f 6e 20 28 72 65 74 75 72 6e  mpletion (return
2c8f0 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f  ed.** [SQLITE_DO
2c900 4e 45 5d 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  NE] from [sqlite
2c910 33 5f 73 74 65 70 28 53 29 5d 29 20 6e 6f 72 0a  3_step(S)]) nor.
2c920 2a 2a 20 62 65 65 6e 20 72 65 73 65 74 20 75 73  ** been reset us
2c930 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
2c940 65 74 28 53 29 5d 2e 20 20 5e 54 68 65 20 73 71  et(S)].  ^The sq
2c950 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28  lite3_stmt_busy(
2c960 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  S).** interface 
2c970 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 69 66  returns false if
2c980 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   S is a NULL poi
2c990 6e 74 65 72 2e 20 20 49 66 20 53 20 69 73 20 6e  nter.  If S is n
2c9a0 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f  ot a .** NULL po
2c9b0 69 6e 74 65 72 20 61 6e 64 20 69 73 20 6e 6f 74  inter and is not
2c9c0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
2c9d0 76 61 6c 69 64 20 5b 70 72 65 70 61 72 65 64 20  valid [prepared 
2c9e0 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62  statement].** ob
2c9f0 6a 65 63 74 2c 20 74 68 65 6e 20 74 68 65 20 62  ject, then the b
2ca00 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
2ca10 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c  ined and probabl
2ca20 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a  y undesirable..*
2ca30 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66  *.** This interf
2ca40 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ace can be used 
2ca50 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b  in combination [
2ca60 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d  sqlite3_next_stm
2ca70 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74  t()].** to locat
2ca80 65 20 61 6c 6c 20 70 72 65 70 61 72 65 64 20 73  e all prepared s
2ca90 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69  tatements associ
2caa0 61 74 65 64 20 77 69 74 68 20 61 20 64 61 74 61  ated with a data
2cab0 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74  base .** connect
2cac0 69 6f 6e 20 74 68 61 74 20 61 72 65 20 69 6e 20  ion that are in 
2cad0 6e 65 65 64 20 6f 66 20 62 65 69 6e 67 20 72 65  need of being re
2cae0 73 65 74 2e 20 20 54 68 69 73 20 63 61 6e 20 62  set.  This can b
2caf0 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65  e used,.** for e
2cb00 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e  xample, in diagn
2cb10 6f 73 74 69 63 20 72 6f 75 74 69 6e 65 73 20 74  ostic routines t
2cb20 6f 20 73 65 61 72 63 68 20 66 6f 72 20 70 72 65  o search for pre
2cb30 70 61 72 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d  pared .** statem
2cb40 65 6e 74 73 20 74 68 61 74 20 61 72 65 20 68 6f  ents that are ho
2cb50 6c 64 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74  lding a transact
2cb60 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74  ion open..*/.int
2cb70 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75   sqlite3_stmt_bu
2cb80 73 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  sy(sqlite3_stmt*
2cb90 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2cba0 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20  EF: Dynamically 
2cbb0 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65  Typed Value Obje
2cbc0 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ct.** KEYWORDS: 
2cbd0 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  {protected sqlit
2cbe0 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f  e3_value} {unpro
2cbf0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2cc00 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  alue}.**.** SQLi
2cc10 74 65 20 75 73 65 73 20 74 68 65 20 73 71 6c 69  te uses the sqli
2cc20 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2cc30 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c   to represent al
2cc40 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74  l values.** that
2cc50 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69   can be stored i
2cc60 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62  n a database tab
2cc70 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20  le. SQLite uses 
2cc80 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a  dynamic typing.*
2cc90 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73  * for the values
2cca0 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61   it stores.  ^Va
2ccb0 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73  lues stored in s
2ccc0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2ccd0 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69  ects.** can be i
2cce0 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e  ntegers, floatin
2ccf0 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20  g point values, 
2cd00 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20  strings, BLOBs, 
2cd10 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41  or NULL..**.** A
2cd20 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  n sqlite3_value 
2cd30 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69  object may be ei
2cd40 74 68 65 72 20 22 70 72 6f 74 65 63 74 65 64 22  ther "protected"
2cd50 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64   or "unprotected
2cd60 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72  "..** Some inter
2cd70 66 61 63 65 73 20 72 65 71 75 69 72 65 20 61 20  faces require a 
2cd80 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2cd90 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20  3_value.  Other 
2cda0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69  interfaces.** wi
2cdb0 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68 65 72  ll accept either
2cdc0 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20   a protected or 
2cdd0 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73  an unprotected s
2cde0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a  qlite3_value..**
2cdf0 20 45 76 65 72 79 20 69 6e 74 65 72 66 61 63 65   Every interface
2ce00 20 74 68 61 74 20 61 63 63 65 70 74 73 20 73 71   that accepts sq
2ce10 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75  lite3_value argu
2ce20 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a  ments specifies.
2ce30 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  ** whether or no
2ce40 74 20 69 74 20 72 65 71 75 69 72 65 73 20 61 20  t it requires a 
2ce50 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2ce60 33 5f 76 61 6c 75 65 2e 20 20 54 68 65 0a 2a 2a  3_value.  The.**
2ce70 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2ce80 64 75 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65  dup()] interface
2ce90 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
2cea0 63 6f 6e 73 74 72 75 63 74 20 61 20 6e 65 77 20  construct a new 
2ceb0 0a 2a 2a 20 70 72 6f 74 65 63 74 65 64 20 73 71  .** protected sq
2cec0 6c 69 74 65 33 5f 76 61 6c 75 65 20 66 72 6f 6d  lite3_value from
2ced0 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20   an unprotected 
2cee0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a  sqlite3_value..*
2cef0 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22  *.** The terms "
2cf00 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22  protected" and "
2cf10 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65 66  unprotected" ref
2cf20 65 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72  er to whether or
2cf30 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20   not.** a mutex 
2cf40 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74  is held.  An int
2cf50 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68  ernal mutex is h
2cf60 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63  eld for a protec
2cf70 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
2cf80 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20  alue object but 
2cf90 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64  no mutex is held
2cfa0 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63   for an unprotec
2cfb0 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
2cfc0 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66  alue object.  If
2cfd0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
2cfe0 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65  led to be single
2cff0 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69  -threaded.** (wi
2d000 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  th [SQLITE_THREA
2d010 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74  DSAFE=0] and wit
2d020 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61  h [sqlite3_threa
2d030 64 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69  dsafe()] returni
2d040 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53  ng 0).** or if S
2d050 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20  QLite is run in 
2d060 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d  one of reduced m
2d070 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b  utex modes .** [
2d080 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
2d090 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b  NGLETHREAD] or [
2d0a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
2d0b0 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68  LTITHREAD].** th
2d0c0 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64  en there is no d
2d0d0 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65  istinction betwe
2d0e0 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64  en protected and
2d0f0 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
2d100 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2d110 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79 20 63  jects and they c
2d120 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65 72  an be used inter
2d130 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77  changeably.  How
2d140 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78  ever,.** for max
2d150 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62  imum code portab
2d160 69 6c 69 74 79 20 69 74 20 69 73 20 72 65 63 6f  ility it is reco
2d170 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70  mmended that app
2d180 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69  lications.** sti
2d190 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74  ll make the dist
2d1a0 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  inction between 
2d1b0 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e  protected and un
2d1c0 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
2d1d0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2d1e0 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74  ts even when not
2d1f0 20 73 74 72 69 63 74 6c 79 20 72 65 71 75 69 72   strictly requir
2d200 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
2d210 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2d220 65 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61  ects that are pa
2d230 73 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65  ssed as paramete
2d240 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69  rs into the.** i
2d250 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
2d260 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
2d270 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
2d280 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74  ons] are protect
2d290 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  ed..** ^The sqli
2d2a0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2d2b0 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
2d2c0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2d2d0 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72  value()] is unpr
2d2e0 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72  otected..** Unpr
2d2f0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2d300 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61  value objects ma
2d310 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77  y only be used w
2d320 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ith.** [sqlite3_
2d330 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20  result_value()] 
2d340 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  and [sqlite3_bin
2d350 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54  d_value()]..** T
2d360 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
2d370 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33  e_blob | sqlite3
2d380 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66  _value_type()] f
2d390 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65  amily of.** inte
2d3a0 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 70  rfaces require p
2d3b0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2d3c0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a  _value objects..
2d3d0 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
2d3e0 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  t sqlite3_value 
2d3f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a  sqlite3_value;..
2d400 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2d410 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e  SQL Function Con
2d420 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  text Object.**.*
2d430 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e  * The context in
2d440 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75   which an SQL fu
2d450 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20  nction executes 
2d460 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a  is stored in an.
2d470 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ** sqlite3_conte
2d480 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70  xt object.  ^A p
2d490 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c  ointer to an sql
2d4a0 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a  ite3_context obj
2d4b0 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73  ect.** is always
2d4c0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
2d4d0 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e   to [application
2d4e0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
2d4f0 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20  ctions]..** The 
2d500 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2d510 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
2d520 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2d530 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a  will pass this.*
2d540 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67  * pointer throug
2d550 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20  h into calls to 
2d560 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
2d570 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65  int | sqlite3_re
2d580 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  sult()],.** [sql
2d590 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
2d5a0 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69  ontext()], [sqli
2d5b0 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d  te3_user_data()]
2d5c0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  ,.** [sqlite3_co
2d5d0 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28  ntext_db_handle(
2d5e0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  )], [sqlite3_get
2d5f0 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20  _auxdata()],.** 
2d600 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f  and/or [sqlite3_
2d610 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a  set_auxdata()]..
2d620 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
2d630 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t sqlite3_contex
2d640 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t sqlite3_contex
2d650 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  t;../*.** CAPI3R
2d660 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75  EF: Binding Valu
2d670 65 73 20 54 6f 20 50 72 65 70 61 72 65 64 20 53  es To Prepared S
2d680 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59  tatements.** KEY
2d690 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72  WORDS: {host par
2d6a0 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61  ameter} {host pa
2d6b0 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20  rameters} {host 
2d6c0 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a  parameter name}.
2d6d0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51  ** KEYWORDS: {SQ
2d6e0 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51  L parameter} {SQ
2d6f0 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70  L parameters} {p
2d700 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67  arameter binding
2d710 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  }.** METHOD: sql
2d720 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
2d730 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61  ^(In the SQL sta
2d740 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75  tement text inpu
2d750 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72  t to [sqlite3_pr
2d760 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
2d770 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a  its variants,.**
2d780 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65   literals may be
2d790 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b   replaced by a [
2d7a0 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20  parameter] that 
2d7b0 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66  matches one of f
2d7c0 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70  ollowing.** temp
2d7d0 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  lates:.**.** <ul
2d7e0 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20  >.** <li>  ?.** 
2d7f0 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c  <li>  ?NNN.** <l
2d800 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e  i>  :VVV.** <li>
2d810 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20    @VVV.** <li>  
2d820 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  $VVV.** </ul>.**
2d830 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c  .** In the templ
2d840 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20  ates above, NNN 
2d850 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e  represents an in
2d860 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a  teger literal,.*
2d870 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72 65 73  * and VVV repres
2d880 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d  ents an alphanum
2d890 65 72 69 63 20 69 64 65 6e 74 69 66 69 65 72 2e  eric identifier.
2d8a0 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20  )^  ^The values 
2d8b0 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61  of these.** para
2d8c0 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c  meters (also cal
2d8d0 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65  led "host parame
2d8e0 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53  ter names" or "S
2d8f0 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a  QL parameters").
2d900 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75 73  ** can be set us
2d910 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
2d920 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
2d930 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a  s defined here..
2d940 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
2d950 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
2d960 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
2d970 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c  ) routines is al
2d980 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65  ways.** a pointe
2d990 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
2d9a0 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72  3_stmt] object r
2d9b0 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20  eturned from.** 
2d9c0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2d9d0 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61  _v2()] or its va
2d9e0 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  riants..**.** ^T
2d9f0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
2da00 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20  nt is the index 
2da10 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d  of the SQL param
2da20 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a  eter to be set..
2da30 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74  ** ^The leftmost
2da40 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68   SQL parameter h
2da50 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31  as an index of 1
2da60 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d  .  ^When the sam
2da70 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70  e named.** SQL p
2da80 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 64  arameter is used
2da90 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c   more than once,
2daa0 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73   second and subs
2dab0 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72  equent.** occurr
2dac0 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 73  ences have the s
2dad0 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 65  ame index as the
2dae0 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63   first occurrenc
2daf0 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78  e..** ^The index
2db00 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d   for named param
2db10 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f  eters can be loo
2db20 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 68 65  ked up using the
2db30 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
2db40 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
2db50 78 28 29 5d 20 41 50 49 20 69 66 20 64 65 73 69  x()] API if desi
2db60 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78  red.  ^The index
2db70 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70  .** for "?NNN" p
2db80 61 72 61 6d 65 74 65 72 73 20 69 73 20 74 68 65  arameters is the
2db90 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a   value of NNN..*
2dba0 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65  * ^The NNN value
2dbb0 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e   must be between
2dbc0 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69   1 and the [sqli
2dbd0 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20  te3_limit()].** 
2dbe0 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54  parameter [SQLIT
2dbf0 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
2dc00 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c  _NUMBER] (defaul
2dc10 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a  t value: 999)..*
2dc20 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20  *.** ^The third 
2dc30 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
2dc40 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f  value to bind to
2dc50 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a   the parameter..
2dc60 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72 64  ** ^If the third
2dc70 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
2dc80 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
2dc90 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  ) or sqlite3_bin
2dca0 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 6f 72  d_text16().** or
2dcb0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
2dcc0 6f 62 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70  ob() is a NULL p
2dcd0 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20  ointer then the 
2dce0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
2dcf0 0a 2a 2a 20 69 73 20 69 67 6e 6f 72 65 64 20 61  .** is ignored a
2dd00 6e 64 20 74 68 65 20 65 6e 64 20 72 65 73 75 6c  nd the end resul
2dd10 74 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73  t is the same as
2dd20 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75   sqlite3_bind_nu
2dd30 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e  ll()..**.** ^(In
2dd40 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20   those routines 
2dd50 74 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72  that have a four
2dd60 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73  th argument, its
2dd70 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a   value is the.**
2dd80 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2dd90 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65   in the paramete
2dda0 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a  r.  To be clear:
2ddb0 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68   the value is th
2ddc0 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c  e.** number of <
2ddd0 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74  u>bytes</u> in t
2dde0 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68  he value, not th
2ddf0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
2de00 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66  acters.)^.** ^If
2de10 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
2de20 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
2de30 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20  _bind_text() or 
2de40 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2de50 74 31 36 28 29 0a 2a 2a 20 69 73 20 6e 65 67 61  t16().** is nega
2de60 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 6c  tive, then the l
2de70 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74 72  ength of the str
2de80 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75  ing is.** the nu
2de90 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 75 70  mber of bytes up
2dea0 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65   to the first ze
2deb0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a  ro terminator..*
2dec0 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20  * If the fourth 
2ded0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
2dee0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29  ite3_bind_blob()
2def0 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
2df00 65 6e 0a 2a 2a 20 74 68 65 20 62 65 68 61 76 69  en.** the behavi
2df10 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
2df20 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 67  .** If a non-neg
2df30 61 74 69 76 65 20 66 6f 75 72 74 68 20 70 61 72  ative fourth par
2df40 61 6d 65 74 65 72 20 69 73 20 70 72 6f 76 69 64  ameter is provid
2df50 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  ed to sqlite3_bi
2df60 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72 20  nd_text().** or 
2df70 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2df80 74 31 36 28 29 20 6f 72 20 73 71 6c 69 74 65 33  t16() or sqlite3
2df90 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20 74  _bind_text64() t
2dfa0 68 65 6e 0a 2a 2a 20 74 68 61 74 20 70 61 72 61  hen.** that para
2dfb0 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 74 68  meter must be th
2dfc0 65 20 62 79 74 65 20 6f 66 66 73 65 74 0a 2a 2a  e byte offset.**
2dfd0 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74   where the NUL t
2dfe0 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 20  erminator would 
2dff0 6f 63 63 75 72 20 61 73 73 75 6d 69 6e 67 20 74  occur assuming t
2e000 68 65 20 73 74 72 69 6e 67 20 77 65 72 65 20 4e  he string were N
2e010 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65 64  UL.** terminated
2e020 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68  .  If any NUL ch
2e030 61 72 61 63 74 65 72 73 20 6f 63 63 75 72 20 61  aracters occur a
2e040 74 20 62 79 74 65 20 6f 66 66 73 65 74 73 20 6c  t byte offsets l
2e050 65 73 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68 65  ess than .** the
2e060 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66 6f   value of the fo
2e070 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
2e080 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e  hen the resultin
2e090 67 20 73 74 72 69 6e 67 20 76 61 6c 75 65 20 77  g string value w
2e0a0 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 65  ill.** contain e
2e0b0 6d 62 65 64 64 65 64 20 4e 55 4c 73 2e 20 20 54  mbedded NULs.  T
2e0c0 68 65 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70  he result of exp
2e0d0 72 65 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76 69  ressions involvi
2e0e0 6e 67 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77 69  ng strings.** wi
2e0f0 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73  th embedded NULs
2e100 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
2e110 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20  *.** ^The fifth 
2e120 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
2e130 42 4c 4f 42 20 61 6e 64 20 73 74 72 69 6e 67 20  BLOB and string 
2e140 62 69 6e 64 69 6e 67 20 69 6e 74 65 72 66 61 63  binding interfac
2e150 65 73 0a 2a 2a 20 69 73 20 61 20 64 65 73 74 72  es.** is a destr
2e160 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69  uctor used to di
2e170 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f  spose of the BLO
2e180 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61  B or.** string a
2e190 66 74 65 72 20 53 51 4c 69 74 65 20 68 61 73 20  fter SQLite has 
2e1a0 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74  finished with it
2e1b0 2e 20 20 5e 54 68 65 20 64 65 73 74 72 75 63 74  .  ^The destruct
2e1c0 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20  or is called.** 
2e1d0 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68  to dispose of th
2e1e0 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  e BLOB or string
2e1f0 20 65 76 65 6e 20 69 66 20 74 68 65 20 63 61 6c   even if the cal
2e200 6c 20 74 6f 20 62 69 6e 64 20 41 50 49 20 66 61  l to bind API fa
2e210 69 6c 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ils..** ^If the 
2e220 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69  fifth argument i
2e230 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c  s.** the special
2e240 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53   value [SQLITE_S
2e250 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c  TATIC], then SQL
2e260 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74  ite assumes that
2e270 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74   the.** informat
2e280 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63  ion is in static
2e290 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63  , unmanaged spac
2e2a0 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e  e and does not n
2e2b0 65 65 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e  eed to be freed.
2e2c0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74  .** ^If the fift
2e2d0 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74  h argument has t
2e2e0 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  he value [SQLITE
2e2f0 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65  _TRANSIENT], the
2e300 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65  n.** SQLite make
2e310 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74  s its own privat
2e320 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61  e copy of the da
2e330 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20  ta immediately, 
2e340 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71  before.** the sq
2e350 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
2e360 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a  outine returns..
2e370 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68  **.** ^The sixth
2e380 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
2e390 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34  ite3_bind_text64
2e3a0 28 29 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f  () must be one o
2e3b0 66 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  f.** [SQLITE_UTF
2e3c0 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  8], [SQLITE_UTF1
2e3d0 36 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  6], [SQLITE_UTF1
2e3e0 36 42 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  6BE], or [SQLITE
2e3f0 5f 55 54 46 31 36 4c 45 5d 0a 2a 2a 20 74 6f 20  _UTF16LE].** to 
2e400 73 70 65 63 69 66 79 20 74 68 65 20 65 6e 63 6f  specify the enco
2e410 64 69 6e 67 20 6f 66 20 74 68 65 20 74 65 78 74  ding of the text
2e420 20 69 6e 20 74 68 65 20 74 68 69 72 64 20 70 61   in the third pa
2e430 72 61 6d 65 74 65 72 2e 20 20 49 66 0a 2a 2a 20  rameter.  If.** 
2e440 74 68 65 20 73 69 78 74 68 20 61 72 67 75 6d 65  the sixth argume
2e450 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  nt to sqlite3_bi
2e460 6e 64 5f 74 65 78 74 36 34 28 29 20 69 73 20 6e  nd_text64() is n
2e470 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a  ot one of the.**
2e480 20 61 6c 6c 6f 77 65 64 20 76 61 6c 75 65 73 20   allowed values 
2e490 73 68 6f 77 6e 20 61 62 6f 76 65 2c 20 6f 72 20  shown above, or 
2e4a0 69 66 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f  if the text enco
2e4b0 64 69 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e  ding is differen
2e4c0 74 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 65 6e  t.** from the en
2e4d0 63 6f 64 69 6e 67 20 73 70 65 63 69 66 69 65 64  coding specified
2e4e0 20 62 79 20 74 68 65 20 73 69 78 74 68 20 70 61   by the sixth pa
2e4f0 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68  rameter, then th
2e500 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73  e behavior.** is
2e510 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
2e520 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62  * ^The sqlite3_b
2e530 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72  ind_zeroblob() r
2e540 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42  outine binds a B
2e550 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20  LOB of length N 
2e560 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65  that.** is fille
2e570 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20  d with zeroes.  
2e580 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73  ^A zeroblob uses
2e590 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20   a fixed amount 
2e5a0 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75  of memory.** (ju
2e5b0 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f  st an integer to
2e5c0 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20   hold its size) 
2e5d0 77 68 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e  while it is bein
2e5e0 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20  g processed..** 
2e5f0 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e  Zeroblobs are in
2e600 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20  tended to serve 
2e610 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20  as placeholders 
2e620 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a  for BLOBs whose.
2e630 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61  ** content is la
2e640 74 65 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e  ter written usin
2e650 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c  g.** [sqlite3_bl
2e660 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d  ob_open | increm
2e670 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20  ental BLOB I/O] 
2e680 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20  routines..** ^A 
2e690 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65 20 66  negative value f
2e6a0 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20  or the zeroblob 
2e6b0 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72  results in a zer
2e6c0 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a  o-length BLOB..*
2e6d0 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20  *.** ^If any of 
2e6e0 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
2e6f0 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72  _*() routines ar
2e700 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  e called with a 
2e710 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
2e720 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72 65  for the [prepare
2e730 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20  d statement] or 
2e740 77 69 74 68 20 61 20 70 72 65 70 61 72 65 64 20  with a prepared 
2e750 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20 77 68  statement for wh
2e760 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ich.** [sqlite3_
2e770 73 74 65 70 28 29 5d 20 68 61 73 20 62 65 65 6e  step()] has been
2e780 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63   called more rec
2e790 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69  ently than [sqli
2e7a0 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a  te3_reset()],.**
2e7b0 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 20 77   then the call w
2e7c0 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
2e7d0 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66 20  TE_MISUSE].  If 
2e7e0 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  any sqlite3_bind
2e7f0 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69  _().** routine i
2e800 73 20 70 61 73 73 65 64 20 61 20 5b 70 72 65 70  s passed a [prep
2e810 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2e820 74 68 61 74 20 68 61 73 20 62 65 65 6e 20 66 69  that has been fi
2e830 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20  nalized, the.** 
2e840 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69  result is undefi
2e850 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79  ned and probably
2e860 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20   harmful..**.** 
2e870 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f  ^Bindings are no
2e880 74 20 63 6c 65 61 72 65 64 20 62 79 20 74 68 65  t cleared by the
2e890 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2e8a0 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e  )] routine..** ^
2e8b0 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65  Unbound paramete
2e8c0 72 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  rs are interpret
2e8d0 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ed as NULL..**.*
2e8e0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62  * ^The sqlite3_b
2e8f0 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72  ind_* routines r
2e900 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
2e910 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20  ] on success or 
2e920 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64  an.** [error cod
2e930 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67 20 67  e] if anything g
2e940 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b  oes wrong..** ^[
2e950 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 5d 20 6d  SQLITE_TOOBIG] m
2e960 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64  ight be returned
2e970 20 69 66 20 74 68 65 20 73 69 7a 65 20 6f 66 20   if the size of 
2e980 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  a string or BLOB
2e990 0a 2a 2a 20 65 78 63 65 65 64 73 20 6c 69 6d 69  .** exceeds limi
2e9a0 74 73 20 69 6d 70 6f 73 65 64 20 62 79 20 5b 73  ts imposed by [s
2e9b0 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53  qlite3_limit]([S
2e9c0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
2e9d0 54 48 5d 29 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  TH]) or.** [SQLI
2e9e0 54 45 5f 4d 41 58 5f 4c 45 4e 47 54 48 5d 2e 0a  TE_MAX_LENGTH]..
2e9f0 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47  ** ^[SQLITE_RANG
2ea00 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  E] is returned i
2ea10 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a  f the parameter.
2ea20 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20  ** index is out 
2ea30 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c  of range.  ^[SQL
2ea40 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65  ITE_NOMEM] is re
2ea50 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63  turned if malloc
2ea60 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20  () fails..**.** 
2ea70 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
2ea80 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2ea90 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b  r_count()],.** [
2eaa0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2eab0 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20  ameter_name()], 
2eac0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  and [sqlite3_bin
2ead0 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
2eae0 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  x()]..*/.int sql
2eaf0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73  ite3_bind_blob(s
2eb00 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2eb10 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  t, const void*, 
2eb20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76  int n, void(*)(v
2eb30 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69  oid*));.int sqli
2eb40 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 36 34 28  te3_bind_blob64(
2eb50 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2eb60 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  nt, const void*,
2eb70 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c   sqlite3_uint64,
2eb80 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
2eb90 20 20 20 20 20 20 20 20 20 76 6f 69 64 28 2a 29           void(*)
2eba0 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
2ebb0 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c  lite3_bind_doubl
2ebc0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2ebd0 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69   int, double);.i
2ebe0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2ebf0 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  int(sqlite3_stmt
2ec00 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e  *, int, int);.in
2ec10 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69  t sqlite3_bind_i
2ec20 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  nt64(sqlite3_stm
2ec30 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33  t*, int, sqlite3
2ec40 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c  _int64);.int sql
2ec50 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73  ite3_bind_null(s
2ec60 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2ec70 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  t);.int sqlite3_
2ec80 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65  bind_text(sqlite
2ec90 33 5f 73 74 6d 74 2a 2c 69 6e 74 2c 63 6f 6e 73  3_stmt*,int,cons
2eca0 74 20 63 68 61 72 2a 2c 69 6e 74 2c 76 6f 69 64  t char*,int,void
2ecb0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
2ecc0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2ecd0 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  xt16(sqlite3_stm
2ece0 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76  t*, int, const v
2ecf0 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  oid*, int, void(
2ed00 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20  *)(void*));.int 
2ed10 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2ed20 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t64(sqlite3_stmt
2ed30 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68  *, int, const ch
2ed40 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e  ar*, sqlite3_uin
2ed50 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20  t64,.           
2ed60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f                vo
2ed70 69 64 28 2a 29 28 76 6f 69 64 2a 29 2c 20 75 6e  id(*)(void*), un
2ed80 73 69 67 6e 65 64 20 63 68 61 72 20 65 6e 63 6f  signed char enco
2ed90 64 69 6e 67 29 3b 0a 69 6e 74 20 73 71 6c 69 74  ding);.int sqlit
2eda0 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71  e3_bind_value(sq
2edb0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2edc0 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f  , const sqlite3_
2edd0 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
2ede0 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c  ite3_bind_zerobl
2edf0 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
2ee00 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 69  , int, int n);.i
2ee10 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2ee20 7a 65 72 6f 62 6c 6f 62 36 34 28 73 71 6c 69 74  zeroblob64(sqlit
2ee30 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73  e3_stmt*, int, s
2ee40 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a  qlite3_uint64);.
2ee50 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2ee60 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50   Number Of SQL P
2ee70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 4d 45 54  arameters.** MET
2ee80 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
2ee90 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  t.**.** ^This ro
2eea0 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65  utine can be use
2eeb0 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75  d to find the nu
2eec0 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72  mber of [SQL par
2eed0 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61  ameters].** in a
2eee0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2eef0 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61  ment].  SQL para
2ef00 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e  meters are token
2ef10 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d  s of the.** form
2ef20 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a   "?", "?NNN", ":
2ef30 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72  AAA", "$AAA", or
2ef40 20 22 40 41 41 41 22 20 74 68 61 74 20 73 65 72   "@AAA" that ser
2ef50 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f  ve as.** placeho
2ef60 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73  lders for values
2ef70 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74   that are [sqlit
2ef80 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62  e3_bind_blob | b
2ef90 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20  ound].** to the 
2efa0 70 61 72 61 6d 65 74 65 72 73 20 61 74 20 61 20  parameters at a 
2efb0 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a  later time..**.*
2efc0 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65  * ^(This routine
2efd0 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e   actually return
2efe0 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
2eff0 68 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 68  he largest (righ
2f000 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65  tmost).** parame
2f010 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72  ter. For all for
2f020 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20  ms except ?NNN, 
2f030 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73  this will corres
2f040 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e  pond to the.** n
2f050 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20  umber of unique 
2f060 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20  parameters.  If 
2f070 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  parameters of th
2f080 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20  e ?NNN form are 
2f090 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d  used,.** there m
2f0a0 61 79 20 62 65 20 67 61 70 73 20 69 6e 20 74 68  ay be gaps in th
2f0b0 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  e list.)^.**.** 
2f0c0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
2f0d0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
2f0e0 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a  ite3_bind()],.**
2f0f0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2f100 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d  arameter_name()]
2f110 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
2f120 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2f130 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e  _index()]..*/.in
2f140 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  t sqlite3_bind_p
2f150 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73  arameter_count(s
2f160 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
2f170 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2f180 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50  Name Of A Host P
2f190 61 72 61 6d 65 74 65 72 0a 2a 2a 20 4d 45 54 48  arameter.** METH
2f1a0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2f1b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2f1c0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2f1d0 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74  er_name(P,N) int
2f1e0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a  erface returns.*
2f1f0 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  * the name of th
2f200 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72 61  e N-th [SQL para
2f210 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 5b 70  meter] in the [p
2f220 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2f230 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70  t] P..** ^(SQL p
2f240 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
2f250 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20   form "?NNN" or 
2f260 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22  ":AAA" or "@AAA"
2f270 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61   or "$AAA".** ha
2f280 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20  ve a name which 
2f290 69 73 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f  is the string "?
2f2a0 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f  NNN" or ":AAA" o
2f2b0 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41  r "@AAA" or "$AA
2f2c0 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65  A".** respective
2f2d0 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20  ly..** In other 
2f2e0 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69  words, the initi
2f2f0 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72  al ":" or "$" or
2f300 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69   "@" or "?".** i
2f310 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61  s included as pa
2f320 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29  rt of the name.)
2f330 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72 73  ^.** ^Parameters
2f340 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22   of the form "?"
2f350 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f   without a follo
2f360 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76  wing integer hav
2f370 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64  e no name.** and
2f380 20 61 72 65 20 72 65 66 65 72 72 65 64 20 74 6f   are referred to
2f390 20 61 73 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f   as "nameless" o
2f3a0 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72  r "anonymous par
2f3b0 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20  ameters"..**.** 
2f3c0 5e 54 68 65 20 66 69 72 73 74 20 68 6f 73 74 20  ^The first host 
2f3d0 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e  parameter has an
2f3e0 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74   index of 1, not
2f3f0 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68   0..**.** ^If th
2f400 65 20 76 61 6c 75 65 20 4e 20 69 73 20 6f 75 74  e value N is out
2f410 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20   of range or if 
2f420 74 68 65 20 4e 2d 74 68 20 70 61 72 61 6d 65 74  the N-th paramet
2f430 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73  er is.** nameles
2f440 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20  s, then NULL is 
2f450 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 65 20  returned.  ^The 
2f460 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
2f470 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20  is.** always in 
2f480 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65  UTF-8 encoding e
2f490 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64  ven if the named
2f4a0 20 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a   parameter was.*
2f4b0 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65  * originally spe
2f4c0 63 69 66 69 65 64 20 61 73 20 55 54 46 2d 31 36  cified as UTF-16
2f4d0 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   in [sqlite3_pre
2f4e0 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20  pare16()] or.** 
2f4f0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2f500 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  16_v2()]..**.** 
2f510 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
2f520 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
2f530 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a  ite3_bind()],.**
2f540 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2f550 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29  arameter_count()
2f560 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
2f570 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2f580 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63  r_index()]..*/.c
2f590 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
2f5a0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2f5b0 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  r_name(sqlite3_s
2f5c0 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a  tmt*, int);../*.
2f5d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64  ** CAPI3REF: Ind
2f5e0 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65  ex Of A Paramete
2f5f0 72 20 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e  r With A Given N
2f600 61 6d 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ame.** METHOD: s
2f610 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
2f620 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 69 6e  * ^Return the in
2f630 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61  dex of an SQL pa
2f640 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74  rameter given it
2f650 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a  s name.  ^The.**
2f660 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74   index value ret
2f670 75 72 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c  urned is suitabl
2f680 65 20 66 6f 72 20 75 73 65 20 61 73 20 74 68 65  e for use as the
2f690 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d   second.** param
2f6a0 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
2f6b0 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
2f6c0 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20  e3_bind()].  ^A 
2f6d0 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72  zero.** is retur
2f6e0 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69  ned if no matchi
2f6f0 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ng parameter is 
2f700 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 72  found.  ^The par
2f710 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d  ameter.** name m
2f720 75 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20  ust be given in 
2f730 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68  UTF-8 even if th
2f740 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65  e original state
2f750 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70  ment.** was prep
2f760 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36  ared from UTF-16
2f770 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c   text using [sql
2f780 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
2f790 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  2()]..**.** See 
2f7a0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
2f7b0 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
2f7c0 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _bind()],.** [sq
2f7d0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2f7e0 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61  eter_count()], a
2f7f0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
2f800 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
2f810 6d 65 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  me()]..*/.int sq
2f820 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2f830 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74  eter_index(sqlit
2f840 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20  e3_stmt*, const 
2f850 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f  char *zName);../
2f860 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
2f870 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67  eset All Binding
2f880 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20  s On A Prepared 
2f890 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54  Statement.** MET
2f8a0 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
2f8b0 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72  t.**.** ^Contrar
2f8c0 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69  y to the intuiti
2f8d0 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c  on of many, [sql
2f8e0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f  ite3_reset()] do
2f8f0 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20  es not reset.** 
2f900 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  the [sqlite3_bin
2f910 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67  d_blob | binding
2f920 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65  s] on a [prepare
2f930 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
2f940 20 5e 55 73 65 20 74 68 69 73 20 72 6f 75 74 69   ^Use this routi
2f950 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20  ne to reset all 
2f960 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20  host parameters 
2f970 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20  to NULL..*/.int 
2f980 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69  sqlite3_clear_bi
2f990 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73  ndings(sqlite3_s
2f9a0 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
2f9b0 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f  PI3REF: Number O
2f9c0 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52  f Columns In A R
2f9d0 65 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 54  esult Set.** MET
2f9e0 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
2f9f0 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20  t.**.** ^Return 
2fa00 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
2fa10 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
2fa20 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65 64  ult set returned
2fa30 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   by the.** [prep
2fa40 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
2fa50 20 5e 49 66 20 74 68 69 73 20 72 6f 75 74 69 6e   ^If this routin
2fa60 65 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 61  e returns 0, tha
2fa70 74 20 6d 65 61 6e 73 20 74 68 65 20 0a 2a 2a 20  t means the .** 
2fa80 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2fa90 65 6e 74 5d 20 72 65 74 75 72 6e 73 20 6e 6f 20  ent] returns no 
2faa0 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c  data (for exampl
2fab0 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a  e an [UPDATE])..
2fac0 2a 2a 20 5e 48 6f 77 65 76 65 72 2c 20 6a 75 73  ** ^However, jus
2fad0 74 20 62 65 63 61 75 73 65 20 74 68 69 73 20 72  t because this r
2fae0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
2faf0 20 70 6f 73 69 74 69 76 65 20 6e 75 6d 62 65 72   positive number
2fb00 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 6d 65 61   does not.** mea
2fb10 6e 20 74 68 61 74 20 6f 6e 65 20 6f 72 20 6d 6f  n that one or mo
2fb20 72 65 20 72 6f 77 73 20 6f 66 20 64 61 74 61 20  re rows of data 
2fb30 77 69 6c 6c 20 62 65 20 72 65 74 75 72 6e 65 64  will be returned
2fb40 2e 20 20 5e 41 20 53 45 4c 45 43 54 20 73 74 61  .  ^A SELECT sta
2fb50 74 65 6d 65 6e 74 0a 2a 2a 20 77 69 6c 6c 20 61  tement.** will a
2fb60 6c 77 61 79 73 20 68 61 76 65 20 61 20 70 6f 73  lways have a pos
2fb70 69 74 69 76 65 20 73 71 6c 69 74 65 33 5f 63 6f  itive sqlite3_co
2fb80 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 20 62 75 74  lumn_count() but
2fb90 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
2fba0 65 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73  e.** WHERE claus
2fbb0 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 61 6e  e constraints an
2fbc0 64 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6e 74  d the table cont
2fbd0 65 6e 74 2c 20 69 74 20 6d 69 67 68 74 20 72 65  ent, it might re
2fbe0 74 75 72 6e 20 6e 6f 20 72 6f 77 73 2e 0a 2a 2a  turn no rows..**
2fbf0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
2fc00 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
2fc10 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  t()].*/.int sqli
2fc20 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
2fc30 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
2fc40 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
2fc50 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e  PI3REF: Column N
2fc60 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74  ames In A Result
2fc70 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20   Set.** METHOD: 
2fc80 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2fc90 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
2fca0 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61  es return the na
2fcb0 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61  me assigned to a
2fcc0 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75   particular colu
2fcd0 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73  mn.** in the res
2fce0 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45  ult set of a [SE
2fcf0 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e  LECT] statement.
2fd00 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63    ^The sqlite3_c
2fd10 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20  olumn_name().** 
2fd20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2fd30 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
2fd40 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
2fd50 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a   UTF-8 string.**
2fd60 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
2fd70 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74  umn_name16() ret
2fd80 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
2fd90 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  o a zero-termina
2fda0 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74  ted.** UTF-16 st
2fdb0 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73  ring.  ^The firs
2fdc0 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  t parameter is t
2fdd0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2fde0 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20  tement].** that 
2fdf0 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b  implements the [
2fe00 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
2fe10 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  t. ^The second p
2fe20 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a  arameter is the.
2fe30 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72  ** column number
2fe40 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74  .  ^The leftmost
2fe50 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65   column is numbe
2fe60 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  r 0..**.** ^The 
2fe70 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
2fe80 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64  pointer is valid
2fe90 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68   until either th
2fea0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2feb0 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73  ement].** is des
2fec0 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74  troyed by [sqlit
2fed0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
2fee0 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74  r until the stat
2fef0 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74  ement is automat
2ff00 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70  ically.** reprep
2ff10 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73  ared by the firs
2ff20 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
2ff30 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61  e3_step()] for a
2ff40 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a   particular run.
2ff50 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  ** or until the 
2ff60 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  next call to.** 
2ff70 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
2ff80 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ame() or sqlite3
2ff90 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29  _column_name16()
2ffa0 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c   on the same col
2ffb0 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73  umn..**.** ^If s
2ffc0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
2ffd0 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65  fails during the
2ffe0 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65   processing of e
2fff0 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a  ither routine.**
30000 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75   (for example du
30010 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f  ring a conversio
30020 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20  n from UTF-8 to 
30030 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a  UTF-16) then a.*
30040 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  * NULL pointer i
30050 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
30060 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61  * ^The name of a
30070 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69   result column i
30080 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
30090 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 66  he "AS" clause f
300a0 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d  or.** that colum
300b0 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 61  n, if there is a
300c0 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66  n AS clause.  If
300d0 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20   there is no AS 
300e0 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74  clause.** then t
300f0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63  he name of the c
30100 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69  olumn is unspeci
30110 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61  fied and may cha
30120 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20  nge from.** one 
30130 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
30140 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a  e to the next..*
30150 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
30160 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
30170 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
30180 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76   int N);.const v
30190 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
301a0 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  umn_name16(sqlit
301b0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29  e3_stmt*, int N)
301c0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
301d0 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74  F: Source Of Dat
301e0 61 20 49 6e 20 41 20 51 75 65 72 79 20 52 65 73  a In A Query Res
301f0 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ult.** METHOD: s
30200 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
30210 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
30220 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e  s provide a mean
30230 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74  s to determine t
30240 68 65 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  he database, tab
30250 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65  le, and.** table
30260 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20   column that is 
30270 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 61 20  the origin of a 
30280 70 61 72 74 69 63 75 6c 61 72 20 72 65 73 75 6c  particular resul
30290 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b  t column in.** [
302a0 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
302b0 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20  t..** ^The name 
302c0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
302d0 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75  or table or colu
302e0 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e  mn can be return
302f0 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20  ed as.** either 
30300 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  a UTF-8 or UTF-1
30310 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20  6 string.  ^The 
30320 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69  _database_ routi
30330 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68  nes return.** th
30340 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c  e database name,
30350 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75   the _table_ rou
30360 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
30370 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64   table name, and
30380 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20  .** the origin_ 
30390 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
303a0 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e  the column name.
303b0 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65  .** ^The returne
303c0 64 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69  d string is vali
303d0 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65  d until the [pre
303e0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
303f0 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a   is destroyed.**
30400 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
30410 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75  finalize()] or u
30420 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65  ntil the stateme
30430 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61  nt is automatica
30440 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65  lly.** reprepare
30450 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63  d by the first c
30460 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
30470 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61  step()] for a pa
30480 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20  rticular run.** 
30490 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d  or until the sam
304a0 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  e information is
304b0 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67   requested.** ag
304c0 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65  ain in a differe
304d0 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a  nt encoding..**.
304e0 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 65  ** ^The names re
304f0 74 75 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f  turned are the o
30500 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73  riginal un-alias
30510 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a  ed names of the.
30520 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  ** database, tab
30530 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a  le, and column..
30540 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
30550 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
30560 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 69 73  se interfaces is
30570 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
30580 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65  tement]..** ^The
30590 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74  se functions ret
305a0 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  urn information 
305b0 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72 65  about the Nth re
305c0 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75  sult column retu
305d0 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73  rned by.** the s
305e0 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20  tatement, where 
305f0 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20  N is the second 
30600 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e  function argumen
30610 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d  t..** ^The left-
30620 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63  most column is c
30630 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 73  olumn 0 for thes
30640 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  e routines..**.*
30650 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f  * ^If the Nth co
30660 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79  lumn returned by
30670 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
30680 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20  s an expression 
30690 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61  or.** subquery a
306a0 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75  nd is not a colu
306b0 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61  mn value, then a
306c0 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63  ll of these func
306d0 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20  tions return.** 
306e0 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f  NULL.  ^These ro
306f0 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f  utine might also
30700 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20   return NULL if 
30710 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
30720 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63  ion error.** occ
30730 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 65  urs.  ^Otherwise
30740 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 68  , they return th
30750 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74  e name of the at
30760 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 2c  tached database,
30770 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f   table,.** or co
30780 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20  lumn that query 
30790 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61  result column wa
307a0 73 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d  s extracted from
307b0 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68  ..**.** ^As with
307c0 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74   all other SQLit
307d0 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 77 68  e APIs, those wh
307e0 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 69  ose names end wi
307f0 74 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a  th "16" return.*
30800 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  * UTF-16 encoded
30810 20 73 74 72 69 6e 67 73 20 61 6e 64 20 74 68 65   strings and the
30820 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73   other functions
30830 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a   return UTF-8..*
30840 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 73  *.** ^These APIs
30850 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61   are only availa
30860 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61  ble if the libra
30870 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  ry was compiled 
30880 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  with the.** [SQL
30890 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d  ITE_ENABLE_COLUM
308a0 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72  N_METADATA] C-pr
308b0 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f  eprocessor symbo
308c0 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20  l..**.** If two 
308d0 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  or more threads 
308e0 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  call one or more
308f0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
30900 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 73  es against the s
30910 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20  ame.** prepared 
30920 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f  statement and co
30930 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65  lumn at the same
30940 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72   time then the r
30950 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e  esults are.** un
30960 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  defined..**.** I
30970 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68  f two or more th
30980 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f  reads call one o
30990 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74  r more.** [sqlit
309a0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
309b0 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e  se_name | column
309c0 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 66   metadata interf
309d0 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65  aces].** for the
309e0 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20   same [prepared 
309f0 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72  statement] and r
30a00 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  esult column.** 
30a10 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
30a20 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
30a30 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
30a40 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
30a50 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
30a60 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c  atabase_name(sql
30a70 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
30a80 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
30a90 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
30aa0 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69  base_name16(sqli
30ab0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
30ac0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
30ad0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65  te3_column_table
30ae0 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
30af0 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
30b00 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
30b10 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31  lumn_table_name1
30b20 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
30b30 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  int);.const char
30b40 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
30b50 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c  _origin_name(sql
30b60 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
30b70 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
30b80 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67  ite3_column_orig
30b90 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  in_name16(sqlite
30ba0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f  3_stmt*,int);../
30bb0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
30bc0 65 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65  eclared Datatype
30bd0 20 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75   Of A Query Resu
30be0 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  lt.** METHOD: sq
30bf0 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
30c00 20 5e 28 54 68 65 20 66 69 72 73 74 20 70 61 72   ^(The first par
30c10 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72 65  ameter is a [pre
30c20 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
30c30 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61  ..** If this sta
30c40 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c  tement is a [SEL
30c50 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61  ECT] statement a
30c60 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  nd the Nth colum
30c70 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75  n of the.** retu
30c80 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 20  rned result set 
30c90 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d  of that [SELECT]
30ca0 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75   is a table colu
30cb0 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78  mn (not an.** ex
30cc0 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71  pression or subq
30cd0 75 65 72 79 29 20 74 68 65 6e 20 74 68 65 20 64  uery) then the d
30ce0 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20  eclared type of 
30cf0 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c  the table.** col
30d00 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e  umn is returned.
30d10 29 5e 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20  )^  ^If the Nth 
30d20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65  column of the re
30d30 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a  sult set is an.*
30d40 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20  * expression or 
30d50 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61  subquery, then a
30d60 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
30d70 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54   returned..** ^T
30d80 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
30d90 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55 54 46  ng is always UTF
30da0 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a  -8 encoded..**.*
30db0 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c  * ^(For example,
30dc0 20 67 69 76 65 6e 20 74 68 65 20 64 61 74 61 62   given the datab
30dd0 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a  ase schema:.**.*
30de0 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 74  * CREATE TABLE t
30df0 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a  1(c1 VARIANT);.*
30e00 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c  *.** and the fol
30e10 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  lowing statement
30e20 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a   to be compiled:
30e30 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31  .**.** SELECT c1
30e40 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31   + 1, c1 FROM t1
30e50 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75  ;.**.** this rou
30e60 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72  tine would retur
30e70 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 41  n the string "VA
30e80 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73  RIANT" for the s
30e90 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20  econd result.** 
30ea0 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61  column (i==1), a
30eb0 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  nd a NULL pointe
30ec0 72 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  r for the first 
30ed0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69  result column (i
30ee0 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53  ==0).)^.**.** ^S
30ef0 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d  QLite uses dynam
30f00 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69  ic run-time typi
30f10 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65  ng.  ^So just be
30f20 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a  cause a column.*
30f30 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f  * is declared to
30f40 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69   contain a parti
30f50 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20  cular type does 
30f60 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68  not mean that th
30f70 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64  e.** data stored
30f80 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20   in that column 
30f90 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72  is of the declar
30fa0 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65  ed type.  SQLite
30fb0 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20   is.** strongly 
30fc0 74 79 70 65 64 2c 20 62 75 74 20 74 68 65 20 74  typed, but the t
30fd0 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63  yping is dynamic
30fe0 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54   not static.  ^T
30ff0 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69  ype.** is associ
31000 61 74 65 64 20 77 69 74 68 20 69 6e 64 69 76 69  ated with indivi
31010 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74  dual values, not
31020 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69   with the contai
31030 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20  ners.** used to 
31040 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65  hold those value
31050 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  s..*/.const char
31060 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
31070 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65  _decltype(sqlite
31080 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
31090 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
310a0 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70  3_column_decltyp
310b0 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
310c0 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  *,int);../*.** C
310d0 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74  API3REF: Evaluat
310e0 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  e An SQL Stateme
310f0 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  nt.** METHOD: sq
31100 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
31110 20 41 66 74 65 72 20 61 20 5b 70 72 65 70 61 72   After a [prepar
31120 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61  ed statement] ha
31130 73 20 62 65 65 6e 20 70 72 65 70 61 72 65 64 20  s been prepared 
31140 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20  using either.** 
31150 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
31160 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v2()] or [sqlit
31170 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
31180 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65  )] or one of the
31190 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
311a0 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70  faces [sqlite3_p
311b0 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71  repare()] or [sq
311c0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
311d0 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f  )], this functio
311e0 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 6c  n.** must be cal
311f0 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  led one or more 
31200 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74  times to evaluat
31210 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e  e the statement.
31220 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69  .**.** The detai
31230 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61 76 69  ls of the behavi
31240 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  or of the sqlite
31250 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66 61  3_step() interfa
31260 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20  ce depend.** on 
31270 77 68 65 74 68 65 72 20 74 68 65 20 73 74 61 74  whether the stat
31280 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61 72  ement was prepar
31290 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77  ed using the new
312a0 65 72 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  er "v2" interfac
312b0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  e.** [sqlite3_pr
312c0 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
312d0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
312e0 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20  16_v2()] or the 
312f0 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20  older legacy.** 
31300 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74  interface [sqlit
31310 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e  e3_prepare()] an
31320 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
31330 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73  re16()].  The us
31340 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20  e of the.** new 
31350 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69  "v2" interface i
31360 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  s recommended fo
31370 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f  r new applicatio
31380 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67 61 63  ns but the legac
31390 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77  y.** interface w
313a0 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20  ill continue to 
313b0 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a  be supported..**
313c0 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67 61  .** ^In the lega
313d0 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  cy interface, th
313e0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77  e return value w
313f0 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b 53  ill be either [S
31400 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20  QLITE_BUSY],.** 
31410 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b  [SQLITE_DONE], [
31420 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51  SQLITE_ROW], [SQ
31430 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20  LITE_ERROR], or 
31440 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
31450 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 22 76  .** ^With the "v
31460 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e  2" interface, an
31470 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b  y of the other [
31480 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72  result codes] or
31490 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
314a0 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67 68  sult codes] migh
314b0 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73  t be returned as
314c0 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53   well..**.** ^[S
314d0 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e  QLITE_BUSY] mean
314e0 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62  s that the datab
314f0 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75  ase engine was u
31500 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65  nable to acquire
31510 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
31520 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20   locks it needs 
31530 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20  to do its job.  
31540 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e  ^If the statemen
31550 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a  t is a [COMMIT].
31560 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 74  ** or occurs out
31570 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c 69  side of an expli
31580 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c  cit transaction,
31590 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 65   then you can re
315a0 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 65  try the.** state
315b0 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73 74  ment.  If the st
315c0 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61  atement is not a
315d0 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63   [COMMIT] and oc
315e0 63 75 72 73 20 77 69 74 68 69 6e 20 61 6e 0a 2a  curs within an.*
315f0 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  * explicit trans
31600 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20  action then you 
31610 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20  should rollback 
31620 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  the transaction 
31630 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e  before.** contin
31640 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51  uing..**.** ^[SQ
31650 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73  LITE_DONE] means
31660 20 74 68 61 74 20 74 68 65 20 73 74 61 74 65 6d   that the statem
31670 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65 64  ent has finished
31680 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75   executing.** su
31690 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c  ccessfully.  sql
316a0 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75  ite3_step() shou
316b0 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64  ld not be called
316c0 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76   again on this v
316d0 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e  irtual.** machin
316e0 65 20 77 69 74 68 6f 75 74 20 66 69 72 73 74 20  e without first 
316f0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
31700 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73  _reset()] to res
31710 65 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a  et the virtual.*
31720 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74  * machine back t
31730 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74  o its initial st
31740 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ate..**.** ^If t
31750 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
31760 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 20   being executed 
31770 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61  returns any data
31780 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52  , then [SQLITE_R
31790 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  OW].** is return
317a0 65 64 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e  ed each time a n
317b0 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69  ew row of data i
317c0 73 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f 63  s ready for proc
317d0 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a  essing by the.**
317e0 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c   caller. The val
317f0 75 65 73 20 6d 61 79 20 62 65 20 61 63 63 65 73  ues may be acces
31800 73 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 63  sed using the [c
31810 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
31820 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69  ctions]..** sqli
31830 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 63 61  te3_step() is ca
31840 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65  lled again to re
31850 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 74 20  trieve the next 
31860 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a  row of data..**.
31870 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ** ^[SQLITE_ERRO
31880 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20  R] means that a 
31890 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28  run-time error (
318a0 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72  such as a constr
318b0 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f  aint.** violatio
318c0 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e  n) has occurred.
318d0 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29    sqlite3_step()
318e0 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63   should not be c
318f0 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a  alled again on.*
31900 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69  * the VM. More i
31910 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62  nformation may b
31920 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69  e found by calli
31930 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ng [sqlite3_errm
31940 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20  sg()]..** ^With 
31950 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
31960 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65  face, a more spe
31970 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65  cific error code
31980 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a   (for example,.*
31990 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  * [SQLITE_INTERR
319a0 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43  UPT], [SQLITE_SC
319b0 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43  HEMA], [SQLITE_C
319c0 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20  ORRUPT], and so 
319d0 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65  forth).** can be
319e0 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c   obtained by cal
319f0 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
31a00 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a  set()] on the.**
31a10 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
31a20 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20  ment].  ^In the 
31a30 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a  "v2" interface,.
31a40 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63  ** the more spec
31a50 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20  ific error code 
31a60 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 72 65  is returned dire
31a70 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f  ctly by sqlite3_
31a80 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53  step()..**.** [S
31a90 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65  QLITE_MISUSE] me
31aa0 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 68 69  ans that the thi
31ab0 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61  s routine was ca
31ac0 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61  lled inappropria
31ad0 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73  tely..** Perhaps
31ae0 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f   it was called o
31af0 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
31b00 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61  atement] that ha
31b10 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65  s.** already bee
31b20 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  n [sqlite3_final
31b30 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d  ize | finalized]
31b40 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20   or on one that 
31b50 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  had.** previousl
31b60 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  y returned [SQLI
31b70 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51  TE_ERROR] or [SQ
31b80 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20  LITE_DONE].  Or 
31b90 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74  it could.** be t
31ba0 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65  he case that the
31bb0 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
31bc0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69  onnection is bei
31bd0 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f  ng used by two o
31be0 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64  r.** more thread
31bf0 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f  s at the same mo
31c00 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a  ment in time..**
31c10 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65 72 73  .** For all vers
31c20 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 75  ions of SQLite u
31c30 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75 64 69  p to and includi
31c40 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61 20 63  ng 3.6.23.1, a c
31c50 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
31c60 65 33 5f 72 65 73 65 74 28 29 5d 20 77 61 73 20  e3_reset()] was 
31c70 72 65 71 75 69 72 65 64 20 61 66 74 65 72 20 73  required after s
31c80 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 72 65  qlite3_step() re
31c90 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e 67 0a  turned anything.
31ca0 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ** other than [S
31cb0 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66 6f 72  QLITE_ROW] befor
31cc0 65 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74  e any subsequent
31cd0 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a   invocation of.*
31ce0 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
31cf0 2e 20 20 46 61 69 6c 75 72 65 20 74 6f 20 72 65  .  Failure to re
31d00 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64  set the prepared
31d10 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
31d20 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65   .** [sqlite3_re
31d30 73 65 74 28 29 5d 20 77 6f 75 6c 64 20 72 65 73  set()] would res
31d40 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54  ult in an [SQLIT
31d50 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75 72 6e  E_MISUSE] return
31d60 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33   from.** sqlite3
31d70 5f 73 74 65 70 28 29 2e 20 20 42 75 74 20 61 66  _step().  But af
31d80 74 65 72 20 5b 76 65 72 73 69 6f 6e 20 33 2e 36  ter [version 3.6
31d90 2e 32 33 2e 31 5d 20 28 5b 64 61 74 65 6f 66 3a  .23.1] ([dateof:
31da0 33 2e 36 2e 32 33 2e 31 5d 2c 0a 2a 2a 20 73 71  3.6.23.1],.** sq
31db0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 62 65 67  lite3_step() beg
31dc0 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73  an.** calling [s
31dd0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
31de0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e  automatically in
31df0 20 74 68 69 73 20 63 69 72 63 75 6d 73 74 61 6e   this circumstan
31e00 63 65 20 72 61 74 68 65 72 0a 2a 2a 20 74 68 61  ce rather.** tha
31e10 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c  n returning [SQL
31e20 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68  ITE_MISUSE].  Th
31e30 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64  is is not consid
31e40 65 72 65 64 20 61 20 63 6f 6d 70 61 74 69 62 69  ered a compatibi
31e50 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65  lity.** break be
31e60 63 61 75 73 65 20 61 6e 79 20 61 70 70 6c 69 63  cause any applic
31e70 61 74 69 6f 6e 20 74 68 61 74 20 65 76 65 72 20  ation that ever 
31e80 72 65 63 65 69 76 65 73 20 61 6e 20 53 51 4c 49  receives an SQLI
31e90 54 45 5f 4d 49 53 55 53 45 20 65 72 72 6f 72 0a  TE_MISUSE error.
31ea0 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62 79 20  ** is broken by 
31eb0 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65  definition.  The
31ec0 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55   [SQLITE_OMIT_AU
31ed0 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65  TORESET] compile
31ee0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20  -time option.** 
31ef0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72  can be used to r
31f00 65 73 74 6f 72 65 20 74 68 65 20 6c 65 67 61 63  estore the legac
31f10 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a  y behavior..**.*
31f20 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72  * <b>Goofy Inter
31f30 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20  face Alert:</b> 
31f40 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  In the legacy in
31f50 74 65 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c  terface, the sql
31f60 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41  ite3_step().** A
31f70 50 49 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  PI always return
31f80 73 20 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f  s a generic erro
31f90 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f  r code, [SQLITE_
31fa0 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e  ERROR], followin
31fb0 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f  g any.** error o
31fc0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
31fd0 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c  E_BUSY] and [SQL
31fe0 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f  ITE_MISUSE].  Yo
31ff0 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b  u must call.** [
32000 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
32010 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
32020 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65  alize()] in orde
32030 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66  r to find one of
32040 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63   the.** specific
32050 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74   [error codes] t
32060 68 61 74 20 62 65 74 74 65 72 20 64 65 73 63 72  hat better descr
32070 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a  ibes the error..
32080 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61 74  ** We admit that
32090 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79   this is a goofy
320a0 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72   design.  The pr
320b0 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66  oblem has been f
320c0 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65  ixed.** with the
320d0 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e   "v2" interface.
320e0 20 20 49 66 20 79 6f 75 20 70 72 65 70 61 72 65    If you prepare
320f0 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c   all of your SQL
32100 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75   statements.** u
32110 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c  sing either [sql
32120 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
32130 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
32140 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69  repare16_v2()] i
32150 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65  nstead.** of the
32160 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33   legacy [sqlite3
32170 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20  _prepare()] and 
32180 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
32190 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  16()] interfaces
321a0 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f  ,.** then the mo
321b0 72 65 20 73 70 65 63 69 66 69 63 20 5b 65 72 72  re specific [err
321c0 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65  or codes] are re
321d0 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a  turned directly.
321e0 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74  ** by sqlite3_st
321f0 65 70 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f  ep().  The use o
32200 66 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  f the "v2" inter
32210 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e  face is recommen
32220 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ded..*/.int sqli
32230 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33  te3_step(sqlite3
32240 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
32250 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72  CAPI3REF: Number
32260 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
32270 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a 20 4d   result set.** M
32280 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
32290 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  tmt.**.** ^The s
322a0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
322b0 74 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 72  t(P) interface r
322c0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
322d0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
322e0 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72  the.** current r
322f0 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ow of the result
32300 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65   set of [prepare
32310 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a  d statement] P..
32320 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 65 64 20  ** ^If prepared 
32330 73 74 61 74 65 6d 65 6e 74 20 50 20 64 6f 65 73  statement P does
32340 20 6e 6f 74 20 68 61 76 65 20 72 65 73 75 6c 74   not have result
32350 73 20 72 65 61 64 79 20 74 6f 20 72 65 74 75 72  s ready to retur
32360 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73 20  n.** (via calls 
32370 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
32380 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c  column_int | sql
32390 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d  ite3_column_*()]
323a0 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65   of.** interface
323b0 73 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  s) then sqlite3_
323c0 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 65  data_count(P) re
323d0 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65  turns 0..** ^The
323e0 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
323f0 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 61  unt(P) routine a
32400 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 20 69 66  lso returns 0 if
32410 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   P is a NULL poi
32420 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  nter..** ^The sq
32430 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
32440 28 50 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  (P) routine retu
32450 72 6e 73 20 30 20 69 66 20 74 68 65 20 70 72 65  rns 0 if the pre
32460 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a  vious call to.**
32470 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28   [sqlite3_step](
32480 50 29 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c  P) returned [SQL
32490 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 65  ITE_DONE].  ^The
324a0 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
324b0 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 72  unt(P).** will r
324c0 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69  eturn non-zero i
324d0 66 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  f previous call 
324e0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
324f0 5d 28 50 29 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ](P) returned.**
32500 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 65   [SQLITE_ROW], e
32510 78 63 65 70 74 20 69 6e 20 74 68 65 20 63 61 73  xcept in the cas
32520 65 20 6f 66 20 74 68 65 20 5b 50 52 41 47 4d 41  e of the [PRAGMA
32530 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61 63   incremental_vac
32540 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69 74  uum].** where it
32550 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
32560 7a 65 72 6f 20 73 69 6e 63 65 20 65 61 63 68 20  zero since each 
32570 73 74 65 70 20 6f 66 20 74 68 61 74 20 6d 75 6c  step of that mul
32580 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67 6d  ti-step.** pragm
32590 61 20 72 65 74 75 72 6e 73 20 30 20 63 6f 6c 75  a returns 0 colu
325a0 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a  mns of data..**.
325b0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
325c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75  lite3_column_cou
325d0 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  nt()].*/.int sql
325e0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
325f0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
32600 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
32610 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74  I3REF: Fundament
32620 61 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 20  al Datatypes.** 
32630 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45  KEYWORDS: SQLITE
32640 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76  _TEXT.**.** ^(Ev
32650 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c  ery value in SQL
32660 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66  ite has one of f
32670 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20  ive fundamental 
32680 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a  datatypes:.**.**
32690 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34   <ul>.** <li> 64
326a0 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
326b0 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62  ger.** <li> 64-b
326c0 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67  it IEEE floating
326d0 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a   point number.**
326e0 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20   <li> string.** 
326f0 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69  <li> BLOB.** <li
32700 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29  > NULL.** </ul>)
32710 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  ^.**.** These co
32720 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65  nstants are code
32730 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68  s for each of th
32740 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a  ose types..**.**
32750 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 53   Note that the S
32760 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74  QLITE_TEXT const
32770 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65  ant was also use
32780 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73  d in SQLite vers
32790 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63  ion 2.** for a c
327a0 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72  ompletely differ
327b0 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f  ent meaning.  So
327c0 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b  ftware that link
327d0 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a  s against both.*
327e0 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  * SQLite version
327f0 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65   2 and SQLite ve
32800 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75  rsion 3 should u
32810 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c  se SQLITE3_TEXT,
32820 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54   not.** SQLITE_T
32830 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  EXT..*/.#define 
32840 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20  SQLITE_INTEGER  
32850 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
32860 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66  _FLOAT    2.#def
32870 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20  ine SQLITE_BLOB 
32880 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
32890 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a  LITE_NULL     5.
328a0 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45  #ifdef SQLITE_TE
328b0 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54  XT.# undef SQLIT
328c0 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64  E_TEXT.#else.# d
328d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58  efine SQLITE_TEX
328e0 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23  T     3.#endif.#
328f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54  define SQLITE3_T
32900 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a  EXT     3../*.**
32910 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c   CAPI3REF: Resul
32920 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20  t Values From A 
32930 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44  Query.** KEYWORD
32940 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73  S: {column acces
32950 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20  s functions}.** 
32960 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
32970 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  stmt.**.** ^Thes
32980 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
32990 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  n information ab
329a0 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c  out a single col
329b0 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65  umn of the curre
329c0 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77  nt.** result row
329d0 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49   of a query.  ^I
329e0 6e 20 65 76 65 72 79 20 63 61 73 65 20 74 68 65  n every case the
329f0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
32a00 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  is a pointer.** 
32a10 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  to the [prepared
32a20 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
32a30 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61   is being evalua
32a40 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65  ted (the [sqlite
32a50 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74  3_stmt*].** that
32a60 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 66 72   was returned fr
32a70 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  om [sqlite3_prep
32a80 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65  are_v2()] or one
32a90 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74 73   of its variants
32aa0 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63  ).** and the sec
32ab0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
32ac0 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  the index of the
32ad0 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63   column for whic
32ae0 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a  h information.**
32af0 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72   should be retur
32b00 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f  ned. ^The leftmo
32b10 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  st column of the
32b20 20 72 65 73 75 6c 74 20 73 65 74 20 68 61 73 20   result set has 
32b30 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20  the index 0..** 
32b40 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63  ^The number of c
32b50 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65  olumns in the re
32b60 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65  sult can be dete
32b70 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20  rmined using.** 
32b80 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
32b90 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  count()]..**.** 
32ba0 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  If the SQL state
32bb0 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75  ment does not cu
32bc0 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f  rrently point to
32bd0 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72   a valid row, or
32be0 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d   if the.** colum
32bf0 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f  n index is out o
32c00 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73  f range, the res
32c10 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ult is undefined
32c20 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  ..** These routi
32c30 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  nes may only be 
32c40 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20  called when the 
32c50 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
32c60 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
32c70 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75  step()] has retu
32c80 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57  rned [SQLITE_ROW
32c90 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a  ] and neither.**
32ca0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
32cb0 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f  )] nor [sqlite3_
32cc0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65  finalize()] have
32cd0 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62   been called sub
32ce0 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66  sequently..** If
32cf0 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f   any of these ro
32d00 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65  utines are calle
32d10 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33  d after [sqlite3
32d20 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20  _reset()] or.** 
32d30 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
32d40 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73  e()] or after [s
32d50 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68  qlite3_step()] h
32d60 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73  as returned.** s
32d70 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74  omething other t
32d80 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  han [SQLITE_ROW]
32d90 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  , the results ar
32da0 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  e undefined..** 
32db0 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  If [sqlite3_step
32dc0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
32dd0 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
32de0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
32df0 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66  .** are called f
32e00 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20  rom a different 
32e10 74 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79  thread while any
32e20 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
32e30 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e  es.** are pendin
32e40 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  g, then the resu
32e50 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
32e60 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
32e70 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
32e80 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  e() routine retu
32e90 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  rns the.** [SQLI
32ea0 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74  TE_INTEGER | dat
32eb0 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20  atype code] for 
32ec0 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61  the initial data
32ed0 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20   type.** of the 
32ee0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20  result column.  
32ef0 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 76 61  ^The returned va
32f00 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53  lue is one of [S
32f10 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a  QLITE_INTEGER],.
32f20 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54  ** [SQLITE_FLOAT
32f30 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d  ], [SQLITE_TEXT]
32f40 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c  , [SQLITE_BLOB],
32f50 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c   or [SQLITE_NULL
32f60 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a  ].  The value.**
32f70 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
32f80 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
32f90 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69  () is only meani
32fa0 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65  ngful if no type
32fb0 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20  .** conversions 
32fc0 68 61 76 65 20 6f 63 63 75 72 72 65 64 20 61 73  have occurred as
32fd0 20 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77   described below
32fe0 2e 20 20 41 66 74 65 72 20 61 20 74 79 70 65 20  .  After a type 
32ff0 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74  conversion,.** t
33000 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
33010 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
33020 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e  umn_type() is un
33030 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65  defined.  Future
33040 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  .** versions of 
33050 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67  SQLite may chang
33060 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  e the behavior o
33070 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  f sqlite3_column
33080 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f  _type().** follo
33090 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76  wing a type conv
330a0 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ersion..**.** ^I
330b0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
330c0 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20  a BLOB or UTF-8 
330d0 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20  string then the 
330e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
330f0 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  ytes().** routin
33100 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
33110 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
33120 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74   that BLOB or st
33130 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
33140 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46   result is a UTF
33150 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  -16 string, then
33160 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
33170 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73  bytes() converts
33180 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74  .** the string t
33190 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e  o UTF-8 and then
331a0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
331b0 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a  ber of bytes..**
331c0 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
331d0 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c  is a numeric val
331e0 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ue then sqlite3_
331f0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75  column_bytes() u
33200 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ses.** [sqlite3_
33210 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63  snprintf()] to c
33220 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75  onvert that valu
33230 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72  e to a UTF-8 str
33240 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a  ing and returns.
33250 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
33260 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73   bytes in that s
33270 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
33280 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c  e result is NULL
33290 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
332a0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 65  olumn_bytes() re
332b0 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a  turns zero..**.*
332c0 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
332d0 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54   is a BLOB or UT
332e0 46 2d 31 36 20 73 74 72 69 6e 67 20 74 68 65 6e  F-16 string then
332f0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   the sqlite3_col
33300 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a  umn_bytes16().**
33310 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
33320 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
33330 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f  ytes in that BLO
33340 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  B or string..** 
33350 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
33360 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67  s a UTF-8 string
33370 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
33380 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
33390 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20  converts.** the 
333a0 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 36  string to UTF-16
333b0 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e   and then return
333c0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
333d0 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68  bytes..** ^If th
333e0 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75  e result is a nu
333f0 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e  meric value then
33400 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
33410 62 79 74 65 73 31 36 28 29 20 75 73 65 73 0a 2a  bytes16() uses.*
33420 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  * [sqlite3_snpri
33430 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72  ntf()] to conver
33440 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20  t that value to 
33450 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  a UTF-16 string 
33460 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  and returns.** t
33470 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
33480 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e  es in that strin
33490 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
334a0 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68  sult is NULL, th
334b0 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
334c0 6e 5f 62 79 74 65 73 31 36 28 29 20 72 65 74 75  n_bytes16() retu
334d0 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20  rns zero..**.** 
334e0 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75  ^The values retu
334f0 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
33500 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d  _column_bytes()]
33510 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   and .** [sqlite
33520 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
33530 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75  ()] do not inclu
33540 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d  de the zero term
33550 69 6e 61 74 6f 72 73 20 61 74 20 74 68 65 20 65  inators at the e
33560 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72  nd.** of the str
33570 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69  ing.  ^For clari
33580 74 79 3a 20 74 68 65 20 76 61 6c 75 65 73 20 72  ty: the values r
33590 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
335a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
335b0 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  tes()] and [sqli
335c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
335d0 31 36 28 29 5d 20 61 72 65 20 74 68 65 20 6e 75  16()] are the nu
335e0 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73  mber of.** bytes
335f0 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20   in the string, 
33600 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  not the number o
33610 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  f characters..**
33620 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74  .** ^Strings ret
33630 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
33640 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61  _column_text() a
33650 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
33660 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65  n_text16(),.** e
33670 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67  ven empty string
33680 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65  s, are always ze
33690 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  ro-terminated.  
336a0 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76  ^The return.** v
336b0 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
336c0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
336d0 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74  for a zero-lengt
336e0 68 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c  h BLOB is a NULL
336f0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
33700 3c 62 3e 57 61 72 6e 69 6e 67 3a 3c 2f 62 3e 20  <b>Warning:</b> 
33710 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75  ^The object retu
33720 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
33730 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
33740 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f   is an.** [unpro
33750 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
33760 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 49  alue] object.  I
33770 6e 20 61 20 6d 75 6c 74 69 74 68 72 65 61 64 65  n a multithreade
33780 64 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 2c 0a 2a  d environment,.*
33790 2a 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64  * an unprotected
337a0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
337b0 62 6a 65 63 74 20 6d 61 79 20 6f 6e 6c 79 20 62  bject may only b
337c0 65 20 75 73 65 64 20 73 61 66 65 6c 79 20 77 69  e used safely wi
337d0 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  th.** [sqlite3_b
337e0 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64  ind_value()] and
337f0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
33800 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66  _value()]..** If
33810 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65   the [unprotecte
33820 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
33830 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
33840 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
33850 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20  column_value()] 
33860 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f  is used in any o
33870 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64  ther way, includ
33880 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20  ing calls.** to 
33890 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73  routines like [s
338a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
338b0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
338c0 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20  lue_text()],.** 
338d0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  or [sqlite3_valu
338e0 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65 20  e_bytes()], the 
338f0 62 65 68 61 76 69 6f 72 20 69 73 20 6e 6f 74 20  behavior is not 
33900 74 68 72 65 61 64 73 61 66 65 2e 0a 2a 2a 0a 2a  threadsafe..**.*
33910 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
33920 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76   attempt to conv
33930 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 77 68  ert the value wh
33940 65 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e  ere appropriate.
33950 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c    ^For.** exampl
33960 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e  e, if the intern
33970 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  al representatio
33980 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61  n is FLOAT and a
33990 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20   text result.** 
339a0 69 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73  is requested, [s
339b0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
339c0 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65 72  )] is used inter
339d0 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d  nally to perform
339e0 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69   the.** conversi
339f0 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  on automatically
33a00 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69  .  ^(The followi
33a10 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73  ng table details
33a20 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73   the conversions
33a30 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70 70  .** that are app
33a40 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lied:.**.** <blo
33a50 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62  ckquote>.** <tab
33a60 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a  le border="1">.*
33a70 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72  * <tr><th> Inter
33a80 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e  nal<br>Type <th>
33a90 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79   Requested<br>Ty
33aa0 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73  pe <th>  Convers
33ab0 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74  ion.**.** <tr><t
33ac0 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
33ad0 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
33ae0 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c  Result is 0.** <
33af0 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
33b00 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
33b10 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30  <td> Result is 0
33b20 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  .0.** <tr><td>  
33b30 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54  NULL    <td>   T
33b40 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75  EXT    <td> Resu
33b50 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  lt is a NULL poi
33b60 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  nter.** <tr><td>
33b70 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
33b80 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65   BLOB    <td> Re
33b90 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70  sult is a NULL p
33ba0 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  ointer.** <tr><t
33bb0 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
33bc0 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
33bd0 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74  Convert from int
33be0 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a  eger to float.**
33bf0 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
33c00 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20  R  <td>   TEXT  
33c10 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e    <td> ASCII ren
33c20 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e  dering of the in
33c30 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  teger.** <tr><td
33c40 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
33c50 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53    BLOB    <td> S
33c60 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e  ame as INTEGER->
33c70 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  TEXT.** <tr><td>
33c80 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49    FLOAT   <td> I
33c90 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43  NTEGER   <td> [C
33ca0 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a  AST] to INTEGER.
33cb0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
33cc0 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54  AT   <td>   TEXT
33cd0 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72      <td> ASCII r
33ce0 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20  endering of the 
33cf0 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  float.** <tr><td
33d00 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
33d10 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 5b    BLOB    <td> [
33d20 43 41 53 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a  CAST] to BLOB.**
33d30 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
33d40 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
33d50 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f    <td> [CAST] to
33d60 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e   INTEGER.** <tr>
33d70 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
33d80 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
33d90 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c  > [CAST] to REAL
33da0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
33db0 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  XT    <td>   BLO
33dc0 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61  B    <td> No cha
33dd0 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  nge.** <tr><td> 
33de0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e   BLOB    <td> IN
33df0 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41  TEGER   <td> [CA
33e00 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a  ST] to INTEGER.*
33e10 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
33e20 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20      <td>  FLOAT 
33e30 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74     <td> [CAST] t
33e40 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74  o REAL.** <tr><t
33e50 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  d>  BLOB    <td>
33e60 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
33e70 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69  Add a zero termi
33e80 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a  nator if needed.
33e90 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c  ** </table>.** <
33ea0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a  /blockquote>)^.*
33eb0 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77  *.** Note that w
33ec0 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73  hen type convers
33ed0 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e  ions occur, poin
33ee0 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 79  ters returned by
33ef0 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20   prior.** calls 
33f00 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
33f10 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65  n_blob(), sqlite
33f20 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c  3_column_text(),
33f30 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74   and/or.** sqlit
33f40 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
33f50 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69  () may be invali
33f60 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63  dated..** Type c
33f70 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70  onversions and p
33f80 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74  ointer invalidat
33f90 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72  ions might occur
33fa0 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f  .** in the follo
33fb0 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a  wing cases:.**.*
33fc0 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  * <ul>.** <li> T
33fd0 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
33fe0 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64  nt is a BLOB and
33ff0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
34000 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20  text() or.**    
34010 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
34020 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c  _text16() is cal
34030 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72  led.  A zero-ter
34040 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a  minator might.**
34050 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65        need to be
34060 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74   added to the st
34070 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c  ring.</li>.** <l
34080 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
34090 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20  ontent is UTF-8 
340a0 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33  text and sqlite3
340b0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
340c0 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c  ) or.**      sql
340d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
340e0 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  16() is called. 
340f0 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73   The content mus
34100 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a  t be converted.*
34110 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36  *      to UTF-16
34120 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  .</li>.** <li> T
34130 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
34140 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 78  nt is UTF-16 tex
34150 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  t and sqlite3_co
34160 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a  lumn_bytes() or.
34170 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f  **      sqlite3_
34180 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73  column_text() is
34190 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f   called.  The co
341a0 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f  ntent must be co
341b0 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20  nverted.**      
341c0 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a  to UTF-8.</li>.*
341d0 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43  * </ul>.**.** ^C
341e0 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65  onversions betwe
341f0 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20  en UTF-16be and 
34200 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77  UTF-16le are alw
34210 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63  ays done in plac
34220 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20  e and do.** not 
34230 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 69  invalidate a pri
34240 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75  or pointer, thou
34250 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65  gh of course the
34260 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
34270 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74  buffer.** that t
34280 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72  he prior pointer
34290 20 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c   references will
342a0 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66   have been modif
342b0 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64  ied.  Other kind
342c0 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69  s.** of conversi
342d0 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70  on are done in p
342e0 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 20  lace when it is 
342f0 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f  possible, but so
34300 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20  metimes they.** 
34310 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65  are not possible
34320 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61   and in those ca
34330 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  ses prior pointe
34340 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74  rs are invalidat
34350 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61  ed..**.** The sa
34360 66 65 73 74 20 70 6f 6c 69 63 79 20 69 73 20 74  fest policy is t
34370 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72  o invoke these r
34380 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e  outines.** in on
34390 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
343a0 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ng ways:.**.** <
343b0 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  ul>.**  <li>sqli
343c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
343d0 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
343e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
343f0 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c  es()</li>.**  <l
34400 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
34410 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64  _blob() followed
34420 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
34430 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a  mn_bytes()</li>.
34440 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
34450 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
34460 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
34470 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
34480 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75  16()</li>.** </u
34490 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65  l>.**.** In othe
344a0 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f  r words, you sho
344b0 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33  uld call sqlite3
344c0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a  _column_text(),.
344d0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
344e0 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c  n_blob(), or sql
344f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
34500 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f  16() first to fo
34510 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a  rce the result.*
34520 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72  * into the desir
34530 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20  ed format, then 
34540 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63  invoke sqlite3_c
34550 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72  olumn_bytes() or
34560 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
34570 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20  mn_bytes16() to 
34580 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66  find the size of
34590 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f   the result.  Do
345a0 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a   not mix calls.*
345b0 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  * to sqlite3_col
345c0 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71  umn_text() or sq
345d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
345e0 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74  b() with calls t
345f0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  o.** sqlite3_col
34600 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61  umn_bytes16(), a
34610 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61  nd do not mix ca
34620 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
34630 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a  olumn_text16().*
34640 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20  * with calls to 
34650 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
34660 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ytes()..**.** ^T
34670 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  he pointers retu
34680 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75  rned are valid u
34690 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76  ntil a type conv
346a0 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73  ersion occurs as
346b0 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62  .** described ab
346c0 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73  ove, or until [s
346d0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
346e0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
346f0 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
34700 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69  e3_finalize()] i
34710 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20  s called.  ^The 
34720 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65  memory space use
34730 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67  d to hold string
34740 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69  s.** and BLOBs i
34750 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69  s freed automati
34760 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 65 6d 3e 6e  cally.  Do <em>n
34770 6f 74 3c 2f 65 6d 3e 20 70 61 73 73 20 74 68 65  ot</em> pass the
34780 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
34790 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  ed.** from [sqli
347a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
347b0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  )], [sqlite3_col
347c0 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63  umn_text()], etc
347d0 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  . into.** [sqlit
347e0 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a  e3_free()]..**.*
347f0 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 20  * ^(If a memory 
34800 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
34810 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74   occurs during t
34820 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66  he evaluation of
34830 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65   any.** of these
34840 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66   routines, a def
34850 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65  ault value is re
34860 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66  turned.  The def
34870 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73  ault value.** is
34880 20 65 69 74 68 65 72 20 74 68 65 20 69 6e 74 65   either the inte
34890 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74  ger 0, the float
348a0 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72  ing point number
348b0 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a   0.0, or a NULL.
348c0 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62  ** pointer.  Sub
348d0 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
348e0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
348f0 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  e()] will return
34900 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  .** [SQLITE_NOME
34910 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76  M].)^.*/.const v
34920 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
34930 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  umn_blob(sqlite3
34940 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
34950 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
34960 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69  olumn_bytes(sqli
34970 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
34980 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
34990 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
349a0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
349b0 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c  int iCol);.doubl
349c0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
349d0 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
349e0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
349f0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
34a00 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33  lumn_int(sqlite3
34a10 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
34a20 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
34a30 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
34a40 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  int64(sqlite3_st
34a50 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
34a60 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63  const unsigned c
34a70 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
34a80 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33  umn_text(sqlite3
34a90 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
34aa0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
34ab0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
34ac0 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  xt16(sqlite3_stm
34ad0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
34ae0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
34af0 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73  n_type(sqlite3_s
34b00 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
34b10 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a  .sqlite3_value *
34b20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
34b30 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  alue(sqlite3_stm
34b40 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a  t*, int iCol);..
34b50 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
34b60 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 72  Destroy A Prepar
34b70 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  ed Statement Obj
34b80 65 63 74 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f  ect.** DESTRUCTO
34b90 52 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  R: sqlite3_stmt.
34ba0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
34bb0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75  e3_finalize() fu
34bc0 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64  nction is called
34bd0 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72   to delete a [pr
34be0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
34bf0 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f  ]..** ^If the mo
34c00 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61  st recent evalua
34c10 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74  tion of the stat
34c20 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65  ement encountere
34c30 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f  d no errors.** o
34c40 72 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65  r if the stateme
34c50 6e 74 20 69 73 20 6e 65 76 65 72 20 62 65 65 6e  nt is never been
34c60 20 65 76 61 6c 75 61 74 65 64 2c 20 74 68 65 6e   evaluated, then
34c70 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
34c80 65 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53  e() returns.** S
34c90 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74  QLITE_OK.  ^If t
34ca0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65  he most recent e
34cb0 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74 61  valuation of sta
34cc0 74 65 6d 65 6e 74 20 53 20 66 61 69 6c 65 64 2c  tement S failed,
34cd0 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   then.** sqlite3
34ce0 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 65 74  _finalize(S) ret
34cf0 75 72 6e 73 20 74 68 65 20 61 70 70 72 6f 70 72  urns the appropr
34d00 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65  iate [error code
34d10 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  ] or.** [extende
34d20 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a  d error code]..*
34d30 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
34d40 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f  3_finalize(S) ro
34d50 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c  utine can be cal
34d60 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74  led at any point
34d70 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c   during.** the l
34d80 69 66 65 20 63 79 63 6c 65 20 6f 66 20 5b 70 72  ife cycle of [pr
34d90 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
34da0 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73  ] S:.** before s
34db0 74 61 74 65 6d 65 6e 74 20 53 20 69 73 20 65 76  tatement S is ev
34dc0 65 72 20 65 76 61 6c 75 61 74 65 64 2c 20 61 66  er evaluated, af
34dd0 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f  ter.** one or mo
34de0 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  re calls to [sql
34df0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f  ite3_reset()], o
34e00 72 20 61 66 74 65 72 20 61 6e 79 20 63 61 6c 6c  r after any call
34e10 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  .** to [sqlite3_
34e20 73 74 65 70 28 29 5d 20 72 65 67 61 72 64 6c 65  step()] regardle
34e30 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
34e40 20 6e 6f 74 20 74 68 65 20 73 74 61 74 65 6d 65   not the stateme
34e50 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65  nt has.** comple
34e60 74 65 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a  ted execution..*
34e70 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73  *.** ^Invoking s
34e80 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
34e90 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ) on a NULL poin
34ea0 74 65 72 20 69 73 20 61 20 68 61 72 6d 6c 65 73  ter is a harmles
34eb0 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54  s no-op..**.** T
34ec0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
34ed0 75 73 74 20 66 69 6e 61 6c 69 7a 65 20 65 76 65  ust finalize eve
34ee0 72 79 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ry [prepared sta
34ef0 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72  tement] in order
34f00 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73   to avoid.** res
34f10 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20 20 49 74  ource leaks.  It
34f20 20 69 73 20 61 20 67 72 69 65 76 6f 75 73 20 65   is a grievous e
34f30 72 72 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70  rror for the app
34f40 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74 72 79 20  lication to try 
34f50 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72 65 70  to use.** a prep
34f60 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61  ared statement a
34f70 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e  fter it has been
34f80 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79   finalized.  Any
34f90 20 75 73 65 20 6f 66 20 61 20 70 72 65 70 61 72   use of a prepar
34fa0 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  ed.** statement 
34fb0 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65  after it has bee
34fc0 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20  n finalized can 
34fd0 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69  result in undefi
34fe0 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73  ned and.** undes
34ff0 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 20  irable behavior 
35000 73 75 63 68 20 61 73 20 73 65 67 66 61 75 6c 74  such as segfault
35010 73 20 61 6e 64 20 68 65 61 70 20 63 6f 72 72 75  s and heap corru
35020 70 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ption..*/.int sq
35030 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73  lite3_finalize(s
35040 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
35050 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
35060 33 52 45 46 3a 20 52 65 73 65 74 20 41 20 50 72  3REF: Reset A Pr
35070 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
35080 20 4f 62 6a 65 63 74 0a 2a 2a 20 4d 45 54 48 4f   Object.** METHO
35090 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
350a0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
350b0 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74 69  3_reset() functi
350c0 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20  on is called to 
350d0 72 65 73 65 74 20 61 20 5b 70 72 65 70 61 72 65  reset a [prepare
350e0 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
350f0 6f 62 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69  object back to i
35100 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65  ts initial state
35110 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20 72 65  , ready to be re
35120 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41  -executed..** ^A
35130 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ny SQL statement
35140 20 76 61 72 69 61 62 6c 65 73 20 74 68 61 74 20   variables that 
35150 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64  had values bound
35160 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a   to them using.*
35170 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  * the [sqlite3_b
35180 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74  ind_blob | sqlit
35190 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d  e3_bind_*() API]
351a0 20 72 65 74 61 69 6e 20 74 68 65 69 72 20 76 61   retain their va
351b0 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71  lues..** Use [sq
351c0 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64  lite3_clear_bind
351d0 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74  ings()] to reset
351e0 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a   the bindings..*
351f0 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  *.** ^The [sqlit
35200 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74  e3_reset(S)] int
35210 65 72 66 61 63 65 20 72 65 73 65 74 73 20 74 68  erface resets th
35220 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
35230 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b  ement] S.** back
35240 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e   to the beginnin
35250 67 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d  g of its program
35260 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
35270 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
35280 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
35290 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a  p(S)] for the.**
352a0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
352b0 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64  ment] S returned
352c0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72   [SQLITE_ROW] or
352d0 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a   [SQLITE_DONE],.
352e0 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65  ** or if [sqlite
352f0 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e  3_step(S)] has n
35300 65 76 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e  ever before been
35310 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a   called on S,.**
35320 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72   then [sqlite3_r
35330 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73  eset(S)] returns
35340 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a   [SQLITE_OK]..**
35350 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  .** ^If the most
35360 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20   recent call to 
35370 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
35380 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72  ] for the.** [pr
35390 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
353a0 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e  ] S indicated an
353b0 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20   error, then.** 
353c0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
353d0 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70  )] returns an ap
353e0 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72  propriate [error
353f0 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54   code]..**.** ^T
35400 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
35410 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(S)] interface 
35420 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20  does not change 
35430 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66  the values.** of
35440 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69   any [sqlite3_bi
35450 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73  nd_blob|bindings
35460 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72  ] on the [prepar
35470 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e  ed statement] S.
35480 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
35490 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74  reset(sqlite3_st
354a0 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
354b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72 65  ** CAPI3REF: Cre
354c0 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20  ate Or Redefine 
354d0 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  SQL Functions.**
354e0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63   KEYWORDS: {func
354f0 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f  tion creation ro
35500 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f  utines}.** KEYWO
35510 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f  RDS: {applicatio
35520 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
35530 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f  nction}.** KEYWO
35540 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f  RDS: {applicatio
35550 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
35560 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48  nctions}.** METH
35570 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
35580 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f  * ^These functio
35590 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79  ns (collectively
355a0 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74   known as "funct
355b0 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75  ion creation rou
355c0 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75  tines").** are u
355d0 73 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66  sed to add SQL f
355e0 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72  unctions or aggr
355f0 65 67 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64  egates or to red
35600 65 66 69 6e 65 20 74 68 65 20 62 65 68 61 76 69  efine the behavi
35610 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e  or.** of existin
35620 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  g SQL functions 
35630 6f 72 20 61 67 67 72 65 67 61 74 65 73 2e 20 20  or aggregates.  
35640 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65  The only differe
35650 6e 63 65 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20  nces between.** 
35660 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
35670 72 65 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f  re the text enco
35680 64 69 6e 67 20 65 78 70 65 63 74 65 64 20 66 6f  ding expected fo
35690 72 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20  r.** the second 
356a0 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 6e  parameter (the n
356b0 61 6d 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74  ame of the funct
356c0 69 6f 6e 20 62 65 69 6e 67 20 63 72 65 61 74 65  ion being create
356d0 64 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 70 72  d).** and the pr
356e0 65 73 65 6e 63 65 20 6f 72 20 61 62 73 65 6e 63  esence or absenc
356f0 65 20 6f 66 20 61 20 64 65 73 74 72 75 63 74 6f  e of a destructo
35700 72 20 63 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a  r callback for.*
35710 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
35720 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a  n data pointer..
35730 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
35740 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
35750 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
35760 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68  ection] to which
35770 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63   the SQL.** func
35780 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64  tion is to be ad
35790 64 65 64 2e 20 20 5e 49 66 20 61 6e 20 61 70 70  ded.  ^If an app
357a0 6c 69 63 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f  lication uses mo
357b0 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61  re than one data
357c0 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
357d0 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69 63 61 74  on then applicat
357e0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
357f0 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62  functions must b
35800 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61  e added.** to ea
35810 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ch database conn
35820 65 63 74 69 6f 6e 20 73 65 70 61 72 61 74 65 6c  ection separatel
35830 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65  y..**.** ^The se
35840 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
35850 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
35860 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74  e SQL function t
35870 6f 20 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a  o be created or.
35880 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 20 5e  ** redefined.  ^
35890 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  The length of th
358a0 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65  e name is limite
358b0 64 20 74 6f 20 32 35 35 20 62 79 74 65 73 20 69  d to 255 bytes i
358c0 6e 20 61 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70  n a UTF-8.** rep
358d0 72 65 73 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63  resentation, exc
358e0 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20 7a 65  lusive of the ze
358f0 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  ro-terminator.  
35900 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e  ^Note that the n
35910 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69  ame.** length li
35920 6d 69 74 20 69 73 20 69 6e 20 55 54 46 2d 38 20  mit is in UTF-8 
35930 62 79 74 65 73 2c 20 6e 6f 74 20 63 68 61 72 61  bytes, not chara
35940 63 74 65 72 73 20 6e 6f 72 20 55 54 46 2d 31 36  cters nor UTF-16
35950 20 62 79 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e   bytes.  .** ^An
35960 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65  y attempt to cre
35970 61 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  ate a function w
35980 69 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d  ith a longer nam
35990 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74  e.** will result
359a0 20 69 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55   in [SQLITE_MISU
359b0 53 45 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e  SE] being return
359c0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74  ed..**.** ^The t
359d0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 28  hird parameter (
359e0 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74 68 65 20  nArg).** is the 
359f0 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
35a00 6e 74 73 20 74 68 61 74 20 74 68 65 20 53 51 4c  nts that the SQL
35a10 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
35a20 61 67 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e  aggregate takes.
35a30 20 5e 49 66 20 74 68 69 73 20 70 61 72 61 6d 65   ^If this parame
35a40 74 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20  ter is -1, then 
35a50 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
35a60 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
35a70 20 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75   may take any nu
35a80 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
35a90 73 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20  s between 0 and 
35aa0 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74  the limit.** set
35ab0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d   by [sqlite3_lim
35ac0 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  it]([SQLITE_LIMI
35ad0 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29  T_FUNCTION_ARG])
35ae0 2e 20 20 49 66 20 74 68 65 20 74 68 69 72 64 0a  .  If the third.
35af0 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ** parameter is 
35b00 6c 65 73 73 20 74 68 61 6e 20 2d 31 20 6f 72 20  less than -1 or 
35b10 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 32 37  greater than 127
35b20 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
35b30 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e  or is.** undefin
35b40 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ed..**.** ^The f
35b50 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c  ourth parameter,
35b60 20 65 54 65 78 74 52 65 70 2c 20 73 70 65 63 69   eTextRep, speci
35b70 66 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51  fies what.** [SQ
35b80 4c 49 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74  LITE_UTF8 | text
35b90 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20   encoding] this 
35ba0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65  SQL function pre
35bb0 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20  fers for.** its 
35bc0 70 61 72 61 6d 65 74 65 72 73 2e 20 20 54 68 65  parameters.  The
35bd0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
35be0 75 6c 64 20 73 65 74 20 74 68 69 73 20 70 61 72  uld set this par
35bf0 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 53 51  ameter to.** [SQ
35c00 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 20 69 66  LITE_UTF16LE] if
35c10 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d   the function im
35c20 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76  plementation inv
35c30 6f 6b 65 73 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  okes .** [sqlite
35c40 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65  3_value_text16le
35c50 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c  ()] on an input,
35c60 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31   or [SQLITE_UTF1
35c70 36 42 45 5d 20 69 66 20 74 68 65 0a 2a 2a 20 69  6BE] if the.** i
35c80 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e  mplementation in
35c90 76 6f 6b 65 73 20 5b 73 71 6c 69 74 65 33 5f 76  vokes [sqlite3_v
35ca0 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29 5d  alue_text16be()]
35cb0 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72   on an input, or
35cc0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  .** [SQLITE_UTF1
35cd0 36 5d 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 76  6] if [sqlite3_v
35ce0 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 69  alue_text16()] i
35cf0 73 20 75 73 65 64 2c 20 6f 72 20 5b 53 51 4c 49  s used, or [SQLI
35d00 54 45 5f 55 54 46 38 5d 0a 2a 2a 20 6f 74 68 65  TE_UTF8].** othe
35d10 72 77 69 73 65 2e 20 20 5e 54 68 65 20 73 61 6d  rwise.  ^The sam
35d20 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6d  e SQL function m
35d30 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65 64  ay be registered
35d40 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20   multiple times 
35d50 75 73 69 6e 67 0a 2a 2a 20 64 69 66 66 65 72 65  using.** differe
35d60 6e 74 20 70 72 65 66 65 72 72 65 64 20 74 65 78  nt preferred tex
35d70 74 20 65 6e 63 6f 64 69 6e 67 73 2c 20 77 69 74  t encodings, wit
35d80 68 20 64 69 66 66 65 72 65 6e 74 20 69 6d 70 6c  h different impl
35d90 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 0a  ementations for.
35da0 2a 2a 20 65 61 63 68 20 65 6e 63 6f 64 69 6e 67  ** each encoding
35db0 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69  ..** ^When multi
35dc0 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ple implementati
35dd0 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
35de0 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61  function are ava
35df0 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a  ilable, SQLite.*
35e00 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20  * will pick the 
35e10 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65  one that involve
35e20 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75  s the least amou
35e30 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65  nt of data conve
35e40 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  rsion..**.** ^Th
35e50 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
35e60 65 72 20 6d 61 79 20 6f 70 74 69 6f 6e 61 6c 6c  er may optionall
35e70 79 20 62 65 20 4f 52 65 64 20 77 69 74 68 20 5b  y be ORed with [
35e80 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49  SQLITE_DETERMINI
35e90 53 54 49 43 5d 0a 2a 2a 20 74 6f 20 73 69 67 6e  STIC].** to sign
35ea0 61 6c 20 74 68 61 74 20 74 68 65 20 66 75 6e 63  al that the func
35eb0 74 69 6f 6e 20 77 69 6c 6c 20 61 6c 77 61 79 73  tion will always
35ec0 20 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65   return the same
35ed0 20 72 65 73 75 6c 74 20 67 69 76 65 6e 0a 2a 2a   result given.**
35ee0 20 74 68 65 20 73 61 6d 65 20 69 6e 70 75 74 73   the same inputs
35ef0 20 77 69 74 68 69 6e 20 61 20 73 69 6e 67 6c 65   within a single
35f00 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20   SQL statement. 
35f10 20 4d 6f 73 74 20 53 51 4c 20 66 75 6e 63 74 69   Most SQL functi
35f20 6f 6e 73 20 61 72 65 0a 2a 2a 20 64 65 74 65 72  ons are.** deter
35f30 6d 69 6e 69 73 74 69 63 2e 20 20 54 68 65 20 62  ministic.  The b
35f40 75 69 6c 74 2d 69 6e 20 5b 72 61 6e 64 6f 6d 28  uilt-in [random(
35f50 29 5d 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  )] SQL function 
35f60 69 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66  is an example of
35f70 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74   a.** function t
35f80 68 61 74 20 69 73 20 6e 6f 74 20 64 65 74 65 72  hat is not deter
35f90 6d 69 6e 69 73 74 69 63 2e 20 20 54 68 65 20 53  ministic.  The S
35fa0 51 4c 69 74 65 20 71 75 65 72 79 20 70 6c 61 6e  QLite query plan
35fb0 6e 65 72 20 69 73 20 61 62 6c 65 20 74 6f 0a 2a  ner is able to.*
35fc0 2a 20 70 65 72 66 6f 72 6d 20 61 64 64 69 74 69  * perform additi
35fd0 6f 6e 61 6c 20 6f 70 74 69 6d 69 7a 61 74 69 6f  onal optimizatio
35fe0 6e 73 20 6f 6e 20 64 65 74 65 72 6d 69 6e 69 73  ns on determinis
35ff0 74 69 63 20 66 75 6e 63 74 69 6f 6e 73 2c 20 73  tic functions, s
36000 6f 20 75 73 65 0a 2a 2a 20 6f 66 20 74 68 65 20  o use.** of the 
36010 5b 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e  [SQLITE_DETERMIN
36020 49 53 54 49 43 5d 20 66 6c 61 67 20 69 73 20 72  ISTIC] flag is r
36030 65 63 6f 6d 6d 65 6e 64 65 64 20 77 68 65 72 65  ecommended where
36040 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a   possible..**.**
36050 20 5e 28 54 68 65 20 66 69 66 74 68 20 70 61 72   ^(The fifth par
36060 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72 62  ameter is an arb
36070 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20  itrary pointer. 
36080 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   The implementat
36090 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75  ion of the.** fu
360a0 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20  nction can gain 
360b0 61 63 63 65 73 73 20 74 6f 20 74 68 69 73 20 70  access to this p
360c0 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 71  ointer using [sq
360d0 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
360e0 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  )].)^.**.** ^The
360f0 20 73 69 78 74 68 2c 20 73 65 76 65 6e 74 68 20   sixth, seventh 
36100 61 6e 64 20 65 69 67 68 74 68 20 70 61 72 61 6d  and eighth param
36110 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53  eters, xFunc, xS
36120 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20  tep and xFinal, 
36130 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20  are.** pointers 
36140 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75  to C-language fu
36150 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70  nctions that imp
36160 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66  lement the SQL f
36170 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
36180 67 72 65 67 61 74 65 2e 20 5e 41 20 73 63 61 6c  gregate. ^A scal
36190 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ar SQL function 
361a0 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c  requires an impl
361b0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
361c0 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62  e xFunc.** callb
361d0 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70  ack only; NULL p
361e0 6f 69 6e 74 65 72 73 20 6d 75 73 74 20 62 65 20  ointers must be 
361f0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 78 53  passed as the xS
36200 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a  tep and xFinal.*
36210 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 5e 41  * parameters. ^A
36220 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  n aggregate SQL 
36230 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
36240 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  s an implementat
36250 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20  ion of xStep.** 
36260 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e  and xFinal and N
36270 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d 75 73 74  ULL pointer must
36280 20 62 65 20 70 61 73 73 65 64 20 66 6f 72 20 78   be passed for x
36290 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65  Func. ^To delete
362a0 20 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20   an existing.** 
362b0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20  SQL function or 
362c0 61 67 67 72 65 67 61 74 65 2c 20 70 61 73 73 20  aggregate, pass 
362d0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 66 6f  NULL pointers fo
362e0 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63  r all three func
362f0 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  tion.** callback
36300 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68  s..**.** ^(If th
36310 65 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65  e ninth paramete
36320 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65  r to sqlite3_cre
36330 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28  ate_function_v2(
36340 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a  ) is not NULL,.*
36350 2a 20 74 68 65 6e 20 69 74 20 69 73 20 64 65 73  * then it is des
36360 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20  tructor for the 
36370 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
36380 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20 54 68   pointer. .** Th
36390 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20  e destructor is 
363a0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65  invoked when the
363b0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c   function is del
363c0 65 74 65 64 2c 20 65 69 74 68 65 72 20 62 79 20  eted, either by 
363d0 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61  being.** overloa
363e0 64 65 64 20 6f 72 20 77 68 65 6e 20 74 68 65 20  ded or when the 
363f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
36400 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a  ion closes.)^.**
36410 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72   ^The destructor
36420 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64   is also invoked
36430 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a   if the call to.
36440 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ** sqlite3_creat
36450 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20  e_function_v2() 
36460 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20  fails..** ^When 
36470 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 63  the destructor c
36480 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 74  allback of the t
36490 65 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  enth parameter i
364a0 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a  s invoked, it.**
364b0 20 69 73 20 70 61 73 73 65 64 20 61 20 73 69 6e   is passed a sin
364c0 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
364d0 63 68 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  ch is a copy of 
364e0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
364f0 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e 74 65 72  data .** pointer
36500 20 77 68 69 63 68 20 77 61 73 20 74 68 65 20 66   which was the f
36510 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  ifth parameter t
36520 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  o sqlite3_create
36530 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 2e 0a  _function_v2()..
36540 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65 72  **.** ^It is per
36550 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69 73 74  mitted to regist
36560 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c  er multiple impl
36570 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74  ementations of t
36580 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74  he same.** funct
36590 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73 61  ions with the sa
365a0 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68  me name but with
365b0 20 65 69 74 68 65 72 20 64 69 66 66 65 72 69 6e   either differin
365c0 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20  g numbers of.** 
365d0 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66  arguments or dif
365e0 66 65 72 69 6e 67 20 70 72 65 66 65 72 72 65 64  fering preferred
365f0 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e   text encodings.
36600 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75    ^SQLite will u
36610 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d  se.** the implem
36620 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f  entation that mo
36630 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68  st closely match
36640 65 73 20 74 68 65 20 77 61 79 20 69 6e 20 77 68  es the way in wh
36650 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66  ich the.** SQL f
36660 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e  unction is used.
36670 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d    ^A function im
36680 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74  plementation wit
36690 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65  h a non-negative
366a0 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d 65 74  .** nArg paramet
366b0 65 72 20 69 73 20 61 20 62 65 74 74 65 72 20 6d  er is a better m
366c0 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63  atch than a func
366d0 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
366e0 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65  ion with.** a ne
366f0 67 61 74 69 76 65 20 6e 41 72 67 2e 20 20 5e 41  gative nArg.  ^A
36700 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
36710 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 65  the preferred te
36720 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d  xt encoding.** m
36730 61 74 63 68 65 73 20 74 68 65 20 64 61 74 61 62  atches the datab
36740 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  ase encoding is 
36750 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63  a better.** matc
36760 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
36770 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f  n where the enco
36780 64 69 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e  ding is differen
36790 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74  t.  .** ^A funct
367a0 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e  ion where the en
367b0 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63  coding differenc
367c0 65 20 69 73 20 62 65 74 77 65 65 6e 20 55 54 46  e is between UTF
367d0 31 36 6c 65 20 61 6e 64 20 55 54 46 31 36 62 65  16le and UTF16be
367e0 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65 72 20  .** is a closer 
367f0 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e  match than a fun
36800 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
36810 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65  encoding differe
36820 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74 77 65 65  nce is.** betwee
36830 6e 20 55 54 46 38 20 61 6e 64 20 55 54 46 31 36  n UTF8 and UTF16
36840 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69  ..**.** ^Built-i
36850 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20  n functions may 
36860 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 20 62 79  be overloaded by
36870 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e   new application
36880 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
36890 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70  ns..**.** ^An ap
368a0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
368b0 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 65  d function is pe
368c0 72 6d 69 74 74 65 64 20 74 6f 20 63 61 6c 6c 20  rmitted to call 
368d0 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20  other.** SQLite 
368e0 69 6e 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77  interfaces.  How
368f0 65 76 65 72 2c 20 73 75 63 68 20 63 61 6c 6c 73  ever, such calls
36900 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f   must not.** clo
36910 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
36920 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66  connection nor f
36930 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65 73 65 74  inalize or reset
36940 20 74 68 65 20 70 72 65 70 61 72 65 64 0a 2a 2a   the prepared.**
36950 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 77 68   statement in wh
36960 69 63 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  ich the function
36970 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a   is running..*/.
36980 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
36990 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73  te_function(.  s
369a0 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f  qlite3 *db,.  co
369b0 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74  nst char *zFunct
369c0 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e  ionName,.  int n
369d0 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  Arg,.  int eText
369e0 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70  Rep,.  void *pAp
369f0 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e  p,.  void (*xFun
36a00 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
36a10 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
36a20 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
36a30 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65   (*xStep)(sqlite
36a40 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
36a50 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
36a60 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c  .  void (*xFinal
36a70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
36a80 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  t*).);.int sqlit
36a90 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
36aa0 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20  on16(.  sqlite3 
36ab0 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69  *db,.  const voi
36ac0 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65  d *zFunctionName
36ad0 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20  ,.  int nArg,.  
36ae0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20  int eTextRep,.  
36af0 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f  void *pApp,.  vo
36b00 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69  id (*xFunc)(sqli
36b10 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
36b20 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
36b30 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65  ),.  void (*xSte
36b40 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  p)(sqlite3_conte
36b50 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
36b60 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
36b70 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74   (*xFinal)(sqlit
36b80 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a  e3_context*).);.
36b90 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
36ba0 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 0a  te_function_v2(.
36bb0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20    sqlite3 *db,. 
36bc0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75   const char *zFu
36bd0 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e  nctionName,.  in
36be0 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54  t nArg,.  int eT
36bf0 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a  extRep,.  void *
36c00 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78  pApp,.  void (*x
36c10 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f  Func)(sqlite3_co
36c20 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
36c30 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
36c40 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c  oid (*xStep)(sql
36c50 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
36c60 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
36c70 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69  *),.  void (*xFi
36c80 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nal)(sqlite3_con
36c90 74 65 78 74 2a 29 2c 0a 20 20 76 6f 69 64 28 2a  text*),.  void(*
36ca0 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29  xDestroy)(void*)
36cb0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
36cc0 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 69  REF: Text Encodi
36cd0 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ngs.**.** These 
36ce0 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 20  constant define 
36cf0 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74 68  integer codes th
36d00 61 74 20 72 65 70 72 65 73 65 6e 74 20 74 68 65  at represent the
36d10 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74   various.** text
36d20 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 6f   encodings suppo
36d30 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a  rted by SQLite..
36d40 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
36d50 45 5f 55 54 46 38 20 20 20 20 20 20 20 20 20 20  E_UTF8          
36d60 20 31 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d   1    /* IMP: R-
36d70 33 37 35 31 34 2d 33 35 35 36 36 20 2a 2f 0a 23  37514-35566 */.#
36d80 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
36d90 46 31 36 4c 45 20 20 20 20 20 20 20 20 32 20 20  F16LE        2  
36da0 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 30 33 33 37    /* IMP: R-0337
36db0 31 2d 33 37 36 33 37 20 2a 2f 0a 23 64 65 66 69  1-37637 */.#defi
36dc0 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42  ne SQLITE_UTF16B
36dd0 45 20 20 20 20 20 20 20 20 33 20 20 20 20 2f 2a  E        3    /*
36de0 20 49 4d 50 3a 20 52 2d 35 31 39 37 31 2d 33 34   IMP: R-51971-34
36df0 31 35 34 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  154 */.#define S
36e00 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20 20  QLITE_UTF16     
36e10 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65       4    /* Use
36e20 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
36e30 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  er */.#define SQ
36e40 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20  LITE_ANY        
36e50 20 20 20 20 35 20 20 20 20 2f 2a 20 44 65 70 72      5    /* Depr
36e60 65 63 61 74 65 64 20 2a 2f 0a 23 64 65 66 69 6e  ecated */.#defin
36e70 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41  e SQLITE_UTF16_A
36e80 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20  LIGNED  8    /* 
36e90 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
36ea0 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f  ollation only */
36eb0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
36ec0 3a 20 46 75 6e 63 74 69 6f 6e 20 46 6c 61 67 73  : Function Flags
36ed0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
36ee0 73 74 61 6e 74 73 20 6d 61 79 20 62 65 20 4f 52  stants may be OR
36ef0 65 64 20 74 6f 67 65 74 68 65 72 20 77 69 74 68  ed together with
36f00 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45   the .** [SQLITE
36f10 5f 55 54 46 38 20 7c 20 70 72 65 66 65 72 72 65  _UTF8 | preferre
36f20 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d  d text encoding]
36f30 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 61   as the fourth a
36f40 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73  rgument.** to [s
36f50 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
36f60 6e 63 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69  nction()], [sqli
36f70 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
36f80 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20  ion16()], or.** 
36f90 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
36fa0 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a  function_v2()]..
36fb0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
36fc0 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43 20  E_DETERMINISTIC 
36fd0 20 20 20 30 78 38 30 30 0a 0a 2f 2a 0a 2a 2a 20     0x800../*.** 
36fe0 43 41 50 49 33 52 45 46 3a 20 44 65 70 72 65 63  CAPI3REF: Deprec
36ff0 61 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  ated Functions.*
37000 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a  * DEPRECATED.**.
37010 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  ** These functio
37020 6e 73 20 61 72 65 20 5b 64 65 70 72 65 63 61 74  ns are [deprecat
37030 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74  ed].  In order t
37040 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61  o maintain.** ba
37050 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
37060 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72  ility with older
37070 20 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e   code, these fun
37080 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20  ctions continue 
37090 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72  .** to be suppor
370a0 74 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e  ted.  However, n
370b0 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ew applications 
370c0 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20  should avoid.** 
370d0 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 73 65  the use of these
370e0 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20   functions.  To 
370f0 65 6e 63 6f 75 72 61 67 65 20 70 72 6f 67 72 61  encourage progra
37100 6d 6d 65 72 73 20 74 6f 20 61 76 6f 69 64 0a 2a  mmers to avoid.*
37110 2a 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * these function
37120 73 2c 20 77 65 20 77 69 6c 6c 20 6e 6f 74 20 65  s, we will not e
37130 78 70 6c 61 69 6e 20 77 68 61 74 20 74 68 65 79  xplain what they
37140 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20   do..*/.#ifndef 
37150 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52  SQLITE_OMIT_DEPR
37160 45 43 41 54 45 44 0a 53 51 4c 49 54 45 5f 44 45  ECATED.SQLITE_DE
37170 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
37180 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
37190 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  ount(sqlite3_con
371a0 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44  text*);.SQLITE_D
371b0 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
371c0 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28 73 71  lite3_expired(sq
371d0 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51  lite3_stmt*);.SQ
371e0 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
371f0 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e  int sqlite3_tran
37200 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71  sfer_bindings(sq
37210 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c  lite3_stmt*, sql
37220 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c  ite3_stmt*);.SQL
37230 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
37240 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61  nt sqlite3_globa
37250 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b  l_recover(void);
37260 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
37270 45 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  ED void sqlite3_
37280 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76  thread_cleanup(v
37290 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  oid);.SQLITE_DEP
372a0 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
372b0 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d  te3_memory_alarm
372c0 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73  (void(*)(void*,s
372d0 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74  qlite3_int64,int
372e0 29 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  ),.             
372f0 20 20 20 20 20 20 20 20 20 76 6f 69 64 2a 2c 73           void*,s
37300 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23  qlite3_int64);.#
37310 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
37320 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67  I3REF: Obtaining
37330 20 53 51 4c 20 56 61 6c 75 65 73 0a 2a 2a 20 4d   SQL Values.** M
37340 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 76  ETHOD: sqlite3_v
37350 61 6c 75 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43  alue.**.** The C
37360 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d  -language implem
37370 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20  entation of SQL 
37380 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67  functions and ag
37390 67 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a  gregates uses.**
373a0 20 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74   this set of int
373b0 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20  erface routines 
373c0 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 70 61  to access the pa
373d0 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f  rameter values o
373e0 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f  n.** the functio
373f0 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e 20  n or aggregate. 
37400 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e   .**.** The xFun
37410 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75  c (for scalar fu
37420 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65  nctions) or xSte
37430 70 20 28 66 6f 72 20 61 67 67 72 65 67 61 74 65  p (for aggregate
37440 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a  s) parameters.**
37450 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   to [sqlite3_cre
37460 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20  ate_function()] 
37470 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
37480 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
37490 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c  ].** define call
374a0 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65  backs that imple
374b0 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e  ment the SQL fun
374c0 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65  ctions and aggre
374d0 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72  gates..** The 3r
374e0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
374f0 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69  hese callbacks i
37500 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
37510 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72  inters to.** [pr
37520 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
37530 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20  value] objects. 
37540 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73   There is one [s
37550 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
37560 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68  ject for.** each
37570 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
37580 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20  e SQL function. 
37590 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
375a0 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65  are used to.** e
375b0 78 74 72 61 63 74 20 76 61 6c 75 65 73 20 66 72  xtract values fr
375c0 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  om the [sqlite3_
375d0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a  value] objects..
375e0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
375f0 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77  ines work only w
37600 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73  ith [protected s
37610 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
37620 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74  jects..** Any at
37630 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65  tempt to use the
37640 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61  se routines on a
37650 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  n [unprotected s
37660 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a  qlite3_value].**
37670 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20   object results 
37680 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68  in undefined beh
37690 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  avior..**.** ^Th
376a0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72  ese routines wor
376b0 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20  k just like the 
376c0 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63  corresponding [c
376d0 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
376e0 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70  ctions].** excep
376f0 74 20 74 68 61 74 20 74 68 65 73 65 20 72 6f 75  t that these rou
37700 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e  tines take a sin
37710 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73  gle [protected s
37720 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
37730 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ject.** pointer 
37740 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71  instead of a [sq
37750 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69  lite3_stmt*] poi
37760 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65  nter and an inte
37770 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65  ger column numbe
37780 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
37790 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
377a0 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 20 65  16() interface e
377b0 78 74 72 61 63 74 73 20 61 20 55 54 46 2d 31 36  xtracts a UTF-16
377c0 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68   string.** in th
377d0 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72  e native byte-or
377e0 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20  der of the host 
377f0 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a  machine.  ^The.*
37800 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  * sqlite3_value_
37810 74 65 78 74 31 36 62 65 28 29 20 61 6e 64 20 73  text16be() and s
37820 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
37830 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63  t16le() interfac
37840 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54  es.** extract UT
37850 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73 20  F-16 strings as 
37860 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c  big-endian and l
37870 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73  ittle-endian res
37880 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a  pectively..**.**
37890 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 76   ^(The sqlite3_v
378a0 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70  alue_numeric_typ
378b0 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74  e() interface at
378c0 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a  tempts to apply.
378d0 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e  ** numeric affin
378e0 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65  ity to the value
378f0 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68  .  This means th
37900 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73  at an attempt is
37910 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76  .** made to conv
37920 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f  ert the value to
37930 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66   an integer or f
37940 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20  loating point.  
37950 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e  If.** such a con
37960 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69  version is possi
37970 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73  ble without loss
37980 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20   of information 
37990 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72  (in other.** wor
379a0 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65  ds, if the value
379b0 20 69 73 20 61 20 73 74 72 69 6e 67 20 74 68 61   is a string tha
379c0 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e  t looks like a n
379d0 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74  umber).** then t
379e0 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73  he conversion is
379f0 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68   performed.  Oth
37a00 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72  erwise no conver
37a10 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20  sion occurs..** 
37a20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  The [SQLITE_INTE
37a30 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20  GER | datatype] 
37a40 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e  after conversion
37a50 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a   is returned.)^.
37a60 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79  **.** Please pay
37a70 20 70 61 72 74 69 63 75 6c 61 72 20 61 74 74 65   particular atte
37a80 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63  ntion to the fac
37a90 74 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74  t that the point
37aa0 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66  er returned.** f
37ab0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  rom [sqlite3_val
37ac0 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c  ue_blob()], [sql
37ad0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
37ae0 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  )], or.** [sqlit
37af0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
37b00 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69  )] can be invali
37b10 64 61 74 65 64 20 62 79 20 61 20 73 75 62 73 65  dated by a subse
37b20 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a  quent call to.**
37b30 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
37b40 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74  bytes()], [sqlit
37b50 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36  e3_value_bytes16
37b60 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
37b70 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20  lue_text()],.** 
37b80 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  or [sqlite3_valu
37b90 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a  e_text16()]..**.
37ba0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
37bb0 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  s must be called
37bc0 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
37bd0 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20  hread as.** the 
37be0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  SQL function tha
37bf0 74 20 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b  t supplied the [
37c00 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20  sqlite3_value*] 
37c10 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63  parameters..*/.c
37c20 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
37c30 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71  e3_value_blob(sq
37c40 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
37c50 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
37c60 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76  _bytes(sqlite3_v
37c70 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
37c80 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31  te3_value_bytes1
37c90 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  6(sqlite3_value*
37ca0 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65  );.double sqlite
37cb0 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73  3_value_double(s
37cc0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
37cd0 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
37ce0 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61  e_int(sqlite3_va
37cf0 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69  lue*);.sqlite3_i
37d00 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c  nt64 sqlite3_val
37d10 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  ue_int64(sqlite3
37d20 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20  _value*);.const 
37d30 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73  unsigned char *s
37d40 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
37d50 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t(sqlite3_value*
37d60 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
37d70 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
37d80 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  t16(sqlite3_valu
37d90 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  e*);.const void 
37da0 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
37db0 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f  ext16le(sqlite3_
37dc0 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76  value*);.const v
37dd0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
37de0 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69  ue_text16be(sqli
37df0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
37e00 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
37e10 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ype(sqlite3_valu
37e20 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
37e30 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74  _value_numeric_t
37e40 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ype(sqlite3_valu
37e50 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  e*);../*.** CAPI
37e60 33 52 45 46 3a 20 46 69 6e 64 69 6e 67 20 54 68  3REF: Finding Th
37e70 65 20 53 75 62 74 79 70 65 20 4f 66 20 53 51 4c  e Subtype Of SQL
37e80 20 56 61 6c 75 65 73 0a 2a 2a 20 4d 45 54 48 4f   Values.** METHO
37e90 44 3a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  D: sqlite3_value
37ea0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
37eb0 65 33 5f 76 61 6c 75 65 5f 73 75 62 74 79 70 65  e3_value_subtype
37ec0 28 56 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  (V) function ret
37ed0 75 72 6e 73 20 74 68 65 20 73 75 62 74 79 70 65  urns the subtype
37ee0 20 66 6f 72 0a 2a 2a 20 61 6e 20 5b 61 70 70 6c   for.** an [appl
37ef0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
37f00 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 20 61 72  SQL function] ar
37f10 67 75 6d 65 6e 74 20 56 2e 20 20 54 68 65 20 73  gument V.  The s
37f20 75 62 74 79 70 65 0a 2a 2a 20 69 6e 66 6f 72 6d  ubtype.** inform
37f30 61 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ation can be use
37f40 64 20 74 6f 20 70 61 73 73 20 61 20 6c 69 6d 69  d to pass a limi
37f50 74 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f  ted amount of co
37f60 6e 74 65 78 74 20 66 72 6f 6d 0a 2a 2a 20 6f 6e  ntext from.** on
37f70 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74  e SQL function t
37f80 6f 20 61 6e 6f 74 68 65 72 2e 20 20 55 73 65 20  o another.  Use 
37f90 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  the [sqlite3_res
37fa0 75 6c 74 5f 73 75 62 74 79 70 65 28 29 5d 0a 2a  ult_subtype()].*
37fb0 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20 73 65 74  * routine to set
37fc0 20 74 68 65 20 73 75 62 74 79 70 65 20 66 6f 72   the subtype for
37fd0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
37fe0 65 20 6f 66 20 61 6e 20 53 51 4c 20 66 75 6e 63  e of an SQL func
37ff0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  tion..**.** SQLi
38000 74 65 20 6d 61 6b 65 73 20 6e 6f 20 75 73 65 20  te makes no use 
38010 6f 66 20 73 75 62 74 79 70 65 20 69 74 73 65 6c  of subtype itsel
38020 66 2e 20 20 49 74 20 6d 65 72 65 6c 79 20 70 61  f.  It merely pa
38030 73 73 65 73 20 74 68 65 20 73 75 62 74 79 70 65  sses the subtype
38040 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 72 65 73  .** from the res
38050 75 6c 74 20 6f 66 20 6f 6e 65 20 5b 61 70 70 6c  ult of one [appl
38060 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
38070 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 20 69 6e  SQL function] in
38080 74 6f 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74 20  to the.** input 
38090 6f 66 20 61 6e 6f 74 68 65 72 2e 0a 2a 2f 0a 75  of another..*/.u
380a0 6e 73 69 67 6e 65 64 20 69 6e 74 20 73 71 6c 69  nsigned int sqli
380b0 74 65 33 5f 76 61 6c 75 65 5f 73 75 62 74 79 70  te3_value_subtyp
380c0 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
380d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
380e0 45 46 3a 20 43 6f 70 79 20 41 6e 64 20 46 72 65  EF: Copy And Fre
380f0 65 20 53 51 4c 20 56 61 6c 75 65 73 0a 2a 2a 20  e SQL Values.** 
38100 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
38110 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  value.**.** ^The
38120 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64   sqlite3_value_d
38130 75 70 28 56 29 20 69 6e 74 65 72 66 61 63 65 20  up(V) interface 
38140 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
38150 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
38160 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 44 20  ue].** object D 
38170 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f  and returns a po
38180 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 63 6f  inter to that co
38190 70 79 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74  py.  ^The [sqlit
381a0 65 33 5f 76 61 6c 75 65 5d 20 72 65 74 75 72 6e  e3_value] return
381b0 65 64 0a 2a 2a 20 69 73 20 61 20 5b 70 72 6f 74  ed.** is a [prot
381c0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
381d0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 65 76 65 6e  lue] object even
381e0 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73   if the input is
381f0 20 6e 6f 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71   not..** ^The sq
38200 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28  lite3_value_dup(
38210 56 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  V) interface ret
38220 75 72 6e 73 20 4e 55 4c 4c 20 69 66 20 56 20 69  urns NULL if V i
38230 73 20 4e 55 4c 4c 20 6f 72 20 69 66 20 61 0a 2a  s NULL or if a.*
38240 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
38250 69 6f 6e 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a  ion fails..**.**
38260 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61   ^The sqlite3_va
38270 6c 75 65 5f 66 72 65 65 28 56 29 20 69 6e 74 65  lue_free(V) inte
38280 72 66 61 63 65 20 66 72 65 65 73 20 61 6e 20 5b  rface frees an [
38290 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
382a0 62 6a 65 63 74 0a 2a 2a 20 70 72 65 76 69 6f 75  bject.** previou
382b0 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  sly obtained fro
382c0 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  m [sqlite3_value
382d0 5f 64 75 70 28 29 5d 2e 20 20 5e 49 66 20 56 20  _dup()].  ^If V 
382e0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
382f0 72 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65  r.** then sqlite
38300 33 5f 76 61 6c 75 65 5f 66 72 65 65 28 56 29 20  3_value_free(V) 
38310 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f  is a harmless no
38320 2d 6f 70 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f  -op..*/.sqlite3_
38330 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 76  value *sqlite3_v
38340 61 6c 75 65 5f 64 75 70 28 63 6f 6e 73 74 20 73  alue_dup(const s
38350 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
38360 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  void sqlite3_val
38370 75 65 5f 66 72 65 65 28 73 71 6c 69 74 65 33 5f  ue_free(sqlite3_
38380 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  value*);../*.** 
38390 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e  CAPI3REF: Obtain
383a0 20 41 67 67 72 65 67 61 74 65 20 46 75 6e 63 74   Aggregate Funct
383b0 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 20 4d  ion Context.** M
383c0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63  ETHOD: sqlite3_c
383d0 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70  ontext.**.** Imp
383e0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
383f0 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
38400 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73  nctions use this
38410 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20 61  .** routine to a
38420 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 66  llocate memory f
38430 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72  or storing their
38440 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54   state..**.** ^T
38450 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68  he first time th
38460 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  e sqlite3_aggreg
38470 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29  ate_context(C,N)
38480 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c   routine is call
38490 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72  ed .** for a par
384a0 74 69 63 75 6c 61 72 20 61 67 67 72 65 67 61 74  ticular aggregat
384b0 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69  e function, SQLi
384c0 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20  te.** allocates 
384d0 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72  N of memory, zer
384e0 6f 65 73 20 6f 75 74 20 74 68 61 74 20 6d 65 6d  oes out that mem
384f0 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73  ory, and returns
38500 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
38510 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e   the new memory.
38520 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20   ^On second and 
38530 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
38540 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61   to.** sqlite3_a
38550 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
38560 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  () for the same 
38570 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
38580 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20  on instance,.** 
38590 74 68 65 20 73 61 6d 65 20 62 75 66 66 65 72 20  the same buffer 
385a0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 53 71  is returned.  Sq
385b0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
385c0 63 6f 6e 74 65 78 74 28 29 20 69 73 20 6e 6f 72  context() is nor
385d0 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20  mally.** called 
385e0 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 69 6e  once for each in
385f0 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  vocation of the 
38600 78 53 74 65 70 20 63 61 6c 6c 62 61 63 6b 20 61  xStep callback a
38610 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c  nd then one.** l
38620 61 73 74 20 74 69 6d 65 20 77 68 65 6e 20 74 68  ast time when th
38630 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63  e xFinal callbac
38640 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e  k is invoked.  ^
38650 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61  (When no rows ma
38660 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67  tch.** an aggreg
38670 61 74 65 20 71 75 65 72 79 2c 20 74 68 65 20 78  ate query, the x
38680 53 74 65 70 28 29 20 63 61 6c 6c 62 61 63 6b 20  Step() callback 
38690 6f 66 20 74 68 65 20 61 67 67 72 65 67 61 74 65  of the aggregate
386a0 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70   function.** imp
386b0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e  lementation is n
386c0 65 76 65 72 20 63 61 6c 6c 65 64 20 61 6e 64 20  ever called and 
386d0 78 46 69 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c  xFinal() is call
386e0 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e  ed exactly once.
386f0 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63 61 73  .** In those cas
38700 65 73 2c 20 73 71 6c 69 74 65 33 5f 61 67 67 72  es, sqlite3_aggr
38710 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
38720 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20  might be called 
38730 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72 73 74  for the.** first
38740 20 74 69 6d 65 20 66 72 6f 6d 20 77 69 74 68 69   time from withi
38750 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a  n xFinal().)^.**
38760 0a 2a 2a 20 5e 54 68 65 20 73 71 6c