/ Hex Artifact Content
Login

Artifact 900a07463a87be50b9954817f4c24a0660b4c4ddc1bfe83dedea484c6ac98425:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 64 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a  ed to operate..*
04e0: 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66  *.** The name of
04f0: 20 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72   this file under
0500: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d   configuration m
0510: 61 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71  anagement is "sq
0520: 6c 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54  lite.h.in"..** T
0530: 68 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65  he makefile make
0540: 73 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61  s some minor cha
0550: 6e 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c  nges to this fil
0560: 65 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72  e (such as inser
0570: 74 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73  ting.** the vers
0580: 69 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20  ion number) and 
0590: 63 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65  changes its name
05a0: 20 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20   to "sqlite3.h" 
05b0: 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68  as.** part of th
05c0: 65 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e  e build process.
05d0: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  .*/.#ifndef SQLI
05e0: 54 45 33 5f 48 0a 23 64 65 66 69 6e 65 20 53 51  TE3_H.#define SQ
05f0: 4c 49 54 45 33 5f 48 0a 23 69 6e 63 6c 75 64 65  LITE3_H.#include
0600: 20 3c 73 74 64 61 72 67 2e 68 3e 20 20 20 20 20   <stdarg.h>     
0610: 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72 20 74 68  /* Needed for th
0620: 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 66 20  e definition of 
0630: 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a  va_list */../*.*
0640: 2a 20 4d 61 6b 65 20 73 75 72 65 20 77 65 20 63  * Make sure we c
0650: 61 6e 20 63 61 6c 6c 20 74 68 69 73 20 73 74 75  an call this stu
0660: 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a  ff from C++..*/.
0670: 23 69 66 64 65 66 20 5f 5f 63 70 6c 75 73 70 6c  #ifdef __cpluspl
0680: 75 73 0a 65 78 74 65 72 6e 20 22 43 22 20 7b 0a  us.extern "C" {.
0690: 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 50  #endif.../*.** P
06a0: 72 6f 76 69 64 65 20 74 68 65 20 61 62 69 6c 69  rovide the abili
06b0: 74 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 6c  ty to override l
06c0: 69 6e 6b 61 67 65 20 66 65 61 74 75 72 65 73 20  inkage features 
06d0: 6f 66 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  of the interface
06e0: 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c  ..*/.#ifndef SQL
06f0: 49 54 45 5f 45 58 54 45 52 4e 0a 23 20 64 65 66  ITE_EXTERN.# def
0700: 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 54 45 52  ine SQLITE_EXTER
0710: 4e 20 65 78 74 65 72 6e 0a 23 65 6e 64 69 66 0a  N extern.#endif.
0720: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 41  #ifndef SQLITE_A
0730: 50 49 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  PI.# define SQLI
0740: 54 45 5f 41 50 49 0a 23 65 6e 64 69 66 0a 23 69  TE_API.#endif.#i
0750: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 43 44 45  fndef SQLITE_CDE
0760: 43 4c 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  CL.# define SQLI
0770: 54 45 5f 43 44 45 43 4c 0a 23 65 6e 64 69 66 0a  TE_CDECL.#endif.
0780: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 41  #ifndef SQLITE_A
0790: 50 49 43 41 4c 4c 0a 23 20 64 65 66 69 6e 65 20  PICALL.# define 
07a0: 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a 23  SQLITE_APICALL.#
07b0: 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51  endif.#ifndef SQ
07c0: 4c 49 54 45 5f 53 54 44 43 41 4c 4c 0a 23 20 64  LITE_STDCALL.# d
07d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 44  efine SQLITE_STD
07e0: 43 41 4c 4c 20 53 51 4c 49 54 45 5f 41 50 49 43  CALL SQLITE_APIC
07f0: 41 4c 4c 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64  ALL.#endif.#ifnd
0800: 65 66 20 53 51 4c 49 54 45 5f 43 41 4c 4c 42 41  ef SQLITE_CALLBA
0810: 43 4b 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  CK.# define SQLI
0820: 54 45 5f 43 41 4c 4c 42 41 43 4b 0a 23 65 6e 64  TE_CALLBACK.#end
0830: 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  if.#ifndef SQLIT
0840: 45 5f 53 59 53 41 50 49 0a 23 20 64 65 66 69 6e  E_SYSAPI.# defin
0850: 65 20 53 51 4c 49 54 45 5f 53 59 53 41 50 49 0a  e SQLITE_SYSAPI.
0860: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68  #endif../*.** Th
0870: 65 73 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73  ese no-op macros
0880: 20 61 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f   are used in fro
0890: 6e 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73  nt of interfaces
08a0: 20 74 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a   to mark those.*
08b0: 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 73 20  * interfaces as 
08c0: 65 69 74 68 65 72 20 64 65 70 72 65 63 61 74 65  either deprecate
08d0: 64 20 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61  d or experimenta
08e0: 6c 2e 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74  l.  New applicat
08f0: 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e  ions.** should n
0900: 6f 74 20 75 73 65 20 64 65 70 72 65 63 61 74 65  ot use deprecate
0910: 64 20 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74  d interfaces - t
0920: 68 65 79 20 61 72 65 20 73 75 70 70 6f 72 74 65  hey are supporte
0930: 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a  d for backwards.
0940: 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ** compatibility
0950: 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69 63 61 74   only.  Applicat
0960: 69 6f 6e 20 77 72 69 74 65 72 73 20 73 68 6f 75  ion writers shou
0970: 6c 64 20 62 65 20 61 77 61 72 65 20 74 68 61 74  ld be aware that
0980: 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e 74 61 6c  .** experimental
0990: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
09a0: 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
09b0: 65 20 69 6e 20 70 6f 69 6e 74 20 72 65 6c 65 61  e in point relea
09c0: 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ses..**.** These
09d0: 20 6d 61 63 72 6f 73 20 75 73 65 64 20 74 6f 20   macros used to 
09e0: 72 65 73 6f 6c 76 65 20 74 6f 20 76 61 72 69 6f  resolve to vario
09f0: 75 73 20 6b 69 6e 64 73 20 6f 66 20 63 6f 6d 70  us kinds of comp
0a00: 69 6c 65 72 20 6d 61 67 69 63 20 74 68 61 74 0a  iler magic that.
0a10: 2a 2a 20 77 6f 75 6c 64 20 67 65 6e 65 72 61 74  ** would generat
0a20: 65 20 77 61 72 6e 69 6e 67 20 6d 65 73 73 61 67  e warning messag
0a30: 65 73 20 77 68 65 6e 20 74 68 65 79 20 77 65 72  es when they wer
0a40: 65 20 75 73 65 64 2e 20 20 42 75 74 20 74 68 61  e used.  But tha
0a50: 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72 20 6d 61  t.** compiler ma
0a60: 67 69 63 20 65 6e 64 65 64 20 75 70 20 67 65 6e  gic ended up gen
0a70: 65 72 61 74 69 6e 67 20 73 75 63 68 20 61 20 66  erating such a f
0a80: 6c 75 72 72 79 20 6f 66 20 62 75 67 20 72 65 70  lurry of bug rep
0a90: 6f 72 74 73 0a 2a 2a 20 74 68 61 74 20 77 65 20  orts.** that we 
0aa0: 68 61 76 65 20 74 61 6b 65 6e 20 69 74 20 61 6c  have taken it al
0ab0: 6c 20 6f 75 74 20 61 6e 64 20 67 6f 6e 65 20 62  l out and gone b
0ac0: 61 63 6b 20 74 6f 20 75 73 69 6e 67 20 73 69 6d  ack to using sim
0ad0: 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72  ple.** noop macr
0ae0: 6f 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  os..*/.#define S
0af0: 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
0b00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
0b10: 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a  EXPERIMENTAL../*
0b20: 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68 65 73 65  .** Ensure these
0b30: 20 73 79 6d 62 6f 6c 73 20 77 65 72 65 20 6e 6f   symbols were no
0b40: 74 20 64 65 66 69 6e 65 64 20 62 79 20 73 6f 6d  t defined by som
0b50: 65 20 70 72 65 76 69 6f 75 73 20 68 65 61 64 65  e previous heade
0b60: 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65  r file..*/.#ifde
0b70: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0b80: 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f  .# undef SQLITE_
0b90: 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69 66 0a 23  VERSION.#endif.#
0ba0: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52  ifdef SQLITE_VER
0bb0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 20 75 6e  SION_NUMBER.# un
0bc0: 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49  def SQLITE_VERSI
0bd0: 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e 64 69 66  ON_NUMBER.#endif
0be0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
0bf0: 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 4c  : Compile-Time L
0c00: 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e  ibrary Version N
0c10: 75 6d 62 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54  umbers.**.** ^(T
0c20: 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  he [SQLITE_VERSI
0c30: 4f 4e 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  ON] C preprocess
0c40: 6f 72 20 6d 61 63 72 6f 20 69 6e 20 74 68 65 20  or macro in the 
0c50: 73 71 6c 69 74 65 33 2e 68 20 68 65 61 64 65 72  sqlite3.h header
0c60: 0a 2a 2a 20 65 76 61 6c 75 61 74 65 73 20 74 6f  .** evaluates to
0c70: 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
0c80: 6c 20 74 68 61 74 20 69 73 20 74 68 65 20 53 51  l that is the SQ
0c90: 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 69 6e 20  Lite version in 
0ca0: 74 68 65 0a 2a 2a 20 66 6f 72 6d 61 74 20 22 58  the.** format "X
0cb0: 2e 59 2e 5a 22 20 77 68 65 72 65 20 58 20 69 73  .Y.Z" where X is
0cc0: 20 74 68 65 20 6d 61 6a 6f 72 20 76 65 72 73 69   the major versi
0cd0: 6f 6e 20 6e 75 6d 62 65 72 20 28 61 6c 77 61 79  on number (alway
0ce0: 73 20 33 20 66 6f 72 0a 2a 2a 20 53 51 4c 69 74  s 3 for.** SQLit
0cf0: 65 33 29 20 61 6e 64 20 59 20 69 73 20 74 68 65  e3) and Y is the
0d00: 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f 6e 20 6e   minor version n
0d10: 75 6d 62 65 72 20 61 6e 64 20 5a 20 69 73 20 74  umber and Z is t
0d20: 68 65 20 72 65 6c 65 61 73 65 20 6e 75 6d 62 65  he release numbe
0d30: 72 2e 29 5e 0a 2a 2a 20 5e 28 54 68 65 20 5b 53  r.)^.** ^(The [S
0d40: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
0d50: 4d 42 45 52 5d 20 43 20 70 72 65 70 72 6f 63 65  MBER] C preproce
0d60: 73 73 6f 72 20 6d 61 63 72 6f 20 72 65 73 6f 6c  ssor macro resol
0d70: 76 65 73 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ves to an intege
0d80: 72 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 76 61  r.** with the va
0d90: 6c 75 65 20 28 58 2a 31 30 30 30 30 30 30 20 2b  lue (X*1000000 +
0da0: 20 59 2a 31 30 30 30 20 2b 20 5a 29 20 77 68 65   Y*1000 + Z) whe
0db0: 72 65 20 58 2c 20 59 2c 20 61 6e 64 20 5a 20 61  re X, Y, and Z a
0dc0: 72 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 6e  re the same.** n
0dd0: 75 6d 62 65 72 73 20 75 73 65 64 20 69 6e 20 5b  umbers used in [
0de0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2e  SQLITE_VERSION].
0df0: 29 5e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  )^.** The SQLITE
0e00: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20  _VERSION_NUMBER 
0e10: 66 6f 72 20 61 6e 79 20 67 69 76 65 6e 20 72 65  for any given re
0e20: 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20  lease of SQLite 
0e30: 77 69 6c 6c 20 61 6c 73 6f 0a 2a 2a 20 62 65 20  will also.** be 
0e40: 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20  larger than the 
0e50: 72 65 6c 65 61 73 65 20 66 72 6f 6d 20 77 68 69  release from whi
0e60: 63 68 20 69 74 20 69 73 20 64 65 72 69 76 65 64  ch it is derived
0e70: 2e 20 20 45 69 74 68 65 72 20 59 20 77 69 6c 6c  .  Either Y will
0e80: 0a 2a 2a 20 62 65 20 68 65 6c 64 20 63 6f 6e 73  .** be held cons
0e90: 74 61 6e 74 20 61 6e 64 20 5a 20 77 69 6c 6c 20  tant and Z will 
0ea0: 62 65 20 69 6e 63 72 65 6d 65 6e 74 65 64 20 6f  be incremented o
0eb0: 72 20 65 6c 73 65 20 59 20 77 69 6c 6c 20 62 65  r else Y will be
0ec0: 20 69 6e 63 72 65 6d 65 6e 74 65 64 0a 2a 2a 20   incremented.** 
0ed0: 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 72 65  and Z will be re
0ee0: 73 65 74 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a  set to zero..**.
0ef0: 2a 2a 20 53 69 6e 63 65 20 5b 76 65 72 73 69 6f  ** Since [versio
0f00: 6e 20 33 2e 36 2e 31 38 5d 20 28 5b 64 61 74 65  n 3.6.18] ([date
0f10: 6f 66 3a 33 2e 36 2e 31 38 5d 29 2c 20 0a 2a 2a  of:3.6.18]), .**
0f20: 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 63   SQLite source c
0f30: 6f 64 65 20 68 61 73 20 62 65 65 6e 20 73 74 6f  ode has been sto
0f40: 72 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 3c 61  red in the.** <a
0f50: 20 68 72 65 66 3d 22 68 74 74 70 3a 2f 2f 77 77   href="http://ww
0f60: 77 2e 66 6f 73 73 69 6c 2d 73 63 6d 2e 6f 72 67  w.fossil-scm.org
0f70: 2f 22 3e 46 6f 73 73 69 6c 20 63 6f 6e 66 69 67  /">Fossil config
0f80: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65  uration manageme
0f90: 6e 74 0a 2a 2a 20 73 79 73 74 65 6d 3c 2f 61 3e  nt.** system</a>
0fa0: 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 53  .  ^The SQLITE_S
0fb0: 4f 55 52 43 45 5f 49 44 20 6d 61 63 72 6f 20 65  OURCE_ID macro e
0fc0: 76 61 6c 75 61 74 65 73 20 74 6f 0a 2a 2a 20 61  valuates to.** a
0fd0: 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 64   string which id
0fe0: 65 6e 74 69 66 69 65 73 20 61 20 70 61 72 74 69  entifies a parti
0ff0: 63 75 6c 61 72 20 63 68 65 63 6b 2d 69 6e 20 6f  cular check-in o
1000: 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 74 68  f SQLite.** with
1010: 69 6e 20 69 74 73 20 63 6f 6e 66 69 67 75 72 61  in its configura
1020: 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20  tion management 
1030: 73 79 73 74 65 6d 2e 20 20 5e 54 68 65 20 53 51  system.  ^The SQ
1040: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 0a 2a  LITE_SOURCE_ID.*
1050: 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e  * string contain
1060: 73 20 74 68 65 20 64 61 74 65 20 61 6e 64 20 74  s the date and t
1070: 69 6d 65 20 6f 66 20 74 68 65 20 63 68 65 63 6b  ime of the check
1080: 2d 69 6e 20 28 55 54 43 29 20 61 6e 64 20 61 20  -in (UTC) and a 
1090: 53 48 41 31 0a 2a 2a 20 6f 72 20 53 48 41 33 2d  SHA1.** or SHA3-
10a0: 32 35 36 20 68 61 73 68 20 6f 66 20 74 68 65 20  256 hash of the 
10b0: 65 6e 74 69 72 65 20 73 6f 75 72 63 65 20 74 72  entire source tr
10c0: 65 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ee..**.** See al
10d0: 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62  so: [sqlite3_lib
10e0: 76 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b  version()],.** [
10f0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1100: 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73  on_number()], [s
1110: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28  qlite3_sourceid(
1120: 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76  )],.** [sqlite_v
1130: 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  ersion()] and [s
1140: 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28  qlite_source_id(
1150: 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  )]..*/.#define S
1160: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20  QLITE_VERSION   
1170: 20 20 20 20 20 22 2d 2d 56 45 52 53 2d 2d 22 0a       "--VERS--".
1180: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
1190: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 2d 2d  ERSION_NUMBER --
11a0: 56 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d 2d  VERSION-NUMBER--
11b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
11c0: 53 4f 55 52 43 45 5f 49 44 20 20 20 20 20 20 22  SOURCE_ID      "
11d0: 2d 2d 53 4f 55 52 43 45 2d 49 44 2d 2d 22 0a 0a  --SOURCE-ID--"..
11e0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
11f0: 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79  Run-Time Library
1200: 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73   Version Numbers
1210: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71  .** KEYWORDS: sq
1220: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 20 73 71  lite3_version sq
1230: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 0a 2a  lite3_sourceid.*
1240: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 72  *.** These inter
1250: 66 61 63 65 73 20 70 72 6f 76 69 64 65 20 74 68  faces provide th
1260: 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69  e same informati
1270: 6f 6e 20 61 73 20 74 68 65 20 5b 53 51 4c 49 54  on as the [SQLIT
1280: 45 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b  E_VERSION],.** [
1290: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
12a0: 55 4d 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51 4c  UMBER], and [SQL
12b0: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43  ITE_SOURCE_ID] C
12c0: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
12d0: 63 72 6f 73 0a 2a 2a 20 62 75 74 20 61 72 65 20  cros.** but are 
12e0: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
12f0: 74 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74  the library inst
1300: 65 61 64 20 6f 66 20 74 68 65 20 68 65 61 64 65  ead of the heade
1310: 72 20 66 69 6c 65 2e 20 20 5e 28 43 61 75 74 69  r file.  ^(Cauti
1320: 6f 75 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d 65  ous.** programme
1330: 72 73 20 6d 69 67 68 74 20 69 6e 63 6c 75 64 65  rs might include
1340: 20 61 73 73 65 72 74 28 29 20 73 74 61 74 65 6d   assert() statem
1350: 65 6e 74 73 20 69 6e 20 74 68 65 69 72 20 61 70  ents in their ap
1360: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20  plication to.** 
1370: 76 65 72 69 66 79 20 74 68 61 74 20 76 61 6c 75  verify that valu
1380: 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  es returned by t
1390: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
13a0: 6d 61 74 63 68 20 74 68 65 20 6d 61 63 72 6f 73  match the macros
13b0: 20 69 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64 65   in.** the heade
13c0: 72 2c 20 61 6e 64 20 74 68 75 73 20 65 6e 73 75  r, and thus ensu
13d0: 72 65 20 74 68 61 74 20 74 68 65 20 61 70 70 6c  re that the appl
13e0: 69 63 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f  ication is.** co
13f0: 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 61 74 63  mpiled with matc
1400: 68 69 6e 67 20 6c 69 62 72 61 72 79 20 61 6e 64  hing library and
1410: 20 68 65 61 64 65 72 20 66 69 6c 65 73 2e 0a 2a   header files..*
1420: 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1430: 3e 3c 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72 74  ><pre>.** assert
1440: 28 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  ( sqlite3_libver
1450: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d 53  sion_number()==S
1460: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
1470: 4d 42 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65 72  MBER );.** asser
1480: 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65  t( strcmp(sqlite
1490: 33 5f 73 6f 75 72 63 65 69 64 28 29 2c 53 51 4c  3_sourceid(),SQL
14a0: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 29 3d 3d  ITE_SOURCE_ID)==
14b0: 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20  0 );.** assert( 
14c0: 73 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 6c  strcmp(sqlite3_l
14d0: 69 62 76 65 72 73 69 6f 6e 28 29 2c 53 51 4c 49  ibversion(),SQLI
14e0: 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d 30 20 29  TE_VERSION)==0 )
14f0: 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
1500: 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a  ckquote>)^.**.**
1510: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 65   ^The sqlite3_ve
1520: 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63  rsion[] string c
1530: 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61 69 6e 73  onstant contains
1540: 20 74 68 65 20 74 65 78 74 20 6f 66 20 5b 53 51   the text of [SQ
1550: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a  LITE_VERSION].**
1560: 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65 20 73 71   macro.  ^The sq
1570: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1580: 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  () function retu
1590: 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
15a0: 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68 65 20 73   the.** to the s
15b0: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
15c0: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74   string constant
15d0: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c  .  The sqlite3_l
15e0: 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a 2a 20 66  ibversion().** f
15f0: 75 6e 63 74 69 6f 6e 20 69 73 20 70 72 6f 76 69  unction is provi
1600: 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 44  ded for use in D
1610: 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c 20 75 73  LLs since DLL us
1620: 65 72 73 20 75 73 75 61 6c 6c 79 20 64 6f 20 6e  ers usually do n
1630: 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69 72 65 63  ot have.** direc
1640: 74 20 61 63 63 65 73 73 20 74 6f 20 73 74 72 69  t access to stri
1650: 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20 77 69 74  ng constants wit
1660: 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20 20 5e 54  hin the DLL.  ^T
1670: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c 69  he.** sqlite3_li
1680: 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28  bversion_number(
1690: 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ) function retur
16a0: 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 65 71  ns an integer eq
16b0: 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54  ual to.** [SQLIT
16c0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
16d0: 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  ].  ^The sqlite3
16e0: 5f 73 6f 75 72 63 65 69 64 28 29 20 66 75 6e 63  _sourceid() func
16f0: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 0a 2a 2a  tion returns .**
1700: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
1710: 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20  string constant 
1720: 77 68 6f 73 65 20 76 61 6c 75 65 20 69 73 20 74  whose value is t
1730: 68 65 20 73 61 6d 65 20 61 73 20 74 68 65 20 0a  he same as the .
1740: 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43  ** [SQLITE_SOURC
1750: 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f 63 65  E_ID] C preproce
1760: 73 73 6f 72 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a  ssor macro..**.*
1770: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
1780: 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d 20 61  ite_version()] a
1790: 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75 72 63  nd [sqlite_sourc
17a0: 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49  e_id()]..*/.SQLI
17b0: 54 45 5f 45 58 54 45 52 4e 20 63 6f 6e 73 74 20  TE_EXTERN const 
17c0: 63 68 61 72 20 73 71 6c 69 74 65 33 5f 76 65 72  char sqlite3_ver
17d0: 73 69 6f 6e 5b 5d 3b 0a 63 6f 6e 73 74 20 63 68  sion[];.const ch
17e0: 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62 76  ar *sqlite3_libv
17f0: 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 63 6f  ersion(void);.co
1800: 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
1810: 33 5f 73 6f 75 72 63 65 69 64 28 76 6f 69 64 29  3_sourceid(void)
1820: 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69  ;.int sqlite3_li
1830: 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28  bversion_number(
1840: 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  void);../*.** CA
1850: 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65  PI3REF: Run-Time
1860: 20 4c 69 62 72 61 72 79 20 43 6f 6d 70 69 6c 61   Library Compila
1870: 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 44 69 61  tion Options Dia
1880: 67 6e 6f 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 5e  gnostics.**.** ^
1890: 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  The sqlite3_comp
18a0: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
18b0: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
18c0: 73 20 30 20 6f 72 20 31 20 0a 2a 2a 20 69 6e 64  s 0 or 1 .** ind
18d0: 69 63 61 74 69 6e 67 20 77 68 65 74 68 65 72 20  icating whether 
18e0: 74 68 65 20 73 70 65 63 69 66 69 65 64 20 6f 70  the specified op
18f0: 74 69 6f 6e 20 77 61 73 20 64 65 66 69 6e 65 64  tion was defined
1900: 20 61 74 20 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20   at .** compile 
1910: 74 69 6d 65 2e 20 20 5e 54 68 65 20 53 51 4c 49  time.  ^The SQLI
1920: 54 45 5f 20 70 72 65 66 69 78 20 6d 61 79 20 62  TE_ prefix may b
1930: 65 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74  e omitted from t
1940: 68 65 20 0a 2a 2a 20 6f 70 74 69 6f 6e 20 6e 61  he .** option na
1950: 6d 65 20 70 61 73 73 65 64 20 74 6f 20 73 71 6c  me passed to sql
1960: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
1970: 6f 6e 5f 75 73 65 64 28 29 2e 20 20 0a 2a 2a 0a  on_used().  .**.
1980: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1990: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65  compileoption_ge
19a0: 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 6c 6c  t() function all
19b0: 6f 77 73 20 69 74 65 72 61 74 69 6e 67 0a 2a 2a  ows iterating.**
19c0: 20 6f 76 65 72 20 74 68 65 20 6c 69 73 74 20 6f   over the list o
19d0: 66 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 77  f options that w
19e0: 65 72 65 20 64 65 66 69 6e 65 64 20 61 74 20 63  ere defined at c
19f0: 6f 6d 70 69 6c 65 20 74 69 6d 65 20 62 79 0a 2a  ompile time by.*
1a00: 2a 20 72 65 74 75 72 6e 69 6e 67 20 74 68 65 20  * returning the 
1a10: 4e 2d 74 68 20 63 6f 6d 70 69 6c 65 20 74 69 6d  N-th compile tim
1a20: 65 20 6f 70 74 69 6f 6e 20 73 74 72 69 6e 67 2e  e option string.
1a30: 20 20 5e 49 66 20 4e 20 69 73 20 6f 75 74 20 6f    ^If N is out o
1a40: 66 20 72 61 6e 67 65 2c 0a 2a 2a 20 73 71 6c 69  f range,.** sqli
1a50: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
1a60: 6e 5f 67 65 74 28 29 20 72 65 74 75 72 6e 73 20  n_get() returns 
1a70: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
1a80: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 0a 2a   ^The SQLITE_ .*
1a90: 2a 20 70 72 65 66 69 78 20 69 73 20 6f 6d 69 74  * prefix is omit
1aa0: 74 65 64 20 66 72 6f 6d 20 61 6e 79 20 73 74 72  ted from any str
1ab0: 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
1ac0: 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d   .** sqlite3_com
1ad0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29  pileoption_get()
1ae0: 2e 0a 2a 2a 0a 2a 2a 20 5e 53 75 70 70 6f 72 74  ..**.** ^Support
1af0: 20 66 6f 72 20 74 68 65 20 64 69 61 67 6e 6f 73   for the diagnos
1b00: 74 69 63 20 66 75 6e 63 74 69 6f 6e 73 20 73 71  tic functions sq
1b10: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1b20: 69 6f 6e 5f 75 73 65 64 28 29 0a 2a 2a 20 61 6e  ion_used().** an
1b30: 64 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  d sqlite3_compil
1b40: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 6d 61  eoption_get() ma
1b50: 79 20 62 65 20 6f 6d 69 74 74 65 64 20 62 79 20  y be omitted by 
1b60: 73 70 65 63 69 66 79 69 6e 67 20 74 68 65 20 0a  specifying the .
1b70: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  ** [SQLITE_OMIT_
1b80: 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49  COMPILEOPTION_DI
1b90: 41 47 53 5d 20 6f 70 74 69 6f 6e 20 61 74 20 63  AGS] option at c
1ba0: 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 0a 2a 2a 0a  ompile time..**.
1bb0: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 53 51 4c  ** See also: SQL
1bc0: 20 66 75 6e 63 74 69 6f 6e 73 20 5b 73 71 6c 69   functions [sqli
1bd0: 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  te_compileoption
1be0: 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20  _used()] and.** 
1bf0: 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f  [sqlite_compileo
1c00: 70 74 69 6f 6e 5f 67 65 74 28 29 5d 20 61 6e 64  ption_get()] and
1c10: 20 74 68 65 20 5b 63 6f 6d 70 69 6c 65 5f 6f 70   the [compile_op
1c20: 74 69 6f 6e 73 20 70 72 61 67 6d 61 5d 2e 0a 2a  tions pragma]..*
1c30: 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  /.#ifndef SQLITE
1c40: 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54  _OMIT_COMPILEOPT
1c50: 49 4f 4e 5f 44 49 41 47 53 0a 69 6e 74 20 73 71  ION_DIAGS.int sq
1c60: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1c70: 69 6f 6e 5f 75 73 65 64 28 63 6f 6e 73 74 20 63  ion_used(const c
1c80: 68 61 72 20 2a 7a 4f 70 74 4e 61 6d 65 29 3b 0a  har *zOptName);.
1c90: 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
1ca0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
1cb0: 6e 5f 67 65 74 28 69 6e 74 20 4e 29 3b 0a 23 65  n_get(int N);.#e
1cc0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
1cd0: 33 52 45 46 3a 20 54 65 73 74 20 54 6f 20 53 65  3REF: Test To Se
1ce0: 65 20 49 66 20 54 68 65 20 4c 69 62 72 61 72 79  e If The Library
1cf0: 20 49 73 20 54 68 72 65 61 64 73 61 66 65 0a 2a   Is Threadsafe.*
1d00: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1d10: 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 20 66  3_threadsafe() f
1d20: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1d30: 7a 65 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79  zero if and only
1d40: 20 69 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61   if.** SQLite wa
1d50: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
1d60: 6d 75 74 65 78 69 6e 67 20 63 6f 64 65 20 6f 6d  mutexing code om
1d70: 69 74 74 65 64 20 64 75 65 20 74 6f 20 74 68 65  itted due to the
1d80: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  .** [SQLITE_THRE
1d90: 41 44 53 41 46 45 5d 20 63 6f 6d 70 69 6c 65 2d  ADSAFE] compile-
1da0: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 62 65 69 6e  time option bein
1db0: 67 20 73 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a  g set to 0..**.*
1dc0: 2a 20 53 51 4c 69 74 65 20 63 61 6e 20 62 65 20  * SQLite can be 
1dd0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6f 72  compiled with or
1de0: 20 77 69 74 68 6f 75 74 20 6d 75 74 65 78 65 73   without mutexes
1df0: 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b  .  When.** the [
1e00: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1e10: 45 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f  E] C preprocesso
1e20: 72 20 6d 61 63 72 6f 20 69 73 20 31 20 6f 72 20  r macro is 1 or 
1e30: 32 2c 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72  2, mutexes.** ar
1e40: 65 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 53 51  e enabled and SQ
1e50: 4c 69 74 65 20 69 73 20 74 68 72 65 61 64 73 61  Lite is threadsa
1e60: 66 65 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a  fe.  When the.**
1e70: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
1e80: 41 46 45 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c  AFE] macro is 0,
1e90: 20 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73   .** the mutexes
1ea0: 20 61 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 57   are omitted.  W
1eb0: 69 74 68 6f 75 74 20 74 68 65 20 6d 75 74 65 78  ithout the mutex
1ec0: 65 73 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 61  es, it is not sa
1ed0: 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c  fe.** to use SQL
1ee0: 69 74 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79  ite concurrently
1ef0: 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20   from more than 
1f00: 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a  one thread..**.*
1f10: 2a 20 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78  * Enabling mutex
1f20: 65 73 20 69 6e 63 75 72 73 20 61 20 6d 65 61 73  es incurs a meas
1f30: 75 72 61 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e  urable performan
1f40: 63 65 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53  ce penalty..** S
1f50: 6f 20 69 66 20 73 70 65 65 64 20 69 73 20 6f 66  o if speed is of
1f60: 20 75 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e   utmost importan
1f70: 63 65 2c 20 69 74 20 6d 61 6b 65 73 20 73 65 6e  ce, it makes sen
1f80: 73 65 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a  se to disable.**
1f90: 20 74 68 65 20 6d 75 74 65 78 65 73 2e 20 20 42   the mutexes.  B
1fa0: 75 74 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73  ut for maximum s
1fb0: 61 66 65 74 79 2c 20 6d 75 74 65 78 65 73 20 73  afety, mutexes s
1fc0: 68 6f 75 6c 64 20 62 65 20 65 6e 61 62 6c 65 64  hould be enabled
1fd0: 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  ..** ^The defaul
1fe0: 74 20 62 65 68 61 76 69 6f 72 20 69 73 20 66 6f  t behavior is fo
1ff0: 72 20 6d 75 74 65 78 65 73 20 74 6f 20 62 65 20  r mutexes to be 
2000: 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  enabled..**.** T
2010: 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61  his interface ca
2020: 6e 20 62 65 20 75 73 65 64 20 62 79 20 61 6e 20  n be used by an 
2030: 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 6d  application to m
2040: 61 6b 65 20 73 75 72 65 20 74 68 61 74 20 74 68  ake sure that th
2050: 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20  e.** version of 
2060: 53 51 4c 69 74 65 20 74 68 61 74 20 69 74 20 69  SQLite that it i
2070: 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73  s linking agains
2080: 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  t was compiled w
2090: 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 73 69 72  ith.** the desir
20a0: 65 64 20 73 65 74 74 69 6e 67 20 6f 66 20 74 68  ed setting of th
20b0: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
20c0: 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a  SAFE] macro..**.
20d0: 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
20e0: 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f  e only reports o
20f0: 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69  n the compile-ti
2100: 6d 65 20 6d 75 74 65 78 20 73 65 74 74 69 6e 67  me mutex setting
2110: 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  .** of the [SQLI
2120: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 66  TE_THREADSAFE] f
2130: 6c 61 67 2e 20 20 49 66 20 53 51 4c 69 74 65 20  lag.  If SQLite 
2140: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
2150: 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48 52 45 41  .** SQLITE_THREA
2160: 44 53 41 46 45 3d 31 20 6f 72 20 3d 32 20 74 68  DSAFE=1 or =2 th
2170: 65 6e 20 6d 75 74 65 78 65 73 20 61 72 65 20 65  en mutexes are e
2180: 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  nabled by defaul
2190: 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20  t but.** can be 
21a0: 66 75 6c 6c 79 20 6f 72 20 70 61 72 74 69 61 6c  fully or partial
21b0: 6c 79 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e  ly disabled usin
21c0: 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  g a call to [sql
21d0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a  ite3_config()].*
21e0: 2a 20 77 69 74 68 20 74 68 65 20 76 65 72 62 73  * with the verbs
21f0: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
2200: 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b  SINGLETHREAD], [
2210: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
2220: 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f  LTITHREAD],.** o
2230: 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  r [SQLITE_CONFIG
2240: 5f 53 45 52 49 41 4c 49 5a 45 44 5d 2e 20 20 5e  _SERIALIZED].  ^
2250: 28 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75  (The return valu
2260: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c 69  e of the.** sqli
2270: 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29  te3_threadsafe()
2280: 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 20   function shows 
2290: 6f 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c 65  only the compile
22a0: 2d 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f 66  -time setting of
22b0: 0a 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65 74  .** thread safet
22c0: 79 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74  y, not any run-t
22d0: 69 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20 74  ime changes to t
22e0: 68 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64 65  hat setting made
22f0: 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   by.** sqlite3_c
2300: 6f 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68 65  onfig(). In othe
2310: 72 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65 74  r words, the ret
2320: 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  urn value from s
2330: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
2340: 65 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61 6e  e().** is unchan
2350: 67 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f 20  ged by calls to 
2360: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
2370: 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68  .)^.**.** See th
2380: 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  e [threading mod
2390: 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  e] documentation
23a0: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
23b0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
23c0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65  int sqlite3_thre
23d0: 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f  adsafe(void);../
23e0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
23f0: 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
2400: 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59  on Handle.** KEY
2410: 57 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65  WORDS: {database
2420: 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61   connection} {da
2430: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2440: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f  ns}.**.** Each o
2450: 70 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62  pen SQLite datab
2460: 61 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74  ase is represent
2470: 65 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20  ed by a pointer 
2480: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
2490: 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20  f.** the opaque 
24a0: 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20  structure named 
24b0: 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69  "sqlite3".  It i
24c0: 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e  s useful to thin
24d0: 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a  k of an sqlite3.
24e0: 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e  ** pointer as an
24f0: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73   object.  The [s
2500: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
2510: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
2520: 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
2530: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69  te3_open_v2()] i
2540: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 74  nterfaces are it
2550: 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20  s constructors, 
2560: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  and [sqlite3_clo
2570: 73 65 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  se()].** and [sq
2580: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
2590: 5d 20 61 72 65 20 69 74 73 20 64 65 73 74 72 75  ] are its destru
25a0: 63 74 6f 72 73 2e 20 20 54 68 65 72 65 20 61 72  ctors.  There ar
25b0: 65 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20  e many other.** 
25c0: 69 6e 74 65 72 66 61 63 65 73 20 28 73 75 63 68  interfaces (such
25d0: 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   as.** [sqlite3_
25e0: 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b  prepare_v2()], [
25f0: 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2600: 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a  unction()], and.
2610: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ** [sqlite3_busy
2620: 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20 6e  _timeout()] to n
2630: 61 6d 65 20 62 75 74 20 74 68 72 65 65 29 20 74  ame but three) t
2640: 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73 20  hat are methods 
2650: 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33  on an.** sqlite3
2660: 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65   object..*/.type
2670: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
2680: 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a  e3 sqlite3;../*.
2690: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34 2d  ** CAPI3REF: 64-
26a0: 42 69 74 20 49 6e 74 65 67 65 72 20 54 79 70 65  Bit Integer Type
26b0: 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73  s.** KEYWORDS: s
26c0: 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69  qlite_int64 sqli
26d0: 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20  te_uint64.**.** 
26e0: 42 65 63 61 75 73 65 20 74 68 65 72 65 20 69 73  Because there is
26f0: 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f   no cross-platfo
2700: 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69 66  rm way to specif
2710: 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72  y 64-bit integer
2720: 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65   types.** SQLite
2730: 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64 65   includes typede
2740: 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73 69  fs for 64-bit si
2750: 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e 65  gned and unsigne
2760: 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a  d integers..**.*
2770: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  * The sqlite3_in
2780: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t64 and sqlite3_
2790: 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 20 70  uint64 are the p
27a0: 72 65 66 65 72 72 65 64 20 74 79 70 65 20 64 65  referred type de
27b0: 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68  finitions..** Th
27c0: 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 61  e sqlite_int64 a
27d0: 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  nd sqlite_uint64
27e0: 20 74 79 70 65 73 20 61 72 65 20 73 75 70 70 6f   types are suppo
27f0: 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  rted for backwar
2800: 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  ds.** compatibil
2810: 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ity only..**.** 
2820: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  ^The sqlite3_int
2830: 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 69 6e  64 and sqlite_in
2840: 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73 74  t64 types can st
2850: 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  ore integer valu
2860: 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 2d 39  es.** between -9
2870: 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38  2233720368547758
2880: 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37 32 30  08 and +92233720
2890: 33 36 38 35 34 37 37 35 38 30 37 20 69 6e 63 6c  36854775807 incl
28a0: 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a 2a 20  usive.  ^The.** 
28b0: 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61  sqlite3_uint64 a
28c0: 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  nd sqlite_uint64
28d0: 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72 65   types can store
28e0: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
28f0: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e  .** between 0 an
2900: 64 20 2b 31 38 34 34 36 37 34 34 30 37 33 37 30  d +1844674407370
2910: 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73 69 76  9551615 inclusiv
2920: 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c  e..*/.#ifdef SQL
2930: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a 20  ITE_INT64_TYPE. 
2940: 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f   typedef SQLITE_
2950: 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74  INT64_TYPE sqlit
2960: 65 5f 69 6e 74 36 34 3b 0a 23 20 69 66 64 65 66  e_int64;.# ifdef
2970: 20 53 51 4c 49 54 45 5f 55 49 4e 54 36 34 5f 54   SQLITE_UINT64_T
2980: 59 50 45 0a 20 20 20 20 74 79 70 65 64 65 66 20  YPE.    typedef 
2990: 53 51 4c 49 54 45 5f 55 49 4e 54 36 34 5f 54 59  SQLITE_UINT64_TY
29a0: 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  PE sqlite_uint64
29b0: 3b 0a 23 20 65 6c 73 65 20 20 0a 20 20 20 20 74  ;.# else  .    t
29c0: 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20  ypedef unsigned 
29d0: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
29e0: 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b  E sqlite_uint64;
29f0: 0a 23 20 65 6e 64 69 66 0a 23 65 6c 69 66 20 64  .# endif.#elif d
2a00: 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29  efined(_MSC_VER)
2a10: 20 7c 7c 20 64 65 66 69 6e 65 64 28 5f 5f 42 4f   || defined(__BO
2a20: 52 4c 41 4e 44 43 5f 5f 29 0a 20 20 74 79 70 65  RLANDC__).  type
2a30: 64 65 66 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69  def __int64 sqli
2a40: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
2a50: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 5f 5f 69  def unsigned __i
2a60: 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74  nt64 sqlite_uint
2a70: 36 34 3b 0a 23 65 6c 73 65 0a 20 20 74 79 70 65  64;.#else.  type
2a80: 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e  def long long in
2a90: 74 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  t sqlite_int64;.
2aa0: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
2ab0: 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74  ed long long int
2ac0: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a   sqlite_uint64;.
2ad0: 23 65 6e 64 69 66 0a 74 79 70 65 64 65 66 20 73  #endif.typedef s
2ae0: 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69  qlite_int64 sqli
2af0: 74 65 33 5f 69 6e 74 36 34 3b 0a 74 79 70 65 64  te3_int64;.typed
2b00: 65 66 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  ef sqlite_uint64
2b10: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 3b   sqlite3_uint64;
2b20: 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70 69  ../*.** If compi
2b30: 6c 69 6e 67 20 66 6f 72 20 61 20 70 72 6f 63 65  ling for a proce
2b40: 73 73 6f 72 20 74 68 61 74 20 6c 61 63 6b 73 20  ssor that lacks 
2b50: 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 73  floating point s
2b60: 75 70 70 6f 72 74 2c 0a 2a 2a 20 73 75 62 73 74  upport,.** subst
2b70: 69 74 75 74 65 20 69 6e 74 65 67 65 72 20 66 6f  itute integer fo
2b80: 72 20 66 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e 74  r floating-point
2b90: 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49  ..*/.#ifdef SQLI
2ba0: 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47  TE_OMIT_FLOATING
2bb0: 5f 50 4f 49 4e 54 0a 23 20 64 65 66 69 6e 65 20  _POINT.# define 
2bc0: 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 69  double sqlite3_i
2bd0: 6e 74 36 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  nt64.#endif../*.
2be0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6c 6f  ** CAPI3REF: Clo
2bf0: 73 69 6e 67 20 41 20 44 61 74 61 62 61 73 65 20  sing A Database 
2c00: 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 44 45  Connection.** DE
2c10: 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65  STRUCTOR: sqlite
2c20: 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  3.**.** ^The sql
2c30: 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64  ite3_close() and
2c40: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76   sqlite3_close_v
2c50: 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65  2() routines are
2c60: 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a 2a 20   destructors.** 
2c70: 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33  for the [sqlite3
2c80: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 43 61  ] object..** ^Ca
2c90: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
2ca0: 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74  lose() and sqlit
2cb0: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 65  e3_close_v2() re
2cc0: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
2cd0: 20 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69   if.** the [sqli
2ce0: 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 73  te3] object is s
2cf0: 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74  uccessfully dest
2d00: 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73  royed and all as
2d10: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f  sociated.** reso
2d20: 75 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f  urces are deallo
2d30: 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  cated..**.** ^If
2d40: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2d50: 6e 6e 65 63 74 69 6f 6e 20 69 73 20 61 73 73 6f  nnection is asso
2d60: 63 69 61 74 65 64 20 77 69 74 68 20 75 6e 66 69  ciated with unfi
2d70: 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64  nalized prepared
2d80: 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 6f  .** statements o
2d90: 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c  r unfinished sql
2da0: 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65  ite3_backup obje
2db0: 63 74 73 20 74 68 65 6e 20 73 71 6c 69 74 65 33  cts then sqlite3
2dc0: 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c  _close().** will
2dd0: 20 6c 65 61 76 65 20 74 68 65 20 64 61 74 61 62   leave the datab
2de0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
2df0: 70 65 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 5b  pen and return [
2e00: 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a  SQLITE_BUSY]..**
2e10: 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f   ^If sqlite3_clo
2e20: 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65  se_v2() is calle
2e30: 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a  d with unfinaliz
2e40: 65 64 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ed prepared stat
2e50: 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 2f 6f 72  ements.** and/or
2e60: 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c 69   unfinished sqli
2e70: 74 65 33 5f 62 61 63 6b 75 70 73 2c 20 74 68 65  te3_backups, the
2e80: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
2e90: 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 63 6f 6d 65  onnection become
2ea0: 73 0a 2a 2a 20 61 6e 20 75 6e 75 73 61 62 6c 65  s.** an unusable
2eb0: 20 22 7a 6f 6d 62 69 65 22 20 77 68 69 63 68 20   "zombie" which 
2ec0: 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c  will automatical
2ed0: 6c 79 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  ly be deallocate
2ee0: 64 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 6c 61  d when the.** la
2ef0: 73 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74  st prepared stat
2f00: 65 6d 65 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a  ement is finaliz
2f10: 65 64 20 6f 72 20 74 68 65 20 6c 61 73 74 20 73  ed or the last s
2f20: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 69 73  qlite3_backup is
2f30: 0a 2a 2a 20 66 69 6e 69 73 68 65 64 2e 20 20 54  .** finished.  T
2f40: 68 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  he sqlite3_close
2f50: 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20  _v2() interface 
2f60: 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  is intended for 
2f70: 75 73 65 20 77 69 74 68 0a 2a 2a 20 68 6f 73 74  use with.** host
2f80: 20 6c 61 6e 67 75 61 67 65 73 20 74 68 61 74 20   languages that 
2f90: 61 72 65 20 67 61 72 62 61 67 65 20 63 6f 6c 6c  are garbage coll
2fa0: 65 63 74 65 64 2c 20 61 6e 64 20 77 68 65 72 65  ected, and where
2fb0: 20 74 68 65 20 6f 72 64 65 72 20 69 6e 20 77 68   the order in wh
2fc0: 69 63 68 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f  ich.** destructo
2fd0: 72 73 20 61 72 65 20 63 61 6c 6c 65 64 20 69 73  rs are called is
2fe0: 20 61 72 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a   arbitrary..**.*
2ff0: 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  * Applications s
3000: 68 6f 75 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66  hould [sqlite3_f
3010: 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69  inalize | finali
3020: 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70 61 72 65  ze] all [prepare
3030: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a  d statements],.*
3040: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  * [sqlite3_blob_
3050: 63 6c 6f 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61  close | close] a
3060: 6c 6c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73  ll [BLOB handles
3070: 5d 2c 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69  ], and .** [sqli
3080: 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73  te3_backup_finis
3090: 68 20 7c 20 66 69 6e 69 73 68 5d 20 61 6c 6c 20  h | finish] all 
30a0: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d  [sqlite3_backup]
30b0: 20 6f 62 6a 65 63 74 73 20 61 73 73 6f 63 69 61   objects associa
30c0: 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ted.** with the 
30d0: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
30e0: 20 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70   prior to attemp
30f0: 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68  ting to close th
3100: 65 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a  e object.  ^If.*
3110: 2a 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f  * sqlite3_close_
3120: 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20 6f  v2() is called o
3130: 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  n a [database co
3140: 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 73  nnection] that s
3150: 74 69 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75 74 73  till has.** outs
3160: 74 61 6e 64 69 6e 67 20 5b 70 72 65 70 61 72 65  tanding [prepare
3170: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b  d statements], [
3180: 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61  BLOB handles], a
3190: 6e 64 2f 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  nd/or.** [sqlite
31a0: 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74  3_backup] object
31b0: 73 20 74 68 65 6e 20 69 74 20 72 65 74 75 72 6e  s then it return
31c0: 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 61 6e  s [SQLITE_OK] an
31d0: 64 20 74 68 65 20 64 65 61 6c 6c 6f 63 61 74 69  d the deallocati
31e0: 6f 6e 0a 2a 2a 20 6f 66 20 72 65 73 6f 75 72 63  on.** of resourc
31f0: 65 73 20 69 73 20 64 65 66 65 72 72 65 64 20 75  es is deferred u
3200: 6e 74 69 6c 20 61 6c 6c 20 5b 70 72 65 70 61 72  ntil all [prepar
3210: 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20  ed statements], 
3220: 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 0a  [BLOB handles],.
3230: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
3240: 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20  backup] objects 
3250: 61 72 65 20 61 6c 73 6f 20 64 65 73 74 72 6f 79  are also destroy
3260: 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ed..**.** ^If an
3270: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
3280: 74 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 77  t is destroyed w
3290: 68 69 6c 65 20 61 20 74 72 61 6e 73 61 63 74 69  hile a transacti
32a0: 6f 6e 20 69 73 20 6f 70 65 6e 2c 0a 2a 2a 20 74  on is open,.** t
32b0: 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69  he transaction i
32c0: 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  s automatically 
32d0: 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a  rolled back..**.
32e0: 2a 2a 20 54 68 65 20 43 20 70 61 72 61 6d 65 74  ** The C paramet
32f0: 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  er to [sqlite3_c
3300: 6c 6f 73 65 28 43 29 5d 20 61 6e 64 20 5b 73 71  lose(C)] and [sq
3310: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 43  lite3_close_v2(C
3320: 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69  )].** must be ei
3330: 74 68 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70  ther a NULL.** p
3340: 6f 69 6e 74 65 72 20 6f 72 20 61 6e 20 5b 73 71  ointer or an [sq
3350: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 6f  lite3] object po
3360: 69 6e 74 65 72 20 6f 62 74 61 69 6e 65 64 0a 2a  inter obtained.*
3370: 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
3380: 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
3390: 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 0a  3_open16()], or.
33a0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ** [sqlite3_open
33b0: 5f 76 32 28 29 5d 2c 20 61 6e 64 20 6e 6f 74 20  _v2()], and not 
33c0: 70 72 65 76 69 6f 75 73 6c 79 20 63 6c 6f 73 65  previously close
33d0: 64 2e 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73  d..** ^Calling s
33e0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 6f  qlite3_close() o
33f0: 72 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f  r sqlite3_close_
3400: 76 32 28 29 20 77 69 74 68 20 61 20 4e 55 4c 4c  v2() with a NULL
3410: 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 61 72 67 75   pointer.** argu
3420: 6d 65 6e 74 20 69 73 20 61 20 68 61 72 6d 6c 65  ment is a harmle
3430: 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 69 6e 74  ss no-op..*/.int
3440: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 73   sqlite3_close(s
3450: 71 6c 69 74 65 33 2a 29 3b 0a 69 6e 74 20 73 71  qlite3*);.int sq
3460: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 73  lite3_close_v2(s
3470: 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
3480: 20 54 68 65 20 74 79 70 65 20 66 6f 72 20 61 20   The type for a 
3490: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
34a0: 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 6c 65  n..** This is le
34b0: 67 61 63 79 20 61 6e 64 20 64 65 70 72 65 63 61  gacy and depreca
34c0: 74 65 64 2e 20 20 49 74 20 69 73 20 69 6e 63 6c  ted.  It is incl
34d0: 75 64 65 64 20 66 6f 72 20 68 69 73 74 6f 72 69  uded for histori
34e0: 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69  cal.** compatibi
34f0: 6c 69 74 79 20 61 6e 64 20 69 73 20 6e 6f 74 20  lity and is not 
3500: 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74  documented..*/.t
3510: 79 70 65 64 65 66 20 69 6e 74 20 28 2a 73 71 6c  ypedef int (*sql
3520: 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76  ite3_callback)(v
3530: 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c  oid*,int,char**,
3540: 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a   char**);../*.**
3550: 20 43 41 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53   CAPI3REF: One-S
3560: 74 65 70 20 51 75 65 72 79 20 45 78 65 63 75 74  tep Query Execut
3570: 69 6f 6e 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a  ion Interface.**
3580: 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
3590: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
35a0: 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66  e3_exec() interf
35b0: 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e 69  ace is a conveni
35c0: 65 6e 63 65 20 77 72 61 70 70 65 72 20 61 72 6f  ence wrapper aro
35d0: 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  und.** [sqlite3_
35e0: 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b  prepare_v2()], [
35f0: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c  sqlite3_step()],
3600: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 69   and [sqlite3_fi
3610: 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74 68  nalize()],.** th
3620: 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70 70  at allows an app
3630: 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e 20  lication to run 
3640: 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d 65  multiple stateme
3650: 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77 69  nts of SQL.** wi
3660: 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f 20  thout having to 
3670: 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20 63  use a lot of C c
3680: 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ode. .**.** ^The
3690: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
36a0: 69 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20 7a  interface runs z
36b0: 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46 2d  ero or more UTF-
36c0: 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73 65  8 encoded,.** se
36d0: 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65  micolon-separate
36e0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
36f0: 70 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73 20  passed into its 
3700: 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a 2a  2nd argument,.**
3710: 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74 20   in the context 
3720: 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  of the [database
3730: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61 73   connection] pas
3740: 73 65 64 20 69 6e 20 61 73 20 69 74 73 20 31 73  sed in as its 1s
3750: 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20  t.** argument.  
3760: 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ^If the callback
3770: 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68 65   function of the
3780: 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f   3rd argument to
3790: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
37a0: 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  () is not NULL, 
37b0: 74 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f 6b  then it is invok
37c0: 65 64 20 66 6f 72 20 65 61 63 68 20 72 65 73 75  ed for each resu
37d0: 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e 67  lt row.** coming
37e0: 20 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61 6c   out of the eval
37f0: 75 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  uated SQL statem
3800: 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68 20  ents.  ^The 4th 
3810: 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73  argument to.** s
3820: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3830: 20 72 65 6c 61 79 65 64 20 74 68 72 6f 75 67 68   relayed through
3840: 20 74 6f 20 74 68 65 20 31 73 74 20 61 72 67 75   to the 1st argu
3850: 6d 65 6e 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20  ment of each.** 
3860: 63 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 63 61 74  callback invocat
3870: 69 6f 6e 2e 20 20 5e 49 66 20 74 68 65 20 63 61  ion.  ^If the ca
3880: 6c 6c 62 61 63 6b 20 70 6f 69 6e 74 65 72 20 74  llback pointer t
3890: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
38a0: 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  .** is NULL, the
38b0: 6e 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 20 69 73  n no callback is
38c0: 20 65 76 65 72 20 69 6e 76 6f 6b 65 64 20 61 6e   ever invoked an
38d0: 64 20 72 65 73 75 6c 74 20 72 6f 77 73 20 61 72  d result rows ar
38e0: 65 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a  e.** ignored..**
38f0: 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72 6f 72  .** ^If an error
3900: 20 6f 63 63 75 72 73 20 77 68 69 6c 65 20 65 76   occurs while ev
3910: 61 6c 75 61 74 69 6e 67 20 74 68 65 20 53 51 4c  aluating the SQL
3920: 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73   statements pass
3930: 65 64 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74  ed into.** sqlit
3940: 65 33 5f 65 78 65 63 28 29 2c 20 74 68 65 6e 20  e3_exec(), then 
3950: 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65  execution of the
3960: 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 6d 65   current stateme
3970: 6e 74 20 73 74 6f 70 73 20 61 6e 64 0a 2a 2a 20  nt stops and.** 
3980: 73 75 62 73 65 71 75 65 6e 74 20 73 74 61 74 65  subsequent state
3990: 6d 65 6e 74 73 20 61 72 65 20 73 6b 69 70 70 65  ments are skippe
39a0: 64 2e 20 20 5e 49 66 20 74 68 65 20 35 74 68 20  d.  ^If the 5th 
39b0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
39c0: 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69  ite3_exec().** i
39d0: 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20  s not NULL then 
39e0: 61 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 61 67  any error messag
39f0: 65 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74  e is written int
3a00: 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
3a10: 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  d.** from [sqlit
3a20: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64  e3_malloc()] and
3a30: 20 70 61 73 73 65 64 20 62 61 63 6b 20 74 68 72   passed back thr
3a40: 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72  ough the 5th par
3a50: 61 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f 20 61 76  ameter..** To av
3a60: 6f 69 64 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 73  oid memory leaks
3a70: 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  , the applicatio
3a80: 6e 20 73 68 6f 75 6c 64 20 69 6e 76 6f 6b 65 20  n should invoke 
3a90: 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
3aa0: 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72 20 6d 65 73  .** on error mes
3ab0: 73 61 67 65 20 73 74 72 69 6e 67 73 20 72 65 74  sage strings ret
3ac0: 75 72 6e 65 64 20 74 68 72 6f 75 67 68 20 74 68  urned through th
3ad0: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
3ae0: 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78  of.** sqlite3_ex
3af0: 65 63 28 29 20 61 66 74 65 72 20 74 68 65 20 65  ec() after the e
3b00: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
3b10: 69 6e 67 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72  ing is no longer
3b20: 20 6e 65 65 64 65 64 2e 0a 2a 2a 20 5e 49 66 20   needed..** ^If 
3b30: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
3b40: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
3b50: 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  c() is not NULL 
3b60: 61 6e 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a  and no errors.**
3b70: 20 6f 63 63 75 72 2c 20 74 68 65 6e 20 73 71 6c   occur, then sql
3b80: 69 74 65 33 5f 65 78 65 63 28 29 20 73 65 74 73  ite3_exec() sets
3b90: 20 74 68 65 20 70 6f 69 6e 74 65 72 20 69 6e 20   the pointer in 
3ba0: 69 74 73 20 35 74 68 20 70 61 72 61 6d 65 74 65  its 5th paramete
3bb0: 72 20 74 6f 0a 2a 2a 20 4e 55 4c 4c 20 62 65 66  r to.** NULL bef
3bc0: 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a  ore returning..*
3bd0: 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 73 71 6c 69  *.** ^If an sqli
3be0: 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62  te3_exec() callb
3bf0: 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ack returns non-
3c00: 7a 65 72 6f 2c 20 74 68 65 20 73 71 6c 69 74 65  zero, the sqlite
3c10: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 72 6f 75 74  3_exec().** rout
3c20: 69 6e 65 20 72 65 74 75 72 6e 73 20 53 51 4c 49  ine returns SQLI
3c30: 54 45 5f 41 42 4f 52 54 20 77 69 74 68 6f 75 74  TE_ABORT without
3c40: 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 63 61   invoking the ca
3c50: 6c 6c 62 61 63 6b 20 61 67 61 69 6e 20 61 6e 64  llback again and
3c60: 0a 2a 2a 20 77 69 74 68 6f 75 74 20 72 75 6e 6e  .** without runn
3c70: 69 6e 67 20 61 6e 79 20 73 75 62 73 65 71 75 65  ing any subseque
3c80: 6e 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  nt SQL statement
3c90: 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 32 6e  s..**.** ^The 2n
3ca0: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  d argument to th
3cb0: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3cc0: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
3cd0: 6f 6e 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  on is the.** num
3ce0: 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
3cf0: 6e 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 5e  n the result.  ^
3d00: 54 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74  The 3rd argument
3d10: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
3d20: 65 78 65 63 28 29 0a 2a 2a 20 63 61 6c 6c 62 61  exec().** callba
3d30: 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  ck is an array o
3d40: 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74  f pointers to st
3d50: 72 69 6e 67 73 20 6f 62 74 61 69 6e 65 64 20 61  rings obtained a
3d60: 73 20 69 66 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71  s if from.** [sq
3d70: 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
3d80: 74 28 29 5d 2c 20 6f 6e 65 20 66 6f 72 20 65 61  t()], one for ea
3d90: 63 68 20 63 6f 6c 75 6d 6e 2e 20 20 5e 49 66 20  ch column.  ^If 
3da0: 61 6e 20 65 6c 65 6d 65 6e 74 20 6f 66 20 61 0a  an element of a.
3db0: 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 69 73  ** result row is
3dc0: 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 63   NULL then the c
3dd0: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 73 74 72  orresponding str
3de0: 69 6e 67 20 70 6f 69 6e 74 65 72 20 66 6f 72 20  ing pointer for 
3df0: 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65  the.** sqlite3_e
3e00: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69  xec() callback i
3e10: 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
3e20: 2e 20 20 5e 54 68 65 20 34 74 68 20 61 72 67 75  .  ^The 4th argu
3e30: 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 73  ment to the.** s
3e40: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61  qlite3_exec() ca
3e50: 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72  llback is an arr
3e60: 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
3e70: 6f 20 73 74 72 69 6e 67 73 20 77 68 65 72 65 20  o strings where 
3e80: 65 61 63 68 0a 2a 2a 20 65 6e 74 72 79 20 72 65  each.** entry re
3e90: 70 72 65 73 65 6e 74 73 20 74 68 65 20 6e 61 6d  presents the nam
3ea0: 65 20 6f 66 20 63 6f 72 72 65 73 70 6f 6e 64 69  e of correspondi
3eb0: 6e 67 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  ng result column
3ec0: 20 61 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20   as obtained.** 
3ed0: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f  from [sqlite3_co
3ee0: 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a  lumn_name()]..**
3ef0: 0a 2a 2a 20 5e 49 66 20 74 68 65 20 32 6e 64 20  .** ^If the 2nd 
3f00: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
3f10: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 61  ite3_exec() is a
3f20: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 61   NULL pointer, a
3f30: 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 61   pointer.** to a
3f40: 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20  n empty string, 
3f50: 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74 68 61  or a pointer tha
3f60: 74 20 63 6f 6e 74 61 69 6e 73 20 6f 6e 6c 79 20  t contains only 
3f70: 77 68 69 74 65 73 70 61 63 65 20 61 6e 64 2f 6f  whitespace and/o
3f80: 72 20 0a 2a 2a 20 53 51 4c 20 63 6f 6d 6d 65 6e  r .** SQL commen
3f90: 74 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51 4c 20  ts, then no SQL 
3fa0: 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 65  statements are e
3fb0: 76 61 6c 75 61 74 65 64 20 61 6e 64 20 74 68 65  valuated and the
3fc0: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20   database.** is 
3fd0: 6e 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a  not changed..**.
3fe0: 2a 2a 20 52 65 73 74 72 69 63 74 69 6f 6e 73 3a  ** Restrictions:
3ff0: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
4000: 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74  li> The applicat
4010: 69 6f 6e 20 6d 75 73 74 20 65 6e 73 75 72 65 20  ion must ensure 
4020: 74 68 61 74 20 74 68 65 20 31 73 74 20 70 61 72  that the 1st par
4030: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
4040: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 20 20 20 20  3_exec().**     
4050: 20 69 73 20 61 20 76 61 6c 69 64 20 61 6e 64 20   is a valid and 
4060: 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63  open [database c
4070: 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c  onnection]..** <
4080: 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74  li> The applicat
4090: 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f  ion must not clo
40a0: 73 65 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  se the [database
40b0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65   connection] spe
40c0: 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20  cified by.**    
40d0: 20 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65    the 1st parame
40e0: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
40f0: 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69  xec() while sqli
4100: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75  te3_exec() is ru
4110: 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e 20 54  nning..** <li> T
4120: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
4130: 75 73 74 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74  ust not modify t
4140: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
4150: 20 74 65 78 74 20 70 61 73 73 65 64 20 69 6e 74   text passed int
4160: 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 32 6e  o.**      the 2n
4170: 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73  d parameter of s
4180: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68  qlite3_exec() wh
4190: 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  ile sqlite3_exec
41a0: 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  () is running..*
41b0: 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69 6e 74 20 73  * </ul>.*/.int s
41c0: 71 6c 69 74 65 33 5f 65 78 65 63 28 0a 20 20 73  qlite3_exec(.  s
41d0: 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 20 20  qlite3*,        
41e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41f0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20            /* An 
4200: 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f  open database */
4210: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  .  const char *s
4220: 71 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  ql,             
4230: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
4240: 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75   SQL to be evalu
4250: 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  ated */.  int (*
4260: 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c  callback)(void*,
4270: 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a  int,char**,char*
4280: 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b  *),  /* Callback
4290: 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76   function */.  v
42a0: 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20  oid *,          
42b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
42c0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 31 73 74            /* 1st
42d0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c   argument to cal
42e0: 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72 20  lback */.  char 
42f0: 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20 20 20  **errmsg        
4300: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4310: 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d        /* Error m
4320: 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  sg written here 
4330: 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
4340: 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 43 6f  I3REF: Result Co
4350: 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  des.** KEYWORDS:
4360: 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 20 64 65   {result code de
4370: 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a  finitions}.**.**
4380: 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e   Many SQLite fun
4390: 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e  ctions return an
43a0: 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20   integer result 
43b0: 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65  code from the se
43c0: 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20  t shown.** here 
43d0: 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69  in order to indi
43e0: 63 61 74 65 20 73 75 63 63 65 73 73 20 6f 72 20  cate success or 
43f0: 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e  failure..**.** N
4400: 65 77 20 65 72 72 6f 72 20 63 6f 64 65 73 20 6d  ew error codes m
4410: 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
4420: 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
4430: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20  f SQLite..**.** 
4440: 53 65 65 20 61 6c 73 6f 3a 20 5b 65 78 74 65 6e  See also: [exten
4450: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20  ded result code 
4460: 64 65 66 69 6e 69 74 69 6f 6e 73 5d 0a 2a 2f 0a  definitions].*/.
4470: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
4480: 4b 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20  K           0   
4490: 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20 72 65  /* Successful re
44a0: 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e  sult */./* begin
44b0: 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f  ning-of-error-co
44c0: 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  des */.#define S
44d0: 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20 20 20  QLITE_ERROR     
44e0: 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20 65 72     1   /* SQL er
44f0: 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67 20 64  ror or missing d
4500: 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69  atabase */.#defi
4510: 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 4e  ne SQLITE_INTERN
4520: 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20 49 6e  AL     2   /* In
4530: 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65 72 72  ternal logic err
4540: 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a 2f 0a  or in SQLite */.
4550: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50  #define SQLITE_P
4560: 45 52 4d 20 20 20 20 20 20 20 20 20 33 20 20 20  ERM         3   
4570: 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d 69 73  /* Access permis
4580: 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23  sion denied */.#
4590: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42  define SQLITE_AB
45a0: 4f 52 54 20 20 20 20 20 20 20 20 34 20 20 20 2f  ORT        4   /
45b0: 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69  * Callback routi
45c0: 6e 65 20 72 65 71 75 65 73 74 65 64 20 61 6e 20  ne requested an 
45d0: 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69 6e 65  abort */.#define
45e0: 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 20   SQLITE_BUSY    
45f0: 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68 65 20       5   /* The 
4600: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73  database file is
4610: 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69   locked */.#defi
4620: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44  ne SQLITE_LOCKED
4630: 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20 41 20         6   /* A 
4640: 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64 61 74  table in the dat
4650: 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65 64 20  abase is locked 
4660: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4670: 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 37  E_NOMEM        7
4680: 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28 29     /* A malloc()
4690: 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65 66 69   failed */.#defi
46a0: 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e  ne SQLITE_READON
46b0: 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20 41 74  LY     8   /* At
46c0: 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65 20 61  tempt to write a
46d0: 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61 62 61   readonly databa
46e0: 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  se */.#define SQ
46f0: 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 20 20  LITE_INTERRUPT  
4700: 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61 74 69    9   /* Operati
4710: 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20 62 79  on terminated by
4720: 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
4730: 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65 20 53  pt()*/.#define S
4740: 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20 20 20  QLITE_IOERR     
4750: 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65 20 6b    10   /* Some k
4760: 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f 4f 20  ind of disk I/O 
4770: 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64 20 2a  error occurred *
4780: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4790: 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31 31 20  _CORRUPT     11 
47a0: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
47b0: 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69 73 20  e disk image is 
47c0: 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 64 65  malformed */.#de
47d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 46  fine SQLITE_NOTF
47e0: 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f 2a 20  OUND    12   /* 
47f0: 55 6e 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65 20 69  Unknown opcode i
4800: 6e 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63  n sqlite3_file_c
4810: 6f 6e 74 72 6f 6c 28 29 20 2a 2f 0a 23 64 65 66  ontrol() */.#def
4820: 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20  ine SQLITE_FULL 
4830: 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 49         13   /* I
4840: 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65 64 20  nsertion failed 
4850: 62 65 63 61 75 73 65 20 64 61 74 61 62 61 73 65  because database
4860: 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66   is full */.#def
4870: 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f  ine SQLITE_CANTO
4880: 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a 20 55  PEN    14   /* U
4890: 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68  nable to open th
48a0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
48b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
48c0: 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35  E_PROTOCOL    15
48d0: 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 6c     /* Database l
48e0: 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72  ock protocol err
48f0: 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  or */.#define SQ
4900: 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20 20 20  LITE_EMPTY      
4910: 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73   16   /* Databas
4920: 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64  e is empty */.#d
4930: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 43 48  efine SQLITE_SCH
4940: 45 4d 41 20 20 20 20 20 20 31 37 20 20 20 2f 2a  EMA      17   /*
4950: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 73 63   The database sc
4960: 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a  hema changed */.
4970: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
4980: 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20 20 20  OOBIG      18   
4990: 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f  /* String or BLO
49a0: 42 20 65 78 63 65 65 64 73 20 73 69 7a 65 20 6c  B exceeds size l
49b0: 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20  imit */.#define 
49c0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
49d0: 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f 72 74  T  19   /* Abort
49e0: 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 61 69   due to constrai
49f0: 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a  nt violation */.
4a00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
4a10: 49 53 4d 41 54 43 48 20 20 20 20 32 30 20 20 20  ISMATCH    20   
4a20: 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d 69 73  /* Data type mis
4a30: 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65  match */.#define
4a40: 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 20   SQLITE_MISUSE  
4a50: 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 62 72      21   /* Libr
4a60: 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72 72 65  ary used incorre
4a70: 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ctly */.#define 
4a80: 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20  SQLITE_NOLFS    
4a90: 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65 73 20     22   /* Uses 
4aa0: 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f 74 20  OS features not 
4ab0: 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73  supported on hos
4ac0: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
4ad0: 49 54 45 5f 41 55 54 48 20 20 20 20 20 20 20 20  ITE_AUTH        
4ae0: 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a  23   /* Authoriz
4af0: 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a  ation denied */.
4b00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
4b10: 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20 20 20  ORMAT      24   
4b20: 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64 61 74  /* Auxiliary dat
4b30: 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65 72 72  abase format err
4b40: 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  or */.#define SQ
4b50: 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20 20 20  LITE_RANGE      
4b60: 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70 61 72   25   /* 2nd par
4b70: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
4b80: 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20 72 61  3_bind out of ra
4b90: 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nge */.#define S
4ba0: 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20 20 20  QLITE_NOTADB    
4bb0: 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f    26   /* File o
4bc0: 70 65 6e 65 64 20 74 68 61 74 20 69 73 20 6e 6f  pened that is no
4bd0: 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  t a database fil
4be0: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
4bf0: 49 54 45 5f 4e 4f 54 49 43 45 20 20 20 20 20 20  ITE_NOTICE      
4c00: 32 37 20 20 20 2f 2a 20 4e 6f 74 69 66 69 63 61  27   /* Notifica
4c10: 74 69 6f 6e 73 20 66 72 6f 6d 20 73 71 6c 69 74  tions from sqlit
4c20: 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64 65 66  e3_log() */.#def
4c30: 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e 49  ine SQLITE_WARNI
4c40: 4e 47 20 20 20 20 20 32 38 20 20 20 2f 2a 20 57  NG     28   /* W
4c50: 61 72 6e 69 6e 67 73 20 66 72 6f 6d 20 73 71 6c  arnings from sql
4c60: 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64  ite3_log() */.#d
4c70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57  efine SQLITE_ROW
4c80: 20 20 20 20 20 20 20 20 20 31 30 30 20 20 2f 2a           100  /*
4c90: 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
4ca0: 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f 77 20  has another row 
4cb0: 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65  ready */.#define
4cc0: 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20   SQLITE_DONE    
4cd0: 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71 6c 69      101  /* sqli
4ce0: 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 66  te3_step() has f
4cf0: 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e  inished executin
4d00: 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65  g */./* end-of-e
4d10: 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f  rror-codes */../
4d20: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
4d30: 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43  xtended Result C
4d40: 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  odes.** KEYWORDS
4d50: 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75  : {extended resu
4d60: 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69  lt code definiti
4d70: 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74  ons}.**.** In it
4d80: 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67  s default config
4d90: 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20  uration, SQLite 
4da0: 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74  API routines ret
4db0: 75 72 6e 20 6f 6e 65 20 6f 66 20 33 30 20 69 6e  urn one of 30 in
4dc0: 74 65 67 65 72 0a 2a 2a 20 5b 72 65 73 75 6c 74  teger.** [result
4dd0: 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65   codes].  Howeve
4de0: 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 61  r, experience ha
4df0: 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e  s shown that man
4e00: 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65  y of.** these re
4e10: 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74  sult codes are t
4e20: 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65  oo coarse-graine
4e30: 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20  d.  They do not 
4e40: 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75  provide as.** mu
4e50: 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  ch information a
4e60: 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73  bout problems as
4e70: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
4e80: 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20  ht like.  In an 
4e90: 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64  effort to.** add
4ea0: 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72  ress this, newer
4eb0: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
4ec0: 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33  ite (version 3.3
4ed0: 2e 38 20 5b 64 61 74 65 6f 66 3a 33 2e 33 2e 38  .8 [dateof:3.3.8
4ee0: 5d 0a 2a 2a 20 61 6e 64 20 6c 61 74 65 72 29 20  ].** and later) 
4ef0: 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f  include.** suppo
4f00: 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  rt for additiona
4f10: 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 74  l result codes t
4f20: 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 65  hat provide more
4f30: 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d   detailed inform
4f40: 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65  ation.** about e
4f50: 72 72 6f 72 73 2e 20 54 68 65 73 65 20 5b 65 78  rrors. These [ex
4f60: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
4f70: 64 65 73 5d 20 61 72 65 20 65 6e 61 62 6c 65 64  des] are enabled
4f80: 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20   or disabled.** 
4f90: 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62 61 73  on a per databas
4fa0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73  e connection bas
4fb0: 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  is using the.** 
4fc0: 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65  [sqlite3_extende
4fd0: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
4fe0: 5d 20 41 50 49 2e 20 20 4f 72 2c 20 74 68 65 20  ] API.  Or, the 
4ff0: 65 78 74 65 6e 64 65 64 20 63 6f 64 65 20 66 6f  extended code fo
5000: 72 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20 72 65  r.** the most re
5010: 63 65 6e 74 20 65 72 72 6f 72 20 63 61 6e 20 62  cent error can b
5020: 65 20 6f 62 74 61 69 6e 65 64 20 75 73 69 6e 67  e obtained using
5030: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74  .** [sqlite3_ext
5040: 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 5d  ended_errcode()]
5050: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
5060: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20  ITE_IOERR_READ  
5070: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5080: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c  ITE_IOERR | (1<<
5090: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
50a0: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
50b0: 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  EAD        (SQLI
50c0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38  TE_IOERR | (2<<8
50d0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
50e0: 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20  E_IOERR_WRITE   
50f0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5100: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29  E_IOERR | (3<<8)
5110: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5120: 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20  _IOERR_FSYNC    
5130: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5140: 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29  _IOERR | (4<<8))
5150: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5160: 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20  IOERR_DIR_FSYNC 
5170: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5180: 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a  IOERR | (5<<8)).
5190: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
51a0: 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20  OERR_TRUNCATE   
51b0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
51c0: 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23  OERR | (6<<8)).#
51d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
51e0: 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20  ERR_FSTAT       
51f0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5200: 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64  ERR | (7<<8)).#d
5210: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5220: 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20  RR_UNLOCK       
5230: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5240: 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65  RR | (8<<8)).#de
5250: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5260: 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_RDLOCK        
5270: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5280: 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66  R | (9<<8)).#def
5290: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
52a0: 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
52b0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
52c0: 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66   | (10<<8)).#def
52d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
52e0: 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20  _BLOCKED        
52f0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5300: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66   | (11<<8)).#def
5310: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5320: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20  _NOMEM          
5330: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5340: 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66   | (12<<8)).#def
5350: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5360: 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20  _ACCESS         
5370: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5380: 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66   | (13<<8)).#def
5390: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
53a0: 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f  _CHECKRESERVEDLO
53b0: 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52  CK (SQLITE_IOERR
53c0: 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66   | (14<<8)).#def
53d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
53e0: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  _LOCK           
53f0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5400: 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66   | (15<<8)).#def
5410: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5420: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20  _CLOSE          
5430: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5440: 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66   | (16<<8)).#def
5450: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5460: 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20  _DIR_CLOSE      
5470: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5480: 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66   | (17<<8)).#def
5490: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
54a0: 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20  _SHMOPEN        
54b0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
54c0: 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66   | (18<<8)).#def
54d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
54e0: 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20  _SHMSIZE        
54f0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5500: 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66   | (19<<8)).#def
5510: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5520: 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20  _SHMLOCK        
5530: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5540: 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66   | (20<<8)).#def
5550: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5560: 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20  _SHMMAP         
5570: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5580: 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66   | (21<<8)).#def
5590: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
55a0: 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20  _SEEK           
55b0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
55c0: 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66   | (22<<8)).#def
55d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
55e0: 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20  _DELETE_NOENT   
55f0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5600: 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66   | (23<<8)).#def
5610: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5620: 5f 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20  _MMAP           
5630: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5640: 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66   | (24<<8)).#def
5650: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5660: 5f 47 45 54 54 45 4d 50 50 41 54 48 20 20 20 20  _GETTEMPPATH    
5670: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5680: 20 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66   | (25<<8)).#def
5690: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
56a0: 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20  _CONVPATH       
56b0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
56c0: 20 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66   | (26<<8)).#def
56d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
56e0: 5f 56 4e 4f 44 45 20 20 20 20 20 20 20 20 20 20  _VNODE          
56f0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5700: 20 7c 20 28 32 37 3c 3c 38 29 29 0a 23 64 65 66   | (27<<8)).#def
5710: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5720: 5f 41 55 54 48 20 20 20 20 20 20 20 20 20 20 20  _AUTH           
5730: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5740: 20 7c 20 28 32 38 3c 3c 38 29 29 0a 23 64 65 66   | (28<<8)).#def
5750: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
5760: 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20  D_SHAREDCACHE   
5770: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45     (SQLITE_LOCKE
5780: 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65  D |  (1<<8)).#de
5790: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
57a0: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20  _RECOVERY       
57b0: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
57c0: 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64     |  (1<<8)).#d
57d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
57e0: 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20 20  Y_SNAPSHOT      
57f0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53       (SQLITE_BUS
5800: 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23  Y   |  (2<<8)).#
5810: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
5820: 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52  NTOPEN_NOTEMPDIR
5830: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
5840: 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29  NTOPEN | (1<<8))
5850: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5860: 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20  CANTOPEN_ISDIR  
5870: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5880: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38  CANTOPEN | (2<<8
5890: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
58a0: 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50  E_CANTOPEN_FULLP
58b0: 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54  ATH       (SQLIT
58c0: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c  E_CANTOPEN | (3<
58d0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
58e0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e  ITE_CANTOPEN_CON
58f0: 56 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c  VPATH       (SQL
5900: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
5910: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
5920: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54  QLITE_CORRUPT_VT
5930: 41 42 20 20 20 20 20 20 20 20 20 20 20 20 28 53  AB            (S
5940: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20  QLITE_CORRUPT | 
5950: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
5960: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f  SQLITE_READONLY_
5970: 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 28  RECOVERY       (
5980: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
5990: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
59a0: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
59b0: 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20  Y_CANTLOCK      
59c0: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   (SQLITE_READONL
59d0: 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  Y | (2<<8)).#def
59e0: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
59f0: 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20  NLY_ROLLBACK    
5a00: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f     (SQLITE_READO
5a10: 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64  NLY | (3<<8)).#d
5a20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
5a30: 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20 20 20  DONLY_DBMOVED   
5a40: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
5a50: 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29 29 0a  DONLY | (4<<8)).
5a60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
5a70: 42 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20  BORT_ROLLBACK   
5a80: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41         (SQLITE_A
5a90: 42 4f 52 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23  BORT | (2<<8)).#
5aa0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5ab0: 4e 53 54 52 41 49 4e 54 5f 43 48 45 43 4b 20 20  NSTRAINT_CHECK  
5ac0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5ad0: 4e 53 54 52 41 49 4e 54 20 7c 20 28 31 3c 3c 38  NSTRAINT | (1<<8
5ae0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5af0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 4f 4d  E_CONSTRAINT_COM
5b00: 4d 49 54 48 4f 4f 4b 20 20 20 28 53 51 4c 49 54  MITHOOK   (SQLIT
5b10: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5b20: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
5b30: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5b40: 5f 46 4f 52 45 49 47 4e 4b 45 59 20 20 20 28 53  _FOREIGNKEY   (S
5b50: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5b60: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69   | (3<<8)).#defi
5b70: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5b80: 41 49 4e 54 5f 46 55 4e 43 54 49 4f 4e 20 20 20  AINT_FUNCTION   
5b90: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5ba0: 41 49 4e 54 20 7c 20 28 34 3c 3c 38 29 29 0a 23  AINT | (4<<8)).#
5bb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5bc0: 4e 53 54 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c  NSTRAINT_NOTNULL
5bd0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5be0: 4e 53 54 52 41 49 4e 54 20 7c 20 28 35 3c 3c 38  NSTRAINT | (5<<8
5bf0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5c00: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 50 52 49  E_CONSTRAINT_PRI
5c10: 4d 41 52 59 4b 45 59 20 20 20 28 53 51 4c 49 54  MARYKEY   (SQLIT
5c20: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5c30: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
5c40: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5c50: 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 28 53  _TRIGGER      (S
5c60: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5c70: 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69   | (7<<8)).#defi
5c80: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5c90: 41 49 4e 54 5f 55 4e 49 51 55 45 20 20 20 20 20  AINT_UNIQUE     
5ca0: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5cb0: 41 49 4e 54 20 7c 20 28 38 3c 3c 38 29 29 0a 23  AINT | (8<<8)).#
5cc0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5cd0: 4e 53 54 52 41 49 4e 54 5f 56 54 41 42 20 20 20  NSTRAINT_VTAB   
5ce0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5cf0: 4e 53 54 52 41 49 4e 54 20 7c 20 28 39 3c 3c 38  NSTRAINT | (9<<8
5d00: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5d10: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 52 4f 57  E_CONSTRAINT_ROW
5d20: 49 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  ID        (SQLIT
5d30: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 28 31  E_CONSTRAINT |(1
5d40: 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  0<<8)).#define S
5d50: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43  QLITE_NOTICE_REC
5d60: 4f 56 45 52 5f 57 41 4c 20 20 20 20 20 20 28 53  OVER_WAL      (S
5d70: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28  QLITE_NOTICE | (
5d80: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5d90: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43  QLITE_NOTICE_REC
5da0: 4f 56 45 52 5f 52 4f 4c 4c 42 41 43 4b 20 28 53  OVER_ROLLBACK (S
5db0: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28  QLITE_NOTICE | (
5dc0: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
5dd0: 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 5f 41 55  QLITE_WARNING_AU
5de0: 54 4f 49 4e 44 45 58 20 20 20 20 20 20 20 28 53  TOINDEX       (S
5df0: 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 7c 20  QLITE_WARNING | 
5e00: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
5e10: 53 51 4c 49 54 45 5f 41 55 54 48 5f 55 53 45 52  SQLITE_AUTH_USER
5e20: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28                 (
5e30: 53 51 4c 49 54 45 5f 41 55 54 48 20 7c 20 28 31  SQLITE_AUTH | (1
5e40: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5e50: 4c 49 54 45 5f 4f 4b 5f 4c 4f 41 44 5f 50 45 52  LITE_OK_LOAD_PER
5e60: 4d 41 4e 45 4e 54 4c 59 20 20 20 20 20 28 53 51  MANENTLY     (SQ
5e70: 4c 49 54 45 5f 4f 4b 20 7c 20 28 31 3c 3c 38 29  LITE_OK | (1<<8)
5e80: 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  )../*.** CAPI3RE
5e90: 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69 6c  F: Flags For Fil
5ea0: 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e  e Open Operation
5eb0: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69  s.**.** These bi
5ec0: 74 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 74  t values are int
5ed0: 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e  ended for use in
5ee0: 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72 61   the.** 3rd para
5ef0: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  meter to the [sq
5f00: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
5f10: 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a 2a   interface and.*
5f20: 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70 61 72  * in the 4th par
5f30: 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ameter to the [s
5f40: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
5f50: 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23 64 65  ] method..*/.#de
5f60: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5f70: 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20  _READONLY       
5f80: 20 20 30 78 30 30 30 30 30 30 30 31 20 20 2f 2a    0x00000001  /*
5f90: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
5fa0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
5fb0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5fc0: 5f 52 45 41 44 57 52 49 54 45 20 20 20 20 20 20  _READWRITE      
5fd0: 20 20 30 78 30 30 30 30 30 30 30 32 20 20 2f 2a    0x00000002  /*
5fe0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
5ff0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
6000: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6010: 5f 43 52 45 41 54 45 20 20 20 20 20 20 20 20 20  _CREATE         
6020: 20 20 30 78 30 30 30 30 30 30 30 34 20 20 2f 2a    0x00000004  /*
6030: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
6040: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
6050: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6060: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20  _DELETEONCLOSE  
6070: 20 20 30 78 30 30 30 30 30 30 30 38 20 20 2f 2a    0x00000008  /*
6080: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6090: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
60a0: 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 20  _EXCLUSIVE      
60b0: 20 20 30 78 30 30 30 30 30 30 31 30 20 20 2f 2a    0x00000010  /*
60c0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
60d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
60e0: 5f 41 55 54 4f 50 52 4f 58 59 20 20 20 20 20 20  _AUTOPROXY      
60f0: 20 20 30 78 30 30 30 30 30 30 32 30 20 20 2f 2a    0x00000020  /*
6100: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6110: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6120: 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 20 20  _URI            
6130: 20 20 30 78 30 30 30 30 30 30 34 30 20 20 2f 2a    0x00000040  /*
6140: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
6150: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
6160: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6170: 5f 4d 45 4d 4f 52 59 20 20 20 20 20 20 20 20 20  _MEMORY         
6180: 20 20 30 78 30 30 30 30 30 30 38 30 20 20 2f 2a    0x00000080  /*
6190: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
61a0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
61b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
61c0: 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20  _MAIN_DB        
61d0: 20 20 30 78 30 30 30 30 30 31 30 30 20 20 2f 2a    0x00000100  /*
61e0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
61f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6200: 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20  _TEMP_DB        
6210: 20 20 30 78 30 30 30 30 30 32 30 30 20 20 2f 2a    0x00000200  /*
6220: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6230: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6240: 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20  _TRANSIENT_DB   
6250: 20 20 30 78 30 30 30 30 30 34 30 30 20 20 2f 2a    0x00000400  /*
6260: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6270: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6280: 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20  _MAIN_JOURNAL   
6290: 20 20 30 78 30 30 30 30 30 38 30 30 20 20 2f 2a    0x00000800  /*
62a0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
62b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
62c0: 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20  _TEMP_JOURNAL   
62d0: 20 20 30 78 30 30 30 30 31 30 30 30 20 20 2f 2a    0x00001000  /*
62e0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
62f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6300: 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20  _SUBJOURNAL     
6310: 20 20 30 78 30 30 30 30 32 30 30 30 20 20 2f 2a    0x00002000  /*
6320: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6330: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6340: 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20  _MASTER_JOURNAL 
6350: 20 20 30 78 30 30 30 30 34 30 30 30 20 20 2f 2a    0x00004000  /*
6360: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6370: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6380: 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20  _NOMUTEX        
6390: 20 20 30 78 30 30 30 30 38 30 30 30 20 20 2f 2a    0x00008000  /*
63a0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
63b0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
63c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
63d0: 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20  _FULLMUTEX      
63e0: 20 20 30 78 30 30 30 31 30 30 30 30 20 20 2f 2a    0x00010000  /*
63f0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
6400: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
6410: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6420: 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20  _SHAREDCACHE    
6430: 20 20 30 78 30 30 30 32 30 30 30 30 20 20 2f 2a    0x00020000  /*
6440: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
6450: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
6460: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6470: 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 20 20  _PRIVATECACHE   
6480: 20 20 30 78 30 30 30 34 30 30 30 30 20 20 2f 2a    0x00040000  /*
6490: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
64a0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
64b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
64c0: 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20  _WAL            
64d0: 20 20 30 78 30 30 30 38 30 30 30 30 20 20 2f 2a    0x00080000  /*
64e0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a   VFS only */../*
64f0: 20 52 65 73 65 72 76 65 64 3a 20 20 20 20 20 20   Reserved:      
6500: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6510: 20 20 20 30 78 30 30 46 30 30 30 30 30 20 2a 2f     0x00F00000 */
6520: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
6530: 3a 20 44 65 76 69 63 65 20 43 68 61 72 61 63 74  : Device Charact
6540: 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54  eristics.**.** T
6550: 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63  he xDeviceCharac
6560: 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64  teristics method
6570: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
6580: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  _io_methods].** 
6590: 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73 20 61  object returns a
65a0: 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
65b0: 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66 20 74  is a vector of t
65c0: 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75  hese.** bit valu
65d0: 65 73 20 65 78 70 72 65 73 73 69 6e 67 20 49 2f  es expressing I/
65e0: 4f 20 63 68 61 72 61 63 74 65 72 69 73 74 69 63  O characteristic
65f0: 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73 74  s of the mass st
6600: 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 20  orage.** device 
6610: 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20 66  that holds the f
6620: 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73 71  ile that the [sq
6630: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
6640: 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a  ].** refers to..
6650: 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  **.** The SQLITE
6660: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72  _IOCAP_ATOMIC pr
6670: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
6680: 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a  t all writes of.
6690: 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20  ** any size are 
66a0: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
66b0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
66c0: 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65  nnn values.** me
66d0: 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f  an that writes o
66e0: 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72  f blocks that ar
66f0: 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73  e nnn bytes in s
6700: 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61  ize and.** are a
6710: 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64  ligned to an add
6720: 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e  ress which is an
6730: 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c   integer multipl
6740: 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20  e of.** nnn are 
6750: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
6760: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
6770: 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e  PPEND value mean
6780: 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64  s.** that when d
6790: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20  ata is appended 
67a0: 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64  to a file, the d
67b0: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a  ata is appended.
67c0: 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68  ** first then th
67d0: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69  e size of the fi
67e0: 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20  le is extended, 
67f0: 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a  never the other.
6800: 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20  ** way around.  
6810: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
6820: 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70  _SEQUENTIAL prop
6830: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a  erty means that.
6840: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ** information i
6850: 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73  s written to dis
6860: 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72  k in the same or
6870: 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20  der as calls.** 
6880: 74 6f 20 78 57 72 69 74 65 28 29 2e 20 20 54 68  to xWrite().  Th
6890: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50  e SQLITE_IOCAP_P
68a0: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
68b0: 54 45 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  TE property mean
68c0: 73 20 74 68 61 74 0a 2a 2a 20 61 66 74 65 72 20  s that.** after 
68d0: 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77 69 6e 67  reboot following
68e0: 20 61 20 63 72 61 73 68 20 6f 72 20 70 6f 77 65   a crash or powe
68f0: 72 20 6c 6f 73 73 2c 20 74 68 65 20 6f 6e 6c 79  r loss, the only
6900: 20 62 79 74 65 73 20 69 6e 20 61 0a 2a 2a 20 66   bytes in a.** f
6910: 69 6c 65 20 74 68 61 74 20 77 65 72 65 20 77 72  ile that were wr
6920: 69 74 74 65 6e 20 61 74 20 74 68 65 20 61 70 70  itten at the app
6930: 6c 69 63 61 74 69 6f 6e 20 6c 65 76 65 6c 20 6d  lication level m
6940: 69 67 68 74 20 68 61 76 65 20 63 68 61 6e 67 65  ight have change
6950: 64 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 61 64  d.** and that ad
6960: 6a 61 63 65 6e 74 20 62 79 74 65 73 2c 20 65 76  jacent bytes, ev
6970: 65 6e 20 62 79 74 65 73 20 77 69 74 68 69 6e 20  en bytes within 
6980: 74 68 65 20 73 61 6d 65 20 73 65 63 74 6f 72 20  the same sector 
6990: 61 72 65 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65  are.** guarantee
69a0: 64 20 74 6f 20 62 65 20 75 6e 63 68 61 6e 67 65  d to be unchange
69b0: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  d.  The SQLITE_I
69c0: 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45  OCAP_UNDELETABLE
69d0: 5f 57 48 45 4e 5f 4f 50 45 4e 0a 2a 2a 20 66 6c  _WHEN_OPEN.** fl
69e0: 61 67 20 69 6e 64 69 63 61 74 65 73 20 74 68 61  ag indicates tha
69f0: 74 20 61 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20  t a file cannot 
6a00: 62 65 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  be deleted when 
6a10: 6f 70 65 6e 2e 20 20 54 68 65 0a 2a 2a 20 53 51  open.  The.** SQ
6a20: 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54  LITE_IOCAP_IMMUT
6a30: 41 42 4c 45 20 66 6c 61 67 20 69 6e 64 69 63 61  ABLE flag indica
6a40: 74 65 73 20 74 68 61 74 20 74 68 65 20 66 69 6c  tes that the fil
6a50: 65 20 69 73 20 6f 6e 0a 2a 2a 20 72 65 61 64 2d  e is on.** read-
6a60: 6f 6e 6c 79 20 6d 65 64 69 61 20 61 6e 64 20 63  only media and c
6a70: 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64  annot be changed
6a80: 20 65 76 65 6e 20 62 79 20 70 72 6f 63 65 73 73   even by process
6a90: 65 73 20 77 69 74 68 0a 2a 2a 20 65 6c 65 76 61  es with.** eleva
6aa0: 74 65 64 20 70 72 69 76 69 6c 65 67 65 73 2e 0a  ted privileges..
6ab0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6ac0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20  E_IOCAP_ATOMIC  
6ad0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
6ae0: 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e  x00000001.#defin
6af0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6b00: 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20 20  TOMIC512        
6b10: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32        0x00000002
6b20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6b30: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20  IOCAP_ATOMIC1K  
6b40: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6b50: 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20  0000004.#define 
6b60: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6b70: 4d 49 43 32 4b 20 20 20 20 20 20 20 20 20 20 20  MIC2K           
6b80: 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0a 23      0x00000008.#
6b90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6ba0: 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20  CAP_ATOMIC4K    
6bb0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6bc0: 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51  00010.#define SQ
6bd0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6be0: 43 38 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  C8K             
6bf0: 20 20 30 78 30 30 30 30 30 30 32 30 0a 23 64 65    0x00000020.#de
6c00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6c10: 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20  P_ATOMIC16K     
6c20: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6c30: 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  040.#define SQLI
6c40: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33  TE_IOCAP_ATOMIC3
6c50: 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  2K              
6c60: 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 69  0x00000080.#defi
6c70: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6c80: 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20  ATOMIC64K       
6c90: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30         0x0000010
6ca0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6cb0: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45  _IOCAP_SAFE_APPE
6cc0: 4e 44 20 20 20 20 20 20 20 20 20 20 20 20 30 78  ND            0x
6cd0: 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65  00000200.#define
6ce0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45   SQLITE_IOCAP_SE
6cf0: 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20 20 20  QUENTIAL        
6d00: 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 0a       0x00000400.
6d10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6d20: 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45  OCAP_UNDELETABLE
6d30: 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30  _WHEN_OPEN  0x00
6d40: 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53  000800.#define S
6d50: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45  QLITE_IOCAP_POWE
6d60: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20  RSAFE_OVERWRITE 
6d70: 20 20 20 30 78 30 30 30 30 31 30 30 30 0a 23 64     0x00001000.#d
6d80: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6d90: 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 20 20 20  AP_IMMUTABLE    
6da0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6db0: 32 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  2000../*.** CAPI
6dc0: 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69  3REF: File Locki
6dd0: 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20  ng Levels.**.** 
6de0: 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20  SQLite uses one 
6df0: 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72  of these integer
6e00: 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73   values as the s
6e10: 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e  econd.** argumen
6e20: 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61  t to calls it ma
6e30: 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b  kes to the xLock
6e40: 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29  () and xUnlock()
6e50: 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61   methods.** of a
6e60: 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  n [sqlite3_io_me
6e70: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a  thods] object..*
6e80: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6e90: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20  _LOCK_NONE      
6ea0: 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
6eb0: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
6ec0: 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
6ed0: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45  e SQLITE_LOCK_RE
6ee0: 53 45 52 56 45 44 20 20 20 20 20 20 32 0a 23 64  SERVED      2.#d
6ef0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
6f00: 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20  K_PENDING       
6f10: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
6f20: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20  _LOCK_EXCLUSIVE 
6f30: 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      4../*.** CAP
6f40: 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69  I3REF: Synchroni
6f50: 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67  zation Type Flag
6f60: 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c  s.**.** When SQL
6f70: 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20  ite invokes the 
6f80: 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f  xSync() method o
6f90: 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  f an.** [sqlite3
6fa0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
6fb0: 65 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f  ect it uses a co
6fc0: 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20  mbination of.** 
6fd0: 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61  these integer va
6fe0: 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f  lues as the seco
6ff0: 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  nd argument..**.
7000: 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49  ** When the SQLI
7010: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
7020: 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69   flag is used, i
7030: 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  t means that the
7040: 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69  .** sync operati
7050: 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f  on only needs to
7060: 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d   flush data to m
7070: 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e  ass storage.  In
7080: 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  ode.** informati
7090: 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66  on need not be f
70a0: 6c 75 73 68 65 64 2e 20 49 66 20 74 68 65 20 6c  lushed. If the l
70b0: 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 6f  ower four bits o
70c0: 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71  f the flag.** eq
70d0: 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ual SQLITE_SYNC_
70e0: 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61  NORMAL, that mea
70f0: 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c  ns to use normal
7100: 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69   fsync() semanti
7110: 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f  cs..** If the lo
7120: 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 65 71  wer four bits eq
7130: 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ual SQLITE_SYNC_
7140: 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73  FULL, that means
7150: 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f  .** to use Mac O
7160: 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79  S X style fullsy
7170: 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73  nc instead of fs
7180: 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20  ync()..**.** Do 
7190: 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74 68 65 20  not confuse the 
71a0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
71b0: 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59  AL and SQLITE_SY
71c0: 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a  NC_FULL flags.**
71d0: 20 77 69 74 68 20 74 68 65 20 5b 50 52 41 47 4d   with the [PRAGM
71e0: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e  A synchronous]=N
71f0: 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47 4d  ORMAL and [PRAGM
7200: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46  A synchronous]=F
7210: 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73 2e  ULL.** settings.
7220: 20 20 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e 6f    The [synchrono
7230: 75 73 20 70 72 61 67 6d 61 5d 20 64 65 74 65 72  us pragma] deter
7240: 6d 69 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c 73  mines when calls
7250: 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e 63   to the.** xSync
7260: 20 56 46 53 20 6d 65 74 68 6f 64 20 6f 63 63 75   VFS method occu
7270: 72 20 61 6e 64 20 61 70 70 6c 69 65 73 20 75 6e  r and applies un
7280: 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20 61  iformly across a
7290: 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a  ll platforms..**
72a0: 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   The SQLITE_SYNC
72b0: 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49  _NORMAL and SQLI
72c0: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61  TE_SYNC_FULL fla
72d0: 67 73 20 64 65 74 65 72 6d 69 6e 65 20 68 6f 77  gs determine how
72e0: 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63 20 6f 72  .** energetic or
72f0: 20 72 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f 72   rigorous or for
7300: 63 65 66 75 6c 20 74 68 65 20 73 79 6e 63 20 6f  ceful the sync o
7310: 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20 61 6e  perations are an
7320: 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 61  d.** only make a
7330: 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 20 4d   difference on M
7340: 61 63 20 4f 53 58 20 66 6f 72 20 74 68 65 20 64  ac OSX for the d
7350: 65 66 61 75 6c 74 20 53 51 4c 69 74 65 20 63 6f  efault SQLite co
7360: 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70 61  de..** (Third-pa
7370: 72 74 79 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  rty VFS implemen
7380: 74 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 61 6c  tations might al
7390: 73 6f 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74  so make the dist
73a0: 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65  inction.** betwe
73b0: 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  en SQLITE_SYNC_N
73c0: 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45  ORMAL and SQLITE
73d0: 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 20  _SYNC_FULL, but 
73e0: 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 65  among the.** ope
73f0: 72 61 74 69 6e 67 20 73 79 73 74 65 6d 73 20 6e  rating systems n
7400: 61 74 69 76 65 6c 79 20 73 75 70 70 6f 72 74 65  atively supporte
7410: 64 20 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e 6c  d by SQLite, onl
7420: 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61 72  y Mac OSX.** car
7430: 65 73 20 61 62 6f 75 74 20 74 68 65 20 64 69 66  es about the dif
7440: 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65  ference.).*/.#de
7450: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43  fine SQLITE_SYNC
7460: 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30  _NORMAL        0
7470: 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53  x00002.#define S
7480: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
7490: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 33           0x00003
74a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
74b0: 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20  SYNC_DATAONLY   
74c0: 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a     0x00010../*.*
74d0: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49  * CAPI3REF: OS I
74e0: 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69  nterface Open Fi
74f0: 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20  le Handle.**.** 
7500: 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  An [sqlite3_file
7510: 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65  ] object represe
7520: 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  nts an open file
7530: 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c   in the .** [sql
7540: 69 74 65 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e  ite3_vfs | OS in
7550: 74 65 72 66 61 63 65 20 6c 61 79 65 72 5d 2e 20  terface layer]. 
7560: 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69   Individual OS i
7570: 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c  nterface.** impl
7580: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c  ementations will
7590: 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63  .** want to subc
75a0: 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74  lass this object
75b0: 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64   by appending ad
75c0: 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a  ditional fields.
75d0: 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e  ** for their own
75e0: 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68   use.  The pMeth
75f0: 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61 20 70  ods entry is a p
7600: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
7610: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
7620: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74  ods] object that
7630: 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73   defines methods
7640: 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a   for performing.
7650: 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e  ** I/O operation
7660: 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69  s on the open fi
7670: 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  le..*/.typedef s
7680: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69  truct sqlite3_fi
7690: 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b  le sqlite3_file;
76a0: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
76b0: 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73  file {.  const s
76c0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
76d0: 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f  _methods *pMetho
76e0: 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  ds;  /* Methods 
76f0: 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  for an open file
7700: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
7710: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
7720: 66 61 63 65 20 46 69 6c 65 20 56 69 72 74 75 61  face File Virtua
7730: 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74  l Methods Object
7740: 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c  .**.** Every fil
7750: 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20  e opened by the 
7760: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
7770: 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c  en] method popul
7780: 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  ates an.** [sqli
7790: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
77a0: 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f   (or, more commo
77b0: 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73 20  nly, a subclass 
77c0: 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
77d0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29  e3_file] object)
77e0: 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20   with a pointer 
77f0: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
7800: 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a  f this object..*
7810: 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65  * This object de
7820: 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f 64  fines the method
7830: 73 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72  s used to perfor
7840: 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74  m various operat
7850: 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20  ions.** against 
7860: 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 65  the open file re
7870: 70 72 65 73 65 6e 74 65 64 20 62 79 20 74 68 65  presented by the
7880: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
7890: 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66  object..**.** If
78a0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
78b0: 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20  s.xOpen] method 
78c0: 73 65 74 73 20 74 68 65 20 73 71 6c 69 74 65 33  sets the sqlite3
78d0: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65  _file.pMethods e
78e0: 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 20  lement .** to a 
78f0: 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  non-NULL pointer
7900: 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74  , then the sqlit
7910: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 43  e3_io_methods.xC
7920: 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d  lose method.** m
7930: 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 76  ay be invoked ev
7940: 65 6e 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74  en if the [sqlit
7950: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 72 65  e3_vfs.xOpen] re
7960: 70 6f 72 74 65 64 20 74 68 61 74 20 69 74 20 66  ported that it f
7970: 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f  ailed.  The.** o
7980: 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 65 76 65  nly way to preve
7990: 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c  nt a call to xCl
79a0: 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  ose following a 
79b0: 66 61 69 6c 65 64 20 5b 73 71 6c 69 74 65 33 5f  failed [sqlite3_
79c0: 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73  vfs.xOpen].** is
79d0: 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65   for the [sqlite
79e0: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74 6f 20  3_vfs.xOpen] to 
79f0: 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f  set the sqlite3_
7a00: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c  file.pMethods el
7a10: 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c  ement.** to NULL
7a20: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67  ..**.** The flag
7a30: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53  s argument to xS
7a40: 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f  ync may be one o
7a50: 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  f [SQLITE_SYNC_N
7a60: 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51  ORMAL] or.** [SQ
7a70: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e  LITE_SYNC_FULL].
7a80: 20 20 54 68 65 20 66 69 72 73 74 20 63 68 6f 69    The first choi
7a90: 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c  ce is the normal
7aa0: 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65   fsync()..** The
7ab0: 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69   second choice i
7ac0: 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73 74 79  s a Mac OS X sty
7ad0: 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68  le fullsync.  Th
7ae0: 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  e [SQLITE_SYNC_D
7af0: 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67  ATAONLY].** flag
7b00: 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20   may be ORed in 
7b10: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  to indicate that
7b20: 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f   only the data o
7b30: 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e  f the file.** an
7b40: 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20  d not its inode 
7b50: 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63  needs to be sync
7b60: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  ed..**.** The in
7b70: 74 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20  teger values to 
7b80: 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c  xLock() and xUnl
7b90: 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66  ock() are one of
7ba0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
7bb0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f   [SQLITE_LOCK_NO
7bc0: 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  NE],.** <li> [SQ
7bd0: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
7be0: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
7bf0: 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44  TE_LOCK_RESERVED
7c00: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
7c10: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d  TE_LOCK_PENDING]
7c20: 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  , or.** <li> [SQ
7c30: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53  LITE_LOCK_EXCLUS
7c40: 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  IVE]..** </ul>.*
7c50: 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61  * xLock() increa
7c60: 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55  ses the lock. xU
7c70: 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65  nlock() decrease
7c80: 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54  s the lock..** T
7c90: 68 65 20 78 43 68 65 63 6b 52 65 73 65 72 76 65  he xCheckReserve
7ca0: 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63  dLock() method c
7cb0: 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e  hecks whether an
7cc0: 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  y database conne
7cd0: 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72  ction,.** either
7ce0: 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73   in this process
7cf0: 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65   or in some othe
7d00: 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f  r process, is ho
7d10: 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56 45 44  lding a RESERVED
7d20: 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72  ,.** PENDING, or
7d30: 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20   EXCLUSIVE lock 
7d40: 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74  on the file.  It
7d50: 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a   returns true.**
7d60: 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20   if such a lock 
7d70: 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65  exists and false
7d80: 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a   otherwise..**.*
7d90: 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  * The xFileContr
7da0: 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61  ol() method is a
7db0: 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61   generic interfa
7dc0: 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63  ce that allows c
7dd0: 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70  ustom.** VFS imp
7de0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20  lementations to 
7df0: 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c  directly control
7e00: 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73   an open file us
7e10: 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ing the.** [sqli
7e20: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
7e30: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ()] interface.  
7e40: 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20  The second "op" 
7e50: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a  argument is an.*
7e60: 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65  * integer opcode
7e70: 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67  .  The third arg
7e80: 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72  ument is a gener
7e90: 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e  ic pointer inten
7ea0: 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20  ded to.** point 
7eb0: 74 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 74  to a structure t
7ec0: 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20  hat may contain 
7ed0: 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61  arguments or spa
7ee0: 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a  ce in which to.*
7ef0: 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 76  * write return v
7f00: 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61  alues.  Potentia
7f10: 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65  l uses for xFile
7f20: 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20  Control() might 
7f30: 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  be.** functions 
7f40: 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69  to enable blocki
7f50: 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69  ng locks with ti
7f60: 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67  meouts, to chang
7f70: 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67  e the.** locking
7f80: 20 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 65   strategy (for e
7f90: 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f  xample to use do
7fa0: 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74  t-file locks), t
7fb0: 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f  o inquire.** abo
7fc0: 75 74 20 74 68 65 20 73 74 61 74 75 73 20 6f 66  ut the status of
7fd0: 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62   a lock, or to b
7fe0: 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73  reak stale locks
7ff0: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a  .  The SQLite.**
8000: 20 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 61   core reserves a
8010: 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20  ll opcodes less 
8020: 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73  than 100 for its
8030: 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b   own use..** A [
8040: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63  file control opc
8050: 6f 64 65 73 20 7c 20 6c 69 73 74 20 6f 66 20 6f  odes | list of o
8060: 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61  pcodes] less tha
8070: 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c 61 62  n 100 is availab
8080: 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  le..** Applicati
8090: 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65 20  ons that define 
80a0: 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f  a custom xFileCo
80b0: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f  ntrol method sho
80c0: 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73 0a  uld use opcodes.
80d0: 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  ** greater than 
80e0: 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e  100 to avoid con
80f0: 66 6c 69 63 74 73 2e 20 20 56 46 53 20 69 6d 70  flicts.  VFS imp
8100: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f  lementations sho
8110: 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  uld.** return [S
8120: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20  QLITE_NOTFOUND] 
8130: 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  for file control
8140: 20 6f 70 63 6f 64 65 73 20 74 68 61 74 20 74 68   opcodes that th
8150: 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63  ey do not.** rec
8160: 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  ognize..**.** Th
8170: 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29 20  e xSectorSize() 
8180: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 74  method returns t
8190: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 6f  he sector size o
81a0: 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 20  f the.** device 
81b0: 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20 74  that underlies t
81c0: 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73 65  he file.  The se
81d0: 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68 65  ctor size is the
81e0: 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74  .** minimum writ
81f0: 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 65  e that can be pe
8200: 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 20  rformed without 
8210: 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74  disturbing.** ot
8220: 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68 65  her bytes in the
8230: 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65 76   file.  The xDev
8240: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
8250: 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72  cs().** method r
8260: 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65 63  eturns a bit vec
8270: 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20 62  tor describing b
8280: 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65 0a  ehaviors of the.
8290: 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 65  ** underlying de
82a0: 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  vice:.**.** <ul>
82b0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
82c0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a  _IOCAP_ATOMIC].*
82d0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
82e0: 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a  OCAP_ATOMIC512].
82f0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8300: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a  IOCAP_ATOMIC1K].
8310: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8320: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a  IOCAP_ATOMIC2K].
8330: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8340: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a  IOCAP_ATOMIC4K].
8350: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8360: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a  IOCAP_ATOMIC8K].
8370: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8380: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d  IOCAP_ATOMIC16K]
8390: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
83a0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b  _IOCAP_ATOMIC32K
83b0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
83c0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34  E_IOCAP_ATOMIC64
83d0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
83e0: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
83f0: 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  PEND].** <li> [S
8400: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
8410: 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  ENTIAL].** <li> 
8420: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e  [SQLITE_IOCAP_UN
8430: 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f  DELETABLE_WHEN_O
8440: 50 45 4e 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  PEN].** <li> [SQ
8450: 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52  LITE_IOCAP_POWER
8460: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 0a  SAFE_OVERWRITE].
8470: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8480: 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 5d  IOCAP_IMMUTABLE]
8490: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
84a0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
84b0: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79  _ATOMIC property
84c0: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20   means that all 
84d0: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79  writes of.** any
84e0: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63   size are atomic
84f0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
8500: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61  CAP_ATOMICnnn va
8510: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61  lues.** mean tha
8520: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63  t writes of bloc
8530: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20  ks that are nnn 
8540: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
8550: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64  d.** are aligned
8560: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77   to an address w
8570: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67  hich is an integ
8580: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a  er multiple of.*
8590: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63  * nnn are atomic
85a0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
85b0: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
85c0: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74  value means.** t
85d0: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73  hat when data is
85e0: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66   appended to a f
85f0: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73  ile, the data is
8600: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72   appended.** fir
8610: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65  st then the size
8620: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   of the file is 
8630: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20  extended, never 
8640: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79  the other.** way
8650: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51   around.  The SQ
8660: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
8670: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d  NTIAL property m
8680: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66  eans that.** inf
8690: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74  ormation is writ
86a0: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74  ten to disk in t
86b0: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73  he same order as
86c0: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72   calls.** to xWr
86d0: 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ite()..**.** If 
86e0: 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73 20  xRead() returns 
86f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f  SQLITE_IOERR_SHO
8700: 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20  RT_READ it must 
8710: 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20  also fill.** in 
8720: 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69  the unread porti
8730: 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66 65  ons of the buffe
8740: 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41  r with zeros.  A
8750: 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69   VFS that.** fai
8760: 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20  ls to zero-fill 
8770: 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68  short reads migh
8780: 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20  t seem to work. 
8790: 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69   However,.** fai
87a0: 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c  lure to zero-fil
87b0: 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77 69  l short reads wi
87c0: 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65  ll eventually le
87d0: 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73  ad to.** databas
87e0: 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f  e corruption..*/
87f0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
8800: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
8810: 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ds sqlite3_io_me
8820: 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
8830: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
8840: 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
8850: 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73  n;.  int (*xClos
8860: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
8870: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64  );.  int (*xRead
8880: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8890: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74   void*, int iAmt
88a0: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
88b0: 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a  iOfst);.  int (*
88c0: 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f  xWrite)(sqlite3_
88d0: 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  file*, const voi
88e0: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71  d*, int iAmt, sq
88f0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
8900: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75  t);.  int (*xTru
8910: 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66  ncate)(sqlite3_f
8920: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
8930: 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74  t64 size);.  int
8940: 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65   (*xSync)(sqlite
8950: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61  3_file*, int fla
8960: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  gs);.  int (*xFi
8970: 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f  leSize)(sqlite3_
8980: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
8990: 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20  nt64 *pSize);.  
89a0: 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c  int (*xLock)(sql
89b0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29  ite3_file*, int)
89c0: 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63  ;.  int (*xUnloc
89d0: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
89e0: 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a  , int);.  int (*
89f0: 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f  xCheckReservedLo
8a00: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
8a10: 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29  *, int *pResOut)
8a20: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43  ;.  int (*xFileC
8a30: 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f  ontrol)(sqlite3_
8a40: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76  file*, int op, v
8a50: 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e  oid *pArg);.  in
8a60: 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29  t (*xSectorSize)
8a70: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
8a80: 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65  .  int (*xDevice
8a90: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 29  Characteristics)
8aa0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
8ab0: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62  .  /* Methods ab
8ac0: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f  ove are valid fo
8ad0: 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20  r version 1 */. 
8ae0: 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29 28   int (*xShmMap)(
8af0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8b00: 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73 7a  nt iPg, int pgsz
8b10: 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61  , int, void vola
8b20: 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28  tile**);.  int (
8b30: 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74  *xShmLock)(sqlit
8b40: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66  e3_file*, int of
8b50: 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74  fset, int n, int
8b60: 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64 20   flags);.  void 
8b70: 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28 73  (*xShmBarrier)(s
8b80: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
8b90: 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70   int (*xShmUnmap
8ba0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8bb0: 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67 29   int deleteFlag)
8bc0: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
8bd0: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
8be0: 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a  or version 2 */.
8bf0: 20 20 69 6e 74 20 28 2a 78 46 65 74 63 68 29 28    int (*xFetch)(
8c00: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
8c10: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
8c20: 73 74 2c 20 69 6e 74 20 69 41 6d 74 2c 20 76 6f  st, int iAmt, vo
8c30: 69 64 20 2a 2a 70 70 29 3b 0a 20 20 69 6e 74 20  id **pp);.  int 
8c40: 28 2a 78 55 6e 66 65 74 63 68 29 28 73 71 6c 69  (*xUnfetch)(sqli
8c50: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
8c60: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20  e3_int64 iOfst, 
8c70: 76 6f 69 64 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d  void *p);.  /* M
8c80: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
8c90: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69   valid for versi
8ca0: 6f 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20 41 64 64  on 3 */.  /* Add
8cb0: 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20  itional methods 
8cc0: 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
8cd0: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
8ce0: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
8cf0: 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20  I3REF: Standard 
8d00: 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63  File Control Opc
8d10: 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  odes.** KEYWORDS
8d20: 3a 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  : {file control 
8d30: 6f 70 63 6f 64 65 73 7d 20 7b 66 69 6c 65 20 63  opcodes} {file c
8d40: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 7d 0a 2a  ontrol opcode}.*
8d50: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67  *.** These integ
8d60: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  er constants are
8d70: 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65   opcodes for the
8d80: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
8d90: 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  thod.** of the [
8da0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
8db0: 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66  ds] object and f
8dc0: 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  or the [sqlite3_
8dd0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a  file_control()].
8de0: 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  ** interface..**
8df0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
8e00: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c  [[SQLITE_FCNTL_L
8e10: 4f 43 4b 53 54 41 54 45 5d 5d 0a 2a 2a 20 54 68  OCKSTATE]].** Th
8e20: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
8e30: 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64  LOCKSTATE] opcod
8e40: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65  e is used for de
8e50: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a  bugging.  This.*
8e60: 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20  * opcode causes 
8e70: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
8e80: 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65   method to write
8e90: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
8ea0: 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63  te of.** the loc
8eb0: 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  k (one of [SQLIT
8ec0: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53  E_LOCK_NONE], [S
8ed0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
8ee0: 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c  D],.** [SQLITE_L
8ef0: 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b  OCK_RESERVED], [
8f00: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
8f10: 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  ING], or [SQLITE
8f20: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d  _LOCK_EXCLUSIVE]
8f30: 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74  ).** into an int
8f40: 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41  eger that the pA
8f50: 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  rg argument poin
8f60: 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61  ts to. This capa
8f70: 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65  bility.** is use
8f80: 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67  d during testing
8f90: 20 61 6e 64 20 69 73 20 6f 6e 6c 79 20 61 76 61   and is only ava
8fa0: 69 6c 61 62 6c 65 20 77 68 65 6e 20 74 68 65 20  ilable when the 
8fb0: 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 63  SQLITE_TEST.** c
8fc0: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
8fd0: 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  on is used..**.*
8fe0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
8ff0: 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d  CNTL_SIZE_HINT]]
9000: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
9010: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d  FCNTL_SIZE_HINT]
9020: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
9030: 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67 69 76  by SQLite to giv
9040: 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79  e the VFS.** lay
9050: 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68 6f 77  er a hint of how
9060: 20 6c 61 72 67 65 20 74 68 65 20 64 61 74 61 62   large the datab
9070: 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 67 72  ase file will gr
9080: 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e 67 20  ow to be during 
9090: 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74  the.** current t
90a0: 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68 69  ransaction.  Thi
90b0: 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20 67 75  s hint is not gu
90c0: 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 61  aranteed to be a
90d0: 63 63 75 72 61 74 65 20 62 75 74 20 69 74 0a 2a  ccurate but it.*
90e0: 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65  * is often close
90f0: 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e  .  The underlyin
9100: 67 20 56 46 53 20 6d 69 67 68 74 20 63 68 6f 6f  g VFS might choo
9110: 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74  se to preallocat
9120: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  e database.** fi
9130: 6c 65 20 73 70 61 63 65 20 62 61 73 65 64 20 6f  le space based o
9140: 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e 20 6f  n this hint in o
9150: 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77 72 69  rder to help wri
9160: 74 65 73 20 74 6f 20 74 68 65 20 64 61 74 61 62  tes to the datab
9170: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20  ase.** file run 
9180: 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  faster..**.** <l
9190: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
91a0: 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a  _CHUNK_SIZE]].**
91b0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
91c0: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f  TL_CHUNK_SIZE] o
91d0: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
91e0: 20 72 65 71 75 65 73 74 20 74 68 61 74 20 74 68   request that th
91f0: 65 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73  e VFS.** extends
9200: 20 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74   and truncates t
9210: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
9220: 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20   in chunks of a 
9230: 73 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a  size specified.*
9240: 2a 20 62 79 20 74 68 65 20 75 73 65 72 2e 20 54  * by the user. T
9250: 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
9260: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  nt to [sqlite3_f
9270: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73  ile_control()] s
9280: 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20  hould .** point 
9290: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74  to an integer (t
92a0: 79 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e  ype int) contain
92b0: 69 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e  ing the new chun
92c0: 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a  k-size to use.**
92d0: 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74   for the nominat
92e0: 65 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c  ed database. All
92f0: 6f 63 61 74 69 6e 67 20 64 61 74 61 62 61 73 65  ocating database
9300: 20 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c   file space in l
9310: 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28  arge.** chunks (
9320: 73 61 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d  say 1MB at a tim
9330: 65 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66  e), may reduce f
9340: 69 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d  ile-system fragm
9350: 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20  entation and.** 
9360: 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61  improve performa
9370: 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74  nce on some syst
9380: 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ems..**.** <li>[
9390: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49  [SQLITE_FCNTL_FI
93a0: 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20  LE_POINTER]].** 
93b0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
93c0: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20  L_FILE_POINTER] 
93d0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
93e0: 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74  o obtain a point
93f0: 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  er.** to the [sq
9400: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
9410: 63 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ct associated wi
9420: 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  th a particular 
9430: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
9440: 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 61 6c 73  ection.  See als
9450: 6f 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  o [SQLITE_FCNTL_
9460: 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d  JOURNAL_POINTER]
9470: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
9480: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e  LITE_FCNTL_JOURN
9490: 41 4c 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20  AL_POINTER]].** 
94a0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
94b0: 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45  L_JOURNAL_POINTE
94c0: 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  R] opcode is use
94d0: 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f  d to obtain a po
94e0: 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
94f0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
9500: 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 64  bject associated
9510: 20 77 69 74 68 20 74 68 65 20 6a 6f 75 72 6e 61   with the journa
9520: 6c 20 66 69 6c 65 20 28 65 69 74 68 65 72 0a 2a  l file (either.*
9530: 2a 20 74 68 65 20 5b 72 6f 6c 6c 62 61 63 6b 20  * the [rollback 
9540: 6a 6f 75 72 6e 61 6c 5d 20 6f 72 20 74 68 65 20  journal] or the 
9550: 5b 77 72 69 74 65 2d 61 68 65 61 64 20 6c 6f 67  [write-ahead log
9560: 5d 29 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  ]) for a particu
9570: 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  lar database.** 
9580: 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65  connection.  See
9590: 20 61 6c 73 6f 20 5b 53 51 4c 49 54 45 5f 46 43   also [SQLITE_FC
95a0: 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52  NTL_FILE_POINTER
95b0: 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  ]..**.** <li>[[S
95c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
95d0: 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20 4e 6f  _OMITTED]].** No
95e0: 20 6c 6f 6e 67 65 72 20 69 6e 20 75 73 65 2e 0a   longer in use..
95f0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9600: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 5d 0a  TE_FCNTL_SYNC]].
9610: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
9620: 43 4e 54 4c 5f 53 59 4e 43 5d 20 6f 70 63 6f 64  CNTL_SYNC] opcod
9630: 65 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 69  e is generated i
9640: 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c  nternally by SQL
9650: 69 74 65 20 61 6e 64 0a 2a 2a 20 73 65 6e 74 20  ite and.** sent 
9660: 74 6f 20 74 68 65 20 56 46 53 20 69 6d 6d 65 64  to the VFS immed
9670: 69 61 74 65 6c 79 20 62 65 66 6f 72 65 20 74 68  iately before th
9680: 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 69  e xSync method i
9690: 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 0a 2a  s invoked on a.*
96a0: 2a 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  * database file 
96b0: 64 65 73 63 72 69 70 74 6f 72 2e 20 4f 72 2c 20  descriptor. Or, 
96c0: 69 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74  if the xSync met
96d0: 68 6f 64 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b  hod is not invok
96e0: 65 64 20 0a 2a 2a 20 62 65 63 61 75 73 65 20 74  ed .** because t
96f0: 68 65 20 75 73 65 72 20 68 61 73 20 63 6f 6e 66  he user has conf
9700: 69 67 75 72 65 64 20 53 51 4c 69 74 65 20 77 69  igured SQLite wi
9710: 74 68 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 73  th .** [PRAGMA s
9720: 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41  ynchronous | PRA
9730: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d  GMA synchronous=
9740: 4f 46 46 5d 20 69 74 20 69 73 20 69 6e 76 6f 6b  OFF] it is invok
9750: 65 64 20 69 6e 20 70 6c 61 63 65 20 0a 2a 2a 20  ed in place .** 
9760: 6f 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74  of the xSync met
9770: 68 6f 64 2e 20 49 6e 20 6d 6f 73 74 20 63 61 73  hod. In most cas
9780: 65 73 2c 20 74 68 65 20 70 6f 69 6e 74 65 72 20  es, the pointer 
9790: 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20  argument passed 
97a0: 77 69 74 68 0a 2a 2a 20 74 68 69 73 20 66 69 6c  with.** this fil
97b0: 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 4e 55 4c  e-control is NUL
97c0: 4c 2e 20 48 6f 77 65 76 65 72 2c 20 69 66 20 74  L. However, if t
97d0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
97e0: 20 69 73 20 62 65 69 6e 67 20 73 79 6e 63 65 64   is being synced
97f0: 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 61  .** as part of a
9800: 20 6d 75 6c 74 69 2d 64 61 74 61 62 61 73 65 20   multi-database 
9810: 63 6f 6d 6d 69 74 2c 20 74 68 65 20 61 72 67 75  commit, the argu
9820: 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 20 61  ment points to a
9830: 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a   nul-terminated.
9840: 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69  ** string contai
9850: 6e 69 6e 67 20 74 68 65 20 74 72 61 6e 73 61 63  ning the transac
9860: 74 69 6f 6e 73 20 6d 61 73 74 65 72 2d 6a 6f 75  tions master-jou
9870: 72 6e 61 6c 20 66 69 6c 65 20 6e 61 6d 65 2e 20  rnal file name. 
9880: 56 46 53 65 73 20 74 68 61 74 20 0a 2a 2a 20 64  VFSes that .** d
9890: 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20  o not need this 
98a0: 73 69 67 6e 61 6c 20 73 68 6f 75 6c 64 20 73 69  signal should si
98b0: 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68  lently ignore th
98c0: 69 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69  is opcode. Appli
98d0: 63 61 74 69 6f 6e 73 20 0a 2a 2a 20 73 68 6f 75  cations .** shou
98e0: 6c 64 20 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c  ld not call [sql
98f0: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
9900: 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f  l()] with this o
9910: 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73  pcode as doing s
9920: 6f 20 6d 61 79 20 0a 2a 2a 20 64 69 73 72 75 70  o may .** disrup
9930: 74 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20  t the operation 
9940: 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a  of the specializ
9950: 65 64 20 56 46 53 65 73 20 74 68 61 74 20 64 6f  ed VFSes that do
9960: 20 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a   require it.  .*
9970: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9980: 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50  E_FCNTL_COMMIT_P
9990: 48 41 53 45 54 57 4f 5d 5d 0a 2a 2a 20 54 68 65  HASETWO]].** The
99a0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43   [SQLITE_FCNTL_C
99b0: 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 20  OMMIT_PHASETWO] 
99c0: 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61  opcode is genera
99d0: 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62  ted internally b
99e0: 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20  y SQLite.** and 
99f0: 73 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20  sent to the VFS 
9a00: 61 66 74 65 72 20 61 20 74 72 61 6e 73 61 63 74  after a transact
9a10: 69 6f 6e 20 68 61 73 20 62 65 65 6e 20 63 6f 6d  ion has been com
9a20: 6d 69 74 74 65 64 20 69 6d 6d 65 64 69 61 74 65  mitted immediate
9a30: 6c 79 0a 2a 2a 20 62 75 74 20 62 65 66 6f 72 65  ly.** but before
9a40: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
9a50: 20 75 6e 6c 6f 63 6b 65 64 2e 20 56 46 53 65 73   unlocked. VFSes
9a60: 20 74 68 61 74 20 64 6f 20 6e 6f 74 20 6e 65 65   that do not nee
9a70: 64 20 74 68 69 73 20 73 69 67 6e 61 6c 0a 2a 2a  d this signal.**
9a80: 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79   should silently
9a90: 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63   ignore this opc
9aa0: 6f 64 65 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e  ode. Application
9ab0: 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c  s should not cal
9ac0: 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  l.** [sqlite3_fi
9ad0: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69  le_control()] wi
9ae0: 74 68 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61  th this opcode a
9af0: 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64  s doing so may d
9b00: 69 73 72 75 70 74 20 74 68 65 20 0a 2a 2a 20 6f  isrupt the .** o
9b10: 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  peration of the 
9b20: 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65  specialized VFSe
9b30: 73 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72  s that do requir
9b40: 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c  e it.  .**.** <l
9b50: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
9b60: 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d  _WIN32_AV_RETRY]
9b70: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
9b80: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56  E_FCNTL_WIN32_AV
9b90: 5f 52 45 54 52 59 5d 20 6f 70 63 6f 64 65 20 69  _RETRY] opcode i
9ba0: 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67  s used to config
9bb0: 75 72 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a  ure automatic.**
9bc0: 20 72 65 74 72 79 20 63 6f 75 6e 74 73 20 61 6e   retry counts an
9bd0: 64 20 69 6e 74 65 72 76 61 6c 73 20 66 6f 72 20  d intervals for 
9be0: 63 65 72 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f  certain disk I/O
9bf0: 20 6f 70 65 72 61 74 69 6f 6e 73 20 66 6f 72 20   operations for 
9c00: 74 68 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b  the.** windows [
9c10: 56 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f  VFS] in order to
9c20: 20 70 72 6f 76 69 64 65 20 72 6f 62 75 73 74 6e   provide robustn
9c30: 65 73 73 20 69 6e 20 74 68 65 20 70 72 65 73 65  ess in the prese
9c40: 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76  nce of.** anti-v
9c50: 69 72 75 73 20 70 72 6f 67 72 61 6d 73 2e 20 20  irus programs.  
9c60: 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20  By default, the 
9c70: 77 69 6e 64 6f 77 73 20 56 46 53 20 77 69 6c 6c  windows VFS will
9c80: 20 72 65 74 72 79 20 66 69 6c 65 20 72 65 61 64   retry file read
9c90: 2c 0a 2a 2a 20 66 69 6c 65 20 77 72 69 74 65 2c  ,.** file write,
9ca0: 20 61 6e 64 20 66 69 6c 65 20 64 65 6c 65 74 65   and file delete
9cb0: 20 6f 70 65 72 61 74 69 6f 6e 73 20 75 70 20 74   operations up t
9cc0: 6f 20 31 30 20 74 69 6d 65 73 2c 20 77 69 74 68  o 10 times, with
9cd0: 20 61 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32   a delay.** of 2
9ce0: 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62  5 milliseconds b
9cf0: 65 66 6f 72 65 20 74 68 65 20 66 69 72 73 74 20  efore the first 
9d00: 72 65 74 72 79 20 61 6e 64 20 77 69 74 68 20 74  retry and with t
9d10: 68 65 20 64 65 6c 61 79 20 69 6e 63 72 65 61 73  he delay increas
9d20: 69 6e 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64  ing.** by an add
9d30: 69 74 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69  itional 25 milli
9d40: 73 65 63 6f 6e 64 73 20 77 69 74 68 20 65 61 63  seconds with eac
9d50: 68 20 73 75 62 73 65 71 75 65 6e 74 20 72 65 74  h subsequent ret
9d60: 72 79 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63  ry.  This.** opc
9d70: 6f 64 65 20 61 6c 6c 6f 77 73 20 74 68 65 73 65  ode allows these
9d80: 20 74 77 6f 20 76 61 6c 75 65 73 20 28 31 30 20   two values (10 
9d90: 72 65 74 72 69 65 73 20 61 6e 64 20 32 35 20 6d  retries and 25 m
9da0: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 64  illiseconds of d
9db0: 65 6c 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61  elay).** to be a
9dc0: 64 6a 75 73 74 65 64 2e 20 20 54 68 65 20 76 61  djusted.  The va
9dd0: 6c 75 65 73 20 61 72 65 20 63 68 61 6e 67 65 64  lues are changed
9de0: 20 66 6f 72 20 61 6c 6c 20 64 61 74 61 62 61 73   for all databas
9df0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a  e connections.**
9e00: 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65   within the same
9e10: 20 70 72 6f 63 65 73 73 2e 20 20 54 68 65 20 61   process.  The a
9e20: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
9e30: 6e 74 65 72 20 74 6f 20 61 6e 20 61 72 72 61 79  nter to an array
9e40: 20 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67   of two.** integ
9e50: 65 72 73 20 77 68 65 72 65 20 74 68 65 20 66 69  ers where the fi
9e60: 72 73 74 20 69 6e 74 65 67 65 72 20 69 20 74 68  rst integer i th
9e70: 65 20 6e 65 77 20 72 65 74 72 79 20 63 6f 75 6e  e new retry coun
9e80: 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  t and the second
9e90: 0a 2a 2a 20 69 6e 74 65 67 65 72 20 69 73 20 74  .** integer is t
9ea0: 68 65 20 64 65 6c 61 79 2e 20 20 49 66 20 65 69  he delay.  If ei
9eb0: 74 68 65 72 20 69 6e 74 65 67 65 72 20 69 73 20  ther integer is 
9ec0: 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74  negative, then t
9ed0: 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73  he setting.** is
9ee0: 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 62 75 74   not changed but
9ef0: 20 69 6e 73 74 65 61 64 20 74 68 65 20 70 72 69   instead the pri
9f00: 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74  or value of that
9f10: 20 73 65 74 74 69 6e 67 20 69 73 20 77 72 69 74   setting is writ
9f20: 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20  ten.** into the 
9f30: 61 72 72 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c  array entry, all
9f40: 6f 77 69 6e 67 20 74 68 65 20 63 75 72 72 65 6e  owing the curren
9f50: 74 20 72 65 74 72 79 20 73 65 74 74 69 6e 67 73  t retry settings
9f60: 20 74 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72   to be.** interr
9f70: 6f 67 61 74 65 64 2e 20 20 54 68 65 20 7a 44 62  ogated.  The zDb
9f80: 4e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69  Name parameter i
9f90: 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a  s ignored..**.**
9fa0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
9fb0: 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d  NTL_PERSIST_WAL]
9fc0: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
9fd0: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
9fe0: 57 41 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  WAL] opcode is u
9ff0: 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75  sed to set or qu
a000: 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69  ery the.** persi
a010: 73 74 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69  stent [WAL | Wri
a020: 74 65 20 41 68 65 61 64 20 4c 6f 67 5d 20 73 65  te Ahead Log] se
a030: 74 74 69 6e 67 2e 20 20 42 79 20 64 65 66 61 75  tting.  By defau
a040: 6c 74 2c 20 74 68 65 20 61 75 78 69 6c 69 61 72  lt, the auxiliar
a050: 79 0a 2a 2a 20 77 72 69 74 65 20 61 68 65 61 64  y.** write ahead
a060: 20 6c 6f 67 20 61 6e 64 20 73 68 61 72 65 64 20   log and shared 
a070: 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 75 73 65  memory files use
a080: 64 20 66 6f 72 20 74 72 61 6e 73 61 63 74 69 6f  d for transactio
a090: 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65  n control.** are
a0a0: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64   automatically d
a0b0: 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65 20  eleted when the 
a0c0: 6c 61 74 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f  latest connectio
a0d0: 6e 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  n to the databas
a0e0: 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65  e.** closes.  Se
a0f0: 74 74 69 6e 67 20 70 65 72 73 69 73 74 65 6e 74  tting persistent
a100: 20 57 41 4c 20 6d 6f 64 65 20 63 61 75 73 65 73   WAL mode causes
a110: 20 74 68 6f 73 65 20 66 69 6c 65 73 20 74 6f 20   those files to 
a120: 70 65 72 73 69 73 74 20 61 66 74 65 72 0a 2a 2a  persist after.**
a130: 20 63 6c 6f 73 65 2e 20 20 50 65 72 73 69 73 74   close.  Persist
a140: 69 6e 67 20 74 68 65 20 66 69 6c 65 73 20 69 73  ing the files is
a150: 20 75 73 65 66 75 6c 20 77 68 65 6e 20 6f 74 68   useful when oth
a160: 65 72 20 70 72 6f 63 65 73 73 65 73 20 74 68 61  er processes tha
a170: 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65  t do not.** have
a180: 20 77 72 69 74 65 20 70 65 72 6d 69 73 73 69 6f   write permissio
a190: 6e 20 6f 6e 20 74 68 65 20 64 69 72 65 63 74 6f  n on the directo
a1a0: 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  ry containing th
a1b0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
a1c0: 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20  want.** to read 
a1d0: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
a1e0: 65 2c 20 61 73 20 74 68 65 20 57 41 4c 20 61 6e  e, as the WAL an
a1f0: 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20  d shared memory 
a200: 66 69 6c 65 73 20 6d 75 73 74 20 65 78 69 73 74  files must exist
a210: 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f 72  .** in order for
a220: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74 6f   the database to
a230: 20 62 65 20 72 65 61 64 61 62 6c 65 2e 20 20 54   be readable.  T
a240: 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
a250: 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ter to.** [sqlit
a260: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
a270: 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f  )] for this opco
a280: 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70  de should be a p
a290: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
a2a0: 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e  eger..** That in
a2b0: 74 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69  teger is 0 to di
a2c0: 73 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74  sable persistent
a2d0: 20 57 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74   WAL mode or 1 t
a2e0: 6f 20 65 6e 61 62 6c 65 20 70 65 72 73 69 73 74  o enable persist
a2f0: 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e  ent.** WAL mode.
a300: 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72    If the integer
a310: 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20   is -1, then it 
a320: 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77  is overwritten w
a330: 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a  ith the current.
a340: 2a 2a 20 57 41 4c 20 70 65 72 73 69 73 74 65 6e  ** WAL persisten
a350: 63 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a  ce setting..**.*
a360: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
a370: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f  CNTL_POWERSAFE_O
a380: 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54  VERWRITE]].** ^T
a390: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
a3a0: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
a3b0: 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20  RITE] opcode is 
a3c0: 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71  used to set or q
a3d0: 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73  uery the.** pers
a3e0: 69 73 74 65 6e 74 20 22 70 6f 77 65 72 73 61 66  istent "powersaf
a3f0: 65 2d 6f 76 65 72 77 72 69 74 65 22 20 6f 72 20  e-overwrite" or 
a400: 22 50 53 4f 57 22 20 73 65 74 74 69 6e 67 2e 20  "PSOW" setting. 
a410: 20 54 68 65 20 50 53 4f 57 20 73 65 74 74 69 6e   The PSOW settin
a420: 67 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73 20  g.** determines 
a430: 74 68 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  the [SQLITE_IOCA
a440: 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  P_POWERSAFE_OVER
a450: 57 52 49 54 45 5d 20 62 69 74 20 6f 66 20 74 68  WRITE] bit of th
a460: 65 0a 2a 2a 20 78 44 65 76 69 63 65 43 68 61 72  e.** xDeviceChar
a470: 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68  acteristics meth
a480: 6f 64 73 2e 20 54 68 65 20 66 6f 75 72 74 68 20  ods. The fourth 
a490: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
a4a0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
a4b0: 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69  ntrol()] for thi
a4c0: 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20  s opcode should 
a4d0: 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  be a pointer to 
a4e0: 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54  an integer..** T
a4f0: 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30  hat integer is 0
a500: 20 74 6f 20 64 69 73 61 62 6c 65 20 7a 65 72 6f   to disable zero
a510: 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20  -damage mode or 
a520: 31 20 74 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f  1 to enable zero
a530: 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e  -damage.** mode.
a540: 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72    If the integer
a550: 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20   is -1, then it 
a560: 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77  is overwritten w
a570: 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a  ith the current.
a580: 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d  ** zero-damage m
a590: 6f 64 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a  ode setting..**.
a5a0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
a5b0: 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d  FCNTL_OVERWRITE]
a5c0: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
a5d0: 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54  E_FCNTL_OVERWRIT
a5e0: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6e 76  E] opcode is inv
a5f0: 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 61  oked by SQLite a
a600: 66 74 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20  fter opening.** 
a610: 61 20 77 72 69 74 65 20 74 72 61 6e 73 61 63 74  a write transact
a620: 69 6f 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20  ion to indicate 
a630: 74 68 61 74 2c 20 75 6e 6c 65 73 73 20 69 74 20  that, unless it 
a640: 69 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66  is rolled back f
a650: 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f  or some.** reaso
a660: 6e 2c 20 74 68 65 20 65 6e 74 69 72 65 20 64 61  n, the entire da
a670: 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c  tabase file will
a680: 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20   be overwritten 
a690: 62 79 20 74 68 65 20 63 75 72 72 65 6e 74 20 0a  by the current .
a6a0: 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20  ** transaction. 
a6b0: 54 68 69 73 20 69 73 20 75 73 65 64 20 62 79 20  This is used by 
a6c0: 56 41 43 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e  VACUUM operation
a6d0: 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  s..**.** <li>[[S
a6e0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e  QLITE_FCNTL_VFSN
a6f0: 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  AME]].** ^The [S
a700: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e  QLITE_FCNTL_VFSN
a710: 41 4d 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20  AME] opcode can 
a720: 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  be used to obtai
a730: 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a  n the names of.*
a740: 2a 20 61 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e  * all [VFSes] in
a750: 20 74 68 65 20 56 46 53 20 73 74 61 63 6b 2e 20   the VFS stack. 
a760: 20 54 68 65 20 6e 61 6d 65 73 20 61 72 65 20 6f   The names are o
a770: 66 20 61 6c 6c 20 56 46 53 20 73 68 69 6d 73 20  f all VFS shims 
a780: 61 6e 64 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c  and the.** final
a790: 20 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46   bottom-level VF
a7a0: 53 20 61 72 65 20 77 72 69 74 74 65 6e 20 69 6e  S are written in
a7b0: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
a7c0: 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c  ed from .** [sql
a7d0: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61  ite3_malloc()] a
a7e0: 6e 64 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  nd the result is
a7f0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20 63   stored in the c
a800: 68 61 72 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a  har* variable.**
a810: 20 74 68 61 74 20 74 68 65 20 66 6f 75 72 74 68   that the fourth
a820: 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 5b 73   parameter of [s
a830: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
a840: 72 6f 6c 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f  rol()] points to
a850: 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 65 72 20  ..** The caller 
a860: 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
a870: 6f 72 20 66 72 65 65 69 6e 67 20 74 68 65 20 6d  or freeing the m
a880: 65 6d 6f 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e  emory when done.
a890: 20 20 41 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c    As with.** all
a8a0: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63   file-control ac
a8b0: 74 69 6f 6e 73 2c 20 74 68 65 72 65 20 69 73 20  tions, there is 
a8c0: 6e 6f 20 67 75 61 72 61 6e 74 65 65 20 74 68 61  no guarantee tha
a8d0: 74 20 74 68 69 73 20 77 69 6c 6c 20 61 63 74 75  t this will actu
a8e0: 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68  ally.** do anyth
a8f0: 69 6e 67 2e 20 20 43 61 6c 6c 65 72 73 20 73 68  ing.  Callers sh
a900: 6f 75 6c 64 20 69 6e 69 74 69 61 6c 69 7a 65 20  ould initialize 
a910: 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62  the char* variab
a920: 6c 65 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20  le to a NULL.** 
a930: 70 6f 69 6e 74 65 72 20 69 6e 20 63 61 73 65 20  pointer in case 
a940: 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  this file-contro
a950: 6c 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65  l is not impleme
a960: 6e 74 65 64 2e 20 20 54 68 69 73 20 66 69 6c 65  nted.  This file
a970: 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69  -control.** is i
a980: 6e 74 65 6e 64 65 64 20 66 6f 72 20 64 69 61 67  ntended for diag
a990: 6e 6f 73 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e  nostic use only.
a9a0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
a9b0: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f  ITE_FCNTL_VFS_PO
a9c0: 49 4e 54 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20  INTER]].** ^The 
a9d0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46  [SQLITE_FCNTL_VF
a9e0: 53 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64  S_POINTER] opcod
a9f0: 65 20 66 69 6e 64 73 20 61 20 70 6f 69 6e 74 65  e finds a pointe
aa00: 72 20 74 6f 20 74 68 65 20 74 6f 70 2d 6c 65 76  r to the top-lev
aa10: 65 6c 0a 2a 2a 20 5b 56 46 53 65 73 5d 20 63 75  el.** [VFSes] cu
aa20: 72 72 65 6e 74 6c 79 20 69 6e 20 75 73 65 2e 20  rrently in use. 
aa30: 20 5e 28 54 68 65 20 61 72 67 75 6d 65 6e 74 20   ^(The argument 
aa40: 58 20 69 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  X in.** sqlite3_
aa50: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 64 62 2c  file_control(db,
aa60: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53  SQLITE_FCNTL_VFS
aa70: 5f 50 4f 49 4e 54 45 52 2c 58 29 20 6d 75 73 74  _POINTER,X) must
aa80: 20 62 65 0a 2a 2a 20 6f 66 20 74 79 70 65 20 22   be.** of type "
aa90: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 2a 2a  [sqlite3_vfs] **
aaa0: 22 2e 20 20 54 68 69 73 20 6f 70 63 6f 64 65 73  ".  This opcodes
aab0: 20 77 69 6c 6c 20 73 65 74 20 2a 58 0a 2a 2a 20   will set *X.** 
aac0: 74 6f 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  to a pointer to 
aad0: 74 68 65 20 74 6f 70 2d 6c 65 76 65 6c 20 56 46  the top-level VF
aae0: 53 2e 29 5e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68  S.)^.** ^When th
aaf0: 65 72 65 20 61 72 65 20 6d 75 6c 74 69 70 6c 65  ere are multiple
ab00: 20 56 46 53 20 73 68 69 6d 73 20 69 6e 20 74 68   VFS shims in th
ab10: 65 20 73 74 61 63 6b 2c 20 74 68 69 73 20 6f 70  e stack, this op
ab20: 63 6f 64 65 20 66 69 6e 64 73 20 74 68 65 0a 2a  code finds the.*
ab30: 2a 20 75 70 70 65 72 2d 6d 6f 73 74 20 73 68 69  * upper-most shi
ab40: 6d 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  m only..**.** <l
ab50: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
ab60: 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68  _PRAGMA]].** ^Wh
ab70: 65 6e 65 76 65 72 20 61 20 5b 50 52 41 47 4d 41  enever a [PRAGMA
ab80: 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 70  ] statement is p
ab90: 61 72 73 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54  arsed, an [SQLIT
aba0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
abb0: 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  .** file control
abc0: 20 69 73 20 73 65 6e 74 20 74 6f 20 74 68 65 20   is sent to the 
abd0: 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  open [sqlite3_fi
abe0: 6c 65 5d 20 6f 62 6a 65 63 74 20 63 6f 72 72 65  le] object corre
abf0: 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74  sponding.** to t
ac00: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
ac10: 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 70 72   to which the pr
ac20: 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 72  agma statement r
ac30: 65 66 65 72 73 2e 20 5e 54 68 65 20 61 72 67 75  efers. ^The argu
ac40: 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  ment.** to the [
ac50: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
ac60: 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  GMA] file contro
ac70: 6c 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  l is an array of
ac80: 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  .** pointers to 
ac90: 73 74 72 69 6e 67 73 20 28 63 68 61 72 2a 2a 29  strings (char**)
aca0: 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 73 65   in which the se
acb0: 63 6f 6e 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20  cond element of 
acc0: 74 68 65 20 61 72 72 61 79 0a 2a 2a 20 69 73 20  the array.** is 
acd0: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
ace0: 70 72 61 67 6d 61 20 61 6e 64 20 74 68 65 20 74  pragma and the t
acf0: 68 69 72 64 20 65 6c 65 6d 65 6e 74 20 69 73 20  hird element is 
ad00: 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  the argument to 
ad10: 74 68 65 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72  the.** pragma or
ad20: 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 70 72 61   NULL if the pra
ad30: 67 6d 61 20 68 61 73 20 6e 6f 20 61 72 67 75 6d  gma has no argum
ad40: 65 6e 74 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c  ent.  ^The handl
ad50: 65 72 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51  er for an.** [SQ
ad60: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
ad70: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A] file control 
ad80: 63 61 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d  can optionally m
ad90: 61 6b 65 20 74 68 65 20 66 69 72 73 74 20 65 6c  ake the first el
ada0: 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20  ement.** of the 
adb0: 63 68 61 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20  char** argument 
adc0: 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e  point to a strin
add0: 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  g obtained from 
ade0: 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  [sqlite3_mprintf
adf0: 28 29 5d 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71  ()].** or the eq
ae00: 75 69 76 61 6c 65 6e 74 20 61 6e 64 20 74 68 61  uivalent and tha
ae10: 74 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65  t string will be
ae20: 63 6f 6d 65 20 74 68 65 20 72 65 73 75 6c 74 20  come the result 
ae30: 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 6f 72  of the pragma or
ae40: 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 6d 65  .** the error me
ae50: 73 73 61 67 65 20 69 66 20 74 68 65 20 70 72 61  ssage if the pra
ae60: 67 6d 61 20 66 61 69 6c 73 2e 20 5e 49 66 20 74  gma fails. ^If t
ae70: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43  he.** [SQLITE_FC
ae80: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65  NTL_PRAGMA] file
ae90: 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73   control returns
aea0: 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e   [SQLITE_NOTFOUN
aeb0: 44 5d 2c 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20  D], then normal 
aec0: 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f  .** [PRAGMA] pro
aed0: 63 65 73 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65  cessing continue
aee0: 73 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c  s.  ^If the [SQL
aef0: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
af00: 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f  ].** file contro
af10: 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  l returns [SQLIT
af20: 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20  E_OK], then the 
af30: 70 61 72 73 65 72 20 61 73 73 75 6d 65 73 20 74  parser assumes t
af40: 68 61 74 20 74 68 65 0a 2a 2a 20 56 46 53 20 68  hat the.** VFS h
af50: 61 73 20 68 61 6e 64 6c 65 64 20 74 68 65 20 50  as handled the P
af60: 52 41 47 4d 41 20 69 74 73 65 6c 66 20 61 6e 64  RAGMA itself and
af70: 20 74 68 65 20 70 61 72 73 65 72 20 67 65 6e 65   the parser gene
af80: 72 61 74 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a  rates a no-op.**
af90: 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
afa0: 65 6e 74 20 69 66 20 72 65 73 75 6c 74 20 73 74  ent if result st
afb0: 72 69 6e 67 20 69 73 20 4e 55 4c 4c 2c 20 6f 72  ring is NULL, or
afc0: 20 74 68 61 74 20 72 65 74 75 72 6e 73 20 61 20   that returns a 
afd0: 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 72  copy.** of the r
afe0: 65 73 75 6c 74 20 73 74 72 69 6e 67 20 69 66 20  esult string if 
aff0: 74 68 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f  the string is no
b000: 6e 2d 4e 55 4c 4c 2e 0a 2a 2a 20 5e 49 66 20 74  n-NULL..** ^If t
b010: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
b020: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
b030: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 0a 2a 2a  ntrol returns.**
b040: 20 61 6e 79 20 72 65 73 75 6c 74 20 63 6f 64 65   any result code
b050: 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
b060: 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49  ITE_OK] or [SQLI
b070: 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68  TE_NOTFOUND], th
b080: 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  at means.** that
b090: 20 74 68 65 20 56 46 53 20 65 6e 63 6f 75 6e 74   the VFS encount
b0a0: 65 72 65 64 20 61 6e 20 65 72 72 6f 72 20 77 68  ered an error wh
b0b0: 69 6c 65 20 68 61 6e 64 6c 69 6e 67 20 74 68 65  ile handling the
b0c0: 20 5b 50 52 41 47 4d 41 5d 20 61 6e 64 20 74 68   [PRAGMA] and th
b0d0: 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74 69 6f 6e  e.** compilation
b0e0: 20 6f 66 20 74 68 65 20 50 52 41 47 4d 41 20 66   of the PRAGMA f
b0f0: 61 69 6c 73 20 77 69 74 68 20 61 6e 20 65 72 72  ails with an err
b100: 6f 72 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54  or.  ^The [SQLIT
b110: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a  E_FCNTL_PRAGMA].
b120: 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  ** file control 
b130: 6f 63 63 75 72 73 20 61 74 20 74 68 65 20 62 65  occurs at the be
b140: 67 69 6e 6e 69 6e 67 20 6f 66 20 70 72 61 67 6d  ginning of pragm
b150: 61 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 61 6c  a statement anal
b160: 79 73 69 73 20 61 6e 64 20 73 6f 0a 2a 2a 20 69  ysis and so.** i
b170: 74 20 69 73 20 61 62 6c 65 20 74 6f 20 6f 76 65  t is able to ove
b180: 72 72 69 64 65 20 62 75 69 6c 74 2d 69 6e 20 5b  rride built-in [
b190: 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e  PRAGMA] statemen
b1a0: 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ts..**.** <li>[[
b1b0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53  SQLITE_FCNTL_BUS
b1c0: 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54  YHANDLER]].** ^T
b1d0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
b1e0: 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 0a 2a 2a  _BUSYHANDLER].**
b1f0: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61   file-control ma
b200: 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 62 79 20  y be invoked by 
b210: 53 51 4c 69 74 65 20 6f 6e 20 74 68 65 20 64 61  SQLite on the da
b220: 74 61 62 61 73 65 20 66 69 6c 65 20 68 61 6e 64  tabase file hand
b230: 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c 79 20 61 66  le.** shortly af
b240: 74 65 72 20 69 74 20 69 73 20 6f 70 65 6e 65 64  ter it is opened
b250: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f   in order to pro
b260: 76 69 64 65 20 61 20 63 75 73 74 6f 6d 20 56 46  vide a custom VF
b270: 53 20 77 69 74 68 20 61 63 63 65 73 73 0a 2a 2a  S with access.**
b280: 20 74 6f 20 74 68 65 20 63 6f 6e 6e 65 63 74 69   to the connecti
b290: 6f 6e 73 20 62 75 73 79 2d 68 61 6e 64 6c 65 72  ons busy-handler
b2a0: 20 63 61 6c 6c 62 61 63 6b 2e 20 54 68 65 20 61   callback. The a
b2b0: 72 67 75 6d 65 6e 74 20 69 73 20 6f 66 20 74 79  rgument is of ty
b2c0: 70 65 20 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20  pe (void **).** 
b2d0: 2d 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77  - an array of tw
b2e0: 6f 20 28 76 6f 69 64 20 2a 29 20 76 61 6c 75 65  o (void *) value
b2f0: 73 2e 20 54 68 65 20 66 69 72 73 74 20 28 76 6f  s. The first (vo
b300: 69 64 20 2a 29 20 61 63 74 75 61 6c 6c 79 20 70  id *) actually p
b310: 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 61 20 66 75  oints.** to a fu
b320: 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 28  nction of type (
b330: 69 6e 74 20 28 2a 29 28 76 6f 69 64 20 2a 29 29  int (*)(void *))
b340: 2e 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e  . In order to in
b350: 76 6f 6b 65 20 74 68 65 20 63 6f 6e 6e 65 63 74  voke the connect
b360: 69 6f 6e 73 0a 2a 2a 20 62 75 73 79 2d 68 61 6e  ions.** busy-han
b370: 64 6c 65 72 2c 20 74 68 69 73 20 66 75 6e 63 74  dler, this funct
b380: 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 69 6e  ion should be in
b390: 76 6f 6b 65 64 20 77 69 74 68 20 74 68 65 20 73  voked with the s
b3a0: 65 63 6f 6e 64 20 28 76 6f 69 64 20 2a 29 20 69  econd (void *) i
b3b0: 6e 0a 2a 2a 20 74 68 65 20 61 72 72 61 79 20 61  n.** the array a
b3c0: 73 20 74 68 65 20 6f 6e 6c 79 20 61 72 67 75 6d  s the only argum
b3d0: 65 6e 74 2e 20 49 66 20 69 74 20 72 65 74 75 72  ent. If it retur
b3e0: 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
b3f0: 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a  n the operation.
b400: 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74  ** should be ret
b410: 72 69 65 64 2e 20 49 66 20 69 74 20 72 65 74 75  ried. If it retu
b420: 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20 63 75  rns zero, the cu
b430: 73 74 6f 6d 20 56 46 53 20 73 68 6f 75 6c 64 20  stom VFS should 
b440: 61 62 61 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20 63  abandon the.** c
b450: 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e  urrent operation
b460: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
b470: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46  LITE_FCNTL_TEMPF
b480: 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70  ILENAME]].** ^Ap
b490: 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 69 6e  plication can in
b4a0: 76 6f 6b 65 20 74 68 65 20 5b 53 51 4c 49 54 45  voke the [SQLITE
b4b0: 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e  _FCNTL_TEMPFILEN
b4c0: 41 4d 45 5d 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  AME] file-contro
b4d0: 6c 0a 2a 2a 20 74 6f 20 68 61 76 65 20 53 51 4c  l.** to have SQL
b4e0: 69 74 65 20 67 65 6e 65 72 61 74 65 20 61 0a 2a  ite generate a.*
b4f0: 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  * temporary file
b500: 6e 61 6d 65 20 75 73 69 6e 67 20 74 68 65 20 73  name using the s
b510: 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 74 68  ame algorithm th
b520: 61 74 20 69 73 20 66 6f 6c 6c 6f 77 65 64 20 74  at is followed t
b530: 6f 20 67 65 6e 65 72 61 74 65 0a 2a 2a 20 74 65  o generate.** te
b540: 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65  mporary filename
b550: 73 20 66 6f 72 20 54 45 4d 50 20 74 61 62 6c 65  s for TEMP table
b560: 73 20 61 6e 64 20 6f 74 68 65 72 20 69 6e 74 65  s and other inte
b570: 72 6e 61 6c 20 75 73 65 73 2e 20 20 54 68 65 0a  rnal uses.  The.
b580: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  ** argument shou
b590: 6c 64 20 62 65 20 61 20 63 68 61 72 2a 2a 20 77  ld be a char** w
b5a0: 68 69 63 68 20 77 69 6c 6c 20 62 65 20 66 69 6c  hich will be fil
b5b0: 6c 65 64 20 77 69 74 68 20 74 68 65 20 66 69 6c  led with the fil
b5c0: 65 6e 61 6d 65 0a 2a 2a 20 77 72 69 74 74 65 6e  ename.** written
b5d0: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
b5e0: 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
b5f0: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20  te3_malloc()].  
b600: 54 68 65 20 63 61 6c 6c 65 72 20 73 68 6f 75 6c  The caller shoul
b610: 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20 5b 73 71 6c  d.** invoke [sql
b620: 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20  ite3_free()] on 
b630: 74 68 65 20 72 65 73 75 6c 74 20 74 6f 20 61 76  the result to av
b640: 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61  oid a memory lea
b650: 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  k..**.** <li>[[S
b660: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50  QLITE_FCNTL_MMAP
b670: 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  _SIZE]].** The [
b680: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41  SQLITE_FCNTL_MMA
b690: 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e  P_SIZE] file con
b6a0: 74 72 6f 6c 20 69 73 20 75 73 65 64 20 74 6f 20  trol is used to 
b6b0: 71 75 65 72 79 20 6f 72 20 73 65 74 20 74 68 65  query or set the
b6c0: 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  .** maximum numb
b6d0: 65 72 20 6f 66 20 62 79 74 65 73 20 74 68 61 74  er of bytes that
b6e0: 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 66 6f   will be used fo
b6f0: 72 20 6d 65 6d 6f 72 79 2d 6d 61 70 70 65 64 20  r memory-mapped 
b700: 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75  I/O..** The argu
b710: 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
b720: 72 20 74 6f 20 61 20 76 61 6c 75 65 20 6f 66 20  r to a value of 
b730: 74 79 70 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  type sqlite3_int
b740: 36 34 20 74 68 61 74 0a 2a 2a 20 69 73 20 61 6e  64 that.** is an
b750: 20 61 64 76 69 73 6f 72 79 20 6d 61 78 69 6d 75   advisory maximu
b760: 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  m number of byte
b770: 73 20 69 6e 20 74 68 65 20 66 69 6c 65 20 74 6f  s in the file to
b780: 20 6d 65 6d 6f 72 79 20 6d 61 70 2e 20 20 54 68   memory map.  Th
b790: 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 73 20  e.** pointer is 
b7a0: 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68  overwritten with
b7b0: 20 74 68 65 20 6f 6c 64 20 76 61 6c 75 65 2e 20   the old value. 
b7c0: 20 54 68 65 20 6c 69 6d 69 74 20 69 73 20 6e 6f   The limit is no
b7d0: 74 20 63 68 61 6e 67 65 64 20 69 66 0a 2a 2a 20  t changed if.** 
b7e0: 74 68 65 20 76 61 6c 75 65 20 6f 72 69 67 69 6e  the value origin
b7f0: 61 6c 6c 79 20 70 6f 69 6e 74 65 64 20 74 6f 20  ally pointed to 
b800: 69 73 20 6e 65 67 61 74 69 76 65 2c 20 61 6e 64  is negative, and
b810: 20 73 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20   so the current 
b820: 6c 69 6d 69 74 20 0a 2a 2a 20 63 61 6e 20 62 65  limit .** can be
b830: 20 71 75 65 72 69 65 64 20 62 79 20 70 61 73 73   queried by pass
b840: 69 6e 67 20 69 6e 20 61 20 70 6f 69 6e 74 65 72  ing in a pointer
b850: 20 74 6f 20 61 20 6e 65 67 61 74 69 76 65 20 6e   to a negative n
b860: 75 6d 62 65 72 2e 20 20 54 68 69 73 0a 2a 2a 20  umber.  This.** 
b870: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20  file-control is 
b880: 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  used internally 
b890: 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 50 52  to implement [PR
b8a0: 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 2e  AGMA mmap_size].
b8b0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
b8c0: 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d  ITE_FCNTL_TRACE]
b8d0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
b8e0: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 66 69  _FCNTL_TRACE] fi
b8f0: 6c 65 20 63 6f 6e 74 72 6f 6c 20 70 72 6f 76 69  le control provi
b900: 64 65 73 20 61 64 76 69 73 6f 72 79 20 69 6e 66  des advisory inf
b910: 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74  ormation.** to t
b920: 68 65 20 56 46 53 20 61 62 6f 75 74 20 77 68 61  he VFS about wha
b930: 74 20 74 68 65 20 68 69 67 68 65 72 20 6c 61 79  t the higher lay
b940: 65 72 73 20 6f 66 20 74 68 65 20 53 51 4c 69 74  ers of the SQLit
b950: 65 20 73 74 61 63 6b 20 61 72 65 20 64 6f 69 6e  e stack are doin
b960: 67 2e 0a 2a 2a 20 54 68 69 73 20 66 69 6c 65 20  g..** This file 
b970: 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20  control is used 
b980: 62 79 20 73 6f 6d 65 20 56 46 53 20 61 63 74 69  by some VFS acti
b990: 76 69 74 79 20 74 72 61 63 69 6e 67 20 5b 73 68  vity tracing [sh
b9a0: 69 6d 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 72 67  ims]..** The arg
b9b0: 75 6d 65 6e 74 20 69 73 20 61 20 7a 65 72 6f 2d  ument is a zero-
b9c0: 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
b9d0: 67 2e 20 20 48 69 67 68 65 72 20 6c 61 79 65 72  g.  Higher layer
b9e0: 73 20 69 6e 20 74 68 65 0a 2a 2a 20 53 51 4c 69  s in the.** SQLi
b9f0: 74 65 20 73 74 61 63 6b 20 6d 61 79 20 67 65 6e  te stack may gen
ba00: 65 72 61 74 65 20 69 6e 73 74 61 6e 63 65 73 20  erate instances 
ba10: 6f 66 20 74 68 69 73 20 66 69 6c 65 20 63 6f 6e  of this file con
ba20: 74 72 6f 6c 20 69 66 0a 2a 2a 20 74 68 65 20 5b  trol if.** the [
ba30: 53 51 4c 49 54 45 5f 55 53 45 5f 46 43 4e 54 4c  SQLITE_USE_FCNTL
ba40: 5f 54 52 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d  _TRACE] compile-
ba50: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65  time option is e
ba60: 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  nabled..**.** <l
ba70: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
ba80: 5f 48 41 53 5f 4d 4f 56 45 44 5d 5d 0a 2a 2a 20  _HAS_MOVED]].** 
ba90: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
baa0: 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 20 66 69 6c  L_HAS_MOVED] fil
bab0: 65 20 63 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70  e control interp
bac0: 72 65 74 73 20 69 74 73 20 61 72 67 75 6d 65 6e  rets its argumen
bad0: 74 20 61 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65  t as a.** pointe
bae0: 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  r to an integer 
baf0: 61 6e 64 20 69 74 20 77 72 69 74 65 73 20 61 20  and it writes a 
bb00: 62 6f 6f 6c 65 61 6e 20 69 6e 74 6f 20 74 68 61  boolean into tha
bb10: 74 20 69 6e 74 65 67 65 72 20 64 65 70 65 6e 64  t integer depend
bb20: 69 6e 67 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65  ing.** on whethe
bb30: 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 66 69 6c  r or not the fil
bb40: 65 20 68 61 73 20 62 65 65 6e 20 72 65 6e 61 6d  e has been renam
bb50: 65 64 2c 20 6d 6f 76 65 64 2c 20 6f 72 20 64 65  ed, moved, or de
bb60: 6c 65 74 65 64 20 73 69 6e 63 65 20 69 74 0a 2a  leted since it.*
bb70: 2a 20 77 61 73 20 66 69 72 73 74 20 6f 70 65 6e  * was first open
bb80: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ed..**.** <li>[[
bb90: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
bba0: 33 32 5f 47 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a  32_GET_HANDLE]].
bbb0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
bbc0: 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48  CNTL_WIN32_GET_H
bbd0: 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 65 20 63 61  ANDLE] opcode ca
bbe0: 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74  n be used to obt
bbf0: 61 69 6e 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72  ain the.** under
bc00: 6c 79 69 6e 67 20 6e 61 74 69 76 65 20 66 69 6c  lying native fil
bc10: 65 20 68 61 6e 64 6c 65 20 61 73 73 6f 63 69 61  e handle associa
bc20: 74 65 64 20 77 69 74 68 20 61 20 66 69 6c 65 20  ted with a file 
bc30: 68 61 6e 64 6c 65 2e 20 20 54 68 69 73 20 66 69  handle.  This fi
bc40: 6c 65 0a 2a 2a 20 63 6f 6e 74 72 6f 6c 20 69 6e  le.** control in
bc50: 74 65 72 70 72 65 74 73 20 69 74 73 20 61 72 67  terprets its arg
bc60: 75 6d 65 6e 74 20 61 73 20 61 20 70 6f 69 6e 74  ument as a point
bc70: 65 72 20 74 6f 20 61 20 6e 61 74 69 76 65 20 66  er to a native f
bc80: 69 6c 65 20 68 61 6e 64 6c 65 20 61 6e 64 0a 2a  ile handle and.*
bc90: 2a 20 77 72 69 74 65 73 20 74 68 65 20 72 65 73  * writes the res
bca0: 75 6c 74 69 6e 67 20 76 61 6c 75 65 20 74 68 65  ulting value the
bcb0: 72 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  re..**.** <li>[[
bcc0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
bcd0: 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a  32_SET_HANDLE]].
bce0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
bcf0: 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48  CNTL_WIN32_SET_H
bd00: 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 65 20 69 73  ANDLE] opcode is
bd10: 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67 67   used for debugg
bd20: 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70  ing.  This.** op
bd30: 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65 20  code causes the 
bd40: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
bd50: 68 6f 64 20 74 6f 20 73 77 61 70 20 74 68 65 20  hod to swap the 
bd60: 66 69 6c 65 20 68 61 6e 64 6c 65 20 77 69 74 68  file handle with
bd70: 20 74 68 65 20 6f 6e 65 0a 2a 2a 20 70 6f 69 6e   the one.** poin
bd80: 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 70 41  ted to by the pA
bd90: 72 67 20 61 72 67 75 6d 65 6e 74 2e 20 20 54 68  rg argument.  Th
bda0: 69 73 20 63 61 70 61 62 69 6c 69 74 79 20 69 73  is capability is
bdb0: 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73   used during tes
bdc0: 74 69 6e 67 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79  ting.** and only
bdd0: 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75 70   needs to be sup
bde0: 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49  ported when SQLI
bdf0: 54 45 5f 54 45 53 54 20 69 73 20 64 65 66 69 6e  TE_TEST is defin
be00: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ed..**.** <li>[[
be10: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c  SQLITE_FCNTL_WAL
be20: 5f 42 4c 4f 43 4b 5d 5d 0a 2a 2a 20 54 68 65 20  _BLOCK]].** The 
be30: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41  [SQLITE_FCNTL_WA
be40: 4c 5f 42 4c 4f 43 4b 5d 20 69 73 20 61 20 73 69  L_BLOCK] is a si
be50: 67 6e 61 6c 20 74 6f 20 74 68 65 20 56 46 53 20  gnal to the VFS 
be60: 6c 61 79 65 72 20 74 68 61 74 20 69 74 20 6d 69  layer that it mi
be70: 67 68 74 0a 2a 2a 20 62 65 20 61 64 76 61 6e 74  ght.** be advant
be80: 61 67 65 6f 75 73 20 74 6f 20 62 6c 6f 63 6b 20  ageous to block 
be90: 6f 6e 20 74 68 65 20 6e 65 78 74 20 57 41 4c 20  on the next WAL 
bea0: 6c 6f 63 6b 20 69 66 20 74 68 65 20 6c 6f 63 6b  lock if the lock
beb0: 20 69 73 20 6e 6f 74 20 69 6d 6d 65 64 69 61 74   is not immediat
bec0: 65 6c 79 0a 2a 2a 20 61 76 61 69 6c 61 62 6c 65  ely.** available
bed0: 2e 20 20 54 68 65 20 57 41 4c 20 73 75 62 73 79  .  The WAL subsy
bee0: 73 74 65 6d 20 69 73 73 75 65 73 20 74 68 69 73  stem issues this
bef0: 20 73 69 67 6e 61 6c 20 64 75 72 69 6e 67 20 72   signal during r
bf00: 61 72 65 0a 2a 2a 20 63 69 72 63 75 6d 73 74 61  are.** circumsta
bf10: 6e 63 65 73 20 69 6e 20 6f 72 64 65 72 20 74 6f  nces in order to
bf20: 20 66 69 78 20 61 20 70 72 6f 62 6c 65 6d 20 77   fix a problem w
bf30: 69 74 68 20 70 72 69 6f 72 69 74 79 20 69 6e 76  ith priority inv
bf40: 65 72 73 69 6f 6e 2e 0a 2a 2a 20 41 70 70 6c 69  ersion..** Appli
bf50: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 3c  cations should <
bf60: 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20 75 73 65 20  em>not</em> use 
bf70: 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  this file-contro
bf80: 6c 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  l..**.** <li>[[S
bf90: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56  QLITE_FCNTL_ZIPV
bfa0: 46 53 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  FS]].** The [SQL
bfb0: 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53  ITE_FCNTL_ZIPVFS
bfc0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6d 70 6c  ] opcode is impl
bfd0: 65 6d 65 6e 74 65 64 20 62 79 20 7a 69 70 76 66  emented by zipvf
bfe0: 73 20 6f 6e 6c 79 2e 20 41 6c 6c 20 6f 74 68 65  s only. All othe
bff0: 72 0a 2a 2a 20 56 46 53 20 73 68 6f 75 6c 64 20  r.** VFS should 
c000: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f  return SQLITE_NO
c010: 54 46 4f 55 4e 44 20 66 6f 72 20 74 68 69 73 20  TFOUND for this 
c020: 6f 70 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  opcode..**.** <l
c030: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
c040: 5f 52 42 55 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  _RBU]].** The [S
c050: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d  QLITE_FCNTL_RBU]
c060: 20 6f 70 63 6f 64 65 20 69 73 20 69 6d 70 6c 65   opcode is imple
c070: 6d 65 6e 74 65 64 20 62 79 20 74 68 65 20 73 70  mented by the sp
c080: 65 63 69 61 6c 20 56 46 53 20 75 73 65 64 20 62  ecial VFS used b
c090: 79 0a 2a 2a 20 74 68 65 20 52 42 55 20 65 78 74  y.** the RBU ext
c0a0: 65 6e 73 69 6f 6e 20 6f 6e 6c 79 2e 20 20 41 6c  ension only.  Al
c0b0: 6c 20 6f 74 68 65 72 20 56 46 53 20 73 68 6f 75  l other VFS shou
c0c0: 6c 64 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  ld return SQLITE
c0d0: 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f 72 0a 2a 2a  _NOTFOUND for.**
c0e0: 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 20 0a   this opcode.  .
c0f0: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </ul>.*/.#def
c100: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c110: 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20  _LOCKSTATE      
c120: 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69           1.#defi
c130: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c140: 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  GET_LOCKPROXYFIL
c150: 45 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e  E       2.#defin
c160: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  e SQLITE_FCNTL_S
c170: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
c180: 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
c190: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41   SQLITE_FCNTL_LA
c1a0: 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20  ST_ERRNO        
c1b0: 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20        4.#define 
c1c0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
c1d0: 45 5f 48 49 4e 54 20 20 20 20 20 20 20 20 20 20  E_HINT          
c1e0: 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53       5.#define S
c1f0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e  QLITE_FCNTL_CHUN
c200: 4b 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 20  K_SIZE          
c210: 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51      6.#define SQ
c220: 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f  LITE_FCNTL_FILE_
c230: 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 20  POINTER         
c240: 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c     7.#define SQL
c250: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f  ITE_FCNTL_SYNC_O
c260: 4d 49 54 54 45 44 20 20 20 20 20 20 20 20 20 20  MITTED          
c270: 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    8.#define SQLI
c280: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41  TE_FCNTL_WIN32_A
c290: 56 5f 52 45 54 52 59 20 20 20 20 20 20 20 20 20  V_RETRY         
c2a0: 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   9.#define SQLIT
c2b0: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
c2c0: 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 31  WAL            1
c2d0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
c2e0: 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45  _FCNTL_OVERWRITE
c2f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 31                11
c300: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c310: 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20  FCNTL_VFSNAME   
c320: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 32 0a               12.
c330: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c340: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f  CNTL_POWERSAFE_O
c350: 56 45 52 57 52 49 54 45 20 20 20 20 31 33 0a 23  VERWRITE    13.#
c360: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
c370: 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20 20 20 20  NTL_PRAGMA      
c380: 20 20 20 20 20 20 20 20 20 20 20 31 34 0a 23 64             14.#d
c390: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
c3a0: 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 20 20  TL_BUSYHANDLER  
c3b0: 20 20 20 20 20 20 20 20 20 20 31 35 0a 23 64 65            15.#de
c3c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c3d0: 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 20 20  L_TEMPFILENAME  
c3e0: 20 20 20 20 20 20 20 20 20 31 36 0a 23 64 65 66           16.#def
c3f0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c400: 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 20 20  _MMAP_SIZE      
c410: 20 20 20 20 20 20 20 20 31 38 0a 23 64 65 66 69          18.#defi
c420: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c430: 54 52 41 43 45 20 20 20 20 20 20 20 20 20 20 20  TRACE           
c440: 20 20 20 20 20 20 20 31 39 0a 23 64 65 66 69 6e         19.#defin
c450: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48  e SQLITE_FCNTL_H
c460: 41 53 5f 4d 4f 56 45 44 20 20 20 20 20 20 20 20  AS_MOVED        
c470: 20 20 20 20 20 20 32 30 0a 23 64 65 66 69 6e 65        20.#define
c480: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59   SQLITE_FCNTL_SY
c490: 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20  NC              
c4a0: 20 20 20 20 20 32 31 0a 23 64 65 66 69 6e 65 20       21.#define 
c4b0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d  SQLITE_FCNTL_COM
c4c0: 4d 49 54 5f 50 48 41 53 45 54 57 4f 20 20 20 20  MIT_PHASETWO    
c4d0: 20 20 20 20 32 32 0a 23 64 65 66 69 6e 65 20 53      22.#define S
c4e0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
c4f0: 32 5f 53 45 54 5f 48 41 4e 44 4c 45 20 20 20 20  2_SET_HANDLE    
c500: 20 20 20 32 33 0a 23 64 65 66 69 6e 65 20 53 51     23.#define SQ
c510: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42  LITE_FCNTL_WAL_B
c520: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20  LOCK            
c530: 20 20 32 34 0a 23 64 65 66 69 6e 65 20 53 51 4c    24.#define SQL
c540: 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53  ITE_FCNTL_ZIPVFS
c550: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
c560: 20 32 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   25.#define SQLI
c570: 54 45 5f 46 43 4e 54 4c 5f 52 42 55 20 20 20 20  TE_FCNTL_RBU    
c580: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
c590: 32 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  26.#define SQLIT
c5a0: 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e  E_FCNTL_VFS_POIN
c5b0: 54 45 52 20 20 20 20 20 20 20 20 20 20 20 20 32  TER            2
c5c0: 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  7.#define SQLITE
c5d0: 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50  _FCNTL_JOURNAL_P
c5e0: 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 32 38  OINTER        28
c5f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c600: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f  FCNTL_WIN32_GET_
c610: 48 41 4e 44 4c 45 20 20 20 20 20 20 20 32 39 0a  HANDLE       29.
c620: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c630: 43 4e 54 4c 5f 50 44 42 20 20 20 20 20 20 20 20  CNTL_PDB        
c640: 20 20 20 20 20 20 20 20 20 20 20 20 33 30 0a 0a              30..
c650: 2f 2a 20 64 65 70 72 65 63 61 74 65 64 20 6e 61  /* deprecated na
c660: 6d 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  mes */.#define S
c670: 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52  QLITE_GET_LOCKPR
c680: 4f 58 59 46 49 4c 45 20 20 20 20 20 20 53 51 4c  OXYFILE      SQL
c690: 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f  ITE_FCNTL_GET_LO
c6a0: 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 66  CKPROXYFILE.#def
c6b0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c  ine SQLITE_SET_L
c6c0: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20  OCKPROXYFILE    
c6d0: 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53    SQLITE_FCNTL_S
c6e0: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
c6f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c700: 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20  LAST_ERRNO      
c710: 20 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43         SQLITE_FC
c720: 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 0a 0a  NTL_LAST_ERRNO..
c730: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
c740: 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a   Mutex Handle.**
c750: 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f  .** The mutex mo
c760: 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69  dule within SQLi
c770: 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69  te defines [sqli
c780: 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65  te3_mutex] to be
c790: 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20   an.** abstract 
c7a0: 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78  type for a mutex
c7b0: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51   object.  The SQ
c7c0: 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20  Lite core never 
c7d0: 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20  looks.** at the 
c7e0: 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65  internal represe
c7f0: 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73  ntation of an [s
c800: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20  qlite3_mutex].  
c810: 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73  It only.** deals
c820: 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74   with pointers t
c830: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  o the [sqlite3_m
c840: 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  utex] object..**
c850: 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20  .** Mutexes are 
c860: 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73  created using [s
c870: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c  qlite3_mutex_all
c880: 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65  oc()]..*/.typede
c890: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
c8a0: 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d  _mutex sqlite3_m
c8b0: 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  utex;../*.** CAP
c8c0: 49 33 52 45 46 3a 20 4c 6f 61 64 61 62 6c 65 20  I3REF: Loadable 
c8d0: 45 78 74 65 6e 73 69 6f 6e 20 54 68 75 6e 6b 0a  Extension Thunk.
c8e0: 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20  **.** A pointer 
c8f0: 74 6f 20 74 68 65 20 6f 70 61 71 75 65 20 73 71  to the opaque sq
c900: 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e  lite3_api_routin
c910: 65 73 20 73 74 72 75 63 74 75 72 65 20 69 73 20  es structure is 
c920: 70 61 73 73 65 64 20 61 73 0a 2a 2a 20 74 68 65  passed as.** the
c930: 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
c940: 20 74 6f 20 65 6e 74 72 79 20 70 6f 69 6e 74 73   to entry points
c950: 20 6f 66 20 5b 6c 6f 61 64 61 62 6c 65 20 65 78   of [loadable ex
c960: 74 65 6e 73 69 6f 6e 73 5d 2e 20 20 54 68 69 73  tensions].  This
c970: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 6d 75  .** structure mu
c980: 73 74 20 62 65 20 74 79 70 65 64 65 66 65 64 20  st be typedefed 
c990: 69 6e 20 6f 72 64 65 72 20 74 6f 20 77 6f 72 6b  in order to work
c9a0: 20 61 72 6f 75 6e 64 20 63 6f 6d 70 69 6c 65 72   around compiler
c9b0: 20 77 61 72 6e 69 6e 67 73 0a 2a 2a 20 6f 6e 20   warnings.** on 
c9c0: 73 6f 6d 65 20 70 6c 61 74 66 6f 72 6d 73 2e 0a  some platforms..
c9d0: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
c9e0: 74 20 73 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f  t sqlite3_api_ro
c9f0: 75 74 69 6e 65 73 20 73 71 6c 69 74 65 33 5f 61  utines sqlite3_a
ca00: 70 69 5f 72 6f 75 74 69 6e 65 73 3b 0a 0a 2f 2a  pi_routines;../*
ca10: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
ca20: 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63   Interface Objec
ca30: 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  t.**.** An insta
ca40: 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74  nce of the sqlit
ca50: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65  e3_vfs object de
ca60: 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66  fines the interf
ca70: 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74  ace between.** t
ca80: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61  he SQLite core a
ca90: 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  nd the underlyin
caa0: 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  g operating syst
cab0: 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a  em.  The "vfs".*
cac0: 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  * in the name of
cad0: 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e   the object stan
cae0: 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20  ds for "virtual 
caf0: 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 20 20 53  file system".  S
cb00: 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c  ee.** the [VFS |
cb10: 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 61 74 69   VFS documentati
cb20: 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 65 72 20  on] for further 
cb30: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
cb40: 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20  ** The value of 
cb50: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65  the iVersion fie
cb60: 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20  ld is initially 
cb70: 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72  1 but may be lar
cb80: 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65  ger in.** future
cb90: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
cba0: 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c  ite.  Additional
cbb0: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61   fields may be a
cbc0: 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a  ppended to this.
cbd0: 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74  ** object when t
cbe0: 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75  he iVersion valu
cbf0: 65 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e 20  e is increased. 
cc00: 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 73   Note that the s
cc10: 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74  tructure.** of t
cc20: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  he sqlite3_vfs o
cc30: 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69 6e  bject changes in
cc40: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
cc50: 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69   between.** SQLi
cc60: 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39  te version 3.5.9
cc70: 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20 79   and 3.6.0 and y
cc80: 65 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  et the iVersion 
cc90: 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a  field was not.**
cca0: 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a   modified..**.**
ccb0: 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69   The szOsFile fi
ccc0: 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65 20  eld is the size 
ccd0: 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 73 65  of the subclasse
cce0: 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  d [sqlite3_file]
ccf0: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75 73  .** structure us
cd00: 65 64 20 62 79 20 74 68 69 73 20 56 46 53 2e 20  ed by this VFS. 
cd10: 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74   mxPathname is t
cd20: 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
cd30: 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61  h of.** a pathna
cd40: 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a  me in this VFS..
cd50: 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64  **.** Registered
cd60: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a   sqlite3_vfs obj
cd70: 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f 6e  ects are kept on
cd80: 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66   a linked list f
cd90: 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20  ormed by.** the 
cda0: 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20  pNext pointer.  
cdb0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  The [sqlite3_vfs
cdc0: 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20  _register()].** 
cdd0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  and [sqlite3_vfs
cde0: 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69  _unregister()] i
cdf0: 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65  nterfaces manage
ce00: 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e   this list.** in
ce10: 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 20 77   a thread-safe w
ce20: 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  ay.  The [sqlite
ce30: 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e  3_vfs_find()] in
ce40: 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63  terface.** searc
ce50: 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20 4e  hes the list.  N
ce60: 65 69 74 68 65 72 20 74 68 65 20 61 70 70 6c 69  either the appli
ce70: 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20  cation code nor 
ce80: 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65  the VFS.** imple
ce90: 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64  mentation should
cea0: 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 20 70   use the pNext p
ceb0: 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  ointer..**.** Th
cec0: 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73  e pNext field is
ced0: 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20   the only field 
cee0: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  in the sqlite3_v
cef0: 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  fs.** structure 
cf00: 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
cf10: 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53   ever modify.  S
cf20: 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20  QLite will only 
cf30: 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64  access.** or mod
cf40: 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 20 77  ify this field w
cf50: 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70  hile holding a p
cf60: 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 69 63  articular static
cf70: 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61   mutex..** The a
cf80: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
cf90: 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61  d never modify a
cfa0: 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74  nything within t
cfb0: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a  he sqlite3_vfs.*
cfc0: 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68  * object once th
cfd0: 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65  e object has bee
cfe0: 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a  n registered..**
cff0: 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69  .** The zName fi
d000: 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61  eld holds the na
d010: 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f  me of the VFS mo
d020: 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20  dule.  The name 
d030: 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75  must.** be uniqu
d040: 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53  e across all VFS
d050: 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20   modules..**.** 
d060: 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f  [[sqlite3_vfs.xO
d070: 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65  pen]].** ^SQLite
d080: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
d090: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70   the zFilename p
d0a0: 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65  arameter to xOpe
d0b0: 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 61  n.** is either a
d0c0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72   NULL pointer or
d0d0: 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64   string obtained
d0e0: 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61  .** from xFullPa
d0f0: 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20 61 6e  thname() with an
d100: 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66 69 78   optional suffix
d110: 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61   added..** ^If a
d120: 20 73 75 66 66 69 78 20 69 73 20 61 64 64 65 64   suffix is added
d130: 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d   to the zFilenam
d140: 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69 74 20  e parameter, it 
d150: 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20  will.** consist 
d160: 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d 22 20  of a single "-" 
d170: 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77  character follow
d180: 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68  ed by no more th
d190: 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e 75  an.** 11 alphanu
d1a0: 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22  meric and/or "-"
d1b0: 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20   characters..** 
d1c0: 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65 72 20  ^SQLite further 
d1d0: 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a  guarantees that.
d1e0: 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77 69  ** the string wi
d1f0: 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20  ll be valid and 
d200: 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20  unchanged until 
d210: 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63  xClose() is.** c
d220: 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20 6f  alled. Because o
d230: 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73  f the previous s
d240: 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20  entence,.** the 
d250: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63  [sqlite3_file] c
d260: 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65 20  an safely store 
d270: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
d280: 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20  .** filename if 
d290: 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65  it needs to reme
d2a0: 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d  mber the filenam
d2b0: 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f  e for some reaso
d2c0: 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69  n..** If the zFi
d2d0: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
d2e0: 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 20 4e   to xOpen is a N
d2f0: 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
d300: 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69   xOpen.** must i
d310: 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74 65  nvent its own te
d320: 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f 72  mporary name for
d330: 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57 68 65   the file.  ^Whe
d340: 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 46  never the .** xF
d350: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
d360: 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c  r is NULL it wil
d370: 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63 61  l also be the ca
d380: 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 66  se that the.** f
d390: 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 77  lags parameter w
d3a0: 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c  ill include [SQL
d3b0: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
d3c0: 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54  NCLOSE]..**.** T
d3d0: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
d3e0: 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63  t to xOpen() inc
d3f0: 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73  ludes all bits s
d400: 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61  et in.** the fla
d410: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b  gs argument to [
d420: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
d430: 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69  )].  Or if [sqli
d440: 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f  te3_open()].** o
d450: 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  r [sqlite3_open1
d460: 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68  6()] is used, th
d470: 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65  en flags include
d480: 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53  s at least.** [S
d490: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
d4a0: 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f  RITE] | [SQLITE_
d4b0: 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a  OPEN_CREATE]. .*
d4c0: 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65  * If xOpen() ope
d4d0: 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f  ns a file read-o
d4e0: 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74 73  nly then it sets
d4f0: 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a   *pOutFlags to.*
d500: 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54  * include [SQLIT
d510: 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d  E_OPEN_READONLY]
d520: 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e  .  Other bits in
d530: 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20   *pOutFlags may 
d540: 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28  be set..**.** ^(
d550: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f  SQLite will also
d560: 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20   add one of the 
d570: 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20  following flags 
d580: 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a  to the xOpen().*
d590: 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e  * call, dependin
d5a0: 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20  g on the object 
d5b0: 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a  being opened:.**
d5c0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
d5d0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
d5e0: 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  AIN_DB].** <li> 
d5f0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
d600: 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  IN_JOURNAL].** <
d610: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
d620: 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c  N_TEMP_DB].** <l
d630: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
d640: 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  _TEMP_JOURNAL].*
d650: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
d660: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44  OPEN_TRANSIENT_D
d670: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  B].** <li>  [SQL
d680: 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52  ITE_OPEN_SUBJOUR
d690: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
d6a0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45  QLITE_OPEN_MASTE
d6b0: 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  R_JOURNAL].** <l
d6c0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
d6d0: 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e  _WAL].** </ul>)^
d6e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20  .**.** The file 
d6f0: 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  I/O implementati
d700: 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f  on can use the o
d710: 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67 73  bject type flags
d720: 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68   to.** change th
d730: 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20 77  e way it deals w
d740: 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20  ith files.  For 
d750: 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c  example, an appl
d760: 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20  ication.** that 
d770: 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62  does not care ab
d780: 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76 65  out crash recove
d790: 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d  ry or rollback m
d7a0: 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65  ight make.** the
d7b0: 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e   open of a journ
d7c0: 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e  al file a no-op.
d7d0: 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 69 73    Writes to this
d7e0: 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a   journal would.*
d7f0: 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73  * also be no-ops
d800: 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d 70  , and any attemp
d810: 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f  t to read the jo
d820: 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 75  urnal would retu
d830: 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45  rn.** SQLITE_IOE
d840: 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70 6c  RR.  Or the impl
d850: 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74  ementation might
d860: 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74 20   recognize that 
d870: 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  a database.** fi
d880: 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67  le will be doing
d890: 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 65   page-aligned se
d8a0: 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20 77  ctor reads and w
d8b0: 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64 6f  rites in a rando
d8c0: 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20 73  m.** order and s
d8d0: 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73 75  et up its I/O su
d8e0: 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69 6e  bsystem accordin
d8f0: 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  gly..**.** SQLit
d900: 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64  e might also add
d910: 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
d920: 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74  owing flags to t
d930: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a  he xOpen method:
d940: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
d950: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  li> [SQLITE_OPEN
d960: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a  _DELETEONCLOSE].
d970: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
d980: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a  OPEN_EXCLUSIVE].
d990: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54  ** </ul>.**.** T
d9a0: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
d9b0: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66  DELETEONCLOSE] f
d9c0: 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69  lag means the fi
d9d0: 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  le should be.** 
d9e0: 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20  deleted when it 
d9f0: 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65  is closed.  ^The
da00: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
da10: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20  LETEONCLOSE].** 
da20: 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20  will be set for 
da30: 54 45 4d 50 20 64 61 74 61 62 61 73 65 73 20 61  TEMP databases a
da40: 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c  nd their journal
da50: 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20  s, transient.** 
da60: 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64 20 73  databases, and s
da70: 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a  ubjournals..**.*
da80: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  * ^The [SQLITE_O
da90: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66  PEN_EXCLUSIVE] f
daa0: 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20 75 73  lag is always us
dab0: 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f  ed in conjunctio
dac0: 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53  n.** with the [S
dad0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
dae0: 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20 61  E] flag, which a
daf0: 72 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c 79  re both directly
db00: 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f  .** analogous to
db10: 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20   the O_EXCL and 
db20: 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f 66  O_CREAT flags of
db30: 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e 28   the POSIX open(
db40: 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 53  ).** API.  The S
db50: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
db60: 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e 20  SIVE flag, when 
db70: 70 61 69 72 65 64 20 77 69 74 68 20 74 68 65 20  paired with the 
db80: 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  .** SQLITE_OPEN_
db90: 43 52 45 41 54 45 2c 20 69 73 20 75 73 65 64 20  CREATE, is used 
dba0: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  to indicate that
dbb0: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77   file should alw
dbc0: 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 65  ays.** be create
dbd0: 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20 69  d, and that it i
dbe0: 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69 74  s an error if it
dbf0: 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 73 2e   already exists.
dc00: 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74  .** It is <i>not
dc10: 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e 64  </i> used to ind
dc20: 69 63 61 74 65 20 74 68 65 20 66 69 6c 65 20 73  icate the file s
dc30: 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 20  hould be opened 
dc40: 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76  .** for exclusiv
dc50: 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20  e access..**.** 
dc60: 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69  ^At least szOsFi
dc70: 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  le bytes of memo
dc80: 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64  ry are allocated
dc90: 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f   by SQLite.** to
dca0: 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69   hold the  [sqli
dcb0: 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74  te3_file] struct
dcc0: 75 72 65 20 70 61 73 73 65 64 20 61 73 20 74 68  ure passed as th
dcd0: 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d  e third.** argum
dce0: 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54  ent to xOpen.  T
dcf0: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20  he xOpen method 
dd00: 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f  does not have to
dd10: 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65  .** allocate the
dd20: 20 73 74 72 75 63 74 75 72 65 3b 20 69 74 20 73   structure; it s
dd30: 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20  hould just fill 
dd40: 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61  it in.  Note tha
dd50: 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d  t.** the xOpen m
dd60: 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20 74  ethod must set t
dd70: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
dd80: 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74 68  pMethods to eith
dd90: 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73  er.** a valid [s
dda0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
ddb0: 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20  s] object or to 
ddc0: 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73  NULL.  xOpen mus
ddd0: 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65  t do.** this eve
dde0: 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66 61  n if the open fa
ddf0: 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78 70  ils.  SQLite exp
de00: 65 63 74 73 20 74 68 61 74 20 74 68 65 20 73 71  ects that the sq
de10: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
de20: 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77  ods.** element w
de30: 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66 74  ill be valid aft
de40: 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e 73  er xOpen returns
de50: 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74   regardless of t
de60: 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72  he success.** or
de70: 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65 20   failure of the 
de80: 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a  xOpen call..**.*
de90: 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  * [[sqlite3_vfs.
dea0: 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68  xAccess]].** ^Th
deb0: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
dec0: 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61   to xAccess() ma
ded0: 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43  y be [SQLITE_ACC
dee0: 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74  ESS_EXISTS].** t
def0: 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 20 65  o test for the e
df00: 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69  xistence of a fi
df10: 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41  le, or [SQLITE_A
df20: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d  CCESS_READWRITE]
df30: 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74   to.** test whet
df40: 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 72 65  her a file is re
df50: 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61  adable and writa
df60: 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ble, or [SQLITE_
df70: 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20  ACCESS_READ].** 
df80: 74 6f 20 74 65 73 74 20 77 68 65 74 68 65 72 20  to test whether 
df90: 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61  a file is at lea
dfa0: 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20 54  st readable.   T
dfb0: 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20 61  he file can be a
dfc0: 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a  .** directory..*
dfd0: 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  *.** ^SQLite wil
dfe0: 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74  l always allocat
dff0: 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74  e at least mxPat
e000: 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f  hname+1 bytes fo
e010: 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20  r the.** output 
e020: 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68  buffer xFullPath
e030: 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63 74  name.  The exact
e040: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74   size of the out
e050: 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73  put buffer.** is
e060: 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20   also passed as 
e070: 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62  a parameter to b
e080: 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 66  oth  methods. If
e090: 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66   the output buff
e0a0: 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72  er.** is not lar
e0b0: 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49  ge enough, [SQLI
e0c0: 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f  TE_CANTOPEN] sho
e0d0: 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e  uld be returned.
e0e0: 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a   Since this is.*
e0f0: 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66  * handled as a f
e100: 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51  atal error by SQ
e110: 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d  Lite, vfs implem
e120: 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  entations should
e130: 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20   endeavor.** to 
e140: 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 20  prevent this by 
e150: 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61  setting mxPathna
e160: 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 65  me to a sufficie
e170: 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65  ntly large value
e180: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e  ..**.** The xRan
e190: 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65  domness(), xSlee
e1a0: 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69 6d  p(), xCurrentTim
e1b0: 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e  e(), and xCurren
e1c0: 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20  tTimeInt64().** 
e1d0: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 6e  interfaces are n
e1e0: 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20 70 61  ot strictly a pa
e1f0: 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79  rt of the filesy
e200: 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61  stem, but they a
e210: 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69  re.** included i
e220: 6e 20 74 68 65 20 56 46 53 20 73 74 72 75 63 74  n the VFS struct
e230: 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65  ure for complete
e240: 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61  ness..** The xRa
e250: 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74  ndomness() funct
e260: 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ion attempts to 
e270: 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79  return nBytes by
e280: 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71  tes.** of good-q
e290: 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73  uality randomnes
e2a0: 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68  s into zOut.  Th
e2b0: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69  e return value i
e2c0: 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20  s.** the actual 
e2d0: 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
e2e0: 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62  of randomness ob
e2f0: 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78  tained..** The x
e300: 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63  Sleep() method c
e310: 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e  auses the callin
e320: 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65  g thread to slee
e330: 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73  p for at.** leas
e340: 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
e350: 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76  microseconds giv
e360: 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72 65  en.  ^The xCurre
e370: 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68  ntTime().** meth
e380: 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c  od returns a Jul
e390: 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66  ian Day Number f
e3a0: 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  or the current d
e3b0: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73 0a  ate and time as.
e3c0: 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f  ** a floating po
e3d0: 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54  int value..** ^T
e3e0: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  he xCurrentTimeI
e3f0: 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72 65  nt64() method re
e400: 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e 74  turns, as an int
e410: 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61 6e  eger, the Julian
e420: 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20 6d  .** Day Number m
e430: 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38 36 34  ultiplied by 864
e440: 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62 65  00000 (the numbe
e450: 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  r of millisecond
e460: 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f  s in .** a 24-ho
e470: 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53  ur day).  .** ^S
e480: 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74  QLite will use t
e490: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  he xCurrentTimeI
e4a0: 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74 6f  nt64() method to
e4b0: 20 67 65 74 20 74 68 65 20 63 75 72 72 65 6e 74   get the current
e4c0: 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69 6d  .** date and tim
e4d0: 65 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f 64  e if that method
e4e0: 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28 69   is available (i
e4f0: 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32 20  f iVersion is 2 
e500: 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20 61  or .** greater a
e510: 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  nd the function 
e520: 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e  pointer is not N
e530: 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66 61  ULL) and will fa
e540: 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43  ll back.** to xC
e550: 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66 20  urrentTime() if 
e560: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
e570: 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61 62  4() is unavailab
e580: 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78  le..**.** ^The x
e590: 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c  SetSystemCall(),
e5a0: 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 28   xGetSystemCall(
e5b0: 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73 74  ), and xNestSyst
e5c0: 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66 61  emCall() interfa
e5d0: 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 75  ces.** are not u
e5e0: 73 65 64 20 62 79 20 74 68 65 20 53 51 4c 69 74  sed by the SQLit
e5f0: 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20 6f  e core.  These o
e600: 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61 63  ptional interfac
e610: 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 0a  es are provided.
e620: 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65 73  ** by some VFSes
e630: 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20 74   to facilitate t
e640: 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56 46  esting of the VF
e650: 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72 72  S code. By overr
e660: 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65 6d  iding .** system
e670: 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e 63   calls with func
e680: 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73 20  tions under its 
e690: 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74 20  control, a test 
e6a0: 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 73  program can.** s
e6b0: 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20 61  imulate faults a
e6c0: 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74 69  nd error conditi
e6d0: 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20 6f  ons that would o
e6e0: 74 68 65 72 77 69 73 65 20 62 65 20 64 69 66 66  therwise be diff
e6f0: 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f  icult.** or impo
e700: 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63 65  ssible to induce
e710: 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20 73 79  .  The set of sy
e720: 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74 20  stem calls that 
e730: 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65  can be overridde
e740: 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f 6d  n.** varies from
e750: 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f 74   one VFS to anot
e760: 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f 6e  her, and from on
e770: 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65  e version of the
e780: 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68 65   same VFS to the
e790: 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c 69  .** next.  Appli
e7a0: 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65  cations that use
e7b0: 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
e7c0: 73 20 6d 75 73 74 20 62 65 20 70 72 65 70 61 72  s must be prepar
e7d0: 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72  ed for any.** or
e7e0: 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69 6e   all of these in
e7f0: 74 65 72 66 61 63 65 73 20 74 6f 20 62 65 20 4e  terfaces to be N
e800: 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69 72  ULL or for their
e810: 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68 61   behavior to cha
e820: 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20  nge.** from one 
e830: 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20 6e  release to the n
e840: 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ext.  Applicatio
e850: 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74 65  ns must not atte
e860: 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a 2a  mpt to access.**
e870: 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d 65   any of these me
e880: 74 68 6f 64 73 20 69 66 20 74 68 65 20 69 56 65  thods if the iVe
e890: 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46 53  rsion of the VFS
e8a0: 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33 2e   is less than 3.
e8b0: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
e8c0: 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73  ct sqlite3_vfs s
e8d0: 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70 65  qlite3_vfs;.type
e8e0: 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74  def void (*sqlit
e8f0: 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 28  e3_syscall_ptr)(
e900: 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73 71  void);.struct sq
e910: 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e  lite3_vfs {.  in
e920: 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20  t iVersion;     
e930: 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74         /* Struct
e940: 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62  ure version numb
e950: 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33 29  er (currently 3)
e960: 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69   */.  int szOsFi
e970: 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f  le;            /
e980: 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61  * Size of subcla
e990: 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c  ssed sqlite3_fil
e9a0: 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74  e */.  int mxPat
e9b0: 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20  hname;          
e9c0: 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20  /* Maximum file 
e9d0: 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20  pathname length 
e9e0: 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73  */.  sqlite3_vfs
e9f0: 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a   *pNext;      /*
ea00: 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65 64   Next registered
ea10: 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20   VFS */.  const 
ea20: 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20  char *zName;    
ea30: 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68     /* Name of th
ea40: 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20  is virtual file 
ea50: 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64  system */.  void
ea60: 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20   *pAppData;     
ea70: 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20       /* Pointer 
ea80: 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73  to application-s
ea90: 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a  pecific data */.
eaa0: 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73    int (*xOpen)(s
eab0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
eac0: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
ead0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20  sqlite3_file*,. 
eae0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e                in
eaf0: 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f  t flags, int *pO
eb00: 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20  utFlags);.  int 
eb10: 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74  (*xDelete)(sqlit
eb20: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
eb30: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
eb40: 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20  syncDir);.  int 
eb50: 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69 74  (*xAccess)(sqlit
eb60: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
eb70: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
eb80: 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73  flags, int *pRes
eb90: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  Out);.  int (*xF
eba0: 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c  ullPathname)(sql
ebb0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
ebc0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
ebd0: 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f  t nOut, char *zO
ebe0: 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78  ut);.  void *(*x
ebf0: 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f  DlOpen)(sqlite3_
ec00: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
ec10: 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20   *zFilename);.  
ec20: 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29  void (*xDlError)
ec30: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
ec40: 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a  nt nByte, char *
ec50: 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64  zErrMsg);.  void
ec60: 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c   (*(*xDlSym)(sql
ec70: 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c  ite3_vfs*,void*,
ec80: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79   const char *zSy
ec90: 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20  mbol))(void);.  
eca0: 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29  void (*xDlClose)
ecb0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76  (sqlite3_vfs*, v
ecc0: 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  oid*);.  int (*x
ecd0: 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69  Randomness)(sqli
ece0: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42  te3_vfs*, int nB
ecf0: 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29  yte, char *zOut)
ed00: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70  ;.  int (*xSleep
ed10: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
ed20: 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73  int microseconds
ed30: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72  );.  int (*xCurr
ed40: 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33  entTime)(sqlite3
ed50: 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b  _vfs*, double*);
ed60: 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73  .  int (*xGetLas
ed70: 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f  tError)(sqlite3_
ed80: 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20  vfs*, int, char 
ed90: 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68  *);.  /*.  ** Th
eda0: 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  e methods above 
edb0: 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20 31  are in version 1
edc0: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76   of the sqlite_v
edd0: 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64  fs object.  ** d
ede0: 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73  efinition.  Thos
edf0: 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72  e that follow ar
ee00: 65 20 61 64 64 65 64 20 69 6e 20 76 65 72 73 69  e added in versi
ee10: 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20 20  on 2 or later.  
ee20: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72  */.  int (*xCurr
ee30: 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73 71  entTimeInt64)(sq
ee40: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69  lite3_vfs*, sqli
ee50: 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f  te3_int64*);.  /
ee60: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
ee70: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
ee80: 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20 32  versions 1 and 2
ee90: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76   of the sqlite_v
eea0: 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20  fs object..  ** 
eeb0: 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65 20  Those below are 
eec0: 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61 6e  for version 3 an
eed0: 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f 0a  d greater..  */.
eee0: 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73 74    int (*xSetSyst
eef0: 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f  emCall)(sqlite3_
ef00: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
ef10: 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33   *zName, sqlite3
ef20: 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 20  _syscall_ptr);. 
ef30: 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c   sqlite3_syscall
ef40: 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73 74 65  _ptr (*xGetSyste
ef50: 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76  mCall)(sqlite3_v
ef60: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
ef70: 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 74  *zName);.  const
ef80: 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53 79   char *(*xNextSy
ef90: 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
efa0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
efb0: 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a  ar *zName);.  /*
efc0: 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64  .  ** The method
efd0: 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76  s above are in v
efe0: 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75 67  ersions 1 throug
eff0: 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69 74  h 3 of the sqlit
f000: 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20  e_vfs object..  
f010: 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61  ** New fields ma
f020: 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e  y be appended in
f030: 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
f040: 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a  .  The iVersion.
f050: 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20    ** value will 
f060: 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76  increment whenev
f070: 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e  er this happens.
f080: 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a   .  */.};../*.**
f090: 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73   CAPI3REF: Flags
f0a0: 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73   for the xAccess
f0b0: 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a   VFS method.**.*
f0c0: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  * These integer 
f0d0: 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65  constants can be
f0e0: 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68 69   used as the thi
f0f0: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  rd parameter to.
f100: 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  ** the xAccess m
f110: 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c  ethod of an [sql
f120: 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
f130: 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e  .  They determin
f140: 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f  e.** what kind o
f150: 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68  f permissions th
f160: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
f170: 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e   is looking for.
f180: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
f190: 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74  ACCESS_EXISTS, t
f1a0: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
f1b0: 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63  d.** simply chec
f1c0: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66  ks whether the f
f1d0: 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57  ile exists..** W
f1e0: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
f1f0: 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65  S_READWRITE, the
f200: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
f210: 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ** checks whethe
f220: 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72 65  r the named dire
f230: 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72 65  ctory is both re
f240: 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61  adable and writa
f250: 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72  ble.** (in other
f260: 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65 73   words, if files
f270: 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20 72   can be added, r
f280: 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e 61  emoved, and rena
f290: 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68  med within.** th
f2a0: 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a  e directory)..**
f2b0: 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45   The SQLITE_ACCE
f2c0: 53 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f 6e  SS_READWRITE con
f2d0: 73 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e 74  stant is current
f2e0: 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79 20  ly used only by 
f2f0: 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f  the.** [temp_sto
f300: 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61  re_directory pra
f310: 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68 69  gma], though thi
f320: 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20 69  s could change i
f330: 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65  n a future.** re
f340: 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e  lease of SQLite.
f350: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
f360: 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65  ACCESS_READ, the
f370: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
f380: 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ** checks whethe
f390: 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65  r the file is re
f3a0: 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51 4c  adable.  The SQL
f3b0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20  ITE_ACCESS_READ 
f3c0: 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63  constant is.** c
f3d0: 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c  urrently unused,
f3e0: 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68 74   though it might
f3f0: 20 62 65 20 75 73 65 64 20 69 6e 20 61 20 66 75   be used in a fu
f400: 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a  ture release of.
f410: 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64  ** SQLite..*/.#d
f420: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
f430: 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a  ESS_EXISTS    0.
f440: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
f450: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20  CCESS_READWRITE 
f460: 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20 50  1   /* Used by P
f470: 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65  RAGMA temp_store
f480: 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64  _directory */.#d
f490: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
f4a0: 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 20  ESS_READ      2 
f4b0: 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a    /* Unused */..
f4c0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
f4d0: 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 53  Flags for the xS
f4e0: 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f  hmLock VFS metho
f4f0: 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  d.**.** These in
f500: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
f510: 64 65 66 69 6e 65 20 74 68 65 20 76 61 72 69 6f  define the vario
f520: 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61  us locking opera
f530: 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64  tions.** allowed
f540: 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b   by the xShmLock
f550: 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69   method of [sqli
f560: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e  te3_io_methods].
f570: 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69    The.** followi
f580: 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20  ng are the only 
f590: 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f  legal combinatio
f5a0: 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20 74  ns of flags to t
f5b0: 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d  he.** xShmLock m
f5c0: 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  ethod:.**.** <ul
f5d0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  >.** <li>  SQLIT
f5e0: 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c  E_SHM_LOCK | SQL
f5f0: 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a  ITE_SHM_SHARED.*
f600: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
f610: 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45  HM_LOCK | SQLITE
f620: 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a  _SHM_EXCLUSIVE.*
f630: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
f640: 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49  HM_UNLOCK | SQLI
f650: 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a  TE_SHM_SHARED.**
f660: 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
f670: 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  M_UNLOCK | SQLIT
f680: 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a  E_SHM_EXCLUSIVE.
f690: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57  ** </ul>.**.** W
f6a0: 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74  hen unlocking, t
f6b0: 68 65 20 73 61 6d 65 20 53 48 41 52 45 44 20 6f  he same SHARED o
f6c0: 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67  r EXCLUSIVE flag
f6d0: 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69 65   must be supplie
f6e0: 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76 65  d as.** was give
f6f0: 6e 20 6f 6e 20 74 68 65 20 63 6f 72 72 65 73 70  n on the corresp
f700: 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a  onding lock.  .*
f710: 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63  *.** The xShmLoc
f720: 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72 61  k method can tra
f730: 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  nsition between 
f740: 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48 41  unlocked and SHA
f750: 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65  RED or.** betwee
f760: 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45  n unlocked and E
f770: 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63 61  XCLUSIVE.  It ca
f780: 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e 20  nnot transition 
f790: 62 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a 2a  between SHARED.*
f7a0: 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e  * and EXCLUSIVE.
f7b0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
f7c0: 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20  TE_SHM_UNLOCK   
f7d0: 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
f7e0: 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20  LITE_SHM_LOCK   
f7f0: 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
f800: 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45  SQLITE_SHM_SHARE
f810: 44 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e  D       4.#defin
f820: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43  e SQLITE_SHM_EXC
f830: 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a  LUSIVE    8../*.
f840: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61 78  ** CAPI3REF: Max
f850: 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e  imum xShmLock in
f860: 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53  dex.**.** The xS
f870: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e  hmLock method on
f880: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
f890: 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76 61  hods] may use va
f8a0: 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20  lues.** between 
f8b0: 30 20 61 6e 64 20 74 68 69 73 20 75 70 70 65 72  0 and this upper
f8c0: 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22 6f   bound as its "o
f8d0: 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74 2e  ffset" argument.
f8e0: 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63  .** The SQLite c
f8f0: 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 61  ore will never a
f900: 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69 72  ttempt to acquir
f910: 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a 2a  e or release a.*
f920: 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f  * lock outside o
f930: 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a  f this range.*/.
f940: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
f950: 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20  HM_NLOCK        
f960: 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  8.../*.** CAPI3R
f970: 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54  EF: Initialize T
f980: 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72  he SQLite Librar
f990: 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  y.**.** ^The sql
f9a0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
f9b0: 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61  ) routine initia
f9c0: 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c  lizes the.** SQL
f9d0: 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e 54  ite library.  ^T
f9e0: 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  he sqlite3_shutd
f9f0: 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a  own() routine.**
fa00: 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79   deallocates any
fa10: 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 20   resources that 
fa20: 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62  were allocated b
fa30: 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  y sqlite3_initia
fa40: 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65  lize()..** These
fa50: 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65   routines are de
fa60: 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69 6e  signed to aid in
fa70: 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c   process initial
fa80: 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73  ization and.** s
fa90: 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64  hutdown on embed
faa0: 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57 6f  ded systems.  Wo
fab0: 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 63  rkstation applic
fac0: 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20  ations using.** 
fad0: 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20  SQLite normally 
fae0: 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69  do not need to i
faf0: 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 20  nvoke either of 
fb00: 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
fb10: 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20  **.** A call to 
fb20: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
fb30: 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 65  ze() is an "effe
fb40: 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69  ctive" call if i
fb50: 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73  t is.** the firs
fb60: 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69  t time sqlite3_i
fb70: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
fb80: 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68  nvoked during th
fb90: 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a  e lifetime of.**
fba0: 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72   the process, or
fbb0: 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69   if it is the fi
fbc0: 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33  rst time sqlite3
fbd0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
fbe0: 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c   invoked.** foll
fbf0: 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20  owing a call to 
fc00: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
fc10: 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65  ().  ^(Only an e
fc20: 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a  ffective call.**
fc30: 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   of sqlite3_init
fc40: 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e  ialize() does an
fc50: 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  y initialization
fc60: 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c  .  All other cal
fc70: 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65  ls.** are harmle
fc80: 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a  ss no-ops.)^.**.
fc90: 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ** A call to sql
fca0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
fcb0: 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65  is an "effective
fcc0: 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20  " call if it is 
fcd0: 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c  the first.** cal
fce0: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
fcf0: 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68  tdown() since th
fd00: 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69  e last sqlite3_i
fd10: 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28  nitialize().  ^(
fd20: 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63  Only.** an effec
fd30: 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c  tive call to sql
fd40: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
fd50: 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69  does any deiniti
fd60: 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c  alization..** Al
fd70: 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61  l other valid ca
fd80: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  lls to sqlite3_s
fd90: 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61  hutdown() are ha
fda0: 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e  rmless no-ops.)^
fdb0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
fdc0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
fdd0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 72  interface is thr
fde0: 65 61 64 73 61 66 65 2c 20 62 75 74 20 73 71 6c  eadsafe, but sql
fdf0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a  ite3_shutdown().
fe00: 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 20  ** is not.  The 
fe10: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
fe20: 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75 73  () interface mus
fe30: 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64  t only be called
fe40: 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c   from a.** singl
fe50: 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f  e thread.  All o
fe60: 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f  pen [database co
fe70: 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20  nnections] must 
fe80: 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c  be closed and al
fe90: 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74  l.** other SQLit
fea0: 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73 74  e resources must
feb0: 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
fec0: 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e  prior to invokin
fed0: 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 75  g.** sqlite3_shu
fee0: 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41  tdown()..**.** A
fef0: 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67  mong other thing
ff00: 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74  s, ^sqlite3_init
ff10: 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e  ialize() will in
ff20: 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  voke.** sqlite3_
ff30: 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69  os_init().  Simi
ff40: 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f  larly, ^sqlite3_
ff50: 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69  shutdown().** wi
ff60: 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ll invoke sqlite
ff70: 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a  3_os_end()..**.*
ff80: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
ff90: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
ffa0: 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ine returns [SQL
ffb0: 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
ffc0: 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73  ss..** ^If for s
ffd0: 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69  ome reason, sqli
ffe0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
fff0: 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e   is unable to in
10000 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20  itialize.** the 
10010 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 70 73  library (perhaps
10020 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f   it is unable to
10030 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64   allocate a need
10040 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 68  ed resource such
10050 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20  .** as a mutex) 
10060 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65  it returns an [e
10070 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72  rror code] other
10080 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b   than [SQLITE_OK
10090 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ]..**.** ^The sq
100a0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
100b0 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61  () routine is ca
100c0 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  lled internally 
100d0 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a  by many other.**
100e0 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
100f0 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70  es so that an ap
10100 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c  plication usuall
10110 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  y does not need 
10120 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c  to.** invoke sql
10130 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
10140 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72  ) directly.  For
10150 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74   example, [sqlit
10160 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61  e3_open()].** ca
10170 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  lls sqlite3_init
10180 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20  ialize() so the 
10190 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77  SQLite library w
101a0 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63  ill be automatic
101b0 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69  ally.** initiali
101c0 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  zed when [sqlite
101d0 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c  3_open()] is cal
101e0 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f  led if it has no
101f0 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64  t be initialized
10200 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e 48  .** already.  ^H
10210 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74  owever, if SQLit
10220 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
10230 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  th the [SQLITE_O
10240 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a  MIT_AUTOINIT].**
10250 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
10260 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61  tion, then the a
10270 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74  utomatic calls t
10280 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  o sqlite3_initia
10290 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d  lize().** are om
102a0 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 70  itted and the ap
102b0 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63  plication must c
102c0 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  all sqlite3_init
102d0 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c  ialize() directl
102e0 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73  y.** prior to us
102f0 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51  ing any other SQ
10300 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
10310 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72   For maximum por
10320 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20  tability,.** it 
10330 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
10340 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  hat applications
10350 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73   always invoke s
10360 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
10370 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20  e().** directly 
10380 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61  prior to using a
10390 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ny other SQLite 
103a0 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 75  interface.  Futu
103b0 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f  re releases.** o
103c0 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71  f SQLite may req
103d0 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f  uire this.  In o
103e0 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
103f0 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 74  behavior exhibit
10400 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74  ed.** when SQLit
10410 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
10420 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  th [SQLITE_OMIT_
10430 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20  AUTOINIT] might 
10440 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65  become the.** de
10450 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69  fault behavior i
10460 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65  n some future re
10470 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e  lease of SQLite.
10480 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
10490 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75  e3_os_init() rou
104a0 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74  tine does operat
104b0 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69  ing-system speci
104c0 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a  fic.** initializ
104d0 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c  ation of the SQL
104e0 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68  ite library.  Th
104f0 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  e sqlite3_os_end
10500 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e  ().** routine un
10510 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20  does the effect 
10520 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  of sqlite3_os_in
10530 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74  it().  Typical t
10540 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65  asks.** performe
10550 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 69  d by these routi
10560 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f  nes include allo
10570 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f  cation or deallo
10580 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61  cation.** of sta
10590 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69  tic resources, i
105a0 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66  nitialization of
105b0 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65   global variable
105c0 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70  s,.** setting up
105d0 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69   a default [sqli
105e0 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c  te3_vfs] module,
105f0 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a   or setting up.*
10600 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  * a default conf
10610 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20  iguration using 
10620 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
10630 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70  )]..**.** The ap
10640 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
10650 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69   never invoke ei
10660 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  ther sqlite3_os_
10670 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  init().** or sql
10680 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69  ite3_os_end() di
10690 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70  rectly.  The app
106a0 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
106b0 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73  only invoke.** s
106c0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
106d0 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
106e0 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65  shutdown().  The
106f0 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
10700 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
10710 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61  is called automa
10720 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74  tically by sqlit
10730 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
10740 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  and.** sqlite3_o
10750 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65  s_end() is calle
10760 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75  d by sqlite3_shu
10770 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70  tdown().  Approp
10780 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  riate.** impleme
10790 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c  ntations for sql
107a0 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61  ite3_os_init() a
107b0 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nd sqlite3_os_en
107c0 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74  d().** are built
107d0 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65   into SQLite whe
107e0 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64  n it is compiled
107f0 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f   for Unix, Windo
10800 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20  ws, or OS/2..** 
10810 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69  When [custom bui
10820 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 20  lds | built for 
10830 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d  other platforms]
10840 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20 5b  .** (using the [
10850 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d  SQLITE_OS_OTHER=
10860 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a  1] compile-time.
10870 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61  ** option) the a
10880 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
10890 73 75 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c  supply a suitabl
108a0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
108b0 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
108c0 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71  os_init() and sq
108d0 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20  lite3_os_end(). 
108e0 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   An application-
108f0 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c  supplied.** impl
10900 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71  ementation of sq
10910 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
10920 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  or sqlite3_os_en
10930 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75  d().** must retu
10940 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  rn [SQLITE_OK] o
10950 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f  n success and so
10960 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20  me other [error 
10970 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61  code] upon.** fa
10980 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ilure..*/.int sq
10990 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
109a0 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69  (void);.int sqli
109b0 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69  te3_shutdown(voi
109c0 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
109d0 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 69  os_init(void);.i
109e0 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nt sqlite3_os_en
109f0 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20  d(void);../*.** 
10a00 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67  CAPI3REF: Config
10a10 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65  uring The SQLite
10a20 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54   Library.**.** T
10a30 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  he sqlite3_confi
10a40 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  g() interface is
10a50 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c   used to make gl
10a60 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69  obal configurati
10a70 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  on.** changes to
10a80 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72   SQLite in order
10a90 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20   to tune SQLite 
10aa0 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20  to the specific 
10ab0 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20  needs of.** the 
10ac0 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68  application.  Th
10ad0 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67  e default config
10ae0 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d  uration is recom
10af0 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a  mended for most.
10b00 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** applications 
10b10 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74  and so this rout
10b20 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e  ine is usually n
10b30 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49  ot necessary.  I
10b40 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64  t is.** provided
10b50 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65   to support rare
10b60 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69   applications wi
10b70 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73  th unusual needs
10b80 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 54 68 65 20 73  ..**.** <b>The s
10b90 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
10ba0 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74  interface is not
10bb0 20 74 68 72 65 61 64 73 61 66 65 2e 20 54 68 65   threadsafe. The
10bc0 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
10bd0 6d 75 73 74 20 65 6e 73 75 72 65 20 74 68 61 74  must ensure that
10be0 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65   no other SQLite
10bf0 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
10c00 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72  invoked by other
10c10 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c  .** threads whil
10c20 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
10c30 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 3c 2f  () is running.</
10c40 62 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  b>.**.** The sql
10c50 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e  ite3_config() in
10c60 74 65 72 66 61 63 65 0a 2a 2a 20 6d 61 79 20 6f  terface.** may o
10c70 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70  nly be invoked p
10c80 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20  rior to library 
10c90 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75  initialization u
10ca0 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
10cb0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f  _initialize()] o
10cc0 72 20 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e  r after shutdown
10cd0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75   by [sqlite3_shu
10ce0 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66  tdown()]..** ^If
10cf0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
10d00 29 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65  ) is called afte
10d10 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  r [sqlite3_initi
10d20 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66  alize()] and bef
10d30 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ore.** [sqlite3_
10d40 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e  shutdown()] then
10d50 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20   it will return 
10d60 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a  SQLITE_MISUSE..*
10d70 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c  * Note, however,
10d80 20 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63   that ^sqlite3_c
10d90 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 63  onfig() can be c
10da0 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66  alled as part of
10db0 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   the.** implemen
10dc0 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70  tation of an app
10dd0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
10de0 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69   [sqlite3_os_ini
10df0 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  t()]..**.** The 
10e00 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
10e10 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  o sqlite3_config
10e20 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  () is an integer
10e30 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74 69  .** [configurati
10e40 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20  on option] that 
10e50 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68  determines.** wh
10e60 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53  at property of S
10e70 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20 63  QLite is to be c
10e80 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62 73  onfigured.  Subs
10e90 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73  equent arguments
10ea0 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69  .** vary dependi
10eb0 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69  ng on the [confi
10ec0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d  guration option]
10ed0 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74  .** in the first
10ee0 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
10ef0 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75   ^When a configu
10f00 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
10f10 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f   set, sqlite3_co
10f20 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b  nfig() returns [
10f30 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e  SQLITE_OK]..** ^
10f40 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73  If the option is
10f50 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69   unknown or SQLi
10f60 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  te is unable to 
10f70 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a  set the option.*
10f80 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74  * then this rout
10f90 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f  ine returns a no
10fa0 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f  n-zero [error co
10fb0 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  de]..*/.int sqli
10fc0 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20  te3_config(int, 
10fd0 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ...);../*.** CAP
10fe0 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65  I3REF: Configure
10ff0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
11000 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  tions.** METHOD:
11010 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54   sqlite3.**.** T
11020 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  he sqlite3_db_co
11030 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
11040 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65   is used to make
11050 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a   configuration.*
11060 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b  * changes to a [
11070 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
11080 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72  ion].  The inter
11090 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20  face is similar 
110a0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
110b0 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74 20  onfig()] except 
110c0 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65 73  that the changes
110d0 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67   apply to a sing
110e0 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  le.** [database 
110f0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65  connection] (spe
11100 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66 69  cified in the fi
11110 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a 2a  rst argument)..*
11120 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  *.** The second 
11130 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
11140 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c  te3_db_config(D,
11150 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a  V,...)  is the.*
11160 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  * [SQLITE_DBCONF
11170 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 63  IG_LOOKASIDE | c
11180 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72  onfiguration ver
11190 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20  b] - an integer 
111a0 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69 6e  code .** that in
111b0 64 69 63 61 74 65 73 20 77 68 61 74 20 61 73 70  dicates what asp
111c0 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61  ect of the [data
111d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
111e0 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 67   is being config
111f0 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71 75  ured..** Subsequ
11200 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76 61  ent arguments va
11210 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ry depending on 
11220 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
11230 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43  n verb..**.** ^C
11240 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
11250 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75  db_config() retu
11260 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20  rn SQLITE_OK if 
11270 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74  and only if.** t
11280 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69  he call is consi
11290 64 65 72 65 64 20 73 75 63 63 65 73 73 66 75 6c  dered successful
112a0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
112b0 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74  _db_config(sqlit
112c0 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e  e3*, int op, ...
112d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
112e0 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63  EF: Memory Alloc
112f0 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a  ation Routines.*
11300 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
11310 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
11320 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
11330 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53 51  rface between SQ
11340 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d  Lite.** and low-
11350 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  level memory all
11360 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
11370 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a  ..**.** This obj
11380 65 63 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f  ect is used in o
11390 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e  nly one place in
113a0 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65   the SQLite inte
113b0 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e  rface..** A poin
113c0 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
113d0 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
113e0 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e  t is the argumen
113f0 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  t to.** [sqlite3
11400 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20  _config()] when 
11410 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
11420 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b  n option is.** [
11430 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
11440 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45  LLOC] or [SQLITE
11450 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
11460 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65 61  C].  .** By crea
11470 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65  ting an instance
11480 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a   of this object.
11490 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69  ** and passing i
114a0 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
114b0 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f  nfig]([SQLITE_CO
114c0 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a  NFIG_MALLOC]).**
114d0 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72   during configur
114e0 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63  ation, an applic
114f0 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 66  ation can specif
11500 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65  y an alternative
11510 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
11520 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20  ation subsystem 
11530 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75 73  for SQLite to us
11540 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  e for all of its
11550 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f  .** dynamic memo
11560 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20  ry needs..**.** 
11570 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74 65  Note that SQLite
11580 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76 65   comes with seve
11590 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65  ral [built-in me
115a0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d  mory allocators]
115b0 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65 72  .** that are per
115c0 66 65 63 74 6c 79 20 61 64 65 71 75 61 74 65 20  fectly adequate 
115d0 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c  for the overwhel
115e0 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66  ming majority of
115f0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
11600 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f   and that this o
11610 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73  bject is only us
11620 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d  eful to a tiny m
11630 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69  inority of appli
11640 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20  cations.** with 
11650 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f  specialized memo
11660 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65  ry allocation re
11670 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69  quirements.  Thi
11680 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61  s object is.** a
11690 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20  lso used during 
116a0 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74  testing of SQLit
116b0 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70  e in order to sp
116c0 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61  ecify an alterna
116d0 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  tive.** memory a
116e0 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69  llocator that si
116f0 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f  mulates memory o
11700 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e  ut-of-memory con
11710 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72  ditions in.** or
11720 64 65 72 20 74 6f 20 76 65 72 69 66 79 20 74 68  der to verify th
11730 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65  at SQLite recove
11740 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72  rs gracefully fr
11750 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69  om such.** condi
11760 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tions..**.** The
11770 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c   xMalloc, xReall
11780 6f 63 2c 20 61 6e 64 20 78 46 72 65 65 20 6d 65  oc, and xFree me
11790 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20  thods must work 
117a0 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c  like the.** mall
117b0 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20  oc(), realloc() 
117c0 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63 74  and free() funct
117d0 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74  ions from the st
117e0 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
117f0 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61  ..** ^SQLite gua
11800 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65  rantees that the
11810 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
11820 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20   to.** xRealloc 
11830 69 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c 75  is always a valu
11840 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 61 20  e returned by a 
11850 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52  prior call to xR
11860 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53  oundup..**.** xS
11870 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72  ize should retur
11880 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20  n the allocated 
11890 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79  size of a memory
118a0 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70   allocation.** p
118b0 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e  reviously obtain
118c0 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20  ed from xMalloc 
118d0 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68  or xRealloc.  Th
118e0 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65  e allocated size
118f0 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 74  .** is always at
11900 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61 73   least as big as
11910 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 73   the requested s
11920 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20 6c  ize but may be l
11930 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  arger..**.** The
11940 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64   xRoundup method
11950 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 77 6f   returns what wo
11960 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f 63  uld be the alloc
11970 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20  ated size of.** 
11980 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
11990 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72 74  ion given a part
119a0 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 65 64  icular requested
119b0 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d   size.  Most mem
119c0 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72  ory.** allocator
119d0 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72  s round up memor
119e0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74  y allocations at
119f0 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e 65   least to the ne
11a00 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f  xt multiple.** o
11a10 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63  f 8.  Some alloc
11a20 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 74  ators round up t
11a30 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 69  o a larger multi
11a40 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 65  ple or to a powe
11a50 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79  r of 2..** Every
11a60 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
11a70 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69 6e  on request comin
11a80 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73 71  g in through [sq
11a90 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a  lite3_malloc()].
11aa0 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  ** or [sqlite3_r
11ab0 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74 20  ealloc()] first 
11ac0 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20  calls xRoundup. 
11ad0 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65 74   If xRoundup ret
11ae0 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74  urns 0, .** that
11af0 20 63 61 75 73 65 73 20 74 68 65 20 63 6f 72 72   causes the corr
11b00 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79  esponding memory
11b10 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66   allocation to f
11b20 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ail..**.** The x
11b30 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69 74  Init method init
11b40 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f  ializes the memo
11b50 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 46  ry allocator.  F
11b60 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69  or example,.** i
11b70 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 65  t might allocate
11b80 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75 74   any require mut
11b90 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c 69  exes or initiali
11ba0 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  ze internal data
11bb0 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e 20  .** structures. 
11bc0 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20 6d   The xShutdown m
11bd0 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64  ethod is invoked
11be0 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62 79   (indirectly) by
11bf0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  .** [sqlite3_shu
11c00 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f  tdown()] and sho
11c10 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 61  uld deallocate a
11c20 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61 63 71  ny resources acq
11c30 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69  uired.** by xIni
11c40 74 2e 20 20 54 68 65 20 70 41 70 70 44 61 74 61  t.  The pAppData
11c50 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65 64   pointer is used
11c60 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72   as the only par
11c70 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e  ameter to.** xIn
11c80 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e  it and xShutdown
11c90 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68  ..**.** SQLite h
11ca0 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45  olds the [SQLITE
11cb0 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41  _MUTEX_STATIC_MA
11cc0 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68 65 6e  STER] mutex when
11cd0 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74   it invokes.** t
11ce0 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c  he xInit method,
11cf0 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20 6d 65   so the xInit me
11d00 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62 65  thod need not be
11d10 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68   threadsafe.  Th
11d20 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d  e.** xShutdown m
11d30 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61  ethod is only ca
11d40 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  lled from [sqlit
11d50 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 73  e3_shutdown()] s
11d60 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  o it does.** not
11d70 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68 72 65   need to be thre
11d80 61 64 73 61 66 65 20 65 69 74 68 65 72 2e 20 20  adsafe either.  
11d90 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65  For all other me
11da0 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a  thods, SQLite.**
11db0 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49   holds the [SQLI
11dc0 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
11dd0 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f  MEM] mutex as lo
11de0 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51  ng as the.** [SQ
11df0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
11e00 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 72 61  TATUS] configura
11e10 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74  tion option is t
11e20 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 68 0a  urned on (which.
11e30 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65 66 61  ** it is by defa
11e40 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 65 20  ult) and so the 
11e50 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75 74 6f  methods are auto
11e60 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69 61 6c  matically serial
11e70 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72  ized..** However
11e80 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  , if [SQLITE_CON
11e90 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69  FIG_MEMSTATUS] i
11ea0 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 6e  s disabled, then
11eb0 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65   the other.** me
11ec0 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20 74 68  thods must be th
11ed0 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c 73 65  readsafe or else
11ee0 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 6e 20   make their own 
11ef0 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72  arrangements for
11f00 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 69 6f  .** serializatio
11f10 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  n..**.** SQLite 
11f20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b  will never invok
11f30 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 20 74  e xInit() more t
11f40 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75 74  han once without
11f50 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a   an intervening.
11f60 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 75 74  ** call to xShut
11f70 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64  down()..*/.typed
11f80 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
11f90 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71  3_mem_methods sq
11fa0 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
11fb0 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  s;.struct sqlite
11fc0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a  3_mem_methods {.
11fd0 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f    void *(*xMallo
11fe0 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20  c)(int);        
11ff0 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63   /* Memory alloc
12000 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a  ation function *
12010 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65 65  /.  void (*xFree
12020 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20  )(void*);       
12030 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69     /* Free a pri
12040 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f  or allocation */
12050 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c  .  void *(*xReal
12060 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b  loc)(void*,int);
12070 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61    /* Resize an a
12080 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69  llocation */.  i
12090 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 64  nt (*xSize)(void
120a0 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a  *);           /*
120b0 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65   Return the size
120c0 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f   of an allocatio
120d0 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f  n */.  int (*xRo
120e0 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20  undup)(int);    
120f0 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75        /* Round u
12100 70 20 72 65 71 75 65 73 74 20 73 69 7a 65 20 74  p request size t
12110 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  o allocation siz
12120 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e  e */.  int (*xIn
12130 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  it)(void*);     
12140 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c        /* Initial
12150 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ize the memory a
12160 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f  llocator */.  vo
12170 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28  id (*xShutdown)(
12180 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20  void*);      /* 
12190 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65  Deinitialize the
121a0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
121b0 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70  r */.  void *pAp
121c0 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20  pData;          
121d0 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e        /* Argumen
121e0 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64  t to xInit() and
121f0 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a   xShutdown() */.
12200 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
12210 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f  EF: Configuratio
12220 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59  n Options.** KEY
12230 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72  WORDS: {configur
12240 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a  ation option}.**
12250 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
12260 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69  nts are the avai
12270 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f  lable integer co
12280 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
12290 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20  ons that.** can 
122a0 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
122b0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
122c0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
122d0 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
122e0 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63  ace..**.** New c
122f0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
12300 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65  ions may be adde
12310 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
12320 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
12330 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66  ** Existing conf
12340 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
12350 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f  s might be disco
12360 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63  ntinued.  Applic
12370 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64  ations.** should
12380 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72   check the retur
12390 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c  n code from [sql
123a0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74  ite3_config()] t
123b0 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74  o make sure that
123c0 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72  .** the call wor
123d0 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ked.  The [sqlit
123e0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  e3_config()] int
123f0 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75  erface will retu
12400 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f  rn a.** non-zero
12410 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66   [error code] if
12420 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20   a discontinued 
12430 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63  or unsupported c
12440 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
12450 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65  ion.** is invoke
12460 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  d..**.** <dl>.**
12470 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
12480 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20  _SINGLETHREAD]] 
12490 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
124a0 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f  G_SINGLETHREAD</
124b0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65  dt>.** <dd>There
124c0 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74   are no argument
124d0 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
124e0 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  .  ^This option 
124f0 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72  sets the.** [thr
12500 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20  eading mode] to 
12510 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20 20  Single-thread.  
12520 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
12530 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61  it disables.** a
12540 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20  ll mutexing and 
12550 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f  puts SQLite into
12560 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74   a mode where it
12570 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65   can only be use
12580 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65  d.** by a single
12590 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20 53   thread.   ^If S
125a0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
125b0 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
125c0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
125d0 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
125e0 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
125f0 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
12600 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f  .** it is not po
12610 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67 65  ssible to change
12620 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20   the [threading 
12630 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20 64  mode] from its d
12640 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20  efault.** value 
12650 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64  of Single-thread
12660 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65 33   and so [sqlite3
12670 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20  _config()] will 
12680 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49  return .** [SQLI
12690 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c  TE_ERROR] if cal
126a0 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c  led with the SQL
126b0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
126c0 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69  ETHREAD.** confi
126d0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
126e0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
126f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
12700 49 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51  ITHREAD]] <dt>SQ
12710 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
12720 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20  ITHREAD</dt>.** 
12730 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f  <dd>There are no
12740 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
12750 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69  is option.  ^Thi
12760 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68  s option sets th
12770 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20  e.** [threading 
12780 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74  mode] to Multi-t
12790 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72  hread.  In other
127a0 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62   words, it disab
127b0 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20  les.** mutexing 
127c0 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  on [database con
127d0 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72  nection] and [pr
127e0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
127f0 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68  ] objects..** Th
12800 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73  e application is
12810 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
12820 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63   serializing acc
12830 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62  ess to.** [datab
12840 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
12850 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
12860 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74  tatements].  But
12870 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a   other mutexes.*
12880 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f  * are enabled so
12890 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
128a0 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 73 65  l be safe to use
128b0 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65   in a multi-thre
128c0 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d  aded.** environm
128d0 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e  ent as long as n
128e0 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 61 74  o two threads at
128f0 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65  tempt to use the
12900 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61   same.** [databa
12910 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
12920 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e  t the same time.
12930 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20    ^If SQLite is 
12940 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
12950 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
12960 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
12970 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
12980 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
12990 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73  on then.** it is
129a0 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f   not possible to
129b0 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d 74   set the Multi-t
129c0 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67  hread [threading
129d0 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73   mode] and.** [s
129e0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
129f0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
12a00 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
12a10 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  alled with the.*
12a20 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  * SQLITE_CONFIG_
12a30 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e 66  MULTITHREAD conf
12a40 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
12a50 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
12a60 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
12a70 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51  IALIZED]] <dt>SQ
12a80 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
12a90 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  ALIZED</dt>.** <
12aa0 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20  dd>There are no 
12ab0 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
12ac0 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73  s option.  ^This
12ad0 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65   option sets the
12ae0 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  .** [threading m
12af0 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a  ode] to Serializ
12b00 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  ed. In other wor
12b10 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e 20  ds, this option 
12b20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d  enables.** all m
12b30 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e 67  utexes including
12b40 20 74 68 65 20 72 65 63 75 72 73 69 76 65 0a 2a   the recursive.*
12b50 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 61  * mutexes on [da
12b60 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
12b70 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  n] and [prepared
12b80 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65   statement] obje
12b90 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20  cts..** In this 
12ba0 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73 20 74  mode (which is t
12bb0 68 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e 20  he default when 
12bc0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
12bd0 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49  ed with.** [SQLI
12be0 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 5d  TE_THREADSAFE=1]
12bf0 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  ) the SQLite lib
12c00 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66  rary will itself
12c10 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73   serialize acces
12c20 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73  s.** to [databas
12c30 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61  e connections] a
12c40 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  nd [prepared sta
12c50 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74  tements] so that
12c60 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74   the.** applicat
12c70 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75  ion is free to u
12c80 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  se the same [dat
12c90 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
12ca0 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65  ] or the.** same
12cb0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
12cc0 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65  ment] in differe
12cd0 6e 74 20 74 68 72 65 61 64 73 20 61 74 20 74 68  nt threads at th
12ce0 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20  e same time..** 
12cf0 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
12d00 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
12d10 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
12d20 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
12d30 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
12d40 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
12d50 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e   then.** it is n
12d60 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73  ot possible to s
12d70 65 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a 65  et the Serialize
12d80 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
12d90 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  e] and.** [sqlit
12da0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c  e3_config()] wil
12db0 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
12dc0 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65  _ERROR] if calle
12dd0 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51  d with the.** SQ
12de0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
12df0 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72 61  ALIZED configura
12e00 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64  tion option.</dd
12e10 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
12e20 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d  _CONFIG_MALLOC]]
12e30 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
12e40 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a  IG_MALLOC</dt>.*
12e50 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c  * <dd> ^(The SQL
12e60 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
12e70 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  C option takes a
12e80 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
12e90 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 61 20   which is .** a 
12ea0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
12eb0 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
12ec0 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
12ed0 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a  ds] structure..*
12ee0 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73  * The argument s
12ef0 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65  pecifies.** alte
12f00 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65  rnative low-leve
12f10 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
12f20 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ion routines to 
12f30 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65  be used in place
12f40 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72   of.** the memor
12f50 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
12f60 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f  tines built into
12f70 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69   SQLite.)^ ^SQLi
12f80 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20  te makes.** its 
12f90 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79  own private copy
12fa0 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20   of the content 
12fb0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
12fc0 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  mem_methods] str
12fd0 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65  ucture.** before
12fe0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
12ff0 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65 74  nfig()] call ret
13000 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  urns.</dd>.**.**
13010 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
13020 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74  _GETMALLOC]] <dt
13030 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
13040 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a  ETMALLOC</dt>.**
13050 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49   <dd> ^(The SQLI
13060 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
13070 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  LOC option takes
13080 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
13090 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61  nt which.** is a
130a0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
130b0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
130c0 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
130d0 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a  ods] structure..
130e0 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
130f0 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  mem_methods].** 
13100 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c  structure is fil
13110 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72  led with the cur
13120 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d  rently defined m
13130 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
13140 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20   routines.)^.** 
13150 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20  This option can 
13160 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c  be used to overl
13170 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20  oad the default 
13180 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
13190 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69  n.** routines wi
131a0 74 68 20 61 20 77 72 61 70 70 65 72 20 74 68 61  th a wrapper tha
131b0 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65  t simulations me
131c0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
131d0 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72  failure or.** tr
131e0 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67  acks memory usag
131f0 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20  e, for example. 
13200 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
13210 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
13220 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49  TATUS]] <dt>SQLI
13230 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
13240 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TUS</dt>.** <dd>
13250 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e   ^The SQLITE_CON
13260 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 6f 70  FIG_MEMSTATUS op
13270 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c  tion takes singl
13280 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79  e argument of ty
13290 70 65 20 69 6e 74 2c 0a 2a 2a 20 69 6e 74 65 72  pe int,.** inter
132a0 70 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c  preted as a bool
132b0 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c  ean, which enabl
132c0 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74  es or disables t
132d0 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66  he collection of
132e0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
132f0 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73  ation statistics
13300 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20  . ^(When memory 
13310 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
13320 73 74 69 63 73 20 61 72 65 0a 2a 2a 20 64 69 73  stics are.** dis
13330 61 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c 6c 6f  abled, the follo
13340 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65  wing SQLite inte
13350 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f  rfaces become no
13360 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a  n-operational:.*
13370 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  *   <ul>.**   <l
13380 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  i> [sqlite3_memo
13390 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20  ry_used()].**   
133a0 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65  <li> [sqlite3_me
133b0 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
133c0 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
133d0 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
133e0 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c  imit64()].**   <
133f0 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61  li> [sqlite3_sta
13400 74 75 73 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 2f  tus64()].**   </
13410 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79  ul>)^.** ^Memory
13420 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74   allocation stat
13430 69 73 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c  istics are enabl
13440 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e  ed by default un
13450 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a  less SQLite is.*
13460 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  * compiled with 
13470 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f  [SQLITE_DEFAULT_
13480 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20  MEMSTATUS]=0 in 
13490 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72  which case memor
134a0 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  y.** allocation 
134b0 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64  statistics are d
134c0 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
134d0 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a  lt..** </dd>.**.
134e0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
134f0 49 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64 74  IG_SCRATCH]] <dt
13500 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
13510 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  CRATCH</dt>.** <
13520 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  dd> ^The SQLITE_
13530 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 6f  CONFIG_SCRATCH o
13540 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20  ption specifies 
13550 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20  a static memory 
13560 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 53  buffer.** that S
13570 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f  QLite can use fo
13580 72 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79  r scratch memory
13590 2e 20 20 5e 28 54 68 65 72 65 20 61 72 65 20 74  .  ^(There are t
135a0 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 0a 2a  hree arguments.*
135b0 2a 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46  * to SQLITE_CONF
135c0 49 47 5f 53 43 52 41 54 43 48 3a 20 20 41 20 70  IG_SCRATCH:  A p
135d0 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79 74 65  ointer an 8-byte
135e0 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f  .** aligned memo
135f0 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d 20 77  ry buffer from w
13600 68 69 63 68 20 74 68 65 20 73 63 72 61 74 63 68  hich the scratch
13610 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c   allocations wil
13620 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74  l be.** drawn, t
13630 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  he size of each 
13640 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69  scratch allocati
13650 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20  on (sz),.** and 
13660 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  the maximum numb
13670 65 72 20 6f 66 20 73 63 72 61 74 63 68 20 61 6c  er of scratch al
13680 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e 29 5e  locations (N).)^
13690 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
136a0 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61  gument must be a
136b0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38   pointer to an 8
136c0 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75  -byte aligned bu
136d0 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65  ffer.** of at le
136e0 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f  ast sz*N bytes o
136f0 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51  f memory..** ^SQ
13700 4c 69 74 65 20 77 69 6c 6c 20 6e 6f 74 20 75 73  Lite will not us
13710 65 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  e more than one 
13720 73 63 72 61 74 63 68 20 62 75 66 66 65 72 73 20  scratch buffers 
13730 70 65 72 20 74 68 72 65 61 64 2e 0a 2a 2a 20 5e  per thread..** ^
13740 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65  SQLite will neve
13750 72 20 72 65 71 75 65 73 74 20 61 20 73 63 72 61  r request a scra
13760 74 63 68 20 62 75 66 66 65 72 20 74 68 61 74 20  tch buffer that 
13770 69 73 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a  is more than 6.*
13780 2a 20 74 69 6d 65 73 20 74 68 65 20 64 61 74 61  * times the data
13790 62 61 73 65 20 70 61 67 65 20 73 69 7a 65 2e 0a  base page size..
137a0 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 6e 65  ** ^If SQLite ne
137b0 65 64 73 20 6e 65 65 64 73 20 61 64 64 69 74 69  eds needs additi
137c0 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20  onal.** scratch 
137d0 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77 68  memory beyond wh
137e0 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62  at is provided b
137f0 79 20 74 68 69 73 20 63 6f 6e 66 69 67 75 72 61  y this configura
13800 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65  tion option, the
13810 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  n .** [sqlite3_m
13820 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65  alloc()] will be
13830 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20   used to obtain 
13840 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65  the memory neede
13850 64 2e 3c 70 3e 0a 2a 2a 20 5e 57 68 65 6e 20 74  d.<p>.** ^When t
13860 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 70  he application p
13870 72 6f 76 69 64 65 73 20 61 6e 79 20 61 6d 6f 75  rovides any amou
13880 6e 74 20 6f 66 20 73 63 72 61 74 63 68 20 6d 65  nt of scratch me
13890 6d 6f 72 79 20 75 73 69 6e 67 0a 2a 2a 20 53 51  mory using.** SQ
138a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
138b0 54 43 48 2c 20 53 51 4c 69 74 65 20 61 76 6f 69  TCH, SQLite avoi
138c0 64 73 20 75 6e 6e 65 63 65 73 73 61 72 79 20 6c  ds unnecessary l
138d0 61 72 67 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  arge.** [sqlite3
138e0 5f 6d 61 6c 6c 6f 63 7c 68 65 61 70 20 61 6c 6c  _malloc|heap all
138f0 6f 63 61 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68  ocations]..** Th
13900 69 73 20 63 61 6e 20 68 65 6c 70 20 5b 52 6f 62  is can help [Rob
13910 73 6f 6e 20 70 72 6f 6f 66 7c 70 72 65 76 65 6e  son proof|preven
13920 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  t memory allocat
13930 69 6f 6e 20 66 61 69 6c 75 72 65 73 5d 20 64 75  ion failures] du
13940 65 20 74 6f 20 68 65 61 70 0a 2a 2a 20 66 72 61  e to heap.** fra
13950 67 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 20 6c 6f  gmentation in lo
13960 77 2d 6d 65 6d 6f 72 79 20 65 6d 62 65 64 64 65  w-memory embedde
13970 64 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 20 3c 2f  d systems..** </
13980 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
13990 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
139a0 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  CHE]] <dt>SQLITE
139b0 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
139c0 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
139d0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
139e0 47 5f 50 41 47 45 43 41 43 48 45 20 6f 70 74 69  G_PAGECACHE opti
139f0 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 6d  on specifies a m
13a00 65 6d 6f 72 79 20 70 6f 6f 6c 0a 2a 2a 20 74 68  emory pool.** th
13a10 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73  at SQLite can us
13a20 65 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61  e for the databa
13a30 73 65 20 70 61 67 65 20 63 61 63 68 65 20 77 69  se page cache wi
13a40 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 20 70  th the default p
13a50 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70  age.** cache imp
13a60 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a  lementation.  .*
13a70 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61  * This configura
13a80 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 61  tion option is a
13a90 20 6e 6f 2d 6f 70 20 69 66 20 61 6e 20 61 70 70   no-op if an app
13aa0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20  lication-define 
13ab0 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d  page.** cache im
13ac0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20  plementation is 
13ad0 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68 65  loaded using the
13ae0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
13af0 50 43 41 43 48 45 32 5d 2e 0a 2a 2a 20 5e 54 68  PCACHE2]..** ^Th
13b00 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
13b10 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54  guments to SQLIT
13b20 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
13b30 48 45 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  HE: A pointer to
13b40 0a 2a 2a 20 38 2d 62 79 74 65 20 61 6c 69 67 6e  .** 8-byte align
13b50 65 64 20 6d 65 6d 6f 72 79 20 28 70 4d 65 6d 29  ed memory (pMem)
13b60 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61  , the size of ea
13b70 63 68 20 70 61 67 65 20 63 61 63 68 65 20 6c 69  ch page cache li
13b80 6e 65 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20  ne (sz),.** and 
13b90 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 61  the number of ca
13ba0 63 68 65 20 6c 69 6e 65 73 20 28 4e 29 2e 0a 2a  che lines (N)..*
13bb0 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e  * The sz argumen
13bc0 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20  t should be the 
13bd0 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67  size of the larg
13be0 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67  est database pag
13bf0 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66  e.** (a power of
13c00 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32   two between 512
13c10 20 61 6e 64 20 36 35 35 33 36 29 20 70 6c 75 73   and 65536) plus
13c20 20 73 6f 6d 65 20 65 78 74 72 61 20 62 79 74 65   some extra byte
13c30 73 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61  s for each.** pa
13c40 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65  ge header.  ^The
13c50 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61   number of extra
13c60 20 62 79 74 65 73 20 6e 65 65 64 65 64 20 62 79   bytes needed by
13c70 20 74 68 65 20 70 61 67 65 20 68 65 61 64 65 72   the page header
13c80 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65 72  .** can be deter
13c90 6d 69 6e 65 64 20 75 73 69 6e 67 20 5b 53 51 4c  mined using [SQL
13ca0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
13cb0 45 5f 48 44 52 53 5a 5d 2e 0a 2a 2a 20 5e 49 74  E_HDRSZ]..** ^It
13cc0 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70   is harmless, ap
13cd0 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73  art from the was
13ce0 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 66  ted memory,.** f
13cf0 6f 72 20 74 68 65 20 73 7a 20 70 61 72 61 6d 65  or the sz parame
13d00 74 65 72 20 74 6f 20 62 65 20 6c 61 72 67 65 72  ter to be larger
13d10 20 74 68 61 6e 20 6e 65 63 65 73 73 61 72 79 2e   than necessary.
13d20 20 20 54 68 65 20 70 4d 65 6d 0a 2a 2a 20 61 72    The pMem.** ar
13d30 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 65  gument must be e
13d40 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69  ither a NULL poi
13d50 6e 74 65 72 20 6f 72 20 61 20 70 6f 69 6e 74 65  nter or a pointe
13d60 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a  r to an 8-byte.*
13d70 2a 20 61 6c 69 67 6e 65 64 20 62 6c 6f 63 6b 20  * aligned block 
13d80 6f 66 20 6d 65 6d 6f 72 79 20 6f 66 20 61 74 20  of memory of at 
13d90 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73  least sz*N bytes
13da0 2c 20 6f 74 68 65 72 77 69 73 65 0a 2a 2a 20 73  , otherwise.** s
13db0 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69  ubsequent behavi
13dc0 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
13dd0 0a 2a 2a 20 5e 57 68 65 6e 20 70 4d 65 6d 20 69  .** ^When pMem i
13de0 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69  s not NULL, SQLi
13df0 74 65 20 77 69 6c 6c 20 73 74 72 69 76 65 20 74  te will strive t
13e00 6f 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  o use the memory
13e10 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 74 6f 20   provided.** to 
13e20 73 61 74 69 73 66 79 20 70 61 67 65 20 63 61 63  satisfy page cac
13e30 68 65 20 6e 65 65 64 73 2c 20 66 61 6c 6c 69 6e  he needs, fallin
13e40 67 20 62 61 63 6b 20 74 6f 20 5b 73 71 6c 69 74  g back to [sqlit
13e50 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 66 0a  e3_malloc()] if.
13e60 2a 2a 20 61 20 70 61 67 65 20 63 61 63 68 65 20  ** a page cache 
13e70 6c 69 6e 65 20 69 73 20 6c 61 72 67 65 72 20 74  line is larger t
13e80 68 61 6e 20 73 7a 20 62 79 74 65 73 20 6f 72 20  han sz bytes or 
13e90 69 66 20 61 6c 6c 20 6f 66 20 74 68 65 20 70 4d  if all of the pM
13ea0 65 6d 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20  em buffer.** is 
13eb0 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 5e 49  exhausted..** ^I
13ec0 66 20 70 4d 65 6d 20 69 73 20 4e 55 4c 4c 20 61  f pMem is NULL a
13ed0 6e 64 20 4e 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f  nd N is non-zero
13ee0 2c 20 74 68 65 6e 20 65 61 63 68 20 64 61 74 61  , then each data
13ef0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
13f00 2a 2a 20 64 6f 65 73 20 61 6e 20 69 6e 69 74 69  ** does an initi
13f10 61 6c 20 62 75 6c 6b 20 61 6c 6c 6f 63 61 74 69  al bulk allocati
13f20 6f 6e 20 66 6f 72 20 70 61 67 65 20 63 61 63 68  on for page cach
13f30 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 66 72 6f 6d  e memory.** from
13f40 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
13f50 28 29 5d 20 73 75 66 66 69 63 69 65 6e 74 20 66  ()] sufficient f
13f60 6f 72 20 4e 20 63 61 63 68 65 20 6c 69 6e 65 73  or N cache lines
13f70 20 69 66 20 4e 20 69 73 20 70 6f 73 69 74 69 76   if N is positiv
13f80 65 20 6f 72 0a 2a 2a 20 6f 66 20 2d 31 30 32 34  e or.** of -1024
13f90 2a 4e 20 62 79 74 65 73 20 69 66 20 4e 20 69 73  *N bytes if N is
13fa0 20 6e 65 67 61 74 69 76 65 2c 20 2e 20 5e 49 66   negative, . ^If
13fb0 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70   additional.** p
13fc0 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79  age cache memory
13fd0 20 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e   is needed beyon
13fe0 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64  d what is provid
13ff0 65 64 20 62 79 20 74 68 65 20 69 6e 69 74 69 61  ed by the initia
14000 6c 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c  l.** allocation,
14010 20 74 68 65 6e 20 53 51 4c 69 74 65 20 67 6f 65   then SQLite goe
14020 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61  s to [sqlite3_ma
14030 6c 6c 6f 63 28 29 5d 20 73 65 70 61 72 61 74 65  lloc()] separate
14040 6c 79 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 61  ly for each.** a
14050 64 64 69 74 69 6f 6e 61 6c 20 63 61 63 68 65 20  dditional cache 
14060 6c 69 6e 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  line. </dd>.**.*
14070 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
14080 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c  G_HEAP]] <dt>SQL
14090 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c  ITE_CONFIG_HEAP<
140a0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
140b0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
140c0 48 45 41 50 20 6f 70 74 69 6f 6e 20 73 70 65 63  HEAP option spec
140d0 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d  ifies a static m
140e0 65 6d 6f 72 79 20 62 75 66 66 65 72 20 0a 2a 2a  emory buffer .**
140f0 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
14100 6c 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66  l use for all of
14110 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d   its dynamic mem
14120 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
14130 65 65 64 73 0a 2a 2a 20 62 65 79 6f 6e 64 20 74  eeds.** beyond t
14140 68 6f 73 65 20 70 72 6f 76 69 64 65 64 20 66 6f  hose provided fo
14150 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  r by [SQLITE_CON
14160 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64  FIG_SCRATCH] and
14170 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
14180 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a  IG_PAGECACHE]..*
14190 2a 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  * ^The SQLITE_CO
141a0 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e  NFIG_HEAP option
141b0 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62   is only availab
141c0 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  le if SQLite is 
141d0 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68  compiled.** with
141e0 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
141f0 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20  ENABLE_MEMSYS3] 
14200 6f 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  or [SQLITE_ENABL
14210 45 5f 4d 45 4d 53 59 53 35 5d 20 61 6e 64 20 72  E_MEMSYS5] and r
14220 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54  eturns.** [SQLIT
14230 45 5f 45 52 52 4f 52 5d 20 69 66 20 69 6e 76 6f  E_ERROR] if invo
14240 6b 65 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a  ked otherwise..*
14250 2a 20 5e 54 68 65 72 65 20 61 72 65 20 74 68 72  * ^There are thr
14260 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  ee arguments to 
14270 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
14280 41 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79 74 65  AP:.** An 8-byte
14290 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72   aligned pointer
142a0 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a   to the memory,.
142b0 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
142c0 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65   bytes in the me
142d0 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64  mory buffer, and
142e0 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   the minimum all
142f0 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a  ocation size..**
14300 20 5e 49 66 20 74 68 65 20 66 69 72 73 74 20 70   ^If the first p
14310 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f  ointer (the memo
14320 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e  ry pointer) is N
14330 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ULL, then SQLite
14340 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75   reverts.** to u
14350 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74  sing its default
14360 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
14370 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61  r (the system ma
14380 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74  lloc() implement
14390 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69  ation),.** undoi
143a0 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76  ng any prior inv
143b0 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49  ocation of [SQLI
143c0 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
143d0 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d  ].  ^If the.** m
143e0 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73  emory pointer is
143f0 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 74   not NULL then t
14400 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d  he alternative m
14410 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
14420 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f  or is engaged to
14430 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53   handle all of S
14440 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c  QLites memory al
14450 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a  location needs..
14460 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f 69  ** The first poi
14470 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79  nter (the memory
14480 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62   pointer) must b
14490 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
144a0 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61  8-byte.** bounda
144b0 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74  ry or subsequent
144c0 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c   behavior of SQL
144d0 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65  ite will be unde
144e0 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69  fined..** The mi
144f0 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e  nimum allocation
14500 20 73 69 7a 65 20 69 73 20 63 61 70 70 65 64 20   size is capped 
14510 61 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e  at 2**12. Reason
14520 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66  able values.** f
14530 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61  or the minimum a
14540 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61  llocation size a
14550 72 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20  re 2**5 through 
14560 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  2**8.</dd>.**.**
14570 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
14580 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c  _MUTEX]] <dt>SQL
14590 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
145a0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
145b0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
145c0 47 5f 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74  G_MUTEX option t
145d0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
145e0 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
145f0 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20  a.** pointer to 
14600 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
14610 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
14620 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
14630 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67  ture..** The arg
14640 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 20  ument specifies 
14650 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d  alternative low-
14660 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74  level mutex rout
14670 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 0a  ines to be used.
14680 2a 2a 20 69 6e 20 70 6c 61 63 65 20 74 68 65 20  ** in place the 
14690 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62  mutex routines b
146a0 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65  uilt into SQLite
146b0 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b  .)^  ^SQLite mak
146c0 65 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  es a copy of.** 
146d0 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
146e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
146f0 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
14700 74 75 72 65 20 62 65 66 6f 72 65 20 74 68 65 20  ture before the 
14710 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
14720 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65  te3_config()] re
14730 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74  turns. ^If SQLit
14740 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
14750 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
14760 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
14770 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
14780 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
14790 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
147a0 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78  the entire mutex
147b0 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73  ing subsystem is
147c0 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
147d0 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63  e build and henc
147e0 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73  e calls to.** [s
147f0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
14800 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
14810 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f  _CONFIG_MUTEX co
14820 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
14830 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72  on will.** retur
14840 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
14850 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
14860 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
14870 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49  MUTEX]] <dt>SQLI
14880 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
14890 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  EX</dt>.** <dd> 
148a0 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  ^(The SQLITE_CON
148b0 46 49 47 5f 47 45 54 4d 55 54 45 58 20 6f 70 74  FIG_GETMUTEX opt
148c0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
148d0 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
148e0 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65  h.** is a pointe
148f0 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
14900 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
14910 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
14920 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a  structure.  The.
14930 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ** [sqlite3_mute
14940 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74  x_methods].** st
14950 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65  ructure is fille
14960 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  d with the curre
14970 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74  ntly defined mut
14980 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a  ex routines.)^.*
14990 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61  * This option ca
149a0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65  n be used to ove
149b0 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c  rload the defaul
149c0 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69  t mutex allocati
149d0 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77  on.** routines w
149e0 69 74 68 20 61 20 77 72 61 70 70 65 72 20 75 73  ith a wrapper us
149f0 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65  ed to track mute
14a00 78 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 66  x usage for perf
14a10 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69  ormance.** profi
14a20 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c  ling or testing,
14a30 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20   for example.   
14a40 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
14a50 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
14a60 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
14a70 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
14a80 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
14a90 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
14aa0 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74   then.** the ent
14ab0 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62  ire mutexing sub
14ac0 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65  system is omitte
14ad0 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64  d from the build
14ae0 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73   and hence calls
14af0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
14b00 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74  config()] with t
14b10 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
14b20 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67  _GETMUTEX config
14b30 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77  uration option w
14b40 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  ill.** return [S
14b50 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64  QLITE_ERROR].</d
14b60 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
14b70 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
14b80 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  DE]] <dt>SQLITE_
14b90 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
14ba0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
14bb0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
14bc0 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f 70 74 69  G_LOOKASIDE opti
14bd0 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67  on takes two arg
14be0 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65  uments that dete
14bf0 72 6d 69 6e 65 0a 2a 2a 20 74 68 65 20 64 65 66  rmine.** the def
14c00 61 75 6c 74 20 73 69 7a 65 20 6f 66 20 6c 6f 6f  ault size of loo
14c10 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 6f 6e  kaside memory on
14c20 20 65 61 63 68 20 5b 64 61 74 61 62 61 73 65 20   each [database 
14c30 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20  connection]..** 
14c40 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
14c50 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a  nt is the.** siz
14c60 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73  e of each lookas
14c70 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20  ide buffer slot 
14c80 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69  and the second i
14c90 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  s the number of.
14ca0 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74  ** slots allocat
14cb0 65 64 20 74 6f 20 65 61 63 68 20 64 61 74 61 62  ed to each datab
14cc0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29  ase connection.)
14cd0 5e 20 20 5e 28 53 51 4c 49 54 45 5f 43 4f 4e 46  ^  ^(SQLITE_CONF
14ce0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a 2a 20  IG_LOOKASIDE.** 
14cf0 73 65 74 73 20 74 68 65 20 3c 69 3e 64 65 66 61  sets the <i>defa
14d00 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64  ult</i> lookasid
14d10 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c  e size. The [SQL
14d20 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
14d30 4b 41 53 49 44 45 5d 0a 2a 2a 20 6f 70 74 69 6f  KASIDE].** optio
14d40 6e 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62  n to [sqlite3_db
14d50 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62  _config()] can b
14d60 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65  e used to change
14d70 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a   the lookaside.*
14d80 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
14d90 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f  on individual co
14da0 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64  nnections.)^ </d
14db0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
14dc0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32  E_CONFIG_PCACHE2
14dd0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
14de0 4e 46 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 74  NFIG_PCACHE2</dt
14df0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20  >.** <dd> ^(The 
14e00 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
14e10 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b  ACHE2 option tak
14e20 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
14e30 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a  ment which is .*
14e40 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * a pointer to a
14e50 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68  n [sqlite3_pcach
14e60 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65  e_methods2] obje
14e70 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74  ct.  This object
14e80 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68   specifies.** th
14e90 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 61  e interface to a
14ea0 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63   custom page cac
14eb0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
14ec0 6e 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  n.)^.** ^SQLite 
14ed0 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
14ee0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 63 61  the [sqlite3_pca
14ef0 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62  che_methods2] ob
14f00 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ject.</dd>.**.**
14f10 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
14f20 5f 47 45 54 50 43 41 43 48 45 32 5d 5d 20 3c 64  _GETPCACHE2]] <d
14f30 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
14f40 47 45 54 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a  GETPCACHE2</dt>.
14f50 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51  ** <dd> ^(The SQ
14f60 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
14f70 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61  CACHE2 option ta
14f80 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
14f90 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69  ument which.** i
14fa0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
14fb0 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68  n [sqlite3_pcach
14fc0 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65  e_methods2] obje
14fd0 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69  ct.  SQLite copi
14fe0 65 73 20 6f 66 0a 2a 2a 20 74 68 65 20 63 75 72  es of.** the cur
14ff0 72 65 6e 74 20 70 61 67 65 20 63 61 63 68 65 20  rent page cache 
15000 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
15010 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e  nto that object.
15020 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  )^ </dd>.**.** [
15030 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  [SQLITE_CONFIG_L
15040 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  OG]] <dt>SQLITE_
15050 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a  CONFIG_LOG</dt>.
15060 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49  ** <dd> The SQLI
15070 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70  TE_CONFIG_LOG op
15080 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
15090 63 6f 6e 66 69 67 75 72 65 20 74 68 65 20 53 51  configure the SQ
150a0 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b  Lite.** global [
150b0 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28  error log]..** (
150c0 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
150d0 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61  IG_LOG option ta
150e0 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  kes two argument
150f0 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  s: a pointer to 
15100 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69  a.** function wi
15110 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74  th a call signat
15120 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76  ure of void(*)(v
15130 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63  oid*,int,const c
15140 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61  har*), .** and a
15150 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64   pointer to void
15160 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69  . ^If the functi
15170 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f  on pointer is no
15180 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a  t NULL, it is.**
15190 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c   invoked by [sql
151a0 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70  ite3_log()] to p
151b0 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67  rocess each logg
151c0 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20  ing event.  ^If 
151d0 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  the.** function 
151e0 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c  pointer is NULL,
151f0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f   the [sqlite3_lo
15200 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62  g()] interface b
15210 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a  ecomes a no-op..
15220 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69  ** ^The void poi
15230 6e 74 65 72 20 74 68 61 74 20 69 73 20 74 68 65  nter that is the
15240 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
15250 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49   to SQLITE_CONFI
15260 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73  G_LOG is.** pass
15270 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68  ed through as th
15280 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
15290 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  r to the applica
152a0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67  tion-defined log
152b0 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ger.** function 
152c0 77 68 65 6e 65 76 65 72 20 74 68 61 74 20 66 75  whenever that fu
152d0 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65  nction is invoke
152e0 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  d.  ^The second 
152f0 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
15300 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74  the logger funct
15310 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ion is a copy of
15320 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
15330 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72  eter to the corr
15340 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71  esponding.** [sq
15350 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c  lite3_log()] cal
15360 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65  l and is intende
15370 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c  d to be a [resul
15380 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a  t code] or an.**
15390 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
153a0 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74  t code].  ^The t
153b0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 70  hird parameter p
153c0 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67  assed to the log
153d0 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65  ger is.** log me
153e0 73 73 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d  ssage after form
153f0 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69  atting via [sqli
15400 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e  te3_snprintf()].
15410 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c  .** The SQLite l
15420 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65  ogging interface
15430 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e   is not reentran
15440 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75  t; the logger fu
15450 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69  nction.** suppli
15460 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ed by the applic
15470 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69  ation must not i
15480 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65  nvoke any SQLite
15490 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49   interface..** I
154a0 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64  n a multi-thread
154b0 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20  ed application, 
154c0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
154d0 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a  defined logger.*
154e0 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  * function must 
154f0 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c  be threadsafe. <
15500 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
15510 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d  ITE_CONFIG_URI]]
15520 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
15530 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28  IG_URI.** <dd>^(
15540 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
15550 47 5f 55 52 49 20 6f 70 74 69 6f 6e 20 74 61 6b  G_URI option tak
15560 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
15570 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74  ment of type int
15580 2e 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f  ..** If non-zero
15590 2c 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c  , then URI handl
155a0 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20  ing is globally 
155b0 65 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 65 20  enabled. If the 
155c0 70 61 72 61 6d 65 74 65 72 20 69 73 20 7a 65 72  parameter is zer
155d0 6f 2c 0a 2a 2a 20 74 68 65 6e 20 55 52 49 20 68  o,.** then URI h
155e0 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61  andling is globa
155f0 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e 29 5e 20  lly disabled.)^ 
15600 5e 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e 67  ^If URI handling
15610 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20   is globally.** 
15620 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c  enabled, all fil
15630 65 6e 61 6d 65 73 20 70 61 73 73 65 64 20 74 6f  enames passed to
15640 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
15650 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
15660 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  _v2()],.** [sqli
15670 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72  te3_open16()] or
15680 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20 61 73  .** specified as
15690 20 70 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48   part of [ATTACH
156a0 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69  ] commands are i
156b0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52  nterpreted as UR
156c0 49 73 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a  Is, regardless.*
156d0 2a 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  * of whether or 
156e0 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  not the [SQLITE_
156f0 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69  OPEN_URI] flag i
15700 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 64  s set when the d
15710 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
15720 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e  ction is opened.
15730 20 5e 49 66 20 69 74 20 69 73 20 67 6c 6f 62 61   ^If it is globa
15740 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 66 69  lly disabled, fi
15750 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f  lenames are.** o
15760 6e 6c 79 20 69 6e 74 65 72 70 72 65 74 65 64 20  nly interpreted 
15770 61 73 20 55 52 49 73 20 69 66 20 74 68 65 20 53  as URIs if the S
15780 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66  QLITE_OPEN_URI f
15790 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20  lag is set when 
157a0 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
157b0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70  connection is op
157c0 65 6e 65 64 2e 20 5e 28 42 79 20 64 65 66 61 75  ened. ^(By defau
157d0 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67  lt, URI handling
157e0 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20   is globally.** 
157f0 64 69 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65  disabled. The de
15800 66 61 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20  fault value may 
15810 62 65 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f  be changed by co
15820 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65  mpiling with the
15830 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f  .** [SQLITE_USE_
15840 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69  URI] symbol defi
15850 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  ned.)^.**.** [[S
15860 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56  QLITE_CONFIG_COV
15870 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e  ERING_INDEX_SCAN
15880 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
15890 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e  NFIG_COVERING_IN
158a0 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e  DEX_SCAN.** <dd>
158b0 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
158c0 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45  IG_COVERING_INDE
158d0 58 5f 53 43 41 4e 20 6f 70 74 69 6f 6e 20 74 61  X_SCAN option ta
158e0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 69 6e 74  kes a single int
158f0 65 67 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  eger.** argument
15900 20 77 68 69 63 68 20 69 73 20 69 6e 74 65 72 70   which is interp
15910 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65  reted as a boole
15920 61 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65  an in order to e
15930 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65  nable or disable
15940 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 63  .** the use of c
15950 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20  overing indices 
15960 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73  for full table s
15970 63 61 6e 73 20 69 6e 20 74 68 65 20 71 75 65 72  cans in the quer
15980 79 20 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a 2a 20  y optimizer..** 
15990 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74  ^The default set
159a0 74 69 6e 67 20 69 73 20 64 65 74 65 72 6d 69 6e  ting is determin
159b0 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53 51  ed.** by the [SQ
159c0 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52  LITE_ALLOW_COVER
159d0 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20  ING_INDEX_SCAN] 
159e0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
159f0 69 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a  ion, or is "on".
15a00 2a 2a 20 69 66 20 74 68 61 74 20 63 6f 6d 70 69  ** if that compi
15a10 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69  le-time option i
15a20 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68  s omitted..** Th
15a30 65 20 61 62 69 6c 69 74 79 20 74 6f 20 64 69 73  e ability to dis
15a40 61 62 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20  able the use of 
15a50 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73  covering indices
15a60 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20   for full table 
15a70 73 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61  scans.** is beca
15a80 75 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65  use some incorre
15a90 63 74 6c 79 20 63 6f 64 65 64 20 6c 65 67 61 63  ctly coded legac
15aa0 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d  y applications m
15ab0 69 67 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e  ight malfunction
15ac0 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 6f 70 74  .** when the opt
15ad0 69 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e 61  imization is ena
15ae0 62 6c 65 64 2e 20 20 50 72 6f 76 69 64 69 6e 67  bled.  Providing
15af0 20 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 0a   the ability to.
15b00 2a 2a 20 64 69 73 61 62 6c 65 20 74 68 65 20 6f  ** disable the o
15b10 70 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f  ptimization allo
15b20 77 73 20 74 68 65 20 6f 6c 64 65 72 2c 20 62 75  ws the older, bu
15b30 67 67 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  ggy application 
15b40 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20  code to work.** 
15b50 77 69 74 68 6f 75 74 20 63 68 61 6e 67 65 20 65  without change e
15b60 76 65 6e 20 77 69 74 68 20 6e 65 77 65 72 20 76  ven with newer v
15b70 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
15b80 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  e..**.** [[SQLIT
15b90 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d  E_CONFIG_PCACHE]
15ba0 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ] [[SQLITE_CONFI
15bb0 47 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a  G_GETPCACHE]].**
15bc0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
15bd0 49 47 5f 50 43 41 43 48 45 20 61 6e 64 20 53 51  IG_PCACHE and SQ
15be0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
15bf0 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68  CACHE.** <dd> Th
15c00 65 73 65 20 6f 70 74 69 6f 6e 73 20 61 72 65 20  ese options are 
15c10 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f  obsolete and sho
15c20 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20  uld not be used 
15c30 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20  by new code..** 
15c40 54 68 65 79 20 61 72 65 20 72 65 74 61 69 6e 65  They are retaine
15c50 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20  d for backwards 
15c60 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 62 75  compatibility bu
15c70 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73  t are now no-ops
15c80 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
15c90 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
15ca0 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74  _SQLLOG]].** <dt
15cb0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
15cc0 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 69  QLLOG.** <dd>Thi
15cd0 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79  s option is only
15ce0 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 73 71   available if sq
15cf0 6c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  lite is compiled
15d00 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51   with the.** [SQ
15d10 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c  LITE_ENABLE_SQLL
15d20 4f 47 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f  OG] pre-processo
15d30 72 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 2e  r macro defined.
15d40 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
15d50 65 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65  ent should.** be
15d60 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
15d70 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65  function of type
15d80 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73   void(*)(void*,s
15d90 71 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68  qlite3*,const ch
15da0 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68  ar*, int)..** Th
15db0 65 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20  e second should 
15dc0 62 65 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64  be of type (void
15dd0 2a 29 2e 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  *). The callback
15de0 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 74   is invoked by t
15df0 68 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e  he library.** in
15e00 20 74 68 72 65 65 20 73 65 70 61 72 61 74 65 20   three separate 
15e10 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 69  circumstances, i
15e20 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65  dentified by the
15e30 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73   value passed as
15e40 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70   the.** fourth p
15e50 61 72 61 6d 65 74 65 72 2e 20 49 66 20 74 68 65  arameter. If the
15e60 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
15e70 72 20 69 73 20 30 2c 20 74 68 65 6e 20 74 68 65  r is 0, then the
15e80 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
15e90 74 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61  tion.** passed a
15ea0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
15eb0 75 6d 65 6e 74 20 68 61 73 20 6a 75 73 74 20 62  ument has just b
15ec0 65 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65 20  een opened. The 
15ed0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a  third argument.*
15ee0 2a 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 62 75  * points to a bu
15ef0 66 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ffer containing 
15f00 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
15f10 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 69  main database fi
15f20 6c 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f  le. If the.** fo
15f30 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
15f40 73 20 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51  s 1, then the SQ
15f50 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  L statement that
15f60 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
15f70 65 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74  eter.** points t
15f80 6f 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20  o has just been 
15f90 65 78 65 63 75 74 65 64 2e 20 4f 72 2c 20 69 66  executed. Or, if
15fa0 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
15fb0 6d 65 74 65 72 20 69 73 20 32 2c 20 74 68 65 6e  meter is 2, then
15fc0 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74 69  .** the connecti
15fd0 6f 6e 20 62 65 69 6e 67 20 70 61 73 73 65 64 20  on being passed 
15fe0 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
15ff0 72 61 6d 65 74 65 72 20 69 73 20 62 65 69 6e 67  rameter is being
16000 20 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20   closed. The.** 
16010 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
16020 69 73 20 70 61 73 73 65 64 20 4e 55 4c 4c 20 49  is passed NULL I
16030 6e 20 74 68 69 73 20 63 61 73 65 2e 20 20 41 6e  n this case.  An
16040 20 65 78 61 6d 70 6c 65 20 6f 66 20 75 73 69 6e   example of usin
16050 67 20 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 67  g this.** config
16060 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 63  uration option c
16070 61 6e 20 62 65 20 73 65 65 6e 20 69 6e 20 74 68  an be seen in th
16080 65 20 22 74 65 73 74 5f 73 71 6c 6c 6f 67 2e 63  e "test_sqllog.c
16090 22 20 73 6f 75 72 63 65 20 66 69 6c 65 20 69 6e  " source file in
160a0 0a 2a 2a 20 74 68 65 20 63 61 6e 6f 6e 69 63 61  .** the canonica
160b0 6c 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20  l SQLite source 
160c0 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tree.</dd>.**.**
160d0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
160e0 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20  _MMAP_SIZE]].** 
160f0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
16100 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c  G_MMAP_SIZE.** <
16110 64 64 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  dd>^SQLITE_CONFI
16120 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 74 61 6b 65  G_MMAP_SIZE take
16130 73 20 74 77 6f 20 36 34 2d 62 69 74 20 69 6e 74  s two 64-bit int
16140 65 67 65 72 20 28 73 71 6c 69 74 65 33 5f 69 6e  eger (sqlite3_in
16150 74 36 34 29 20 76 61 6c 75 65 73 0a 2a 2a 20 74  t64) values.** t
16160 68 61 74 20 61 72 65 20 74 68 65 20 64 65 66 61  hat are the defa
16170 75 6c 74 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69  ult mmap size li
16180 6d 69 74 20 28 74 68 65 20 64 65 66 61 75 6c 74  mit (the default
16190 20 73 65 74 74 69 6e 67 20 66 6f 72 0a 2a 2a 20   setting for.** 
161a0 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a  [PRAGMA mmap_siz
161b0 65 5d 29 20 61 6e 64 20 74 68 65 20 6d 61 78 69  e]) and the maxi
161c0 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70  mum allowed mmap
161d0 20 73 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20   size limit..** 
161e0 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74  ^The default set
161f0 74 69 6e 67 20 63 61 6e 20 62 65 20 6f 76 65 72  ting can be over
16200 72 69 64 64 65 6e 20 62 79 20 65 61 63 68 20 64  ridden by each d
16210 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
16220 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 65 69 74 68  on using.** eith
16230 65 72 20 74 68 65 20 5b 50 52 41 47 4d 41 20 6d  er the [PRAGMA m
16240 6d 61 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e  map_size] comman
16250 64 2c 20 6f 72 20 62 79 20 75 73 69 6e 67 20 74  d, or by using t
16260 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43  he.** [SQLITE_FC
16270 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66  NTL_MMAP_SIZE] f
16280 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e 28  ile control.  ^(
16290 54 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f  The maximum allo
162a0 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a  wed mmap size.**
162b0 20 77 69 6c 6c 20 62 65 20 73 69 6c 65 6e 74 6c   will be silentl
162c0 79 20 74 72 75 6e 63 61 74 65 64 20 69 66 20 6e  y truncated if n
162d0 65 63 65 73 73 61 72 79 20 73 6f 20 74 68 61 74  ecessary so that
162e0 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 65 78 63   it does not exc
162f0 65 65 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69  eed the.** compi
16300 6c 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20  le-time maximum 
16310 6d 6d 61 70 20 73 69 7a 65 20 73 65 74 20 62 79  mmap size set by
16320 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
16330 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63  MAX_MMAP_SIZE] c
16340 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
16350 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74  on.)^.** ^If eit
16360 68 65 72 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  her argument to 
16370 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e  this option is n
16380 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68  egative, then th
16390 61 74 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a  at argument is.*
163a0 2a 20 63 68 61 6e 67 65 64 20 74 6f 20 69 74 73  * changed to its
163b0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65   compile-time de
163c0 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  fault..**.** [[S
163d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e  QLITE_CONFIG_WIN
163e0 33 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a  32_HEAPSIZE]].**
163f0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
16400 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a  IG_WIN32_HEAPSIZ
16410 45 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51  E.** <dd>^The SQ
16420 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33  LITE_CONFIG_WIN3
16430 32 5f 48 45 41 50 53 49 5a 45 20 6f 70 74 69 6f  2_HEAPSIZE optio
16440 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61  n is only availa
16450 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 73  ble if SQLite is
16460 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72  .** compiled for
16470 20 57 69 6e 64 6f 77 73 20 77 69 74 68 20 74 68   Windows with th
16480 65 20 5b 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f  e [SQLITE_WIN32_
16490 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d 70 72 6f 63  MALLOC] pre-proc
164a0 65 73 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a 20 64  essor macro.** d
164b0 65 66 69 6e 65 64 2e 20 5e 53 51 4c 49 54 45 5f  efined. ^SQLITE_
164c0 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41  CONFIG_WIN32_HEA
164d0 50 53 49 5a 45 20 74 61 6b 65 73 20 61 20 33 32  PSIZE takes a 32
164e0 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e  -bit unsigned in
164f0 74 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a 20 74  teger value.** t
16500 68 61 74 20 73 70 65 63 69 66 69 65 73 20 74 68  hat specifies th
16510 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f  e maximum size o
16520 66 20 74 68 65 20 63 72 65 61 74 65 64 20 68 65  f the created he
16530 61 70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  ap..**.** [[SQLI
16540 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
16550 5f 48 44 52 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e  _HDRSZ]].** <dt>
16560 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
16570 41 43 48 45 5f 48 44 52 53 5a 0a 2a 2a 20 3c 64  ACHE_HDRSZ.** <d
16580 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  d>^The SQLITE_CO
16590 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53  NFIG_PCACHE_HDRS
165a0 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  Z option takes a
165b0 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65   single paramete
165c0 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20  r which.** is a 
165d0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
165e0 74 65 67 65 72 20 61 6e 64 20 77 72 69 74 65 73  teger and writes
165f0 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67   into that integ
16600 65 72 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  er the number of
16610 20 65 78 74 72 61 0a 2a 2a 20 62 79 74 65 73 20   extra.** bytes 
16620 70 65 72 20 70 61 67 65 20 72 65 71 75 69 72 65  per page require
16630 64 20 66 6f 72 20 65 61 63 68 20 70 61 67 65 20  d for each page 
16640 69 6e 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  in [SQLITE_CONFI
16650 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a  G_PAGECACHE]..**
16660 20 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 65   The amount of e
16670 78 74 72 61 20 73 70 61 63 65 20 72 65 71 75 69  xtra space requi
16680 72 65 64 20 63 61 6e 20 63 68 61 6e 67 65 20 64  red can change d
16690 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
166a0 63 6f 6d 70 69 6c 65 72 2c 0a 2a 2a 20 74 61 72  compiler,.** tar
166b0 67 65 74 20 70 6c 61 74 66 6f 72 6d 2c 20 61 6e  get platform, an
166c0 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  d SQLite version
166d0 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
166e0 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 5d 5d 0a  _CONFIG_PMASZ]].
166f0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
16700 4e 46 49 47 5f 50 4d 41 53 5a 0a 2a 2a 20 3c 64  NFIG_PMASZ.** <d
16710 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  d>^The SQLITE_CO
16720 4e 46 49 47 5f 50 4d 41 53 5a 20 6f 70 74 69 6f  NFIG_PMASZ optio
16730 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
16740 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68   parameter which
16750 0a 2a 2a 20 69 73 20 61 6e 20 75 6e 73 69 67 6e  .** is an unsign
16760 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 73  ed integer and s
16770 65 74 73 20 74 68 65 20 22 4d 69 6e 69 6d 75 6d  ets the "Minimum
16780 20 50 4d 41 20 53 69 7a 65 22 20 66 6f 72 20 74   PMA Size" for t
16790 68 65 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64  he multithreaded
167a0 0a 2a 2a 20 73 6f 72 74 65 72 20 74 6f 20 74 68  .** sorter to th
167b0 61 74 20 69 6e 74 65 67 65 72 2e 20 20 54 68 65  at integer.  The
167c0 20 64 65 66 61 75 6c 74 20 6d 69 6e 69 6d 75 6d   default minimum
167d0 20 50 4d 41 20 53 69 7a 65 20 69 73 20 73 65 74   PMA Size is set
167e0 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49   by the.** [SQLI
167f0 54 45 5f 53 4f 52 54 45 52 5f 50 4d 41 53 5a 5d  TE_SORTER_PMASZ]
16800 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
16810 74 69 6f 6e 2e 20 20 4e 65 77 20 74 68 72 65 61  tion.  New threa
16820 64 73 20 61 72 65 20 6c 61 75 6e 63 68 65 64 0a  ds are launched.
16830 2a 2a 20 74 6f 20 68 65 6c 70 20 77 69 74 68 20  ** to help with 
16840 73 6f 72 74 20 6f 70 65 72 61 74 69 6f 6e 73 20  sort operations 
16850 77 68 65 6e 20 6d 75 6c 74 69 74 68 72 65 61 64  when multithread
16860 65 64 20 73 6f 72 74 69 6e 67 0a 2a 2a 20 69 73  ed sorting.** is
16870 20 65 6e 61 62 6c 65 64 20 28 75 73 69 6e 67 20   enabled (using 
16880 74 68 65 20 5b 50 52 41 47 4d 41 20 74 68 72 65  the [PRAGMA thre
16890 61 64 73 5d 20 63 6f 6d 6d 61 6e 64 29 20 61 6e  ads] command) an
168a0 64 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20  d the amount of 
168b0 63 6f 6e 74 65 6e 74 0a 2a 2a 20 74 6f 20 62 65  content.** to be
168c0 20 73 6f 72 74 65 64 20 65 78 63 65 65 64 73 20   sorted exceeds 
168d0 74 68 65 20 70 61 67 65 20 73 69 7a 65 20 74 69  the page size ti
168e0 6d 65 73 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20  mes the minimum 
168f0 6f 66 20 74 68 65 0a 2a 2a 20 5b 50 52 41 47 4d  of the.** [PRAGM
16900 41 20 63 61 63 68 65 5f 73 69 7a 65 5d 20 73 65  A cache_size] se
16910 74 74 69 6e 67 20 61 6e 64 20 74 68 69 73 20 76  tting and this v
16920 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  alue..**.** [[SQ
16930 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54  LITE_CONFIG_STMT
16940 4a 52 4e 4c 5f 53 50 49 4c 4c 5d 5d 0a 2a 2a 20  JRNL_SPILL]].** 
16950 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
16960 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c  G_STMTJRNL_SPILL
16970 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c  .** <dd>^The SQL
16980 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a  ITE_CONFIG_STMTJ
16990 52 4e 4c 5f 53 50 49 4c 4c 20 6f 70 74 69 6f 6e  RNL_SPILL option
169a0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
169b0 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a  parameter which.
169c0 2a 2a 20 62 65 63 6f 6d 65 73 20 74 68 65 20 5b  ** becomes the [
169d0 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61  statement journa
169e0 6c 5d 20 73 70 69 6c 6c 2d 74 6f 2d 64 69 73 6b  l] spill-to-disk
169f0 20 74 68 72 65 73 68 6f 6c 64 2e 20 20 0a 2a 2a   threshold.  .**
16a00 20 5b 53 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72   [Statement jour
16a10 6e 61 6c 73 5d 20 61 72 65 20 68 65 6c 64 20 69  nals] are held i
16a20 6e 20 6d 65 6d 6f 72 79 20 75 6e 74 69 6c 20 74  n memory until t
16a30 68 65 69 72 20 73 69 7a 65 20 28 69 6e 20 62 79  heir size (in by
16a40 74 65 73 29 0a 2a 2a 20 65 78 63 65 65 64 73 20  tes).** exceeds 
16a50 74 68 69 73 20 74 68 72 65 73 68 6f 6c 64 2c 20  this threshold, 
16a60 61 74 20 77 68 69 63 68 20 70 6f 69 6e 74 20 74  at which point t
16a70 68 65 79 20 61 72 65 20 77 72 69 74 74 65 6e 20  hey are written 
16a80 74 6f 20 64 69 73 6b 2e 0a 2a 2a 20 4f 72 20 69  to disk..** Or i
16a90 66 20 74 68 65 20 74 68 72 65 73 68 6f 6c 64 20  f the threshold 
16aa0 69 73 20 2d 31 2c 20 73 74 61 74 65 6d 65 6e 74  is -1, statement
16ab0 20 6a 6f 75 72 6e 61 6c 73 20 61 72 65 20 61 6c   journals are al
16ac0 77 61 79 73 20 68 65 6c 64 0a 2a 2a 20 65 78 63  ways held.** exc
16ad0 6c 75 73 69 76 65 6c 79 20 69 6e 20 6d 65 6d 6f  lusively in memo
16ae0 72 79 2e 0a 2a 2a 20 53 69 6e 63 65 20 6d 61 6e  ry..** Since man
16af0 79 20 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72  y statement jour
16b00 6e 61 6c 73 20 6e 65 76 65 72 20 62 65 63 6f 6d  nals never becom
16b10 65 20 6c 61 72 67 65 2c 20 73 65 74 74 69 6e 67  e large, setting
16b20 20 74 68 65 20 73 70 69 6c 6c 0a 2a 2a 20 74 68   the spill.** th
16b30 72 65 73 68 6f 6c 64 20 74 6f 20 61 20 76 61 6c  reshold to a val
16b40 75 65 20 73 75 63 68 20 61 73 20 36 34 4b 69 42  ue such as 64KiB
16b50 20 63 61 6e 20 67 72 65 61 74 6c 79 20 72 65 64   can greatly red
16b60 75 63 65 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f  uce the amount o
16b70 66 0a 2a 2a 20 49 2f 4f 20 72 65 71 75 69 72 65  f.** I/O require
16b80 64 20 74 6f 20 73 75 70 70 6f 72 74 20 73 74 61  d to support sta
16b90 74 65 6d 65 6e 74 20 72 6f 6c 6c 62 61 63 6b 2e  tement rollback.
16ba0 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20  .** The default 
16bb0 76 61 6c 75 65 20 66 6f 72 20 74 68 69 73 20 73  value for this s
16bc0 65 74 74 69 6e 67 20 69 73 20 63 6f 6e 74 72 6f  etting is contro
16bd0 6c 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b  lled by the.** [
16be0 53 51 4c 49 54 45 5f 53 54 4d 54 4a 52 4e 4c 5f  SQLITE_STMTJRNL_
16bf0 53 50 49 4c 4c 5d 20 63 6f 6d 70 69 6c 65 2d 74  SPILL] compile-t
16c00 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 3c  ime option..** <
16c10 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
16c20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
16c30 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f  NGLETHREAD  1  /
16c40 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
16c50 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
16c60 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 20  ULTITHREAD   2  
16c70 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
16c80 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16c90 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20  SERIALIZED    3 
16ca0 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
16cb0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
16cc0 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34  _MALLOC        4
16cd0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d    /* sqlite3_mem
16ce0 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
16cf0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16d00 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20  IG_GETMALLOC    
16d10 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d   5  /* sqlite3_m
16d20 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  em_methods* */.#
16d30 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
16d40 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 20  NFIG_SCRATCH    
16d50 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20     6  /* void*, 
16d60 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f  int sz, int N */
16d70 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16d80 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
16d90 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a       7  /* void*
16da0 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20  , int sz, int N 
16db0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16dc0 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20  E_CONFIG_HEAP   
16dd0 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69         8  /* voi
16de0 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69  d*, int nByte, i
16df0 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e  nt min */.#defin
16e00 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16e10 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 39 20  MEMSTATUS     9 
16e20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23   /* boolean */.#
16e30 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
16e40 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20  NFIG_MUTEX      
16e50 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33    10  /* sqlite3
16e60 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20  _mutex_methods* 
16e70 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16e80 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
16e90 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c  X     11  /* sql
16ea0 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
16eb0 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f  ds* */./* previo
16ec0 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46  usly SQLITE_CONF
16ed0 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32  IG_CHUNKALLOC 12
16ee0 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e   which is now un
16ef0 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e  used. */ .#defin
16f00 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16f10 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20  LOOKASIDE    13 
16f20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23   /* int int */.#
16f30 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
16f40 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20 20 20  NFIG_PCACHE     
16f50 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a    14  /* no-op *
16f60 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16f70 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
16f80 45 20 20 20 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f  E    15  /* no-o
16f90 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  p */.#define SQL
16fa0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20  ITE_CONFIG_LOG  
16fb0 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a 20 78          16  /* x
16fc0 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23  Func, void* */.#
16fd0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
16fe0 4e 46 49 47 5f 55 52 49 20 20 20 20 20 20 20 20  NFIG_URI        
16ff0 20 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a    17  /* int */.
17000 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
17010 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 20 20  ONFIG_PCACHE2   
17020 20 20 20 31 38 20 20 2f 2a 20 73 71 6c 69 74 65     18  /* sqlite
17030 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
17040 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  2* */.#define SQ
17050 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
17060 43 41 43 48 45 32 20 20 20 31 39 20 20 2f 2a 20  CACHE2   19  /* 
17070 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
17080 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66  ethods2* */.#def
17090 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
170a0 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58  G_COVERING_INDEX
170b0 5f 53 43 41 4e 20 32 30 20 20 2f 2a 20 69 6e 74  _SCAN 20  /* int
170c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
170d0 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47  TE_CONFIG_SQLLOG
170e0 20 20 20 20 20 20 20 32 31 20 20 2f 2a 20 78 53         21  /* xS
170f0 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20 2a 2f 0a  qllog, void* */.
17100 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
17110 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20  ONFIG_MMAP_SIZE 
17120 20 20 20 32 32 20 20 2f 2a 20 73 71 6c 69 74 65     22  /* sqlite
17130 33 5f 69 6e 74 36 34 2c 20 73 71 6c 69 74 65 33  3_int64, sqlite3
17140 5f 69 6e 74 36 34 20 2a 2f 0a 23 64 65 66 69 6e  _int64 */.#defin
17150 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
17160 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 20  WIN32_HEAPSIZE  
17170 20 20 20 20 32 33 20 20 2f 2a 20 69 6e 74 20 6e      23  /* int n
17180 42 79 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  Byte */.#define 
17190 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
171a0 41 43 48 45 5f 48 44 52 53 5a 20 20 20 20 20 20  ACHE_HDRSZ      
171b0 20 20 32 34 20 20 2f 2a 20 69 6e 74 20 2a 70 73    24  /* int *ps
171c0 7a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  z */.#define SQL
171d0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a  ITE_CONFIG_PMASZ
171e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
171f0 35 20 20 2f 2a 20 75 6e 73 69 67 6e 65 64 20 69  5  /* unsigned i
17200 6e 74 20 73 7a 50 6d 61 20 2a 2f 0a 23 64 65 66  nt szPma */.#def
17210 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
17220 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c  G_STMTJRNL_SPILL
17230 20 20 20 20 20 20 32 36 20 20 2f 2a 20 69 6e 74        26  /* int
17240 20 6e 42 79 74 65 20 2a 2f 0a 0a 2f 2a 0a 2a 2a   nByte */../*.**
17250 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62   CAPI3REF: Datab
17260 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43  ase Connection C
17270 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74  onfiguration Opt
17280 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
17290 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74   constants are t
172a0 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74  he available int
172b0 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69  eger configurati
172c0 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a  on options that.
172d0 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64  ** can be passed
172e0 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   as the second a
172f0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b  rgument to the [
17300 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
17310 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  g()] interface..
17320 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67  **.** New config
17330 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
17340 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
17350 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
17360 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78  of SQLite..** Ex
17370 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61  isting configura
17380 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67  tion options mig
17390 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75  ht be discontinu
173a0 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  ed.  Application
173b0 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63  s.** should chec
173c0 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64  k the return cod
173d0 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  e from [sqlite3_
173e0 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20  db_config()] to 
173f0 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a  make sure that.*
17400 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65  * the call worke
17410 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  d.  ^The [sqlite
17420 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69  3_db_config()] i
17430 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65  nterface will re
17440 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65  turn a.** non-ze
17450 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ro [error code] 
17460 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65  if a discontinue
17470 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64  d or unsupported
17480 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
17490 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f  ption.** is invo
174a0 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  ked..**.** <dl>.
174b0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
174c0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
174d0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
174e0 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
174f0 20 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61   three additiona
17500 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  l arguments that
17510 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a   determine the .
17520 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  ** [lookaside me
17530 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20  mory allocator] 
17540 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f  configuration fo
17550 72 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  r the [database 
17560 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20  connection]..** 
17570 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
17580 65 6e 74 20 28 74 68 65 20 74 68 69 72 64 20 70  ent (the third p
17590 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
175a0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
175b0 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65  ] is a.** pointe
175c0 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75  r to a memory bu
175d0 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72 20  ffer to use for 
175e0 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
175f0 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  ..** ^The first 
17600 61 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20 74  argument after t
17610 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  he SQLITE_DBCONF
17620 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72  IG_LOOKASIDE ver
17630 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c  b.** may be NULL
17640 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 53   in which case S
17650 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63  QLite will alloc
17660 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61  ate the.** looka
17670 73 69 64 65 20 62 75 66 66 65 72 20 69 74 73 65  side buffer itse
17680 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  lf using [sqlite
17690 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68  3_malloc()]. ^Th
176a0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
176b0 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65  t is the.** size
176c0 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69   of each lookasi
176d0 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e 20  de buffer slot. 
176e0 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75   ^The third argu
176f0 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62  ment is the numb
17700 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20  er of.** slots. 
17710 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   The size of the
17720 20 62 75 66 66 65 72 20 69 6e 20 74 68 65 20 66   buffer in the f
17730 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75  irst argument mu
17740 73 74 20 62 65 20 67 72 65 61 74 65 72 20 74 68  st be greater th
17750 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74  an.** or equal t
17760 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66  o the product of
17770 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20   the second and 
17780 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e  third arguments.
17790 20 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a 20    The buffer.** 
177a0 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20  must be aligned 
177b0 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75  to an 8-byte bou
177c0 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65 20  ndary.  ^If the 
177d0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
177e0 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43  to.** SQLITE_DBC
177f0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
17800 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c  is not a multipl
17810 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69 6e  e of 8, it is in
17820 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e  ternally.** roun
17830 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65 20  ded down to the 
17840 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75 6c  next smaller mul
17850 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28 54  tiple of 8.  ^(T
17860 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  he lookaside mem
17870 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  ory.** configura
17880 74 69 6f 6e 20 66 6f 72 20 61 20 64 61 74 61 62  tion for a datab
17890 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63  ase connection c
178a0 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e 67  an only be chang
178b0 65 64 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a 20  ed when that.** 
178c0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e 6f  connection is no
178d0 74 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69 6e  t currently usin
178e0 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  g lookaside memo
178f0 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72 20  ry, or in other 
17900 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74 68  words.** when th
17910 65 20 22 63 75 72 72 65 6e 74 20 76 61 6c 75 65  e "current value
17920 22 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  " returned by.**
17930 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 61   [sqlite3_db_sta
17940 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 43  tus](D,[SQLITE_C
17950 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d  ONFIG_LOOKASIDE]
17960 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a 2a  ,...) is zero..*
17970 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f  * Any attempt to
17980 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b   change the look
17990 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f 6e  aside memory con
179a0 66 69 67 75 72 61 74 69 6f 6e 20 77 68 65 6e 20  figuration when 
179b0 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65 6d  lookaside.** mem
179c0 6f 72 79 20 69 73 20 69 6e 20 75 73 65 20 6c 65  ory is in use le
179d0 61 76 65 73 20 74 68 65 20 63 6f 6e 66 69 67 75  aves the configu
179e0 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65 64  ration unchanged
179f0 20 61 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a 2a   and returns .**
17a00 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 29   [SQLITE_BUSY].)
17a10 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  ^</dd>.**.** <dt
17a20 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
17a30 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64 74  _ENABLE_FKEY</dt
17a40 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
17a50 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  option is used t
17a60 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61  o enable or disa
17a70 62 6c 65 20 74 68 65 20 65 6e 66 6f 72 63 65 6d  ble the enforcem
17a80 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69  ent of.** [forei
17a90 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e  gn key constrain
17aa0 74 73 5d 2e 20 20 54 68 65 72 65 20 73 68 6f 75  ts].  There shou
17ab0 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69  ld be two additi
17ac0 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a  onal arguments..
17ad0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
17ae0 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65  ument is an inte
17af0 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74  ger which is 0 t
17b00 6f 20 64 69 73 61 62 6c 65 20 46 4b 20 65 6e 66  o disable FK enf
17b10 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73  orcement,.** pos
17b20 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20  itive to enable 
17b30 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f  FK enforcement o
17b40 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65  r negative to le
17b50 61 76 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  ave FK enforceme
17b60 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e  nt.** unchanged.
17b70 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72    The second par
17b80 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
17b90 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
17ba0 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20  r into which.** 
17bb0 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20  is written 0 or 
17bc0 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  1 to indicate wh
17bd0 65 74 68 65 72 20 46 4b 20 65 6e 66 6f 72 63 65  ether FK enforce
17be0 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f 72 20 6f  ment is off or o
17bf0 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74  n.** following t
17c00 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73  his call.  The s
17c10 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
17c20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f  may be a NULL po
17c30 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69  inter, in.** whi
17c40 63 68 20 63 61 73 65 20 74 68 65 20 46 4b 20 65  ch case the FK e
17c50 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65 74 74 69  nforcement setti
17c60 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74  ng is not report
17c70 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a  ed back. </dd>.*
17c80 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
17c90 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
17ca0 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20  TRIGGER</dt>.** 
17cb0 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
17cc0 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61  n is used to ena
17cd0 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 5b  ble or disable [
17ce0 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c  CREATE TRIGGER |
17cf0 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 54   triggers]..** T
17d00 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74  here should be t
17d10 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72  wo additional ar
17d20 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20  guments..** The 
17d30 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
17d40 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
17d50 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  ch is 0 to disab
17d60 6c 65 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a 20  le triggers,.** 
17d70 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62  positive to enab
17d80 6c 65 20 74 72 69 67 67 65 72 73 20 6f 72 20 6e  le triggers or n
17d90 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65  egative to leave
17da0 20 74 68 65 20 73 65 74 74 69 6e 67 20 75 6e 63   the setting unc
17db0 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73  hanged..** The s
17dc0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
17dd0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
17de0 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20  an integer into 
17df0 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74  which.** is writ
17e00 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e  ten 0 or 1 to in
17e10 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 74  dicate whether t
17e20 72 69 67 67 65 72 73 20 61 72 65 20 64 69 73 61  riggers are disa
17e30 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a  bled or enabled.
17e40 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69  ** following thi
17e50 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63  s call.  The sec
17e60 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61  ond parameter ma
17e70 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  y be a NULL poin
17e80 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68  ter, in.** which
17e90 20 63 61 73 65 20 74 68 65 20 74 72 69 67 67 65   case the trigge
17ea0 72 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74  r setting is not
17eb0 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20   reported back. 
17ec0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
17ed0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
17ee0 45 4e 41 42 4c 45 5f 46 54 53 33 5f 54 4f 4b 45  ENABLE_FTS3_TOKE
17ef0 4e 49 5a 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  NIZER</dt>.** <d
17f00 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
17f10 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c  is used to enabl
17f20 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65  e or disable the
17f30 20 74 77 6f 2d 61 72 67 75 6d 65 6e 74 0a 2a 2a   two-argument.**
17f40 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20   version of the 
17f50 5b 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28  [fts3_tokenizer(
17f60 29 5d 20 66 75 6e 63 74 69 6f 6e 20 77 68 69 63  )] function whic
17f70 68 20 69 73 20 70 61 72 74 20 6f 66 20 74 68 65  h is part of the
17f80 0a 2a 2a 20 5b 46 54 53 33 5d 20 66 75 6c 6c 2d  .** [FTS3] full-
17f90 74 65 78 74 20 73 65 61 72 63 68 20 65 6e 67 69  text search engi
17fa0 6e 65 20 65 78 74 65 6e 73 69 6f 6e 2e 0a 2a 2a  ne extension..**
17fb0 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65   There should be
17fc0 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
17fd0 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68  arguments..** Th
17fe0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
17ff0 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77   is an integer w
18000 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73  hich is 0 to dis
18010 61 62 6c 65 20 66 74 73 33 5f 74 6f 6b 65 6e 69  able fts3_tokeni
18020 7a 65 72 28 29 20 6f 72 0a 2a 2a 20 70 6f 73 69  zer() or.** posi
18030 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 66  tive to enable f
18040 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28 29 20  ts3_tokenizer() 
18050 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c  or negative to l
18060 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e 67  eave the setting
18070 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a  .** unchanged..*
18080 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * The second par
18090 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
180a0 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
180b0 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20  r into which.** 
180c0 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20  is written 0 or 
180d0 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  1 to indicate wh
180e0 65 74 68 65 72 20 66 74 73 33 5f 74 6f 6b 65 6e  ether fts3_token
180f0 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65 64  izer is disabled
18100 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66   or enabled.** f
18110 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61  ollowing this ca
18120 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ll.  The second 
18130 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
18140 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
18150 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73   in.** which cas
18160 65 20 74 68 65 20 6e 65 77 20 73 65 74 74 69 6e  e the new settin
18170 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65  g is not reporte
18180 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a  d back. </dd>.**
18190 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
181a0 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 4c  BCONFIG_ENABLE_L
181b0 4f 41 44 5f 45 58 54 45 4e 53 49 4f 4e 3c 2f 64  OAD_EXTENSION</d
181c0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
181d0 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
181e0 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73  to enable or dis
181f0 61 62 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65  able the [sqlite
18200 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e  3_load_extension
18210 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
18220 20 69 6e 64 65 70 65 6e 64 65 6e 74 6c 79 20 6f   independently o
18230 66 20 74 68 65 20 5b 6c 6f 61 64 5f 65 78 74 65  f the [load_exte
18240 6e 73 69 6f 6e 28 29 5d 20 53 51 4c 20 66 75 6e  nsion()] SQL fun
18250 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20 5b 73  ction..** The [s
18260 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f  qlite3_enable_lo
18270 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20  ad_extension()] 
18280 41 50 49 20 65 6e 61 62 6c 65 73 20 6f 72 20 64  API enables or d
18290 69 73 61 62 6c 65 73 20 62 6f 74 68 20 74 68 65  isables both the
182a0 0a 2a 2a 20 43 2d 41 50 49 20 5b 73 71 6c 69 74  .** C-API [sqlit
182b0 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  e3_load_extensio
182c0 6e 28 29 5d 20 61 6e 64 20 74 68 65 20 53 51 4c  n()] and the SQL
182d0 20 66 75 6e 63 74 69 6f 6e 20 5b 6c 6f 61 64 5f   function [load_
182e0 65 78 74 65 6e 73 69 6f 6e 28 29 5d 2e 0a 2a 2a  extension()]..**
182f0 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65   There should be
18300 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
18310 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 57 68  arguments..** Wh
18320 65 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  en the first arg
18330 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 69 6e  ument to this in
18340 74 65 72 66 61 63 65 20 69 73 20 31 2c 20 74 68  terface is 1, th
18350 65 6e 20 6f 6e 6c 79 20 74 68 65 20 43 2d 41 50  en only the C-AP
18360 49 20 69 73 0a 2a 2a 20 65 6e 61 62 6c 65 64 20  I is.** enabled 
18370 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63  and the SQL func
18380 74 69 6f 6e 20 72 65 6d 61 69 6e 73 20 64 69 73  tion remains dis
18390 61 62 6c 65 64 2e 20 20 49 66 20 74 68 65 20 66  abled.  If the f
183a0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
183b0 0a 2a 2a 20 74 68 69 73 20 69 6e 74 65 72 66 61  .** this interfa
183c0 63 65 20 69 73 20 30 2c 20 74 68 65 6e 20 62 6f  ce is 0, then bo
183d0 74 68 20 74 68 65 20 43 2d 41 50 49 20 61 6e 64  th the C-API and
183e0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
183f0 6e 20 61 72 65 20 64 69 73 61 62 6c 65 64 2e 0a  n are disabled..
18400 2a 2a 20 49 66 20 74 68 65 20 66 69 72 73 74 20  ** If the first 
18410 61 72 67 75 6d 65 6e 74 20 69 73 20 2d 31 2c 20  argument is -1, 
18420 74 68 65 6e 20 6e 6f 20 63 68 61 6e 67 65 73 20  then no changes 
18430 61 72 65 20 6d 61 64 65 20 74 6f 20 73 74 61 74  are made to stat
18440 65 20 6f 66 20 65 69 74 68 65 72 20 74 68 65 0a  e of either the.
18450 2a 2a 20 43 2d 41 50 49 20 6f 72 20 74 68 65 20  ** C-API or the 
18460 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  SQL function..**
18470 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
18480 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74  meter is a point
18490 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
184a0 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69   into which.** i
184b0 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31  s written 0 or 1
184c0 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65   to indicate whe
184d0 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 6c 6f  ther [sqlite3_lo
184e0 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20  ad_extension()] 
184f0 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 73 20  interface.** is 
18500 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62  disabled or enab
18510 6c 65 64 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  led following th
18520 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65  is call.  The se
18530 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d  cond parameter m
18540 61 79 0a 2a 2a 20 62 65 20 61 20 4e 55 4c 4c 20  ay.** be a NULL 
18550 70 6f 69 6e 74 65 72 2c 20 69 6e 20 77 68 69 63  pointer, in whic
18560 68 20 63 61 73 65 20 74 68 65 20 6e 65 77 20 73  h case the new s
18570 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65  etting is not re
18580 70 6f 72 74 65 64 20 62 61 63 6b 2e 0a 2a 2a 20  ported back..** 
18590 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
185a0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
185b0 4d 41 49 4e 44 42 4e 41 4d 45 3c 2f 64 74 3e 0a  MAINDBNAME</dt>.
185c0 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
185d0 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
185e0 63 68 61 6e 67 65 20 74 68 65 20 6e 61 6d 65 20  change the name 
185f0 6f 66 20 74 68 65 20 22 6d 61 69 6e 22 20 64 61  of the "main" da
18600 74 61 62 61 73 65 0a 2a 2a 20 73 63 68 65 6d 61  tabase.** schema
18610 2e 20 20 5e 54 68 65 20 73 6f 6c 65 20 61 72 67  .  ^The sole arg
18620 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
18630 65 72 20 74 6f 20 61 20 63 6f 6e 73 74 61 6e 74  er to a constant
18640 20 55 54 46 38 20 73 74 72 69 6e 67 0a 2a 2a 20   UTF8 string.** 
18650 77 68 69 63 68 20 77 69 6c 6c 20 62 65 63 6f 6d  which will becom
18660 65 20 74 68 65 20 6e 65 77 20 73 63 68 65 6d 61  e the new schema
18670 20 6e 61 6d 65 20 69 6e 20 70 6c 61 63 65 20 6f   name in place o
18680 66 20 22 6d 61 69 6e 22 2e 20 20 5e 53 51 4c 69  f "main".  ^SQLi
18690 74 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6d  te.** does not m
186a0 61 6b 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68  ake a copy of th
186b0 65 20 6e 65 77 20 6d 61 69 6e 20 73 63 68 65 6d  e new main schem
186c0 61 20 6e 61 6d 65 20 73 74 72 69 6e 67 2c 20 73  a name string, s
186d0 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
186e0 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e 73 75 72 65  n.** must ensure
186f0 20 74 68 61 74 20 74 68 65 20 61 72 67 75 6d 65   that the argume
18700 6e 74 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74  nt passed into t
18710 68 69 73 20 44 42 43 4f 4e 46 49 47 20 6f 70 74  his DBCONFIG opt
18720 69 6f 6e 20 69 73 20 75 6e 63 68 61 6e 67 65 64  ion is unchanged
18730 0a 2a 2a 20 75 6e 74 69 6c 20 61 66 74 65 72 20  .** until after 
18740 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
18750 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 0a  nection closes..
18760 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </dd>.**.** <
18770 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
18780 49 47 5f 4e 4f 5f 43 4b 50 54 5f 4f 4e 5f 43 4c  IG_NO_CKPT_ON_CL
18790 4f 53 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  OSE</dt>.** <dd>
187a0 20 55 73 75 61 6c 6c 79 2c 20 77 68 65 6e 20 61   Usually, when a
187b0 20 64 61 74 61 62 61 73 65 20 69 6e 20 77 61 6c   database in wal
187c0 20 6d 6f 64 65 20 69 73 20 63 6c 6f 73 65 64 20   mode is closed 
187d0 6f 72 20 64 65 74 61 63 68 65 64 20 66 72 6f 6d  or detached from
187e0 20 61 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 20   a .** database 
187f0 68 61 6e 64 6c 65 2c 20 53 51 4c 69 74 65 20 63  handle, SQLite c
18800 68 65 63 6b 73 20 69 66 20 74 68 69 73 20 77 69  hecks if this wi
18810 6c 6c 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65  ll mean that the
18820 72 65 20 61 72 65 20 6e 6f 77 20 6e 6f 20 0a 2a  re are now no .*
18830 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 61 74  * connections at
18840 20 61 6c 6c 20 74 6f 20 74 68 65 20 64 61 74 61   all to the data
18850 62 61 73 65 2e 20 49 66 20 73 6f 2c 20 69 74 20  base. If so, it 
18860 70 65 72 66 6f 72 6d 73 20 61 20 63 68 65 63 6b  performs a check
18870 70 6f 69 6e 74 20 0a 2a 2a 20 6f 70 65 72 61 74  point .** operat
18880 69 6f 6e 20 62 65 66 6f 72 65 20 63 6c 6f 73 69  ion before closi
18890 6e 67 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  ng the connectio
188a0 6e 2e 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 6d  n. This option m
188b0 61 79 20 62 65 20 75 73 65 64 20 74 6f 0a 2a 2a  ay be used to.**
188c0 20 6f 76 65 72 72 69 64 65 20 74 68 69 73 20 62   override this b
188d0 65 68 61 76 69 6f 75 72 2e 20 54 68 65 20 66 69  ehaviour. The fi
188e0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 70 61  rst parameter pa
188f0 73 73 65 64 20 74 6f 20 74 68 69 73 20 6f 70 65  ssed to this ope
18900 72 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 61 6e 20  ration.** is an 
18910 69 6e 74 65 67 65 72 20 2d 20 6e 6f 6e 2d 7a 65  integer - non-ze
18920 72 6f 20 74 6f 20 64 69 73 61 62 6c 65 20 63 68  ro to disable ch
18930 65 63 6b 70 6f 69 6e 74 73 2d 6f 6e 2d 63 6c 6f  eckpoints-on-clo
18940 73 65 2c 20 6f 72 20 7a 65 72 6f 20 28 74 68 65  se, or zero (the
18950 0a 2a 2a 20 64 65 66 61 75 6c 74 29 20 74 6f 20  .** default) to 
18960 65 6e 61 62 6c 65 20 74 68 65 6d 2e 20 54 68 65  enable them. The
18970 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
18980 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  r is a pointer t
18990 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20  o an integer.** 
189a0 69 6e 74 6f 20 77 68 69 63 68 20 69 73 20 77 72  into which is wr
189b0 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20  itten 0 or 1 to 
189c0 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72  indicate whether
189d0 20 63 68 65 63 6b 70 6f 69 6e 74 73 2d 6f 6e 2d   checkpoints-on-
189e0 63 6c 6f 73 65 0a 2a 2a 20 68 61 76 65 20 62 65  close.** have be
189f0 65 6e 20 64 69 73 61 62 6c 65 64 20 2d 20 30 20  en disabled - 0 
18a00 69 66 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20  if they are not 
18a10 64 69 73 61 62 6c 65 64 2c 20 31 20 69 66 20 74  disabled, 1 if t
18a20 68 65 79 20 61 72 65 2e 0a 2a 2a 20 3c 2f 64 64  hey are..** </dd
18a30 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
18a40 54 45 5f 44 42 43 4f 4e 46 49 47 5f 46 55 4c 4c  TE_DBCONFIG_FULL
18a50 5f 45 51 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  _EQP</dt>.** <dd
18a60 3e 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68  > By default, th
18a70 65 20 6f 75 74 70 75 74 20 6f 66 20 45 58 50 4c  e output of EXPL
18a80 41 49 4e 20 51 55 45 52 59 20 50 4c 41 4e 20 63  AIN QUERY PLAN c
18a90 6f 6d 6d 61 6e 64 73 20 64 6f 65 73 20 6e 6f 74  ommands does not
18aa0 20 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 6f 75 74   .** include out
18ab0 70 75 74 20 66 6f 72 20 61 6e 79 20 6f 70 65 72  put for any oper
18ac0 61 74 69 6f 6e 73 20 70 65 72 66 6f 72 6d 65 64  ations performed
18ad0 20 62 79 20 74 72 69 67 67 65 72 20 70 72 6f 67   by trigger prog
18ae0 72 61 6d 73 2e 20 54 68 69 73 0a 2a 2a 20 6f 70  rams. This.** op
18af0 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
18b00 73 65 74 20 6f 72 20 63 6c 65 61 72 20 28 74 68  set or clear (th
18b10 65 20 64 65 66 61 75 6c 74 29 20 61 20 66 6c 61  e default) a fla
18b20 67 20 74 68 61 74 20 67 6f 76 65 72 6e 73 20 74  g that governs t
18b30 68 69 73 0a 2a 2a 20 62 65 68 61 76 69 6f 72 2e  his.** behavior.
18b40 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
18b50 65 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 74  eter passed to t
18b60 68 69 73 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  his operation is
18b70 20 61 6e 20 69 6e 74 65 67 65 72 20 2d 0a 2a 2a   an integer -.**
18b80 20 6e 6f 6e 2d 7a 65 72 6f 20 74 6f 20 65 6e 61   non-zero to ena
18b90 62 6c 65 20 6f 75 74 70 75 74 20 66 6f 72 20 74  ble output for t
18ba0 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 73 2c  rigger programs,
18bb0 20 6f 72 20 7a 65 72 6f 20 74 6f 20 64 69 73 61   or zero to disa
18bc0 62 6c 65 20 69 74 2e 0a 2a 2a 20 54 68 65 20 73  ble it..** The s
18bd0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
18be0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
18bf0 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20  an integer into 
18c00 77 68 69 63 68 20 69 73 20 77 72 69 74 74 65 6e  which is written
18c10 20 0a 2a 2a 20 30 20 6f 72 20 31 20 74 6f 20 69   .** 0 or 1 to i
18c20 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20  ndicate whether 
18c30 6f 75 74 70 75 74 2d 66 6f 72 2d 74 72 69 67 67  output-for-trigg
18c40 65 72 73 20 68 61 73 20 62 65 65 6e 20 64 69 73  ers has been dis
18c50 61 62 6c 65 64 20 2d 20 30 20 69 66 20 0a 2a 2a  abled - 0 if .**
18c60 20 69 74 20 69 73 20 6e 6f 74 20 64 69 73 61 62   it is not disab
18c70 6c 65 64 2c 20 31 20 69 66 20 69 74 20 69 73 2e  led, 1 if it is.
18c80 20 20 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 20 3c    .** </dd>.** <
18c90 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
18ca0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
18cb0 4d 41 49 4e 44 42 4e 41 4d 45 20 20 20 20 20 20  MAINDBNAME      
18cc0 20 20 20 20 20 20 31 30 30 30 20 2f 2a 20 63 6f        1000 /* co
18cd0 6e 73 74 20 63 68 61 72 2a 20 2a 2f 0a 23 64 65  nst char* */.#de
18ce0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
18cf0 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20  NFIG_LOOKASIDE  
18d00 20 20 20 20 20 20 20 20 20 20 20 31 30 30 31 20             1001 
18d10 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74  /* void* int int
18d20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18d30 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
18d40 4c 45 5f 46 4b 45 59 20 20 20 20 20 20 20 20 20  LE_FKEY         
18d50 20 20 31 30 30 32 20 2f 2a 20 69 6e 74 20 69 6e    1002 /* int in
18d60 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t* */.#define SQ
18d70 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
18d80 41 42 4c 45 5f 54 52 49 47 47 45 52 20 20 20 20  ABLE_TRIGGER    
18d90 20 20 20 20 31 30 30 33 20 2f 2a 20 69 6e 74 20      1003 /* int 
18da0 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  int* */.#define 
18db0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
18dc0 45 4e 41 42 4c 45 5f 46 54 53 33 5f 54 4f 4b 45  ENABLE_FTS3_TOKE
18dd0 4e 49 5a 45 52 20 31 30 30 34 20 2f 2a 20 69 6e  NIZER 1004 /* in
18de0 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e  t int* */.#defin
18df0 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
18e00 47 5f 45 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45 58  G_ENABLE_LOAD_EX
18e10 54 45 4e 53 49 4f 4e 20 31 30 30 35 20 2f 2a 20  TENSION 1005 /* 
18e20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66  int int* */.#def
18e30 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
18e40 46 49 47 5f 4e 4f 5f 43 4b 50 54 5f 4f 4e 5f 43  FIG_NO_CKPT_ON_C
18e50 4c 4f 53 45 20 20 20 20 20 20 31 30 30 36 20 2f  LOSE      1006 /
18e60 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64  * int int* */.#d
18e70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
18e80 4f 4e 46 49 47 5f 46 55 4c 4c 5f 45 51 50 20 20  ONFIG_FULL_EQP  
18e90 20 20 20 20 20 20 20 20 20 20 20 20 31 30 30 37              1007
18ea0 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a   /* int int* */.
18eb0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
18ec0 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61  : Enable Or Disa
18ed0 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65 73  ble Extended Res
18ee0 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4d 45 54  ult Codes.** MET
18ef0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
18f00 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
18f10 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
18f20 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20  codes() routine 
18f30 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
18f40 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65  les the.** [exte
18f50 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
18f60 73 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53 51  s] feature of SQ
18f70 4c 69 74 65 2e 20 5e 54 68 65 20 65 78 74 65 6e  Lite. ^The exten
18f80 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f  ded result.** co
18f90 64 65 73 20 61 72 65 20 64 69 73 61 62 6c 65 64  des are disabled
18fa0 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20   by default for 
18fb0 68 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61  historical compa
18fc0 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74  tibility..*/.int
18fd0 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
18fe0 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73  d_result_codes(s
18ff0 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f  qlite3*, int ono
19000 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ff);../*.** CAPI
19010 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72  3REF: Last Inser
19020 74 20 52 6f 77 69 64 0a 2a 2a 20 4d 45 54 48 4f  t Rowid.** METHO
19030 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
19040 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20   ^Each entry in 
19050 6d 6f 73 74 20 53 51 4c 69 74 65 20 74 61 62 6c  most SQLite tabl
19060 65 73 20 28 65 78 63 65 70 74 20 66 6f 72 20 5b  es (except for [
19070 57 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74  WITHOUT ROWID] t
19080 61 62 6c 65 73 29 0a 2a 2a 20 68 61 73 20 61 20  ables).** has a 
19090 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73 69  unique 64-bit si
190a0 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20  gned.** integer 
190b0 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b  key called the [
190c0 52 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d  ROWID | "rowid"]
190d0 2e 20 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20  . ^The rowid is 
190e0 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65  always available
190f0 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c  .** as an undecl
19100 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65  ared column name
19110 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72  d ROWID, OID, or
19120 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67   _ROWID_ as long
19130 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d   as those.** nam
19140 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20  es are not also 
19150 75 73 65 64 20 62 79 20 65 78 70 6c 69 63 69 74  used by explicit
19160 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75  ly declared colu
19170 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20  mns. ^If.** the 
19180 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75  table has a colu
19190 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45  mn of type [INTE
191a0 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d  GER PRIMARY KEY]
191b0 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d   then that colum
191c0 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20  n.** is another 
191d0 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f  alias for the ro
191e0 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  wid..**.** ^The 
191f0 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
19200 65 72 74 5f 72 6f 77 69 64 28 44 29 20 69 6e 74  ert_rowid(D) int
19210 65 72 66 61 63 65 20 75 73 75 61 6c 6c 79 20 72  erface usually r
19220 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69  eturns the [rowi
19230 64 5d 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 6f 73  d] of.** the mos
19240 74 20 72 65 63 65 6e 74 20 73 75 63 63 65 73 73  t recent success
19250 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74  ful [INSERT] int
19260 6f 20 61 20 72 6f 77 69 64 20 74 61 62 6c 65 20  o a rowid table 
19270 6f 72 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  or [virtual tabl
19280 65 5d 0a 2a 2a 20 6f 6e 20 64 61 74 61 62 61 73  e].** on databas
19290 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20  e connection D. 
192a0 5e 49 6e 73 65 72 74 73 20 69 6e 74 6f 20 5b 57  ^Inserts into [W
192b0 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61  ITHOUT ROWID] ta
192c0 62 6c 65 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20  bles are not.** 
192d0 72 65 63 6f 72 64 65 64 2e 20 5e 49 66 20 6e 6f  recorded. ^If no
192e0 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53   successful [INS
192f0 45 52 54 5d 73 20 69 6e 74 6f 20 72 6f 77 69 64  ERT]s into rowid
19300 20 74 61 62 6c 65 73 20 68 61 76 65 20 65 76 65   tables have eve
19310 72 20 6f 63 63 75 72 72 65 64 20 0a 2a 2a 20 6f  r occurred .** o
19320 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
19330 6f 6e 6e 65 63 74 69 6f 6e 20 44 2c 20 74 68 65  onnection D, the
19340 6e 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69  n sqlite3_last_i
19350 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20 72  nsert_rowid(D) r
19360 65 74 75 72 6e 73 20 0a 2a 2a 20 7a 65 72 6f 2e  eturns .** zero.
19370 0a 2a 2a 0a 2a 2a 20 41 73 20 77 65 6c 6c 20 61  .**.** As well a
19380 73 20 62 65 69 6e 67 20 73 65 74 20 61 75 74 6f  s being set auto
19390 6d 61 74 69 63 61 6c 6c 79 20 61 73 20 72 6f 77  matically as row
193a0 73 20 61 72 65 20 69 6e 73 65 72 74 65 64 20 69  s are inserted i
193b0 6e 74 6f 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  nto database.** 
193c0 74 61 62 6c 65 73 2c 20 74 68 65 20 76 61 6c 75  tables, the valu
193d0 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  e returned by th
193e0 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20  is function may 
193f0 62 65 20 73 65 74 20 65 78 70 6c 69 63 69 74 6c  be set explicitl
19400 79 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  y by.** [sqlite3
19410 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72 74  _set_last_insert
19420 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 0a 2a 2a 20  _rowid()].**.** 
19430 53 6f 6d 65 20 76 69 72 74 75 61 6c 20 74 61 62  Some virtual tab
19440 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
19450 6e 73 20 6d 61 79 20 49 4e 53 45 52 54 20 72 6f  ns may INSERT ro
19460 77 73 20 69 6e 74 6f 20 72 6f 77 69 64 20 74 61  ws into rowid ta
19470 62 6c 65 73 20 61 73 0a 2a 2a 20 70 61 72 74 20  bles as.** part 
19480 6f 66 20 63 6f 6d 6d 69 74 74 69 6e 67 20 61 20  of committing a 
19490 74 72 61 6e 73 61 63 74 69 6f 6e 20 28 65 2e 67  transaction (e.g
194a0 2e 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20  . to flush data 
194b0 61 63 63 75 6d 75 6c 61 74 65 64 20 69 6e 20 6d  accumulated in m
194c0 65 6d 6f 72 79 0a 2a 2a 20 74 6f 20 64 69 73 6b  emory.** to disk
194d0 29 2e 20 49 6e 20 74 68 69 73 20 63 61 73 65 20  ). In this case 
194e0 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
194f0 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f   to this functio
19500 6e 20 72 65 74 75 72 6e 20 74 68 65 20 72 6f 77  n return the row
19510 69 64 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  id.** associated
19520 20 77 69 74 68 20 74 68 65 73 65 20 69 6e 74 65   with these inte
19530 72 6e 61 6c 20 49 4e 53 45 52 54 20 6f 70 65 72  rnal INSERT oper
19540 61 74 69 6f 6e 73 2c 20 77 68 69 63 68 20 6c 65  ations, which le
19550 61 64 73 20 74 6f 20 0a 2a 2a 20 75 6e 69 6e 74  ads to .** unint
19560 75 69 74 69 76 65 20 72 65 73 75 6c 74 73 2e 20  uitive results. 
19570 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d  Virtual table im
19580 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 68  plementations th
19590 61 74 20 64 6f 20 77 72 69 74 65 20 74 6f 20 72  at do write to r
195a0 6f 77 69 64 0a 2a 2a 20 74 61 62 6c 65 73 20 69  owid.** tables i
195b0 6e 20 74 68 69 73 20 77 61 79 20 63 61 6e 20 61  n this way can a
195c0 76 6f 69 64 20 74 68 69 73 20 70 72 6f 62 6c 65  void this proble
195d0 6d 20 62 79 20 72 65 73 74 6f 72 69 6e 67 20 74  m by restoring t
195e0 68 65 20 6f 72 69 67 69 6e 61 6c 20 0a 2a 2a 20  he original .** 
195f0 72 6f 77 69 64 20 76 61 6c 75 65 20 75 73 69 6e  rowid value usin
19600 67 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c  g [sqlite3_set_l
19610 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
19620 28 29 5d 20 62 65 66 6f 72 65 20 72 65 74 75 72  ()] before retur
19630 6e 69 6e 67 20 0a 2a 2a 20 63 6f 6e 74 72 6f 6c  ning .** control
19640 20 74 6f 20 74 68 65 20 75 73 65 72 2e 0a 2a 2a   to the user..**
19650 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53  .** ^(If an [INS
19660 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68  ERT] occurs with
19670 69 6e 20 61 20 74 72 69 67 67 65 72 20 74 68 65  in a trigger the
19680 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  n this routine w
19690 69 6c 6c 20 0a 2a 2a 20 72 65 74 75 72 6e 20 74  ill .** return t
196a0 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68  he [rowid] of th
196b0 65 20 69 6e 73 65 72 74 65 64 20 72 6f 77 20 61  e inserted row a
196c0 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72  s long as the tr
196d0 69 67 67 65 72 20 69 73 20 0a 2a 2a 20 72 75 6e  igger is .** run
196e0 6e 69 6e 67 2e 20 4f 6e 63 65 20 74 68 65 20 74  ning. Once the t
196f0 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 65  rigger program e
19700 6e 64 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72  nds, the value r
19710 65 74 75 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74  eturned .** by t
19720 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 76 65  his routine reve
19730 72 74 73 20 74 6f 20 77 68 61 74 20 69 74 20 77  rts to what it w
19740 61 73 20 62 65 66 6f 72 65 20 74 68 65 20 74 72  as before the tr
19750 69 67 67 65 72 20 77 61 73 20 66 69 72 65 64 2e  igger was fired.
19760 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e  )^.**.** ^An [IN
19770 53 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73  SERT] that fails
19780 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72   due to a constr
19790 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69  aint violation i
197a0 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65  s not a.** succe
197b0 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61  ssful [INSERT] a
197c0 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  nd does not chan
197d0 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ge the value ret
197e0 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a  urned by this.**
197f0 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 73   routine.  ^Thus
19800 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c   INSERT OR FAIL,
19810 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52   INSERT OR IGNOR
19820 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c  E, INSERT OR ROL
19830 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e  LBACK,.** and IN
19840 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61  SERT OR ABORT ma
19850 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f  ke no changes to
19860 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
19870 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75  e of this.** rou
19880 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20  tine when their 
19890 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e  insertion fails.
198a0 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 20    ^(When INSERT 
198b0 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e  OR REPLACE.** en
198c0 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74  counters a const
198d0 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c  raint violation,
198e0 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69   it does not fai
198f0 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52  l.  The.** INSER
19900 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63  T continues to c
19910 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20  ompletion after 
19920 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68  deleting rows th
19930 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65  at caused.** the
19940 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62   constraint prob
19950 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52  lem so INSERT OR
19960 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c   REPLACE will al
19970 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74  ways change.** t
19980 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
19990 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  of this interfac
199a0 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20  e.)^.**.** ^For 
199b0 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20  the purposes of 
199c0 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e  this routine, an
199d0 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e   [INSERT] is con
199e0 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65  sidered to.** be
199f0 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e   successful even
19a00 20 69 66 20 69 74 20 69 73 20 73 75 62 73 65 71   if it is subseq
19a10 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61  uently rolled ba
19a20 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66  ck..**.** This f
19a30 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65 73  unction is acces
19a40 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 61  sible to SQL sta
19a50 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65 0a  tements via the.
19a60 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f  ** [last_insert_
19a70 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e 63  rowid() SQL func
19a80 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  tion]..**.** If 
19a90 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
19aa0 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77  d performs a new
19ab0 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65   [INSERT] on the
19ac0 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73   same.** databas
19ad0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69  e connection whi
19ae0 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  le the [sqlite3_
19af0 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
19b00 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  d()].** function
19b10 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20   is running and 
19b20 74 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 65  thus changes the
19b30 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f   last insert [ro
19b40 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  wid],.** then th
19b50 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
19b60 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73   by [sqlite3_las
19b70 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
19b80 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63  ] is.** unpredic
19b90 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20  table and might 
19ba0 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65 72  not equal either
19bb0 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20   the old or the 
19bc0 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65  new.** last inse
19bd0 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73  rt [rowid]..*/.s
19be0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
19bf0 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
19c00 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29  _rowid(sqlite3*)
19c10 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
19c20 46 3a 20 53 65 74 20 74 68 65 20 4c 61 73 74 20  F: Set the Last 
19c30 49 6e 73 65 72 74 20 52 6f 77 69 64 20 76 61 6c  Insert Rowid val
19c40 75 65 2e 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ue..** METHOD: s
19c50 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65  qlite3.**.** The
19c60 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73   sqlite3_set_las
19c70 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44  t_insert_rowid(D
19c80 2c 20 52 29 20 6d 65 74 68 6f 64 20 61 6c 6c 6f  , R) method allo
19c90 77 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ws the applicati
19ca0 6f 6e 20 74 6f 0a 2a 2a 20 73 65 74 20 74 68 65  on to.** set the
19cb0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
19cc0 62 79 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74  by calling sqlit
19cd0 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
19ce0 6f 77 69 64 28 44 29 20 74 6f 20 52 20 0a 2a 2a  owid(D) to R .**
19cf0 20 77 69 74 68 6f 75 74 20 69 6e 73 65 72 74 69   without inserti
19d00 6e 67 20 61 20 72 6f 77 20 69 6e 74 6f 20 74 68  ng a row into th
19d10 65 20 64 61 74 61 62 61 73 65 2e 0a 2a 2f 0a 76  e database..*/.v
19d20 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  oid sqlite3_set_
19d30 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
19d40 64 28 73 71 6c 69 74 65 33 2a 2c 73 71 6c 69 74  d(sqlite3*,sqlit
19d50 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a  e3_int64);../*.*
19d60 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e  * CAPI3REF: Coun
19d70 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20  t The Number Of 
19d80 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a  Rows Modified.**
19d90 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
19da0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
19db0 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
19dc0 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  e number of rows
19dd0 20 6d 6f 64 69 66 69 65 64 2c 20 69 6e 73 65 72   modified, inser
19de0 74 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 65  ted or.** delete
19df0 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65  d by the most re
19e00 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64  cently completed
19e10 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20   INSERT, UPDATE 
19e20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61  or DELETE.** sta
19e30 74 65 6d 65 6e 74 20 6f 6e 20 74 68 65 20 64 61  tement on the da
19e40 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
19e50 6e 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  n specified by t
19e60 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65  he only paramete
19e70 72 2e 0a 2a 2a 20 5e 45 78 65 63 75 74 69 6e 67  r..** ^Executing
19e80 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20   any other type 
19e90 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  of SQL statement
19ea0 20 64 6f 65 73 20 6e 6f 74 20 6d 6f 64 69 66 79   does not modify
19eb0 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65   the value.** re
19ec0 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 66  turned by this f
19ed0 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  unction..**.** ^
19ee0 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61 64  Only changes mad
19ef0 65 20 64 69 72 65 63 74 6c 79 20 62 79 20 74 68  e directly by th
19f00 65 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  e INSERT, UPDATE
19f10 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65   or DELETE state
19f20 6d 65 6e 74 20 61 72 65 0a 2a 2a 20 63 6f 6e 73  ment are.** cons
19f30 69 64 65 72 65 64 20 2d 20 61 75 78 69 6c 69 61  idered - auxilia
19f40 72 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65  ry changes cause
19f50 64 20 62 79 20 5b 43 52 45 41 54 45 20 54 52 49  d by [CREATE TRI
19f60 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d  GGER | triggers]
19f70 2c 20 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b  , .** [foreign k
19f80 65 79 20 61 63 74 69 6f 6e 73 5d 20 6f 72 20 5b  ey actions] or [
19f90 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61  REPLACE] constra
19fa0 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61  int resolution a
19fb0 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a  re not counted..
19fc0 2a 2a 20 0a 2a 2a 20 43 68 61 6e 67 65 73 20 74  ** .** Changes t
19fd0 6f 20 61 20 76 69 65 77 20 74 68 61 74 20 61 72  o a view that ar
19fe0 65 20 69 6e 74 65 72 63 65 70 74 65 64 20 62 79  e intercepted by
19ff0 20 0a 2a 2a 20 5b 49 4e 53 54 45 41 44 20 4f 46   .** [INSTEAD OF
1a000 20 74 72 69 67 67 65 72 20 7c 20 49 4e 53 54 45   trigger | INSTE
1a010 41 44 20 4f 46 20 74 72 69 67 67 65 72 73 5d 20  AD OF triggers] 
1a020 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e  are not counted.
1a030 20 5e 54 68 65 20 76 61 6c 75 65 20 0a 2a 2a 20   ^The value .** 
1a040 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
1a050 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6d  te3_changes() im
1a060 6d 65 64 69 61 74 65 6c 79 20 61 66 74 65 72 20  mediately after 
1a070 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  an INSERT, UPDAT
1a080 45 20 6f 72 20 0a 2a 2a 20 44 45 4c 45 54 45 20  E or .** DELETE 
1a090 73 74 61 74 65 6d 65 6e 74 20 72 75 6e 20 6f 6e  statement run on
1a0a0 20 61 20 76 69 65 77 20 69 73 20 61 6c 77 61 79   a view is alway
1a0b0 73 20 7a 65 72 6f 2e 20 4f 6e 6c 79 20 63 68 61  s zero. Only cha
1a0c0 6e 67 65 73 20 6d 61 64 65 20 74 6f 20 72 65 61  nges made to rea
1a0d0 6c 20 0a 2a 2a 20 74 61 62 6c 65 73 20 61 72 65  l .** tables are
1a0e0 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20   counted..**.** 
1a0f0 54 68 69 6e 67 73 20 61 72 65 20 6d 6f 72 65 20  Things are more 
1a100 63 6f 6d 70 6c 69 63 61 74 65 64 20 69 66 20 74  complicated if t
1a110 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  he sqlite3_chang
1a120 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  es() function is
1a130 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 77 68 69  .** executed whi
1a140 6c 65 20 61 20 74 72 69 67 67 65 72 20 70 72 6f  le a trigger pro
1a150 67 72 61 6d 20 69 73 20 72 75 6e 6e 69 6e 67 2e  gram is running.
1a160 20 54 68 69 73 20 6d 61 79 20 68 61 70 70 65 6e   This may happen
1a170 20 69 66 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72   if the.** progr
1a180 61 6d 20 75 73 65 73 20 74 68 65 20 5b 63 68 61  am uses the [cha
1a190 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74  nges() SQL funct
1a1a0 69 6f 6e 5d 2c 20 6f 72 20 69 66 20 73 6f 6d 65  ion], or if some
1a1b0 20 6f 74 68 65 72 20 63 61 6c 6c 62 61 63 6b 0a   other callback.
1a1c0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 6e 76 6f  ** function invo
1a1d0 6b 65 73 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  kes sqlite3_chan
1a1e0 67 65 73 28 29 20 64 69 72 65 63 74 6c 79 2e 20  ges() directly. 
1a1f0 45 73 73 65 6e 74 69 61 6c 6c 79 3a 0a 2a 2a 20  Essentially:.** 
1a200 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  .** <ul>.**   <l
1a210 69 3e 20 5e 28 42 65 66 6f 72 65 20 65 6e 74 65  i> ^(Before ente
1a220 72 69 6e 67 20 61 20 74 72 69 67 67 65 72 20 70  ring a trigger p
1a230 72 6f 67 72 61 6d 20 74 68 65 20 76 61 6c 75 65  rogram the value
1a240 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
1a250 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63         sqlite3_c
1a260 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f  hanges() functio
1a270 6e 20 69 73 20 73 61 76 65 64 2e 20 41 66 74 65  n is saved. Afte
1a280 72 20 74 68 65 20 74 72 69 67 67 65 72 20 70 72  r the trigger pr
1a290 6f 67 72 61 6d 20 0a 2a 2a 20 20 20 20 20 20 20  ogram .**       
1a2a0 20 68 61 73 20 66 69 6e 69 73 68 65 64 2c 20 74   has finished, t
1a2b0 68 65 20 6f 72 69 67 69 6e 61 6c 20 76 61 6c 75  he original valu
1a2c0 65 20 69 73 20 72 65 73 74 6f 72 65 64 2e 29 5e  e is restored.)^
1a2d0 0a 2a 2a 20 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e  .** .**   <li> ^
1a2e0 28 57 69 74 68 69 6e 20 61 20 74 72 69 67 67 65  (Within a trigge
1a2f0 72 20 70 72 6f 67 72 61 6d 20 65 61 63 68 20 49  r program each I
1a300 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 61 6e  NSERT, UPDATE an
1a310 64 20 44 45 4c 45 54 45 20 0a 2a 2a 20 20 20 20  d DELETE .**    
1a320 20 20 20 20 73 74 61 74 65 6d 65 6e 74 20 73 65      statement se
1a330 74 73 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ts the value ret
1a340 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
1a350 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20  _changes() .**  
1a360 20 20 20 20 20 20 75 70 6f 6e 20 63 6f 6d 70 6c        upon compl
1a370 65 74 69 6f 6e 20 61 73 20 6e 6f 72 6d 61 6c 2e  etion as normal.
1a380 20 4f 66 20 63 6f 75 72 73 65 2c 20 74 68 69 73   Of course, this
1a390 20 76 61 6c 75 65 20 77 69 6c 6c 20 6e 6f 74 20   value will not 
1a3a0 69 6e 63 6c 75 64 65 20 0a 2a 2a 20 20 20 20 20  include .**     
1a3b0 20 20 20 61 6e 79 20 63 68 61 6e 67 65 73 20 70     any changes p
1a3c0 65 72 66 6f 72 6d 65 64 20 62 79 20 73 75 62 2d  erformed by sub-
1a3d0 74 72 69 67 67 65 72 73 2c 20 61 73 20 74 68 65  triggers, as the
1a3e0 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
1a3f0 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 76 61  () .**        va
1a400 6c 75 65 20 77 69 6c 6c 20 62 65 20 73 61 76 65  lue will be save
1a410 64 20 61 6e 64 20 72 65 73 74 6f 72 65 64 20 61  d and restored a
1a420 66 74 65 72 20 65 61 63 68 20 73 75 62 2d 74 72  fter each sub-tr
1a430 69 67 67 65 72 20 68 61 73 20 72 75 6e 2e 29 5e  igger has run.)^
1a440 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a  .** </ul>.** .**
1a450 20 5e 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61   ^This means tha
1a460 74 20 69 66 20 74 68 65 20 63 68 61 6e 67 65 73  t if the changes
1a470 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  () SQL function 
1a480 28 6f 72 20 73 69 6d 69 6c 61 72 29 20 69 73 20  (or similar) is 
1a490 75 73 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 66  used.** by the f
1a4a0 69 72 73 74 20 49 4e 53 45 52 54 2c 20 55 50 44  irst INSERT, UPD
1a4b0 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74  ATE or DELETE st
1a4c0 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61  atement within a
1a4d0 20 74 72 69 67 67 65 72 2c 20 69 74 20 0a 2a 2a   trigger, it .**
1a4e0 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c   returns the val
1a4f0 75 65 20 61 73 20 73 65 74 20 77 68 65 6e 20 74  ue as set when t
1a500 68 65 20 63 61 6c 6c 69 6e 67 20 73 74 61 74 65  he calling state
1a510 6d 65 6e 74 20 62 65 67 61 6e 20 65 78 65 63 75  ment began execu
1a520 74 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 69 74 20  ting..** ^If it 
1a530 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20 73  is used by the s
1a540 65 63 6f 6e 64 20 6f 72 20 73 75 62 73 65 71 75  econd or subsequ
1a550 65 6e 74 20 73 75 63 68 20 73 74 61 74 65 6d 65  ent such stateme
1a560 6e 74 20 77 69 74 68 69 6e 20 61 20 74 72 69 67  nt within a trig
1a570 67 65 72 20 0a 2a 2a 20 70 72 6f 67 72 61 6d 2c  ger .** program,
1a580 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
1a590 6e 65 64 20 72 65 66 6c 65 63 74 73 20 74 68 65  ned reflects the
1a5a0 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
1a5b0 6d 6f 64 69 66 69 65 64 20 62 79 20 74 68 65 20  modified by the 
1a5c0 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 49 4e 53  .** previous INS
1a5d0 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44  ERT, UPDATE or D
1a5e0 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20  ELETE statement 
1a5f0 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20  within the same 
1a600 74 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 53  trigger..**.** S
1a610 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c  ee also the [sql
1a620 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
1a630 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c  es()] interface,
1a640 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63   the.** [count_c
1a650 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20  hanges pragma], 
1a660 61 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 65 73  and the [changes
1a670 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
1a680 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70  ..**.** If a sep
1a690 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b  arate thread mak
1a6a0 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68  es changes on th
1a6b0 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
1a6c0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68  connection.** wh
1a6d0 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61  ile [sqlite3_cha
1a6e0 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69  nges()] is runni
1a6f0 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ng then the valu
1a700 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73  e returned.** is
1a710 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
1a720 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75  nd not meaningfu
1a730 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l..*/.int sqlite
1a740 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65  3_changes(sqlite
1a750 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
1a760 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62  3REF: Total Numb
1a770 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66  er Of Rows Modif
1a780 69 65 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ied.** METHOD: s
1a790 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
1a7a0 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
1a7b0 72 6e 73 20 74 68 65 20 74 6f 74 61 6c 20 6e 75  rns the total nu
1a7c0 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 69 6e 73  mber of rows ins
1a7d0 65 72 74 65 64 2c 20 6d 6f 64 69 66 69 65 64 20  erted, modified 
1a7e0 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79  or.** deleted by
1a7f0 20 61 6c 6c 20 5b 49 4e 53 45 52 54 5d 2c 20 5b   all [INSERT], [
1a800 55 50 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45  UPDATE] or [DELE
1a810 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 63  TE] statements c
1a820 6f 6d 70 6c 65 74 65 64 0a 2a 2a 20 73 69 6e 63  ompleted.** sinc
1a830 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  e the database c
1a840 6f 6e 6e 65 63 74 69 6f 6e 20 77 61 73 20 6f 70  onnection was op
1a850 65 6e 65 64 2c 20 69 6e 63 6c 75 64 69 6e 67 20  ened, including 
1a860 74 68 6f 73 65 20 65 78 65 63 75 74 65 64 20 61  those executed a
1a870 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 72 69  s.** part of tri
1a880 67 67 65 72 20 70 72 6f 67 72 61 6d 73 2e 20 5e  gger programs. ^
1a890 45 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f 74  Executing any ot
1a8a0 68 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c 20  her type of SQL 
1a8b0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 64 6f 65  statement.** doe
1a8c0 73 20 6e 6f 74 20 61 66 66 65 63 74 20 74 68 65  s not affect the
1a8d0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
1a8e0 62 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  by sqlite3_total
1a8f0 5f 63 68 61 6e 67 65 73 28 29 2e 0a 2a 2a 20 0a  _changes()..** .
1a900 2a 2a 20 5e 43 68 61 6e 67 65 73 20 6d 61 64 65  ** ^Changes made
1a910 20 61 73 20 70 61 72 74 20 6f 66 20 5b 66 6f 72   as part of [for
1a920 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73  eign key actions
1a930 5d 20 61 72 65 20 69 6e 63 6c 75 64 65 64 20 69  ] are included i
1a940 6e 20 74 68 65 0a 2a 2a 20 63 6f 75 6e 74 2c 20  n the.** count, 
1a950 62 75 74 20 74 68 6f 73 65 20 6d 61 64 65 20 61  but those made a
1a960 73 20 70 61 72 74 20 6f 66 20 52 45 50 4c 41 43  s part of REPLAC
1a970 45 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73  E constraint res
1a980 6f 6c 75 74 69 6f 6e 20 61 72 65 0a 2a 2a 20 6e  olution are.** n
1a990 6f 74 2e 20 5e 43 68 61 6e 67 65 73 20 74 6f 20  ot. ^Changes to 
1a9a0 61 20 76 69 65 77 20 74 68 61 74 20 61 72 65 20  a view that are 
1a9b0 69 6e 74 65 72 63 65 70 74 65 64 20 62 79 20 49  intercepted by I
1a9c0 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65  NSTEAD OF trigge
1a9d0 72 73 20 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63  rs .** are not c
1a9e0 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 53  ounted..** .** S
1a9f0 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c  ee also the [sql
1aa00 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20  ite3_changes()] 
1aa10 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a  interface, the.*
1aa20 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73  * [count_changes
1aa30 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68   pragma], and th
1aa40 65 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e [total_changes
1aa50 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
1aa60 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70  ..**.** If a sep
1aa70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b  arate thread mak
1aa80 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68  es changes on th
1aa90 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
1aaa0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68  connection.** wh
1aab0 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74  ile [sqlite3_tot
1aac0 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73  al_changes()] is
1aad0 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68   running then th
1aae0 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72  e value.** retur
1aaf0 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69 63 74  ned is unpredict
1ab00 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61  able and not mea
1ab10 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20  ningful..*/.int 
1ab20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
1ab30 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b  anges(sqlite3*);
1ab40 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1ab50 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f  : Interrupt A Lo
1ab60 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79  ng-Running Query
1ab70 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
1ab80 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  te3.**.** ^This 
1ab90 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20  function causes 
1aba0 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61  any pending data
1abb0 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74  base operation t
1abc0 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72  o abort and.** r
1abd0 65 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 72  eturn at its ear
1abe0 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74  liest opportunit
1abf0 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  y. This routine 
1ac00 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20  is typically.** 
1ac10 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e  called in respon
1ac20 73 65 20 74 6f 20 61 20 75 73 65 72 20 61 63 74  se to a user act
1ac30 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 73  ion such as pres
1ac40 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a  sing "Cancel".**
1ac50 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65   or Ctrl-C where
1ac60 20 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 20   the user wants 
1ac70 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65  a long query ope
1ac80 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a  ration to halt.*
1ac90 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a  * immediately..*
1aca0 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 65  *.** ^It is safe
1acb0 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f   to call this ro
1acc0 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72  utine from a thr
1acd0 65 61 64 20 64 69 66 66 65 72 65 6e 74 20 66 72  ead different fr
1ace0 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64  om the.** thread
1acf0 20 74 68 61 74 20 69 73 20 63 75 72 72 65 6e 74   that is current
1ad00 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64  ly running the d
1ad10 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f  atabase operatio
1ad20 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73  n.  But it.** is
1ad30 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c   not safe to cal
1ad40 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  l this routine w
1ad50 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20  ith a [database 
1ad60 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74  connection] that
1ad70 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72  .** is closed or
1ad80 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66   might close bef
1ad90 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  ore sqlite3_inte
1ada0 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e  rrupt() returns.
1adb0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51  .**.** ^If an SQ
1adc0 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76  L operation is v
1add0 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73  ery nearly finis
1ade0 68 65 64 20 61 74 20 74 68 65 20 74 69 6d 65 20  hed at the time 
1adf0 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  when.** sqlite3_
1ae00 69 6e 74 65 72 72 75 70 74 28 29 20 69 73 20 63  interrupt() is c
1ae10 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d  alled, then it m
1ae20 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e  ight not have an
1ae30 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20   opportunity.** 
1ae40 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74 65  to be interrupte
1ae50 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74  d and might cont
1ae60 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69  inue to completi
1ae70 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51  on..**.** ^An SQ
1ae80 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74  L operation that
1ae90 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20   is interrupted 
1aea0 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
1aeb0 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a  ITE_INTERRUPT]..
1aec0 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65 72  ** ^If the inter
1aed0 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61  rupted SQL opera
1aee0 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52  tion is an INSER
1aef0 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
1af00 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20  LETE.** that is 
1af10 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63  inside an explic
1af20 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20  it transaction, 
1af30 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20  then the entire 
1af40 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77  transaction.** w
1af50 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61  ill be rolled ba
1af60 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ck automatically
1af70 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1af80 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44  ite3_interrupt(D
1af90 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66  ) call is in eff
1afa0 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75  ect until all cu
1afb0 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a  rrently running.
1afc0 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
1afd0 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  s on [database c
1afe0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d  onnection] D com
1aff0 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77  plete.  ^Any new
1b000 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
1b010 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72  ** that are star
1b020 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71  ted after the sq
1b030 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1b040 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72  ) call and befor
1b050 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e  e the .** runnin
1b060 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61  g statements rea
1b070 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e  ches zero are in
1b080 74 65 72 72 75 70 74 65 64 20 61 73 20 69 66 20  terrupted as if 
1b090 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a  they had been.**
1b0a0 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74   running prior t
1b0b0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  o the sqlite3_in
1b0c0 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20  terrupt() call. 
1b0d0 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d   ^New SQL statem
1b0e0 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ents.** that are
1b0f0 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74   started after t
1b100 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65  he running state
1b110 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68  ment count reach
1b120 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e  es zero are.** n
1b130 6f 74 20 65 66 66 65 63 74 65 64 20 62 79 20 74  ot effected by t
1b140 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
1b150 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61  rupt()..** ^A ca
1b160 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ll to sqlite3_in
1b170 74 65 72 72 75 70 74 28 44 29 20 74 68 61 74 20  terrupt(D) that 
1b180 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68 65 72  occurs when ther
1b190 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67  e are no running
1b1a0 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
1b1b0 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e  ts is a no-op an
1b1c0 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20  d has no effect 
1b1d0 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  on SQL statement
1b1e0 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74  s.** that are st
1b1f0 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20  arted after the 
1b200 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1b210 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73  t() call returns
1b220 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
1b230 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69  3_interrupt(sqli
1b240 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
1b250 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e  PI3REF: Determin
1b260 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74  e If An SQL Stat
1b270 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74  ement Is Complet
1b280 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  e.**.** These ro
1b290 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66 75  utines are usefu
1b2a0 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64  l during command
1b2b0 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64  -line input to d
1b2c0 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a  etermine if the.
1b2d0 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74  ** currently ent
1b2e0 65 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20  ered text seems 
1b2f0 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65  to form a comple
1b300 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  te SQL statement
1b310 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69   or.** if additi
1b320 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65  onal input is ne
1b330 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64  eded before send
1b340 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74  ing the text int
1b350 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20  o.** SQLite for 
1b360 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65  parsing.  ^These
1b370 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
1b380 20 31 20 69 66 20 74 68 65 20 69 6e 70 75 74 20   1 if the input 
1b390 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72  string.** appear
1b3a0 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65  s to be a comple
1b3b0 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  te SQL statement
1b3c0 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20  .  ^A statement 
1b3d0 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a  is judged to be.
1b3e0 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69  ** complete if i
1b3f0 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 65  t ends with a se
1b400 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e  micolon token an
1b410 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69  d is not a prefi
1b420 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66  x of a.** well-f
1b430 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54 52 49  ormed CREATE TRI
1b440 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20  GGER statement. 
1b450 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61   ^Semicolons tha
1b460 74 20 61 72 65 20 65 6d 62 65 64 64 65 64 20 77  t are embedded w
1b470 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20  ithin.** string 
1b480 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74  literals or quot
1b490 65 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61  ed identifier na
1b4a0 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20  mes or comments 
1b4b0 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70  are not.** indep
1b4c0 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74  endent tokens (t
1b4d0 68 65 79 20 61 72 65 20 70 61 72 74 20 6f 66 20  hey are part of 
1b4e0 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69  the token in whi
1b4f0 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65  ch they are.** e
1b500 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74 68 75  mbedded) and thu
1b510 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61  s do not count a
1b520 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65  s a statement te
1b530 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74  rminator.  ^Whit
1b540 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f  espace.** and co
1b550 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c  mments that foll
1b560 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d  ow the final sem
1b570 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72  icolon are ignor
1b580 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ed..**.** ^These
1b590 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
1b5a0 20 30 20 69 66 20 74 68 65 20 73 74 61 74 65 6d   0 if the statem
1b5b0 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74  ent is incomplet
1b5c0 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d  e.  ^If a.** mem
1b5d0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
1b5e0 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54  ails, then SQLIT
1b5f0 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72  E_NOMEM is retur
1b600 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ned..**.** ^Thes
1b610 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f  e routines do no
1b620 74 20 70 61 72 73 65 20 74 68 65 20 53 51 4c 20  t parse the SQL 
1b630 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a  statements thus.
1b640 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65  ** will not dete
1b650 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79  ct syntactically
1b660 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a   incorrect SQL..
1b670 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74  **.** ^(If SQLit
1b680 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69  e has not been i
1b690 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67  nitialized using
1b6a0 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
1b6b0 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a  lize()] prior .*
1b6c0 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71  * to invoking sq
1b6d0 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
1b6e0 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  () then sqlite3_
1b6f0 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
1b700 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d  invoked.** autom
1b710 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69  atically by sqli
1b720 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
1b730 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69 74 69  .  If that initi
1b740 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c  alization fails,
1b750 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74  .** then the ret
1b760 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  urn value from s
1b770 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
1b780 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d  6() will be non-
1b790 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65  zero.** regardle
1b7a0 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
1b7b0 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53   not the input S
1b7c0 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29  QL is complete.)
1b7d0 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75  ^.**.** The inpu
1b7e0 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
1b7f0 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62  mplete()] must b
1b800 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  e a zero-termina
1b810 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72  ted.** UTF-8 str
1b820 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  ing..**.** The i
1b830 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  nput to [sqlite3
1b840 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d  _complete16()] m
1b850 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65  ust be a zero-te
1b860 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d  rminated.** UTF-
1b870 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74  16 string in nat
1b880 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
1b890 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
1b8a0 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68  omplete(const ch
1b8b0 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71  ar *sql);.int sq
1b8c0 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
1b8d0 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  (const void *sql
1b8e0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1b8f0 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 43  EF: Register A C
1b900 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c  allback To Handl
1b910 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72  e SQLITE_BUSY Er
1b920 72 6f 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  rors.** KEYWORDS
1b930 3a 20 7b 62 75 73 79 2d 68 61 6e 64 6c 65 72 20  : {busy-handler 
1b940 63 61 6c 6c 62 61 63 6b 7d 20 7b 62 75 73 79 20  callback} {busy 
1b950 68 61 6e 64 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48  handler}.** METH
1b960 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
1b970 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62  * ^The sqlite3_b
1b980 75 73 79 5f 68 61 6e 64 6c 65 72 28 44 2c 58 2c  usy_handler(D,X,
1b990 50 29 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20  P) routine sets 
1b9a0 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
1b9b0 69 6f 6e 20 58 0a 2a 2a 20 74 68 61 74 20 6d 69  ion X.** that mi
1b9c0 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  ght be invoked w
1b9d0 69 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77  ith argument P w
1b9e0 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74  henever.** an at
1b9f0 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f  tempt is made to
1ba00 20 61 63 63 65 73 73 20 61 20 64 61 74 61 62 61   access a databa
1ba10 73 65 20 74 61 62 6c 65 20 61 73 73 6f 63 69 61  se table associa
1ba20 74 65 64 20 77 69 74 68 0a 2a 2a 20 5b 64 61 74  ted with.** [dat
1ba30 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1ba40 5d 20 44 20 77 68 65 6e 20 61 6e 6f 74 68 65 72  ] D when another
1ba50 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72   thread.** or pr
1ba60 6f 63 65 73 73 20 68 61 73 20 74 68 65 20 74 61  ocess has the ta
1ba70 62 6c 65 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20 54  ble locked..** T
1ba80 68 65 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  he sqlite3_busy_
1ba90 68 61 6e 64 6c 65 72 28 29 20 69 6e 74 65 72 66  handler() interf
1baa0 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 69  ace is used to i
1bab0 6d 70 6c 65 6d 65 6e 74 0a 2a 2a 20 5b 73 71 6c  mplement.** [sql
1bac0 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
1bad0 74 28 29 5d 20 61 6e 64 20 5b 50 52 41 47 4d 41  t()] and [PRAGMA
1bae0 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 2e 0a   busy_timeout]..
1baf0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75  **.** ^If the bu
1bb00 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e  sy callback is N
1bb10 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54  ULL, then [SQLIT
1bb20 45 5f 42 55 53 59 5d 0a 2a 2a 20 69 73 20 72 65  E_BUSY].** is re
1bb30 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65  turned immediate
1bb40 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65  ly upon encounte
1bb50 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20  ring the lock.  
1bb60 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c  ^If the busy cal
1bb70 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20  lback.** is not 
1bb80 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63  NULL, then the c
1bb90 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62 65  allback might be
1bba0 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77   invoked with tw
1bbb0 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a  o arguments..**.
1bbc0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
1bbd0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62 75  gument to the bu
1bbe0 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20  sy handler is a 
1bbf0 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64  copy of the void
1bc00 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a  * pointer which.
1bc10 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72 64 20  ** is the third 
1bc20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
1bc30 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
1bc40 28 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64  ().  ^The second
1bc50 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
1bc60 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
1bc70 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65   callback is the
1bc80 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73   number of times
1bc90 20 74 68 61 74 20 74 68 65 20 62 75 73 79 20 68   that the busy h
1bca0 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65  andler has.** be
1bcb0 65 6e 20 69 6e 76 6f 6b 65 64 20 70 72 65 76 69  en invoked previ
1bcc0 6f 75 73 6c 79 20 66 6f 72 20 74 68 65 20 73 61  ously for the sa
1bcd0 6d 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74  me locking event
1bce0 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75  .  ^If the.** bu
1bcf0 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  sy callback retu
1bd00 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61  rns 0, then no a
1bd10 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70  dditional attemp
1bd20 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a  ts are made to.*
1bd30 2a 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74  * access the dat
1bd40 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54  abase and [SQLIT
1bd50 45 5f 42 55 53 59 5d 20 69 73 20 72 65 74 75 72  E_BUSY] is retur
1bd60 6e 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70  ned.** to the ap
1bd70 70 6c 69 63 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49  plication..** ^I
1bd80 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  f the callback r
1bd90 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
1bda0 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74   then another at
1bdb0 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65  tempt.** is made
1bdc0 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64   to access the d
1bdd0 61 74 61 62 61 73 65 20 61 6e 64 20 74 68 65 20  atabase and the 
1bde0 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a  cycle repeats..*
1bdf0 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63  *.** The presenc
1be00 65 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64  e of a busy hand
1be10 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61  ler does not gua
1be20 72 61 6e 74 65 65 20 74 68 61 74 20 69 74 20 77  rantee that it w
1be30 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a  ill be invoked.*
1be40 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69 73 20  * when there is 
1be50 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e  lock contention.
1be60 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74 65   ^If SQLite dete
1be70 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f  rmines that invo
1be80 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a  king the busy.**
1be90 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72   handler could r
1bea0 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c  esult in a deadl
1beb0 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20  ock, it will go 
1bec0 61 68 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e  ahead and return
1bed0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a   [SQLITE_BUSY].*
1bee0 2a 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  * to the applica
1bef0 74 69 6f 6e 20 69 6e 73 74 65 61 64 20 6f 66 20  tion instead of 
1bf00 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 0a 2a 2a  invoking the .**
1bf10 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a   busy handler..*
1bf20 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65  * Consider a sce
1bf30 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20  nario where one 
1bf40 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69  process is holdi
1bf50 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74  ng a read lock t
1bf60 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79  hat.** it is try
1bf70 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  ing to promote t
1bf80 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63  o a reserved loc
1bf90 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e  k and.** a secon
1bfa0 64 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c  d process is hol
1bfb0 64 69 6e 67 20 61 20 72 65 73 65 72 76 65 64 20  ding a reserved 
1bfc0 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73 20  lock that it is 
1bfd0 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f  trying.** to pro
1bfe0 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75  mote to an exclu
1bff0 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20  sive lock.  The 
1c000 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 63 61  first process ca
1c010 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20  nnot proceed.** 
1c020 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c  because it is bl
1c030 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73 65 63  ocked by the sec
1c040 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f  ond and the seco
1c050 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f  nd process canno
1c060 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63  t.** proceed bec
1c070 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b  ause it is block
1c080 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 2e  ed by the first.
1c090 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73    If both proces
1c0a0 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68  ses.** invoke th
1c0b0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c  e busy handlers,
1c0c0 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61   neither will ma
1c0d0 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e  ke any progress.
1c0e0 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20    Therefore,.** 
1c0f0 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b  SQLite returns [
1c100 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72  SQLITE_BUSY] for
1c110 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   the first proce
1c120 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20  ss, hoping that 
1c130 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64  this.** will ind
1c140 75 63 65 20 74 68 65 20 66 69 72 73 74 20 70 72  uce the first pr
1c150 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65  ocess to release
1c160 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61   its read lock a
1c170 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20  nd allow.** the 
1c180 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74  second process t
1c190 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a  o proceed..**.**
1c1a0 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 75   ^The default bu
1c1b0 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e  sy callback is N
1c1c0 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ULL..**.** ^(The
1c1d0 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61  re can only be a
1c1e0 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e   single busy han
1c1f0 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72  dler defined for
1c200 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61   each.** [databa
1c210 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
1c220 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62   Setting a new b
1c230 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61  usy handler clea
1c240 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f  rs any.** previo
1c250 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72  usly set handler
1c260 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20  .)^  ^Note that 
1c270 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
1c280 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
1c290 0a 2a 2a 20 6f 72 20 65 76 61 6c 75 61 74 69 6e  .** or evaluatin
1c2a0 67 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74  g [PRAGMA busy_t
1c2b0 69 6d 65 6f 75 74 3d 4e 5d 20 77 69 6c 6c 20 63  imeout=N] will c
1c2c0 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 62 75 73  hange the.** bus
1c2d0 79 20 68 61 6e 64 6c 65 72 20 61 6e 64 20 74 68  y handler and th
1c2e0 75 73 20 63 6c 65 61 72 20 61 6e 79 20 70 72 65  us clear any pre
1c2f0 76 69 6f 75 73 6c 79 20 73 65 74 20 62 75 73 79  viously set busy
1c300 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20   handler..**.** 
1c310 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63  The busy callbac
1c320 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b  k should not tak
1c330 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68  e any actions wh
1c340 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a  ich modify the.*
1c350 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
1c360 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
1c370 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ed the busy hand
1c380 6c 65 72 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  ler.  In other w
1c390 6f 72 64 73 2c 0a 2a 2a 20 74 68 65 20 62 75 73  ords,.** the bus
1c3a0 79 20 68 61 6e 64 6c 65 72 20 69 73 20 6e 6f 74  y handler is not
1c3b0 20 72 65 65 6e 74 72 61 6e 74 2e 20 20 41 6e 79   reentrant.  Any
1c3c0 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a   such actions.**
1c3d0 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66   result in undef
1c3e0 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a  ined behavior..*
1c3f0 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e  * .** A busy han
1c400 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c  dler must not cl
1c410 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ose the database
1c420 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f   connection.** o
1c430 72 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  r [prepared stat
1c440 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f  ement] that invo
1c450 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e  ked the busy han
1c460 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  dler..*/.int sql
1c470 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
1c480 72 28 73 71 6c 69 74 65 33 2a 2c 69 6e 74 28 2a  r(sqlite3*,int(*
1c490 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 76 6f 69  )(void*,int),voi
1c4a0 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
1c4b0 33 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 79  3REF: Set A Busy
1c4c0 20 54 69 6d 65 6f 75 74 0a 2a 2a 20 4d 45 54 48   Timeout.** METH
1c4d0 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
1c4e0 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
1c4f0 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f  sets a [sqlite3_
1c500 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62  busy_handler | b
1c510 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61  usy handler] tha
1c520 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20  t sleeps.** for 
1c530 61 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75  a specified amou
1c540 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20  nt of time when 
1c550 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65  a table is locke
1c560 64 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72  d.  ^The handler
1c570 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d  .** will sleep m
1c580 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e  ultiple times un
1c590 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73  til at least "ms
1c5a0 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  " milliseconds o
1c5b0 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61  f sleeping.** ha
1c5c0 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20  ve accumulated. 
1c5d0 20 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73 74   ^After at least
1c5e0 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e   "ms" millisecon
1c5f0 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a  ds of sleeping,.
1c600 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72  ** the handler r
1c610 65 74 75 72 6e 73 20 30 20 77 68 69 63 68 20 63  eturns 0 which c
1c620 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73  auses [sqlite3_s
1c630 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e  tep()] to return
1c640 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  .** [SQLITE_BUSY
1c650 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e  ]..**.** ^Callin
1c660 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  g this routine w
1c670 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20  ith an argument 
1c680 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75  less than or equ
1c690 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75  al to zero.** tu
1c6a0 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79  rns off all busy
1c6b0 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a   handlers..**.**
1c6c0 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c   ^(There can onl
1c6d0 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75  y be a single bu
1c6e0 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61  sy handler for a
1c6f0 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b   particular.** [
1c700 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1c710 69 6f 6e 5d 20 61 74 20 61 6e 79 20 67 69 76 65  ion] at any give
1c720 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e  n moment.  If an
1c730 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c  other busy handl
1c740 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65  er.** was define
1c750 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74  d  (using [sqlit
1c760 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
1c770 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c  )]) prior to cal
1c780 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75  ling.** this rou
1c790 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72  tine, that other
1c7a0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
1c7b0 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2a 0a 2a   cleared.)^.**.*
1c7c0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 50 52  * See also:  [PR
1c7d0 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75  AGMA busy_timeou
1c7e0 74 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  t].*/.int sqlite
1c7f0 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73  3_busy_timeout(s
1c800 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29  qlite3*, int ms)
1c810 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1c820 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52  F: Convenience R
1c830 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e  outines For Runn
1c840 69 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 20 4d  ing Queries.** M
1c850 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
1c860 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 6c  *.** This is a l
1c870 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 20  egacy interface 
1c880 74 68 61 74 20 69 73 20 70 72 65 73 65 72 76 65  that is preserve
1c890 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20  d for backwards 
1c8a0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
1c8b0 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20 69 6e  * Use of this in
1c8c0 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72  terface is not r
1c8d0 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a  ecommended..**.*
1c8e0 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20  * Definition: A 
1c8f0 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c  <b>result table<
1c900 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61  /b> is memory da
1c910 74 61 20 73 74 72 75 63 74 75 72 65 20 63 72 65  ta structure cre
1c920 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b  ated by the.** [
1c930 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1c940 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20  e()] interface. 
1c950 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
1c960 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63  records the.** c
1c970 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72 65  omplete query re
1c980 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f  sults from one o
1c990 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a  r more queries..
1c9a0 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20  **.** The table 
1c9b0 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73  conceptually has
1c9c0 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77   a number of row
1c9d0 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20  s and columns.  
1c9e0 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d  But.** these num
1c9f0 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72  bers are not par
1ca00 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  t of the result 
1ca10 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54  table itself.  T
1ca20 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20  hese.** numbers 
1ca30 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70  are obtained sep
1ca40 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20  arately.  Let N 
1ca50 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  be the number of
1ca60 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62   rows.** and M b
1ca70 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  e the number of 
1ca80 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41  columns..**.** A
1ca90 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73   result table is
1caa0 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
1cab0 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65  nters to zero-te
1cac0 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
1cad0 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65  trings..** There
1cae0 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65   are (N+1)*M ele
1caf0 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72  ments in the arr
1cb00 61 79 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d  ay.  The first M
1cb10 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a   pointers point.
1cb20 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69  ** to zero-termi
1cb30 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68  nated strings th
1cb40 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20  at  contain the 
1cb50 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c  names of the col
1cb60 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d  umns..** The rem
1cb70 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61  aining entries a
1cb80 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72  ll point to quer
1cb90 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c  y results.  NULL
1cba0 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a   values result.*
1cbb0 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  * in NULL pointe
1cbc0 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76  rs.  All other v
1cbd0 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68 65  alues are in the
1cbe0 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65  ir UTF-8 zero-te
1cbf0 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69  rminated.** stri
1cc00 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  ng representatio
1cc10 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 62 79  n as returned by
1cc20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
1cc30 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _text()]..**.** 
1cc40 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d  A result table m
1cc50 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20  ight consist of 
1cc60 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f  one or more memo
1cc70 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a  ry allocations..
1cc80 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66  ** It is not saf
1cc90 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 73 75  e to pass a resu
1cca0 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c  lt table directl
1ccb0 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72  y to [sqlite3_fr
1ccc0 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75  ee()]..** A resu
1ccd0 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20  lt table should 
1cce0 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75  be deallocated u
1ccf0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72  sing [sqlite3_fr
1cd00 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a  ee_table()]..**.
1cd10 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 6d 70  ** ^(As an examp
1cd20 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  le of the result
1cd30 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73   table format, s
1cd40 75 70 70 6f 73 65 20 61 20 71 75 65 72 79 20 72  uppose a query r
1cd50 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66  esult.** is as f
1cd60 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
1cd70 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1cd80 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20  **        Name  
1cd90 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20        | Age.**  
1cda0 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d        ----------
1cdb0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a  -------------.**
1cdc0 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 20 20          Alice   
1cdd0 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20      | 43.**     
1cde0 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c     Bob         |
1cdf0 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69   28.**        Ci
1ce00 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a  ndy       | 21.*
1ce10 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1ce20 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72  uote>.**.** Ther
1ce30 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e  e are two column
1ce40 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65   (M==2) and thre
1ce50 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20  e rows (N==3).  
1ce60 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75  Thus the.** resu
1ce70 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38 20 65  lt table has 8 e
1ce80 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65  ntries.  Suppose
1ce90 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
1cea0 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69  e is stored.** i
1ceb0 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73  n an array names
1cec0 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e   azResult.  Then
1ced0 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20   azResult holds 
1cee0 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a  this content:.**
1cef0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1cf00 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20  <pre>.**        
1cf10 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20  azResult&#91;0] 
1cf20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20  = "Name";.**    
1cf30 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1cf40 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20  ;1] = "Age";.** 
1cf50 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1cf60 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22  #91;2] = "Alice"
1cf70 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1cf80 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34  sult&#91;3] = "4
1cf90 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  3";.**        az
1cfa0 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20  Result&#91;4] = 
1cfb0 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20  "Bob";.**       
1cfc0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d   azResult&#91;5]
1cfd0 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20   = "28";.**     
1cfe0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1cff0 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a  6] = "Cindy";.**
1d000 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1d010 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a  &#91;7] = "21";.
1d020 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1d030 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  quote>)^.**.** ^
1d040 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
1d050 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e  table() function
1d060 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f   evaluates one o
1d070 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f  r more.** semico
1d080 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51  lon-separated SQ
1d090 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20  L statements in 
1d0a0 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  the zero-termina
1d0b0 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72  ted UTF-8.** str
1d0c0 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70  ing of its 2nd p
1d0d0 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74  arameter and ret
1d0e0 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61  urns a result ta
1d0f0 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f  ble to the.** po
1d100 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69  inter given in i
1d110 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  ts 3rd parameter
1d120 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68  ..**.** After th
1d130 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68 61  e application ha
1d140 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
1d150 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 20  the result from 
1d160 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1d170 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20  e(),.** it must 
1d180 70 61 73 73 20 74 68 65 20 72 65 73 75 6c 74 20  pass the result 
1d190 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f  table pointer to
1d1a0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61   sqlite3_free_ta
1d1b0 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74  ble() in order t
1d1c0 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65  o.** release the
1d1d0 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73   memory that was
1d1e0 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61   malloced.  Beca
1d1f0 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 74  use of the way t
1d200 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  he.** [sqlite3_m
1d210 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73  alloc()] happens
1d220 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f   within sqlite3_
1d230 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65  get_table(), the
1d240 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63   calling.** func
1d250 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72  tion must not tr
1d260 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74  y to call [sqlit
1d270 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63  e3_free()] direc
1d280 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73  tly.  Only.** [s
1d290 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
1d2a0 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20  e()] is able to 
1d2b0 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f  release the memo
1d2c0 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20  ry properly and 
1d2d0 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68  safely..**.** Th
1d2e0 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  e sqlite3_get_ta
1d2f0 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ble() interface 
1d300 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61  is implemented a
1d310 73 20 61 20 77 72 61 70 70 65 72 20 61 72 6f 75  s a wrapper arou
1d320 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  nd.** [sqlite3_e
1d330 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c  xec()].  The sql
1d340 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1d350 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f   routine does no
1d360 74 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a  t have access.**
1d370 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c   to any internal
1d380 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73   data structures
1d390 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20   of SQLite.  It 
1d3a0 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75  uses only the pu
1d3b0 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63  blic.** interfac
1d3c0 65 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20  e defined here. 
1d3d0 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63   As a consequenc
1d3e0 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f  e, errors that o
1d3f0 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77  ccur in the.** w
1d400 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74  rapper layer out
1d410 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65  side of the inte
1d420 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78  rnal [sqlite3_ex
1d430 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e  ec()] call are n
1d440 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20  ot.** reflected 
1d450 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  in subsequent ca
1d460 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
1d470 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a  errcode()] or.**
1d480 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
1d490 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
1d4a0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20  te3_get_table(. 
1d4b0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
1d4c0 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65         /* An ope
1d4d0 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20  n database */.  
1d4e0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
1d4f0 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20  ,     /* SQL to 
1d500 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a  be evaluated */.
1d510 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73    char ***pazRes
1d520 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c  ult,    /* Resul
1d530 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20  ts of the query 
1d540 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c  */.  int *pnRow,
1d550 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75             /* Nu
1d560 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72  mber of result r
1d570 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65  ows written here
1d580 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c   */.  int *pnCol
1d590 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e  umn,        /* N
1d5a0 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20  umber of result 
1d5b0 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20  columns written 
1d5c0 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a  here */.  char *
1d5d0 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20  *pzErrmsg       
1d5e0 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69  /* Error msg wri
1d5f0 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a  tten here */.);.
1d600 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65  void sqlite3_fre
1d610 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72  e_table(char **r
1d620 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  esult);../*.** C
1d630 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74  API3REF: Formatt
1d640 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69  ed String Printi
1d650 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a  ng Functions.**.
1d660 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
1d670 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65  s are work-alike
1d680 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66  s of the "printf
1d690 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75  ()" family of fu
1d6a0 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20  nctions.** from 
1d6b0 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
1d6c0 69 62 72 61 72 79 2e 0a 2a 2a 20 54 68 65 73 65  ibrary..** These
1d6d0 20 72 6f 75 74 69 6e 65 73 20 75 6e 64 65 72 73   routines unders
1d6e0 74 61 6e 64 20 6d 6f 73 74 20 6f 66 20 74 68 65  tand most of the
1d6f0 20 63 6f 6d 6d 6f 6e 20 4b 26 52 20 66 6f 72 6d   common K&R form
1d700 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 2c 0a  atting options,.
1d710 2a 2a 20 70 6c 75 73 20 73 6f 6d 65 20 61 64 64  ** plus some add
1d720 69 74 69 6f 6e 61 6c 20 6e 6f 6e 2d 73 74 61 6e  itional non-stan
1d730 64 61 72 64 20 66 6f 72 6d 61 74 73 2c 20 64 65  dard formats, de
1d740 74 61 69 6c 65 64 20 62 65 6c 6f 77 2e 0a 2a 2a  tailed below..**
1d750 20 4e 6f 74 65 20 74 68 61 74 20 73 6f 6d 65 20   Note that some 
1d760 6f 66 20 74 68 65 20 6d 6f 72 65 20 6f 62 73 63  of the more obsc
1d770 75 72 65 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f  ure formatting o
1d780 70 74 69 6f 6e 73 20 66 72 6f 6d 20 72 65 63 65  ptions from rece
1d790 6e 74 0a 2a 2a 20 43 2d 6c 69 62 72 61 72 79 20  nt.** C-library 
1d7a0 73 74 61 6e 64 61 72 64 73 20 61 72 65 20 6f 6d  standards are om
1d7b0 69 74 74 65 64 20 66 72 6f 6d 20 74 68 69 73 20  itted from this 
1d7c0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a  implementation..
1d7d0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1d7e0 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64  e3_mprintf() and
1d7f0 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74   sqlite3_vmprint
1d800 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69  f() routines wri
1d810 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75  te their.** resu
1d820 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20  lts into memory 
1d830 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
1d840 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1d850 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73  ..** The strings
1d860 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
1d870 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20  se two routines 
1d880 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c  should be.** rel
1d890 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65  eased by [sqlite
1d8a0 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74  3_free()].  ^Bot
1d8b0 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  h routines retur
1d8c0 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e  n a.** NULL poin
1d8d0 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f  ter if [sqlite3_
1d8e0 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61  malloc()] is una
1d8f0 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
1d900 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79  enough.** memory
1d910 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73   to hold the res
1d920 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a  ulting string..*
1d930 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74  *.** ^(The sqlit
1d940 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f  e3_snprintf() ro
1d950 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72  utine is similar
1d960 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22   to "snprintf()"
1d970 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61   from.** the sta
1d980 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
1d990 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20    The result is 
1d9a0 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65  written into the
1d9b0 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c  .** buffer suppl
1d9c0 69 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ied as the secon
1d9d0 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73  d parameter whos
1d9e0 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20  e size is given 
1d9f0 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  by.** the first 
1da00 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20  parameter. Note 
1da10 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f  that the order o
1da20 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74  f the.** first t
1da30 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73  wo parameters is
1da40 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73   reversed from s
1da50 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68  nprintf().)^  Th
1da60 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74  is is an.** hist
1da70 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20  orical accident 
1da80 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66  that cannot be f
1da90 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 65  ixed without bre
1daa0 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72  aking.** backwar
1dab0 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
1dac0 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74  .  ^(Note also t
1dad0 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72  hat sqlite3_snpr
1dae0 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e  intf().** return
1daf0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69  s a pointer to i
1db00 74 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61  ts buffer instea
1db10 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20  d of the number 
1db20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73  of.** characters
1db30 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65   actually writte
1db40 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65  n into the buffe
1db50 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74  r.)^  We admit t
1db60 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  hat.** the numbe
1db70 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20  r of characters 
1db80 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65  written would be
1db90 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72   a more useful r
1dba0 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62  eturn.** value b
1dbb0 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61  ut we cannot cha
1dbc0 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  nge the implemen
1dbd0 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65  tation of sqlite
1dbe0 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
1dbf0 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61  now without brea
1dc00 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69  king compatibili
1dc10 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f  ty..**.** ^As lo
1dc20 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72  ng as the buffer
1dc30 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72   size is greater
1dc40 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69   than zero, sqli
1dc50 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
1dc60 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  * guarantees tha
1dc70 74 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20  t the buffer is 
1dc80 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d  always zero-term
1dc90 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69  inated.  ^The fi
1dca0 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  rst.** parameter
1dcb0 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61   "n" is the tota
1dcc0 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75  l size of the bu
1dcd0 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20  ffer, including 
1dce0 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65  space for.** the
1dcf0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
1dd00 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73  .  So the longes
1dd10 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61  t string that ca
1dd20 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a  n be completely.
1dd30 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20  ** written will 
1dd40 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72  be n-1 character
1dd50 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  s..**.** ^The sq
1dd60 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28  lite3_vsnprintf(
1dd70 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76  ) routine is a v
1dd80 61 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f  arargs version o
1dd90 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  f sqlite3_snprin
1dda0 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tf()..**.** Thes
1ddb0 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69  e routines all i
1ddc0 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64  mplement some ad
1ddd0 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74  ditional formatt
1dde0 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74  ing.** options t
1ddf0 68 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66  hat are useful f
1de00 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20  or constructing 
1de10 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
1de20 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73  ** All of the us
1de30 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72  ual printf() for
1de40 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20  matting options 
1de50 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74  apply.  In addit
1de60 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73  ion, there.** is
1de70 20 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c   are "%q", "%Q",
1de80 20 22 25 77 22 20 61 6e 64 20 22 25 7a 22 20 6f   "%w" and "%z" o
1de90 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ptions..**.** ^(
1dea0 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f  The %q option wo
1deb0 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74  rks like %s in t
1dec0 68 61 74 20 69 74 20 73 75 62 73 74 69 74 75 74  hat it substitut
1ded0 65 73 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61  es a nul-termina
1dee0 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72  ted.** string fr
1def0 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  om the argument 
1df00 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c  list.  But %q al
1df10 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79  so doubles every
1df20 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e   '\'' character.
1df30 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e  .** %q is design
1df40 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64  ed for use insid
1df50 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72  e a string liter
1df60 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c 69  al.)^  By doubli
1df70 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20  ng each '\''.** 
1df80 63 68 61 72 61 63 74 65 72 20 69 74 20 65 73 63  character it esc
1df90 61 70 65 73 20 74 68 61 74 20 63 68 61 72 61 63  apes that charac
1dfa0 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69  ter and allows i
1dfb0 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64  t to be inserted
1dfc0 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72   into.** the str
1dfd0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65  ing..**.** For e
1dfe0 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74  xample, assume t
1dff0 68 65 20 73 74 72 69 6e 67 20 76 61 72 69 61 62  he string variab
1e000 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e  le zText contain
1e010 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77  s text as follow
1e020 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
1e030 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
1e040 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74  har *zText = "It
1e050 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 22  's a happy day!"
1e060 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
1e070 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f  ckquote>.**.** O
1e080 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69 73 20  ne can use this 
1e090 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73  text in an SQL s
1e0a0 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c  tatement as foll
1e0b0 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
1e0c0 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1e0d0 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71   char *zSQL = sq
1e0e0 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49  lite3_mprintf("I
1e0f0 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
1e100 20 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20   VALUES('%q')", 
1e110 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69  zText);.**  sqli
1e120 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51  te3_exec(db, zSQ
1e130 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20  L, 0, 0, 0);.** 
1e140 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53   sqlite3_free(zS
1e150 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  QL);.** </pre></
1e160 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
1e170 2a 20 42 65 63 61 75 73 65 20 74 68 65 20 25 71  * Because the %q
1e180 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69   format string i
1e190 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27  s used, the '\''
1e1a0 20 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54   character in zT
1e1b0 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65  ext.** is escape
1e1c0 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65  d and the SQL ge
1e1d0 6e 65 72 61 74 65 64 20 69 73 20 61 73 20 66 6f  nerated is as fo
1e1e0 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
1e1f0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1e200 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  *  INSERT INTO t
1e210 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74  able1 VALUES('It
1e220 27 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21  ''s a happy day!
1e230 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  ').** </pre></bl
1e240 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
1e250 54 68 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e  This is correct.
1e260 20 20 48 61 64 20 77 65 20 75 73 65 64 20 25 73    Had we used %s
1e270 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20   instead of %q, 
1e280 74 68 65 20 67 65 6e 65 72 61 74 65 64 20 53 51  the generated SQ
1e290 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20  L.** would have 
1e2a0 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73  looked like this
1e2b0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1e2c0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e  ote><pre>.**  IN
1e2d0 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31  SERT INTO table1
1e2e0 20 56 41 4c 55 45 53 28 27 49 74 27 73 20 61 20   VALUES('It's a 
1e2f0 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a  happy day!');.**
1e300 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1e310 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ote>.**.** This 
1e320 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69  second example i
1e330 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20  s an SQL syntax 
1e340 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e  error.  As a gen
1e350 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68  eral rule you sh
1e360 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75  ould.** always u
1e370 73 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66  se %q instead of
1e380 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69   %s when inserti
1e390 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73  ng text into a s
1e3a0 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a  tring literal..*
1e3b0 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f 70  *.** ^(The %Q op
1e3c0 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20  tion works like 
1e3d0 25 71 20 65 78 63 65 70 74 20 69 74 20 61 6c 73  %q except it als
1e3e0 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75  o adds single qu
1e3f0 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74  otes around.** t
1e400 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68  he outside of th
1e410 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20  e total string. 
1e420 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69   Additionally, i
1e430 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
1e440 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65  in the.** argume
1e450 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c  nt list is a NUL
1e460 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75  L pointer, %Q su
1e470 62 73 74 69 74 75 74 65 73 20 74 68 65 20 74 65  bstitutes the te
1e480 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f  xt "NULL" (witho
1e490 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f  ut.** single quo
1e4a0 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72  tes).)^  So, for
1e4b0 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f   example, one co
1e4c0 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c  uld say:.**.** <
1e4d0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1e4e0 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20  .**  char *zSQL 
1e4f0 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  = sqlite3_mprint
1e500 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  f("INSERT INTO t
1e510 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22  able VALUES(%Q)"
1e520 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71  , zText);.**  sq
1e530 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a  lite3_exec(db, z
1e540 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a  SQL, 0, 0, 0);.*
1e550 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  *  sqlite3_free(
1e560 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  zSQL);.** </pre>
1e570 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1e580 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f  .** The code abo
1e590 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61  ve will render a
1e5a0 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61   correct SQL sta
1e5b0 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53  tement in the zS
1e5c0 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65  QL.** variable e
1e5d0 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74  ven if the zText
1e5e0 20 76 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e   variable is a N
1e5f0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
1e600 2a 2a 20 5e 28 54 68 65 20 22 25 77 22 20 66 6f  ** ^(The "%w" fo
1e610 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20  rmatting option 
1e620 69 73 20 6c 69 6b 65 20 22 25 71 22 20 65 78 63  is like "%q" exc
1e630 65 70 74 20 74 68 61 74 20 69 74 20 65 78 70 65  ept that it expe
1e640 63 74 73 20 74 6f 0a 2a 2a 20 62 65 20 63 6f 6e  cts to.** be con
1e650 74 61 69 6e 65 64 20 77 69 74 68 69 6e 20 64 6f  tained within do
1e660 75 62 6c 65 2d 71 75 6f 74 65 73 20 69 6e 73 74  uble-quotes inst
1e670 65 61 64 20 6f 66 20 73 69 6e 67 6c 65 20 71 75  ead of single qu
1e680 6f 74 65 73 2c 20 61 6e 64 20 69 74 0a 2a 2a 20  otes, and it.** 
1e690 65 73 63 61 70 65 73 20 74 68 65 20 64 6f 75 62  escapes the doub
1e6a0 6c 65 2d 71 75 6f 74 65 20 63 68 61 72 61 63 74  le-quote charact
1e6b0 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68  er instead of th
1e6c0 65 20 73 69 6e 67 6c 65 2d 71 75 6f 74 65 0a 2a  e single-quote.*
1e6d0 2a 20 63 68 61 72 61 63 74 65 72 2e 29 5e 20 20  * character.)^  
1e6e0 54 68 65 20 22 25 77 22 20 66 6f 72 6d 61 74 74  The "%w" formatt
1e6f0 69 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20 69 6e  ing option is in
1e700 74 65 6e 64 65 64 20 66 6f 72 20 73 61 66 65 6c  tended for safel
1e710 79 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74  y inserting.** t
1e720 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20  able and column 
1e730 6e 61 6d 65 73 20 69 6e 74 6f 20 61 20 63 6f 6e  names into a con
1e740 73 74 72 75 63 74 65 64 20 53 51 4c 20 73 74 61  structed SQL sta
1e750 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28  tement..**.** ^(
1e760 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74  The "%z" formatt
1e770 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73  ing option works
1e780 20 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20 77   like "%s" but w
1e790 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74  ith the.** addit
1e7a0 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 74  ion that after t
1e7b0 68 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 65  he string has be
1e7c0 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69  en read and copi
1e7d0 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72  ed into.** the r
1e7e0 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f  esult, [sqlite3_
1e7f0 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65  free()] is calle
1e800 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73  d on the input s
1e810 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72  tring.)^.*/.char
1e820 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74   *sqlite3_mprint
1e830 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e  f(const char*,..
1e840 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  .);.char *sqlite
1e850 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74  3_vmprintf(const
1e860 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29   char*, va_list)
1e870 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  ;.char *sqlite3_
1e880 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61  snprintf(int,cha
1e890 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  r*,const char*, 
1e8a0 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69  ...);.char *sqli
1e8b0 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e  te3_vsnprintf(in
1e8c0 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t,char*,const ch
1e8d0 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a  ar*, va_list);..
1e8e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1e8f0 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f  Memory Allocatio
1e900 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a  n Subsystem.**.*
1e910 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72  * The SQLite cor
1e920 65 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72  e uses these thr
1e930 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20  ee routines for 
1e940 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a  all of its own.*
1e950 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72  * internal memor
1e960 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
1e970 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68  ds. "Core" in th
1e980 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65  e previous sente
1e990 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  nce.** does not 
1e9a0 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e  include operatin
1e9b0 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69  g-system specifi
1e9c0 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  c VFS implementa
1e9d0 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69  tion.  The.** Wi
1e9e0 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e  ndows VFS uses n
1e9f0 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61  ative malloc() a
1ea00 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f  nd free() for so
1ea10 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a  me operations..*
1ea20 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1ea30 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69  3_malloc() routi
1ea40 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ne returns a poi
1ea50 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a  nter to a block.
1ea60 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20  ** of memory at 
1ea70 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e  least N bytes in
1ea80 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e   length, where N
1ea90 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65   is the paramete
1eaa0 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  r..** ^If sqlite
1eab0 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e  3_malloc() is un
1eac0 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73  able to obtain s
1ead0 75 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a  ufficient free.*
1eae0 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74  * memory, it ret
1eaf0 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
1eb00 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61  ter.  ^If the pa
1eb10 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20  rameter N to.** 
1eb20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1eb30 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61   is zero or nega
1eb40 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65  tive then sqlite
1eb50 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72  3_malloc() retur
1eb60 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69  ns.** a NULL poi
1eb70 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nter..**.** ^The
1eb80 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36   sqlite3_malloc6
1eb90 34 28 4e 29 20 72 6f 75 74 69 6e 65 20 77 6f 72  4(N) routine wor
1eba0 6b 73 20 6a 75 73 74 20 6c 69 6b 65 0a 2a 2a 20  ks just like.** 
1ebb0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e  sqlite3_malloc(N
1ebc0 29 20 65 78 63 65 70 74 20 74 68 61 74 20 4e 20  ) except that N 
1ebd0 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 36  is an unsigned 6
1ebe0 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 69 6e  4-bit integer in
1ebf0 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 73 69  stead.** of a si
1ec00 67 6e 65 64 20 33 32 2d 62 69 74 20 69 6e 74 65  gned 32-bit inte
1ec10 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c  ger..**.** ^Call
1ec20 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65  ing sqlite3_free
1ec30 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65  () with a pointe
1ec40 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74  r previously ret
1ec50 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69  urned.** by sqli
1ec60 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20  te3_malloc() or 
1ec70 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1ec80 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 20  ) releases that 
1ec90 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61  memory so.** tha
1eca0 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 65  t it might be re
1ecb0 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69  used.  ^The sqli
1ecc0 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69  te3_free() routi
1ecd0 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70  ne is.** a no-op
1ece0 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69   if is called wi
1ecf0 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
1ed00 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55  r.  Passing a NU
1ed10 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f  LL pointer.** to
1ed20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
1ed30 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66  is harmless.  Af
1ed40 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c  ter being freed,
1ed50 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c   memory.** shoul
1ed60 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 61  d neither be rea
1ed70 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20  d nor written.  
1ed80 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65  Even reading pre
1ed90 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a  viously freed.**
1eda0 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65   memory might re
1edb0 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e  sult in a segmen
1edc0 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20  tation fault or 
1edd0 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72  other severe err
1ede0 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f  or..** Memory co
1edf0 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d  rruption, a segm
1ee00 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20  entation fault, 
1ee10 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20  or other severe 
1ee20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72  error.** might r
1ee30 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33  esult if sqlite3
1ee40 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65  _free() is calle
1ee50 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c  d with a non-NUL
1ee60 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a  L pointer that.*
1ee70 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e  * was not obtain
1ee80 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ed from sqlite3_
1ee90 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69  malloc() or sqli
1eea0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a  te3_realloc()..*
1eeb0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1eec0 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69  3_realloc(X,N) i
1eed0 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
1eee0 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a  s to resize a.**
1eef0 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c   prior memory al
1ef00 6c 6f 63 61 74 69 6f 6e 20 58 20 74 6f 20 62 65  location X to be
1ef10 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
1ef20 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 58 20  s..** ^If the X 
1ef30 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
1ef40 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e  ite3_realloc(X,N
1ef50 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70  ).** is a NULL p
1ef60 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20  ointer then its 
1ef70 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e  behavior is iden
1ef80 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67  tical to calling
1ef90 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
1efa0 6f 63 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20 74 68  oc(N)..** ^If th
1efb0 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e N parameter to
1efc0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1efd0 28 58 2c 4e 29 20 69 73 20 7a 65 72 6f 20 6f 72  (X,N) is zero or
1efe0 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65  .** negative the
1eff0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
1f000 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61  s exactly the sa
1f010 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a  me as calling.**
1f020 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 58 29   sqlite3_free(X)
1f030 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65  ..** ^sqlite3_re
1f040 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72  alloc(X,N) retur
1f050 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
1f060 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
1f070 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61  ion.** of at lea
1f080 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69  st N bytes in si
1f090 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 69 6e  ze or NULL if in
1f0a0 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72  sufficient memor
1f0b0 79 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a  y is available..
1f0c0 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20  ** ^If M is the 
1f0d0 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f  size of the prio
1f0e0 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68  r allocation, th
1f0f0 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65  en min(N,M) byte
1f100 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f  s.** of the prio
1f110 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65  r allocation are
1f120 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65   copied into the
1f130 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75   beginning of bu
1f140 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ffer returned.**
1f150 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   by sqlite3_real
1f160 6c 6f 63 28 58 2c 4e 29 20 61 6e 64 20 74 68 65  loc(X,N) and the
1f170 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
1f180 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e  n is freed..** ^
1f190 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  If sqlite3_reall
1f1a0 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 20  oc(X,N) returns 
1f1b0 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20 70 6f  NULL and N is po
1f1c0 73 69 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65  sitive, then the
1f1d0 0a 2a 2a 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  .** prior alloca
1f1e0 74 69 6f 6e 20 69 73 20 6e 6f 74 20 66 72 65 65  tion is not free
1f1f0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
1f200 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28  lite3_realloc64(
1f210 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 73 20  X,N) interfaces 
1f220 77 6f 72 6b 73 20 74 68 65 20 73 61 6d 65 20 61  works the same a
1f230 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 61  s.** sqlite3_rea
1f240 6c 6c 6f 63 28 58 2c 4e 29 20 65 78 63 65 70 74  lloc(X,N) except
1f250 20 74 68 61 74 20 4e 20 69 73 20 61 20 36 34 2d   that N is a 64-
1f260 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74  bit unsigned int
1f270 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20  eger instead.** 
1f280 6f 66 20 61 20 33 32 2d 62 69 74 20 73 69 67 6e  of a 32-bit sign
1f290 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a  ed integer..**.*
1f2a0 2a 20 5e 49 66 20 58 20 69 73 20 61 20 6d 65 6d  * ^If X is a mem
1f2b0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 70  ory allocation p
1f2c0 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e  reviously obtain
1f2d0 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ed from sqlite3_
1f2e0 6d 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c  malloc(),.** sql
1f2f0 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c  ite3_malloc64(),
1f300 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1f310 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  (), or sqlite3_r
1f320 65 61 6c 6c 6f 63 36 34 28 29 2c 20 74 68 65 6e  ealloc64(), then
1f330 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a  .** sqlite3_msiz
1f340 65 28 58 29 20 72 65 74 75 72 6e 73 20 74 68 65  e(X) returns the
1f350 20 73 69 7a 65 20 6f 66 20 74 68 61 74 20 6d 65   size of that me
1f360 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1f370 69 6e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 54 68  in bytes..** ^Th
1f380 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
1f390 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a   by sqlite3_msiz
1f3a0 65 28 58 29 20 6d 69 67 68 74 20 62 65 20 6c 61  e(X) might be la
1f3b0 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 6e 75  rger than the nu
1f3c0 6d 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74 65 73  mber.** of bytes
1f3d0 20 72 65 71 75 65 73 74 65 64 20 77 68 65 6e 20   requested when 
1f3e0 58 20 77 61 73 20 61 6c 6c 6f 63 61 74 65 64 2e  X was allocated.
1f3f0 20 20 5e 49 66 20 58 20 69 73 20 61 20 4e 55 4c    ^If X is a NUL
1f400 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a 2a  L pointer then.*
1f410 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28  * sqlite3_msize(
1f420 58 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e  X) returns zero.
1f430 20 20 49 66 20 58 20 70 6f 69 6e 74 73 20 74 6f    If X points to
1f440 20 73 6f 6d 65 74 68 69 6e 67 20 74 68 61 74 20   something that 
1f450 69 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 62 65  is not.** the be
1f460 67 69 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d 6f 72  ginning of memor
1f470 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 6f 72  y allocation, or
1f480 20 69 66 20 69 74 20 70 6f 69 6e 74 73 20 74 6f   if it points to
1f490 20 61 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a 20 76   a formerly.** v
1f4a0 61 6c 69 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  alid memory allo
1f4b0 63 61 74 69 6f 6e 20 74 68 61 74 20 68 61 73 20  cation that has 
1f4c0 6e 6f 77 20 62 65 65 6e 20 66 72 65 65 64 2c 20  now been freed, 
1f4d0 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
1f4e0 72 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  r.** of sqlite3_
1f4f0 6d 73 69 7a 65 28 58 29 20 69 73 20 75 6e 64 65  msize(X) is unde
1f500 66 69 6e 65 64 20 61 6e 64 20 70 6f 73 73 69 62  fined and possib
1f510 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a  ly harmful..**.*
1f520 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65  * ^The memory re
1f530 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
1f540 33 5f 6d 61 6c 6c 6f 63 28 29 2c 20 73 71 6c 69  3_malloc(), sqli
1f550 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 0a 2a  te3_realloc(),.*
1f560 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
1f570 36 34 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65  64(), and sqlite
1f580 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29 0a 2a 2a  3_realloc64().**
1f590 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e   is always align
1f5a0 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61  ed to at least a
1f5b0 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72  n 8 byte boundar
1f5c0 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20  y, or to a.** 4 
1f5d0 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69 66  byte boundary if
1f5e0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42   the [SQLITE_4_B
1f5f0 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c  YTE_ALIGNED_MALL
1f600 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  OC] compile-time
1f610 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  .** option is us
1f620 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c  ed..**.** In SQL
1f630 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
1f640 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20  0 and 3.5.1, it 
1f650 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  was possible to 
1f660 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51  define.** the SQ
1f670 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59  LITE_OMIT_MEMORY
1f680 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63  _ALLOCATION whic
1f690 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68  h would cause th
1f6a0 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d  e built-in.** im
1f6b0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
1f6c0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74  these routines t
1f6d0 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54  o be omitted.  T
1f6e0 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a  hat capability.*
1f6f0 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70  * is no longer p
1f700 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62  rovided.  Only b
1f710 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
1f720 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65  llocators can be
1f730 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69   used..**.** Pri
1f740 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72  or to SQLite ver
1f750 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68 65  sion 3.7.10, the
1f760 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65   Windows OS inte
1f770 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c  rface layer call
1f780 65 64 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d  ed.** the system
1f790 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72   malloc() and fr
1f7a0 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 68  ee() directly wh
1f7b0 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a  en converting.**
1f7c0 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65   filenames betwe
1f7d0 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63  en the UTF-8 enc
1f7e0 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 51  oding used by SQ
1f7f0 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74  Lite.** and what
1f800 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e  ever filename en
1f810 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 62  coding is used b
1f820 79 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72  y the particular
1f830 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74   Windows.** inst
1f840 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72  allation.  Memor
1f850 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
1f860 6f 72 73 20 77 65 72 65 20 64 65 74 65 63 74 65  ors were detecte
1f870 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 77  d, but.** they w
1f880 65 72 65 20 72 65 70 6f 72 74 65 64 20 62 61 63  ere reported bac
1f890 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e  k as [SQLITE_CAN
1f8a0 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51  TOPEN] or.** [SQ
1f8b0 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68  LITE_IOERR] rath
1f8c0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
1f8d0 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  NOMEM]..**.** Th
1f8e0 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65  e pointer argume
1f8f0 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  nts to [sqlite3_
1f900 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  free()] and [sql
1f910 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a  ite3_realloc()].
1f920 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 65  ** must be eithe
1f930 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70  r NULL or else p
1f940 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64  ointers obtained
1f950 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a   from a prior.**
1f960 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b   invocation of [
1f970 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1f980 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
1f990 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61  alloc()] that ha
1f9a0 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65  ve.** not yet be
1f9b0 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a  en released..**.
1f9c0 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
1f9d0 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64  on must not read
1f9e0 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70 61   or write any pa
1f9f0 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b  rt of.** a block
1fa00 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72   of memory after
1fa10 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c   it has been rel
1fa20 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b  eased using.** [
1fa30 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
1fa40 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
1fa50 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20  loc()]..*/.void 
1fa60 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  *sqlite3_malloc(
1fa70 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69  int);.void *sqli
1fa80 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 73 71 6c  te3_malloc64(sql
1fa90 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 76 6f  ite3_uint64);.vo
1faa0 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c  id *sqlite3_real
1fab0 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b  loc(void*, int);
1fac0 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72  .void *sqlite3_r
1fad0 65 61 6c 6c 6f 63 36 34 28 76 6f 69 64 2a 2c 20  ealloc64(void*, 
1fae0 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b  sqlite3_uint64);
1faf0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72  .void sqlite3_fr
1fb00 65 65 28 76 6f 69 64 2a 29 3b 0a 73 71 6c 69 74  ee(void*);.sqlit
1fb10 65 33 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65  e3_uint64 sqlite
1fb20 33 5f 6d 73 69 7a 65 28 76 6f 69 64 2a 29 3b 0a  3_msize(void*);.
1fb30 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1fb40 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f   Memory Allocato
1fb50 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a  r Statistics.**.
1fb60 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64  ** SQLite provid
1fb70 65 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74  es these two int
1fb80 65 72 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f  erfaces for repo
1fb90 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61  rting on the sta
1fba0 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  tus.** of the [s
1fbb0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1fbc0 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  , [sqlite3_free(
1fbd0 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
1fbe0 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72  _realloc()].** r
1fbf0 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66  outines, which f
1fc00 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e  orm the built-in
1fc10 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1fc20 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a  on subsystem..**
1fc30 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
1fc40 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
1fc50 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
1fc60 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
1fc70 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72  ytes.** of memor
1fc80 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73  y currently outs
1fc90 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65  tanding (malloce
1fca0 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29  d but not freed)
1fcb0 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  ..** ^The [sqlit
1fcc0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
1fcd0 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72  ter()] routine r
1fce0 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d  eturns the maxim
1fcf0 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b  um.** value of [
1fd00 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
1fd10 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65  sed()] since the
1fd20 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b   high-water mark
1fd30 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73  .** was last res
1fd40 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73  et.  ^The values
1fd50 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
1fd60 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
1fd70 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  d()] and.** [sql
1fd80 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
1fd90 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65  water()] include
1fda0 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a   any overhead.**
1fdb0 20 61 64 64 65 64 20 62 79 20 53 51 4c 69 74 65   added by SQLite
1fdc0 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e   in its implemen
1fdd0 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  tation of [sqlit
1fde0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a  e3_malloc()],.**
1fdf0 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61   but not overhea
1fe00 64 20 61 64 64 65 64 20 62 79 20 74 68 65 20 61  d added by the a
1fe10 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79  ny underlying sy
1fe20 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20  stem library.** 
1fe30 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73  routines that [s
1fe40 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1fe50 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a   may call..**.**
1fe60 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67   ^The memory hig
1fe70 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20  h-water mark is 
1fe80 72 65 73 65 74 20 74 6f 20 74 68 65 20 63 75 72  reset to the cur
1fe90 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a  rent value of.**
1fea0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1feb0 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20  _used()] if and 
1fec0 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72 61  only if the para
1fed0 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c  meter to.** [sql
1fee0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
1fef0 77 61 74 65 72 28 29 5d 20 69 73 20 74 72 75 65  water()] is true
1ff00 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65  .  ^The value re
1ff10 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71  turned.** by [sq
1ff20 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
1ff30 68 77 61 74 65 72 28 31 29 5d 20 69 73 20 74 68  hwater(1)] is th
1ff40 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72  e high-water mar
1ff50 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68  k.** prior to th
1ff60 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69  e reset..*/.sqli
1ff70 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
1ff80 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f  3_memory_used(vo
1ff90 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74  id);.sqlite3_int
1ffa0 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  64 sqlite3_memor
1ffb0 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 20  y_highwater(int 
1ffc0 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a  resetFlag);../*.
1ffd0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 65  ** CAPI3REF: Pse
1ffe0 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65  udo-Random Numbe
1fff0 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a  r Generator.**.*
20000 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e  * SQLite contain
20010 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79  s a high-quality
20020 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e   pseudo-random n
20030 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20  umber generator 
20040 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a  (PRNG) used to.*
20050 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20  * select random 
20060 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d  [ROWID | ROWIDs]
20070 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20   when inserting 
20080 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f  new records into
20090 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a   a table that.**
200a0 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 68   already uses th
200b0 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62  e largest possib
200c0 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65  le [ROWID].  The
200d0 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73   PRNG is also us
200e0 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75  ed for.** the bu
200f0 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20  ild-in random() 
20100 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29  and randomblob()
20110 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20   SQL functions. 
20120 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
20130 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63  allows.** applic
20140 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73  ations to access
20150 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66   the same PRNG f
20160 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65  or other purpose
20170 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c  s..**.** ^A call
20180 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   to this routine
20190 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20   stores N bytes 
201a0 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e  of randomness in
201b0 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 20  to buffer P..** 
201c0 5e 54 68 65 20 50 20 70 61 72 61 6d 65 74 65 72  ^The P parameter
201d0 20 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c 20 70   can be a NULL p
201e0 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ointer..**.** ^I
201f0 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68  f this routine h
20200 61 73 20 6e 6f 74 20 62 65 65 6e 20 70 72 65 76  as not been prev
20210 69 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20 6f 72  iously called or
20220 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 73   if the previous
20230 0a 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e 20 6c  .** call had N l
20240 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 6f 72 20  ess than one or 
20250 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66  a NULL pointer f
20260 6f 72 20 50 2c 20 74 68 65 6e 20 74 68 65 20 50  or P, then the P
20270 52 4e 47 20 69 73 0a 2a 2a 20 73 65 65 64 65 64  RNG is.** seeded
20280 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73   using randomnes
20290 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  s obtained from 
202a0 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20  the xRandomness 
202b0 6d 65 74 68 6f 64 20 6f 66 0a 2a 2a 20 74 68 65  method of.** the
202c0 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
202d0 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a  3_vfs] object..*
202e0 2a 20 5e 49 66 20 74 68 65 20 70 72 65 76 69 6f  * ^If the previo
202f0 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20  us call to this 
20300 72 6f 75 74 69 6e 65 20 68 61 64 20 61 6e 20 4e  routine had an N
20310 20 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20 61 6e   of 1 or more an
20320 64 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c 20  d a.** non-NULL 
20330 50 20 74 68 65 6e 20 74 68 65 20 70 73 65 75 64  P then the pseud
20340 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20  o-randomness is 
20350 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74  generated.** int
20360 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68  ernally and with
20370 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20  out recourse to 
20380 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
20390 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a  ] xRandomness.**
203a0 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64   method..*/.void
203b0 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e   sqlite3_randomn
203c0 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20  ess(int N, void 
203d0 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  *P);../*.** CAPI
203e0 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69  3REF: Compile-Ti
203f0 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e  me Authorization
20400 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45   Callbacks.** ME
20410 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
20420 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
20430 65 20 72 65 67 69 73 74 65 72 73 20 61 6e 20 61  e registers an a
20440 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
20450 63 6b 20 77 69 74 68 20 61 20 70 61 72 74 69 63  ck with a partic
20460 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ular.** [databas
20470 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73  e connection], s
20480 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66  upplied in the f
20490 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  irst argument..*
204a0 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65  * ^The authorize
204b0 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
204c0 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61  voked as SQL sta
204d0 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e  tements are bein
204e0 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79  g compiled.** by
204f0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
20500 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  e()] or its vari
20510 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72  ants [sqlite3_pr
20520 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20  epare_v2()],.** 
20530 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
20540 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  16()] and [sqlit
20550 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
20560 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 75 73  )].  ^At various
20570 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e  .** points durin
20580 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f  g the compilatio
20590 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f  n process, as lo
205a0 67 69 63 20 69 73 20 62 65 69 6e 67 20 63 72 65  gic is being cre
205b0 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f  ated.** to perfo
205c0 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f  rm various actio
205d0 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ns, the authoriz
205e0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
205f0 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65  nvoked to.** see
20600 20 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e   if those action
20610 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20  s are allowed.  
20620 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20  ^The authorizer 
20630 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a  callback should.
20640 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
20650 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74  E_OK] to allow t
20660 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49  he action, [SQLI
20670 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69  TE_IGNORE] to di
20680 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70  sallow the.** sp
20690 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75  ecific action bu
206a0 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20  t allow the SQL 
206b0 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e  statement to con
206c0 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63  tinue to be.** c
206d0 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c  ompiled, or [SQL
206e0 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75  ITE_DENY] to cau
206f0 73 65 20 74 68 65 20 65 6e 74 69 72 65 20 53 51  se the entire SQ
20700 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62  L statement to b
20710 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69  e.** rejected wi
20720 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49  th an error.  ^I
20730 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  f the authorizer
20740 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
20750 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f  s.** any value o
20760 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
20770 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49  E_IGNORE], [SQLI
20780 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49  TE_OK], or [SQLI
20790 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e  TE_DENY].** then
207a0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72   the [sqlite3_pr
207b0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65  epare_v2()] or e
207c0 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74  quivalent call t
207d0 68 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a  hat triggered.**
207e0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
207f0 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61  will fail with a
20800 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  n error message.
20810 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
20820 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
20830 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68   [SQLITE_OK], th
20840 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65  at means the ope
20850 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73  ration.** reques
20860 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65  ted is ok.  ^Whe
20870 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  n the callback r
20880 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44  eturns [SQLITE_D
20890 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71  ENY], the.** [sq
208a0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
208b0 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e  ()] or equivalen
208c0 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67  t call that trig
208d0 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74  gered the.** aut
208e0 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69  horizer will fai
208f0 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  l with an error 
20900 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69  message explaini
20910 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73  ng that.** acces
20920 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a  s is denied. .**
20930 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70  .** ^The first p
20940 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
20950 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
20960 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ack is a copy of
20970 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61   the third.** pa
20980 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
20990 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
209a0 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63  rizer() interfac
209b0 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  e. ^The second p
209c0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74  arameter.** to t
209d0 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  he callback is a
209e0 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54  n integer [SQLIT
209f0 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20  E_COPY | action 
20a00 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69  code] that speci
20a10 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74  fies.** the part
20a20 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f  icular action to
20a30 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20   be authorized. 
20a40 5e 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75  ^The third throu
20a50 67 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 74  gh sixth paramet
20a60 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61  ers.** to the ca
20a70 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d  llback are zero-
20a80 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
20a90 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20  gs that contain 
20aa0 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65  additional.** de
20ab0 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20  tails about the 
20ac0 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74  action to be aut
20ad0 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  horized..**.** ^
20ae0 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f  If the action co
20af0 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45  de is [SQLITE_RE
20b00 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63  AD].** and the c
20b10 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
20b20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20  [SQLITE_IGNORE] 
20b30 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65  then the.** [pre
20b40 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
20b50 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f   statement is co
20b60 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73 75 62  nstructed to sub
20b70 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c  stitute.** a NUL
20b80 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65  L value in place
20b90 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f   of the table co
20ba0 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20  lumn that would 
20bb0 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61  have.** been rea
20bc0 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  d if [SQLITE_OK]
20bd0 20 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e   had been return
20be0 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45  ed.  The [SQLITE
20bf0 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75  _IGNORE].** retu
20c00 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  rn can be used t
20c10 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73  o deny an untrus
20c20 74 65 64 20 75 73 65 72 20 61 63 63 65 73 73 20  ted user access 
20c30 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a  to individual.**
20c40 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61   columns of a ta
20c50 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ble..** ^If the 
20c60 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b  action code is [
20c70 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61  SQLITE_DELETE] a
20c80 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  nd the callback 
20c90 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49  returns.** [SQLI
20ca0 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20  TE_IGNORE] then 
20cb0 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65  the [DELETE] ope
20cc0 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20  ration proceeds 
20cd0 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e  but the.** [trun
20ce0 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f  cate optimizatio
20cf0 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20 61  n] is disabled a
20d00 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20  nd all rows are 
20d10 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75  deleted individu
20d20 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61  ally..**.** An a
20d30 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65  uthorizer is use
20d40 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  d when [sqlite3_
20d50 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72  prepare | prepar
20d60 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74  ing].** SQL stat
20d70 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75  ements from an u
20d80 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c  ntrusted source,
20d90 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20   to ensure that 
20da0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
20db0 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79  ts.** do not try
20dc0 20 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 20   to access data 
20dd0 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c  they are not all
20de0 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20  owed to see, or 
20df0 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74  that they do not
20e00 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75  .** try to execu
20e10 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61  te malicious sta
20e20 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d  tements that dam
20e30 61 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  age the database
20e40 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c  .  For.** exampl
20e50 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  e, an applicatio
20e60 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73  n may allow a us
20e70 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69  er to enter arbi
20e80 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65  trary.** SQL que
20e90 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74  ries for evaluat
20ea0 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 73  ion by a databas
20eb0 65 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 6c  e.  But the appl
20ec0 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20  ication does.** 
20ed0 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 65  not want the use
20ee0 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20  r to be able to 
20ef0 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 63  make arbitrary c
20f00 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a  hanges to the.**
20f10 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61   database.  An a
20f20 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20  uthorizer could 
20f30 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70  then be put in p
20f40 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a  lace while the.*
20f50 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53  * user-entered S
20f60 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c  QL is being [sql
20f70 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70  ite3_prepare | p
20f80 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a  repared] that.**
20f90 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79   disallows every
20fa0 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45  thing except [SE
20fb0 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73  LECT] statements
20fc0 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74  ..**.** Applicat
20fd0 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74  ions that need t
20fe0 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72  o process SQL fr
20ff0 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75  om untrusted sou
21000 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c  rces.** might al
21010 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65  so consider lowe
21020 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69  ring resource li
21030 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69  mits using [sqli
21040 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20  te3_limit()].** 
21050 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74  and limiting dat
21060 61 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67  abase size using
21070 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63   the [max_page_c
21080 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a  ount] [PRAGMA].*
21090 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f  * in addition to
210a0 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72   using an author
210b0 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e  izer..**.** ^(On
210c0 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68  ly a single auth
210d0 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e  orizer can be in
210e0 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61   place on a data
210f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
21100 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45  ** at a time.  E
21110 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ach call to sqli
21120 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
21130 65 72 20 6f 76 65 72 72 69 64 65 73 20 74 68 65  er overrides the
21140 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c  .** previous cal
21150 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 74  l.)^  ^Disable t
21160 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79  he authorizer by
21170 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55   installing a NU
21180 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20  LL callback..** 
21190 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69  The authorizer i
211a0 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  s disabled by de
211b0 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  fault..**.** The
211c0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
211d0 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f  back must not do
211e0 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77   anything that w
211f0 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68  ill modify.** th
21200 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
21210 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
21220 65 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ed the authorize
21230 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e  r callback..** N
21240 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65  ote that [sqlite
21250 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
21260 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  and [sqlite3_ste
21270 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79  p()] both modify
21280 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61   their.** databa
21290 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66  se connections f
212a0 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f  or the meaning o
212b0 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68  f "modify" in th
212c0 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a  is paragraph..**
212d0 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74  .** ^When [sqlit
212e0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
212f0 20 69 73 20 75 73 65 64 20 74 6f 20 70 72 65 70   is used to prep
21300 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c  are a statement,
21310 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   the.** statemen
21320 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70 72  t might be re-pr
21330 65 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73  epared during [s
21340 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64  qlite3_step()] d
21350 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65  ue to a .** sche
21360 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63  ma change.  Henc
21370 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  e, the applicati
21380 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65  on should ensure
21390 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72   that the.** cor
213a0 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20  rect authorizer 
213b0 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73  callback remains
213c0 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67   in place during
213d0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
213e0 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f  ep()]..**.** ^No
213f0 74 65 20 74 68 61 74 20 74 68 65 20 61 75 74 68  te that the auth
21400 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
21410 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20  is invoked only 
21420 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74  during.** [sqlit
21430 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
21440 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20   its variants.  
21450 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73  Authorization is
21460 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65   not.** performe
21470 64 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65  d during stateme
21480 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e  nt evaluation in
21490 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
214a0 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20  ], unless.** as 
214b0 73 74 61 74 65 64 20 69 6e 20 74 68 65 20 70 72  stated in the pr
214c0 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68  evious paragraph
214d0 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  , sqlite3_step()
214e0 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69   invokes.** sqli
214f0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
21500 20 74 6f 20 72 65 70 72 65 70 61 72 65 20 61 20   to reprepare a 
21510 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20  statement after 
21520 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e  a schema change.
21530 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
21540 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a  set_authorizer(.
21550 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e    sqlite3*,.  in
21560 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a  t (*xAuth)(void*
21570 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a  ,int,const char*
21580 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
21590 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
215a0 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70  har*),.  void *p
215b0 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a  UserData.);../*.
215c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74  ** CAPI3REF: Aut
215d0 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43  horizer Return C
215e0 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  odes.**.** The [
215f0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
21600 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69  orizer | authori
21610 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  zer callback fun
21620 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72  ction] must.** r
21630 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51  eturn either [SQ
21640 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20  LITE_OK] or one 
21650 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e  of these two con
21660 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a  stants in order.
21670 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c  ** to signal SQL
21680 69 74 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e  ite whether or n
21690 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73  ot the action is
216a0 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65   permitted.  See
216b0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
216c0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
216d0 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63  | authorizer doc
216e0 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20  umentation] for 
216f0 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e  additional.** in
21700 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
21710 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 49 54   Note that SQLIT
21720 45 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f  E_IGNORE is also
21730 20 75 73 65 64 20 61 73 20 61 20 5b 63 6f 6e 66   used as a [conf
21740 6c 69 63 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20  lict resolution 
21750 6d 6f 64 65 5d 0a 2a 2a 20 72 65 74 75 72 6e 65  mode].** returne
21760 64 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69  d from the [sqli
21770 74 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66  te3_vtab_on_conf
21780 6c 69 63 74 28 29 5d 20 69 6e 74 65 72 66 61 63  lict()] interfac
21790 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e..*/.#define SQ
217a0 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20  LITE_DENY   1   
217b0 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c  /* Abort the SQL
217c0 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20   statement with 
217d0 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  an error */.#def
217e0 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ine SQLITE_IGNOR
217f0 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61  E 2   /* Don't a
21800 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74  llow access, but
21810 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20   don't generate 
21820 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a  an error */../*.
21830 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74  ** CAPI3REF: Aut
21840 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43  horizer Action C
21850 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  odes.**.** The [
21860 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
21870 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66  orizer()] interf
21880 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ace registers a 
21890 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
218a0 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76  n.** that is inv
218b0 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a  oked to authoriz
218c0 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74  e certain SQL st
218d0 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e  atement actions.
218e0 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20    The.** second 
218f0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
21900 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
21910 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61  integer code tha
21920 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77  t specifies.** w
21930 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65  hat action is be
21940 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20  ing authorized. 
21950 20 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69   These are the i
21960 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f  nteger action co
21970 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  des that.** the 
21980 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
21990 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65  ack may be passe
219a0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61  d..**.** These a
219b0 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65  ction code value
219c0 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b  s signify what k
219d0 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e  ind of operation
219e0 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74   is to be.** aut
219f0 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72  horized.  The 3r
21a00 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65  d and 4th parame
21a10 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 68  ters to the auth
21a20 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c  orization.** cal
21a30 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77  lback function w
21a40 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72  ill be parameter
21a50 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64  s or NULL depend
21a60 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20  ing on which of 
21a70 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69  these.** codes i
21a80 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65  s used as the se
21a90 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20  cond parameter. 
21aa0 20 5e 28 54 68 65 20 35 74 68 20 70 61 72 61 6d   ^(The 5th param
21ab0 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61  eter to the.** a
21ac0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
21ad0 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ck is the name o
21ae0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28  f the database (
21af0 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a  "main", "temp",.
21b00 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c  ** etc.) if appl
21b10 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20  icable.)^  ^The 
21b20 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  6th parameter to
21b30 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
21b40 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74  callback.** is t
21b50 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69  he name of the i
21b60 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65  nner-most trigge
21b70 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69  r or view that i
21b80 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
21b90 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20  r.** the access 
21ba0 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20  attempt or NULL 
21bb0 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61  if this access a
21bc0 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74  ttempt is direct
21bd0 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c  ly from.** top-l
21be0 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a  evel SQL code..*
21bf0 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /./*************
21c00 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
21c10 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33  ************** 3
21c20 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20  rd ************ 
21c30 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f  4th ***********/
21c40 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
21c50 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20  CREATE_INDEX    
21c60 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64        1   /* Ind
21c70 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
21c80 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
21c90 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
21ca0 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20  REATE_TABLE     
21cb0 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c       2   /* Tabl
21cc0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
21cd0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
21ce0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
21cf0 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20  EATE_TEMP_INDEX 
21d00 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78      3   /* Index
21d10 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
21d20 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
21d30 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
21d40 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20  ATE_TEMP_TABLE  
21d50 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20     4   /* Table 
21d60 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
21d70 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
21d80 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
21d90 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20  TE_TEMP_TRIGGER 
21da0 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72    5   /* Trigger
21db0 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
21dc0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
21dd0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
21de0 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20  E_TEMP_VIEW     
21df0 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d   6   /* View Nam
21e00 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
21e10 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
21e20 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
21e30 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20  _TRIGGER        
21e40 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  7   /* Trigger N
21e50 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
21e60 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
21e70 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
21e80 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20 38  VIEW           8
21e90 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
21ea0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
21eb0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
21ec0 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20   SQLITE_DELETE  
21ed0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 39 20                9 
21ee0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
21ef0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
21f00 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
21f10 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45  SQLITE_DROP_INDE
21f20 58 20 20 20 20 20 20 20 20 20 20 20 31 30 20 20  X           10  
21f30 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
21f40 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
21f50 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
21f60 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45  QLITE_DROP_TABLE
21f70 20 20 20 20 20 20 20 20 20 20 20 31 31 20 20 20             11   
21f80 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
21f90 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
21fa0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
21fb0 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49  LITE_DROP_TEMP_I
21fc0 4e 44 45 58 20 20 20 20 20 20 31 32 20 20 20 2f  NDEX      12   /
21fd0 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
21fe0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
21ff0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22000 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41  ITE_DROP_TEMP_TA
22010 42 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a  BLE      13   /*
22020 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
22030 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
22040 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
22050 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49  TE_DROP_TEMP_TRI
22060 47 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20  GGER    14   /* 
22070 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
22080 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
22090 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
220a0 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57  E_DROP_TEMP_VIEW
220b0 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56         15   /* V
220c0 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
220d0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
220e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
220f0 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20  _DROP_TRIGGER   
22100 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72        16   /* Tr
22110 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
22120 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
22130 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22140 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20  DROP_VIEW       
22150 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65       17   /* Vie
22160 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
22170 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
22180 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
22190 4e 53 45 52 54 20 20 20 20 20 20 20 20 20 20 20  NSERT           
221a0 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c      18   /* Tabl
221b0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
221c0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
221d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52  define SQLITE_PR
221e0 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20  AGMA            
221f0 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d     19   /* Pragm
22200 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61  a Name     1st a
22210 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64  rg or NULL */.#d
22220 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
22230 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  D               
22240 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20    20   /* Table 
22250 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e  Name      Column
22260 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
22270 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45  fine SQLITE_SELE
22280 43 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CT              
22290 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20   21   /* NULL   
222a0 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20           NULL   
222b0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
222c0 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  ine SQLITE_TRANS
222d0 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20  ACTION          
222e0 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f  22   /* Operatio
222f0 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  n       NULL    
22300 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
22310 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45  ne SQLITE_UPDATE
22320 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
22330 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  3   /* Table Nam
22340 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61  e      Column Na
22350 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
22360 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20  e SQLITE_ATTACH 
22370 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34                24
22380 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20     /* Filename  
22390 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
223a0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
223b0 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20   SQLITE_DETACH  
223c0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20               25 
223d0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61    /* Database Na
223e0 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20  me   NULL       
223f0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
22400 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42  SQLITE_ALTER_TAB
22410 4c 45 20 20 20 20 20 20 20 20 20 20 32 36 20 20  LE          26  
22420 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d   /* Database Nam
22430 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20  e   Table Name  
22440 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
22450 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20  QLITE_REINDEX   
22460 20 20 20 20 20 20 20 20 20 20 20 32 37 20 20 20             27   
22470 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
22480 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
22490 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
224a0 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20  LITE_ANALYZE    
224b0 20 20 20 20 20 20 20 20 20 20 32 38 20 20 20 2f            28   /
224c0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
224d0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
224e0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
224f0 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c  ITE_CREATE_VTABL
22500 45 20 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a  E        29   /*
22510 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
22520 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20   Module Name    
22530 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
22540 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20  TE_DROP_VTABLE  
22550 20 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20          30   /* 
22560 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
22570 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20  Module Name     
22580 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22590 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20  E_FUNCTION      
225a0 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e         31   /* N
225b0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 46  ULL            F
225c0 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a  unction Name   *
225d0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
225e0 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20  _SAVEPOINT      
225f0 20 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70        32   /* Op
22600 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61  eration       Sa
22610 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f  vepoint Name  */
22620 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22630 43 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 20  COPY            
22640 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20        0   /* No 
22650 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 23  longer used */.#
22660 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
22670 43 55 52 53 49 56 45 20 20 20 20 20 20 20 20 20  CURSIVE         
22680 20 20 20 33 33 20 20 20 2f 2a 20 4e 55 4c 4c 20     33   /* NULL 
22690 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20             NULL 
226a0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 0a 2f             */../
226b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
226c0 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69  racing And Profi
226d0 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  ling Functions.*
226e0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
226f0 33 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  3.**.** These ro
22700 75 74 69 6e 65 73 20 61 72 65 20 64 65 70 72 65  utines are depre
22710 63 61 74 65 64 2e 20 55 73 65 20 74 68 65 20 5b  cated. Use the [
22720 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32  sqlite3_trace_v2
22730 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  ()] interface.**
22740 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20   instead of the 
22750 72 6f 75 74 69 6e 65 73 20 64 65 73 63 72 69 62  routines describ
22760 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54  ed here..**.** T
22770 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
22780 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20  gister callback 
22790 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63  functions that c
227a0 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a  an be used for.*
227b0 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72  * tracing and pr
227c0 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63  ofiling the exec
227d0 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61  ution of SQL sta
227e0 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  tements..**.** ^
227f0 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
22800 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64  ction registered
22810 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63   by sqlite3_trac
22820 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61  e() is invoked a
22830 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d  t.** various tim
22840 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73  es when an SQL s
22850 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e  tatement is bein
22860 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65  g run by [sqlite
22870 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54  3_step()]..** ^T
22880 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  he sqlite3_trace
22890 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  () callback is i
228a0 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54  nvoked with a UT
228b0 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  F-8 rendering of
228c0 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74   the.** SQL stat
228d0 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74 68  ement text as th
228e0 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73  e statement firs
228f0 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69  t begins executi
22900 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f  ng..** ^(Additio
22910 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63  nal sqlite3_trac
22920 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69  e() callbacks mi
22930 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20  ght occur.** as 
22940 65 61 63 68 20 74 72 69 67 67 65 72 65 64 20 73  each triggered s
22950 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74  ubprogram is ent
22960 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62  ered.  The callb
22970 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72  acks for trigger
22980 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55  s.** contain a U
22990 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74  TF-8 SQL comment
229a0 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 73   that identifies
229b0 20 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a   the trigger.)^.
229c0 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
229d0 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d  E_TRACE_SIZE_LIM
229e0 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  IT] compile-time
229f0 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75   option can be u
22a00 73 65 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20  sed to limit.** 
22a10 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b 62  the length of [b
22a20 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 5d 20  ound parameter] 
22a30 65 78 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68 65  expansion in the
22a40 20 6f 75 74 70 75 74 20 6f 66 20 73 71 6c 69 74   output of sqlit
22a50 65 33 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a  e3_trace()..**.*
22a60 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  * ^The callback 
22a70 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65  function registe
22a80 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70  red by sqlite3_p
22a90 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f  rofile() is invo
22aa0 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53  ked.** as each S
22ab0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e  QL statement fin
22ac0 69 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f  ishes.  ^The pro
22ad0 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f  file callback co
22ae0 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72  ntains.** the or
22af0 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74  iginal statement
22b00 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74   text and an est
22b10 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c  imate of wall-cl
22b20 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68  ock time.** of h
22b30 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61  ow long that sta
22b40 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72  tement took to r
22b50 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c  un.  ^The profil
22b60 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69  e callback.** ti
22b70 6d 65 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f  me is in units o
22b80 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68  f nanoseconds, h
22b90 6f 77 65 76 65 72 20 74 68 65 20 63 75 72 72 65  owever the curre
22ba0 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  nt implementatio
22bb0 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70  n.** is only cap
22bc0 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63  able of millisec
22bd0 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73  ond resolution s
22be0 6f 20 74 68 65 20 73 69 78 20 6c 65 61 73 74 20  o the six least 
22bf0 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64  significant.** d
22c00 69 67 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d  igits in the tim
22c10 65 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73  e are meaningles
22c20 73 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  s.  Future versi
22c30 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a  ons of SQLite.**
22c40 20 6d 69 67 68 74 20 70 72 6f 76 69 64 65 20 67   might provide g
22c50 72 65 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f  reater resolutio
22c60 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65  n on the profile
22c70 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65  r callback.  The
22c80 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66  .** sqlite3_prof
22c90 69 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  ile() function i
22ca0 73 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70  s considered exp
22cb0 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73  erimental and is
22cc0 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63  .** subject to c
22cd0 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20  hange in future 
22ce0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
22cf0 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 44 45  te..*/.SQLITE_DE
22d00 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 2a 73  PRECATED void *s
22d10 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c  qlite3_trace(sql
22d20 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a  ite3*,.   void(*
22d30 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f  xTrace)(void*,co
22d40 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64  nst char*), void
22d50 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  *);.SQLITE_DEPRE
22d60 43 41 54 45 44 20 76 6f 69 64 20 2a 73 71 6c 69  CATED void *sqli
22d70 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69  te3_profile(sqli
22d80 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78  te3*,.   void(*x
22d90 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63  Profile)(void*,c
22da0 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74  onst char*,sqlit
22db0 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64  e3_uint64), void
22dc0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
22dd0 52 45 46 3a 20 53 51 4c 20 54 72 61 63 65 20 45  REF: SQL Trace E
22de0 76 65 6e 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45  vent Codes.** KE
22df0 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54  YWORDS: SQLITE_T
22e00 52 41 43 45 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  RACE.**.** These
22e10 20 63 6f 6e 73 74 61 6e 74 73 20 69 64 65 6e 74   constants ident
22e20 69 66 79 20 63 6c 61 73 73 65 73 20 6f 66 20 65  ify classes of e
22e30 76 65 6e 74 73 20 74 68 61 74 20 63 61 6e 20 62  vents that can b
22e40 65 20 6d 6f 6e 69 74 6f 72 65 64 0a 2a 2a 20 75  e monitored.** u
22e50 73 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65  sing the [sqlite
22e60 33 5f 74 72 61 63 65 5f 76 32 28 29 5d 20 74 72  3_trace_v2()] tr
22e70 61 63 69 6e 67 20 6c 6f 67 69 63 2e 20 20 54 68  acing logic.  Th
22e80 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
22e90 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  .** to [sqlite3_
22ea0 74 72 61 63 65 5f 76 32 28 29 5d 20 69 73 20 61  trace_v2()] is a
22eb0 6e 20 4f 52 2d 65 64 20 63 6f 6d 62 69 6e 61 74  n OR-ed combinat
22ec0 69 6f 6e 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f  ion of one or mo
22ed0 72 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c  re of.** the fol
22ee0 6c 6f 77 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73  lowing constants
22ef0 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  .  ^The first ar
22f00 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 74 72  gument to the tr
22f10 61 63 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  ace callback.** 
22f20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  is one of the fo
22f30 6c 6c 6f 77 69 6e 67 20 63 6f 6e 73 74 61 6e 74  llowing constant
22f40 73 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 74 72 61  s..**.** New tra
22f50 63 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20 6d  cing constants m
22f60 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
22f70 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a  uture releases..
22f80 2a 2a 0a 2a 2a 20 5e 41 20 74 72 61 63 65 20 63  **.** ^A trace c
22f90 61 6c 6c 62 61 63 6b 20 68 61 73 20 66 6f 75 72  allback has four
22fa0 20 61 72 67 75 6d 65 6e 74 73 3a 20 78 43 61 6c   arguments: xCal
22fb0 6c 62 61 63 6b 28 54 2c 43 2c 50 2c 58 29 2e 0a  lback(T,C,P,X)..
22fc0 2a 2a 20 5e 54 68 65 20 54 20 61 72 67 75 6d 65  ** ^The T argume
22fd0 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65  nt is one of the
22fe0 20 69 6e 74 65 67 65 72 20 74 79 70 65 20 63 6f   integer type co
22ff0 64 65 73 20 61 62 6f 76 65 2e 0a 2a 2a 20 5e 54  des above..** ^T
23000 68 65 20 43 20 61 72 67 75 6d 65 6e 74 20 69 73  he C argument is
23010 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63   a copy of the c
23020 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 20 70  ontext pointer p
23030 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a  assed in as the.
23040 2a 2a 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  ** fourth argume
23050 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74  nt to [sqlite3_t
23060 72 61 63 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 54  race_v2()]..** T
23070 68 65 20 50 20 61 6e 64 20 58 20 61 72 67 75 6d  he P and X argum
23080 65 6e 74 73 20 61 72 65 20 70 6f 69 6e 74 65 72  ents are pointer
23090 73 20 77 68 6f 73 65 20 6d 65 61 6e 69 6e 67 73  s whose meanings
230a0 20 64 65 70 65 6e 64 20 6f 6e 20 54 2e 0a 2a 2a   depend on T..**
230b0 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51  .** <dl>.** [[SQ
230c0 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 5d  LITE_TRACE_STMT]
230d0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41  ] <dt>SQLITE_TRA
230e0 43 45 5f 53 54 4d 54 3c 2f 64 74 3e 0a 2a 2a 20  CE_STMT</dt>.** 
230f0 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54  <dd>^An SQLITE_T
23100 52 41 43 45 5f 53 54 4d 54 20 63 61 6c 6c 62 61  RACE_STMT callba
23110 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68  ck is invoked wh
23120 65 6e 20 61 20 70 72 65 70 61 72 65 64 20 73 74  en a prepared st
23130 61 74 65 6d 65 6e 74 0a 2a 2a 20 66 69 72 73 74  atement.** first
23140 20 62 65 67 69 6e 73 20 72 75 6e 6e 69 6e 67 20   begins running 
23150 61 6e 64 20 70 6f 73 73 69 62 6c 79 20 61 74 20  and possibly at 
23160 6f 74 68 65 72 20 74 69 6d 65 73 20 64 75 72 69  other times duri
23170 6e 67 20 74 68 65 0a 2a 2a 20 65 78 65 63 75 74  ng the.** execut
23180 69 6f 6e 20 6f 66 20 74 68 65 20 70 72 65 70 61  ion of the prepa
23190 72 65 64 20 73 74 61 74 65 6d 65 6e 74 2c 20 73  red statement, s
231a0 75 63 68 20 61 73 20 61 74 20 74 68 65 20 73 74  uch as at the st
231b0 61 72 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20 74  art of each.** t
231c0 72 69 67 67 65 72 20 73 75 62 70 72 6f 67 72 61  rigger subprogra
231d0 6d 2e 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65  m. ^The P argume
231e0 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  nt is a pointer 
231f0 74 6f 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  to the.** [prepa
23200 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
23210 5e 54 68 65 20 58 20 61 72 67 75 6d 65 6e 74 20  ^The X argument 
23220 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
23230 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 0a 2a  a string which.*
23240 2a 20 69 73 20 74 68 65 20 75 6e 65 78 70 61 6e  * is the unexpan
23250 64 65 64 20 53 51 4c 20 74 65 78 74 20 6f 66 20  ded SQL text of 
23260 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
23270 74 65 6d 65 6e 74 20 6f 72 20 61 6e 20 53 51 4c  tement or an SQL
23280 20 63 6f 6d 6d 65 6e 74 20 0a 2a 2a 20 74 68 61   comment .** tha
23290 74 20 69 6e 64 69 63 61 74 65 73 20 74 68 65 20  t indicates the 
232a0 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 61 20  invocation of a 
232b0 74 72 69 67 67 65 72 2e 20 20 5e 54 68 65 20 63  trigger.  ^The c
232c0 61 6c 6c 62 61 63 6b 20 63 61 6e 20 63 6f 6d 70  allback can comp
232d0 75 74 65 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20  ute.** the same 
232e0 74 65 78 74 20 74 68 61 74 20 77 6f 75 6c 64 20  text that would 
232f0 68 61 76 65 20 62 65 65 6e 20 72 65 74 75 72 6e  have been return
23300 65 64 20 62 79 20 74 68 65 20 6c 65 67 61 63 79  ed by the legacy
23310 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28   [sqlite3_trace(
23320 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  )].** interface 
23330 62 79 20 75 73 69 6e 67 20 74 68 65 20 58 20 61  by using the X a
23340 72 67 75 6d 65 6e 74 20 77 68 65 6e 20 58 20 62  rgument when X b
23350 65 67 69 6e 73 20 77 69 74 68 20 22 2d 2d 22 20  egins with "--" 
23360 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20  and invoking.** 
23370 5b 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65  [sqlite3_expande
23380 64 5f 73 71 6c 28 50 29 5d 20 6f 74 68 65 72 77  d_sql(P)] otherw
23390 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  ise..**.** [[SQL
233a0 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c  ITE_TRACE_PROFIL
233b0 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54  E]] <dt>SQLITE_T
233c0 52 41 43 45 5f 50 52 4f 46 49 4c 45 3c 2f 64 74  RACE_PROFILE</dt
233d0 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c  >.** <dd>^An SQL
233e0 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c  ITE_TRACE_PROFIL
233f0 45 20 63 61 6c 6c 62 61 63 6b 20 70 72 6f 76 69  E callback provi
23400 64 65 73 20 61 70 70 72 6f 78 69 6d 61 74 65 6c  des approximatel
23410 79 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 69 6e  y the same.** in
23420 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 69 73 20  formation as is 
23430 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20  provided by the 
23440 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65  [sqlite3_profile
23450 28 29 5d 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  ()] callback..**
23460 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74   ^The P argument
23470 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
23480 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
23490 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 74 68  tatement] and th
234a0 65 0a 2a 2a 20 58 20 61 72 67 75 6d 65 6e 74 20  e.** X argument 
234b0 70 6f 69 6e 74 73 20 74 6f 20 61 20 36 34 2d 62  points to a 64-b
234c0 69 74 20 69 6e 74 65 67 65 72 20 77 68 69 63 68  it integer which
234d0 20 69 73 20 74 68 65 20 65 73 74 69 6d 61 74 65   is the estimate
234e0 64 20 6f 66 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  d of.** the numb
234f0 65 72 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64  er of nanosecond
23500 20 74 68 61 74 20 74 68 65 20 70 72 65 70 61 72   that the prepar
23510 65 64 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f  ed statement too
23520 6b 20 74 6f 20 72 75 6e 2e 0a 2a 2a 20 5e 54 68  k to run..** ^Th
23530 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50  e SQLITE_TRACE_P
23540 52 4f 46 49 4c 45 20 63 61 6c 6c 62 61 63 6b 20  ROFILE callback 
23550 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  is invoked when 
23560 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69  the statement fi
23570 6e 69 73 68 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  nishes..**.** [[
23580 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57  SQLITE_TRACE_ROW
23590 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52  ]] <dt>SQLITE_TR
235a0 41 43 45 5f 52 4f 57 3c 2f 64 74 3e 0a 2a 2a 20  ACE_ROW</dt>.** 
235b0 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54  <dd>^An SQLITE_T
235c0 52 41 43 45 5f 52 4f 57 20 63 61 6c 6c 62 61 63  RACE_ROW callbac
235d0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65  k is invoked whe
235e0 6e 65 76 65 72 20 61 20 70 72 65 70 61 72 65 64  never a prepared
235f0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 67 65  .** statement ge
23600 6e 65 72 61 74 65 73 20 61 20 73 69 6e 67 6c 65  nerates a single
23610 20 72 6f 77 20 6f 66 20 72 65 73 75 6c 74 2e 20   row of result. 
23620 20 0a 2a 2a 20 5e 54 68 65 20 50 20 61 72 67 75   .** ^The P argu
23630 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
23640 72 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72  r to the [prepar
23650 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e  ed statement] an
23660 64 20 74 68 65 0a 2a 2a 20 58 20 61 72 67 75 6d  d the.** X argum
23670 65 6e 74 20 69 73 20 75 6e 75 73 65 64 2e 0a 2a  ent is unused..*
23680 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52  *.** [[SQLITE_TR
23690 41 43 45 5f 43 4c 4f 53 45 5d 5d 20 3c 64 74 3e  ACE_CLOSE]] <dt>
236a0 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f  SQLITE_TRACE_CLO
236b0 53 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e  SE</dt>.** <dd>^
236c0 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  An SQLITE_TRACE_
236d0 43 4c 4f 53 45 20 63 61 6c 6c 62 61 63 6b 20 69  CLOSE callback i
236e0 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61  s invoked when a
236f0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
23700 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 0a  nection closes..
23710 2a 2a 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65  ** ^The P argume
23720 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  nt is a pointer 
23730 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  to the [database
23740 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 6a   connection] obj
23750 65 63 74 0a 2a 2a 20 61 6e 64 20 74 68 65 20 58  ect.** and the X
23760 20 61 72 67 75 6d 65 6e 74 20 69 73 20 75 6e 75   argument is unu
23770 73 65 64 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  sed..** </dl>.*/
23780 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
23790 54 52 41 43 45 5f 53 54 4d 54 20 20 20 20 20 20  TRACE_STMT      
237a0 20 30 78 30 31 0a 23 64 65 66 69 6e 65 20 53 51   0x01.#define SQ
237b0 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49  LITE_TRACE_PROFI
237c0 4c 45 20 20 20 20 30 78 30 32 0a 23 64 65 66 69  LE    0x02.#defi
237d0 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  ne SQLITE_TRACE_
237e0 52 4f 57 20 20 20 20 20 20 20 20 30 78 30 34 0a  ROW        0x04.
237f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
23800 52 41 43 45 5f 43 4c 4f 53 45 20 20 20 20 20 20  RACE_CLOSE      
23810 30 78 30 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0x08../*.** CAPI
23820 33 52 45 46 3a 20 53 51 4c 20 54 72 61 63 65 20  3REF: SQL Trace 
23830 48 6f 6f 6b 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  Hook.** METHOD: 
23840 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
23850 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  he sqlite3_trace
23860 5f 76 32 28 44 2c 4d 2c 58 2c 50 29 20 69 6e 74  _v2(D,M,X,P) int
23870 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
23880 20 61 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63   a trace callbac
23890 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20  k.** function X 
238a0 61 67 61 69 6e 73 74 20 5b 64 61 74 61 62 61 73  against [databas
238b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c  e connection] D,
238c0 20 75 73 69 6e 67 20 70 72 6f 70 65 72 74 79 20   using property 
238d0 6d 61 73 6b 20 4d 0a 2a 2a 20 61 6e 64 20 63 6f  mask M.** and co
238e0 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 20 50 2e  ntext pointer P.
238f0 20 20 5e 49 66 20 74 68 65 20 58 20 63 61 6c 6c    ^If the X call
23900 62 61 63 6b 20 69 73 0a 2a 2a 20 4e 55 4c 4c 20  back is.** NULL 
23910 6f 72 20 69 66 20 74 68 65 20 4d 20 6d 61 73 6b  or if the M mask
23920 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74   is zero, then t
23930 72 61 63 69 6e 67 20 69 73 20 64 69 73 61 62 6c  racing is disabl
23940 65 64 2e 20 20 54 68 65 0a 2a 2a 20 4d 20 61 72  ed.  The.** M ar
23950 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65  gument should be
23960 20 74 68 65 20 62 69 74 77 69 73 65 20 4f 52 2d   the bitwise OR-
23970 65 64 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f  ed combination o
23980 66 0a 2a 2a 20 7a 65 72 6f 20 6f 72 20 6d 6f 72  f.** zero or mor
23990 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5d  e [SQLITE_TRACE]
239a0 20 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a   constants..**.*
239b0 2a 20 5e 45 61 63 68 20 63 61 6c 6c 20 74 6f 20  * ^Each call to 
239c0 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 74  either sqlite3_t
239d0 72 61 63 65 28 29 20 6f 72 20 73 71 6c 69 74 65  race() or sqlite
239e0 33 5f 74 72 61 63 65 5f 76 32 28 29 20 6f 76 65  3_trace_v2() ove
239f0 72 72 69 64 65 73 20 0a 2a 2a 20 28 63 61 6e 63  rrides .** (canc
23a00 65 6c 73 29 20 61 6e 79 20 70 72 69 6f 72 20 63  els) any prior c
23a10 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
23a20 74 72 61 63 65 28 29 20 6f 72 20 73 71 6c 69 74  trace() or sqlit
23a30 65 33 5f 74 72 61 63 65 5f 76 32 28 29 2e 0a 2a  e3_trace_v2()..*
23a40 2a 0a 2a 2a 20 5e 54 68 65 20 58 20 63 61 6c 6c  *.** ^The X call
23a50 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
23a60 77 68 65 6e 65 76 65 72 20 61 6e 79 20 6f 66 20  whenever any of 
23a70 74 68 65 20 65 76 65 6e 74 73 20 69 64 65 6e 74  the events ident
23a80 69 66 69 65 64 20 62 79 20 0a 2a 2a 20 6d 61 73  ified by .** mas
23a90 6b 20 4d 20 6f 63 63 75 72 2e 20 20 5e 54 68 65  k M occur.  ^The
23aa0 20 69 6e 74 65 67 65 72 20 72 65 74 75 72 6e 20   integer return 
23ab0 76 61 6c 75 65 20 66 72 6f 6d 20 74 68 65 20 63  value from the c
23ac0 61 6c 6c 62 61 63 6b 20 69 73 20 63 75 72 72 65  allback is curre
23ad0 6e 74 6c 79 0a 2a 2a 20 69 67 6e 6f 72 65 64 2c  ntly.** ignored,
23ae0 20 74 68 6f 75 67 68 20 74 68 69 73 20 6d 61 79   though this may
23af0 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72   change in futur
23b00 65 20 72 65 6c 65 61 73 65 73 2e 20 20 43 61 6c  e releases.  Cal
23b10 6c 62 61 63 6b 0a 2a 2a 20 69 6d 70 6c 65 6d 65  lback.** impleme
23b20 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ntations should 
23b30 72 65 74 75 72 6e 20 7a 65 72 6f 20 74 6f 20 65  return zero to e
23b40 6e 73 75 72 65 20 66 75 74 75 72 65 20 63 6f 6d  nsure future com
23b50 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a  patibility..**.*
23b60 2a 20 5e 41 20 74 72 61 63 65 20 63 61 6c 6c 62  * ^A trace callb
23b70 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  ack is invoked w
23b80 69 74 68 20 66 6f 75 72 20 61 72 67 75 6d 65 6e  ith four argumen
23b90 74 73 3a 20 63 61 6c 6c 62 61 63 6b 28 54 2c 43  ts: callback(T,C
23ba0 2c 50 2c 58 29 2e 0a 2a 2a 20 5e 54 68 65 20 54  ,P,X)..** ^The T
23bb0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65   argument is one
23bc0 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   of the [SQLITE_
23bd0 54 52 41 43 45 5d 0a 2a 2a 20 63 6f 6e 73 74 61  TRACE].** consta
23be0 6e 74 73 20 74 6f 20 69 6e 64 69 63 61 74 65 20  nts to indicate 
23bf0 77 68 79 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  why the callback
23c00 20 77 61 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a   was invoked..**
23c10 20 5e 54 68 65 20 43 20 61 72 67 75 6d 65 6e 74   ^The C argument
23c20 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
23c30 65 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65  e context pointe
23c40 72 2e 0a 2a 2a 20 54 68 65 20 50 20 61 6e 64 20  r..** The P and 
23c50 58 20 61 72 67 75 6d 65 6e 74 73 20 61 72 65 20  X arguments are 
23c60 70 6f 69 6e 74 65 72 73 20 77 68 6f 73 65 20 6d  pointers whose m
23c70 65 61 6e 69 6e 67 73 20 64 65 70 65 6e 64 20 6f  eanings depend o
23c80 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  n T..**.** The s
23c90 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28  qlite3_trace_v2(
23ca0 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69  ) interface is i
23cb0 6e 74 65 6e 64 65 64 20 74 6f 20 72 65 70 6c 61  ntended to repla
23cc0 63 65 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a  ce the legacy.**
23cd0 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c   interfaces [sql
23ce0 69 74 65 33 5f 74 72 61 63 65 28 29 5d 20 61 6e  ite3_trace()] an
23cf0 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  d [sqlite3_profi
23d00 6c 65 28 29 5d 2c 20 62 6f 74 68 20 6f 66 20 77  le()], both of w
23d10 68 69 63 68 0a 2a 2a 20 61 72 65 20 64 65 70 72  hich.** are depr
23d20 65 63 61 74 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73  ecated..*/.int s
23d30 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28  qlite3_trace_v2(
23d40 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 75  .  sqlite3*,.  u
23d50 6e 73 69 67 6e 65 64 20 75 4d 61 73 6b 2c 0a 20  nsigned uMask,. 
23d60 20 69 6e 74 28 2a 78 43 61 6c 6c 62 61 63 6b 29   int(*xCallback)
23d70 28 75 6e 73 69 67 6e 65 64 2c 76 6f 69 64 2a 2c  (unsigned,void*,
23d80 76 6f 69 64 2a 2c 76 6f 69 64 2a 29 2c 0a 20 20  void*,void*),.  
23d90 76 6f 69 64 20 2a 70 43 74 78 0a 29 3b 0a 0a 2f  void *pCtx.);../
23da0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51  *.** CAPI3REF: Q
23db0 75 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 61  uery Progress Ca
23dc0 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f  llbacks.** METHO
23dd0 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
23de0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72   ^The sqlite3_pr
23df0 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 44  ogress_handler(D
23e00 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63  ,N,X,P) interfac
23e10 65 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c  e causes the cal
23e20 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f  lback.** functio
23e30 6e 20 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  n X to be invoke
23e40 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64  d periodically d
23e50 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69  uring long runni
23e60 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b  ng calls to.** [
23e70 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c  sqlite3_exec()],
23e80 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
23e90 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67  ] and [sqlite3_g
23ea0 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a  et_table()] for.
23eb0 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
23ec0 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78  ection D.  An ex
23ed0 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68  ample use for th
23ee0 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  is.** interface 
23ef0 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49  is to keep a GUI
23f00 20 75 70 64 61 74 65 64 20 64 75 72 69 6e 67 20   updated during 
23f10 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a  a large query..*
23f20 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d 65  *.** ^The parame
23f30 74 65 72 20 50 20 69 73 20 70 61 73 73 65 64 20  ter P is passed 
23f40 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 6f  through as the o
23f50 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f  nly parameter to
23f60 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63   the .** callbac
23f70 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e  k function X.  ^
23f80 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20  The parameter N 
23f90 69 73 20 74 68 65 20 61 70 70 72 6f 78 69 6d 61  is the approxima
23fa0 74 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a  te number of .**
23fb0 20 5b 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e   [virtual machin
23fc0 65 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20  e instructions] 
23fd0 74 68 61 74 20 61 72 65 20 65 76 61 6c 75 61 74  that are evaluat
23fe0 65 64 20 62 65 74 77 65 65 6e 20 73 75 63 63 65  ed between succe
23ff0 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74  ssive.** invocat
24000 69 6f 6e 73 20 6f 66 20 74 68 65 20 63 61 6c 6c  ions of the call
24010 62 61 63 6b 20 58 2e 20 20 5e 49 66 20 4e 20 69  back X.  ^If N i
24020 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20  s less than one 
24030 74 68 65 6e 20 74 68 65 20 70 72 6f 67 72 65 73  then the progres
24040 73 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 69 73 20  s.** handler is 
24050 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  disabled..**.** 
24060 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 70  ^Only a single p
24070 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
24080 6d 61 79 20 62 65 20 64 65 66 69 6e 65 64 20 61  may be defined a
24090 74 20 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a  t one time per.*
240a0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
240b0 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67  ection]; setting
240c0 20 61 20 6e 65 77 20 70 72 6f 67 72 65 73 73 20   a new progress 
240d0 68 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73 20  handler cancels 
240e0 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20  the.** old one. 
240f0 20 5e 53 65 74 74 69 6e 67 20 70 61 72 61 6d 65   ^Setting parame
24100 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69  ter X to NULL di
24110 73 61 62 6c 65 73 20 74 68 65 20 70 72 6f 67 72  sables the progr
24120 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20  ess handler..** 
24130 5e 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61  ^The progress ha
24140 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f 20 64 69  ndler is also di
24150 73 61 62 6c 65 64 20 62 79 20 73 65 74 74 69 6e  sabled by settin
24160 67 20 4e 20 74 6f 20 61 20 76 61 6c 75 65 20 6c  g N to a value l
24170 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a  ess.** than 1..*
24180 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 6f  *.** ^If the pro
24190 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72  gress callback r
241a0 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
241b0 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69   the operation i
241c0 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64  s.** interrupted
241d0 2e 20 20 54 68 69 73 20 66 65 61 74 75 72 65 20  .  This feature 
241e0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69  can be used to i
241f0 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43  mplement a.** "C
24200 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e  ancel" button on
24210 20 61 20 47 55 49 20 70 72 6f 67 72 65 73 73 20   a GUI progress 
24220 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a  dialog box..**.*
24230 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 68  * The progress h
24240 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20  andler callback 
24250 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
24260 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
24270 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
24280 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
24290 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
242a0 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
242b0 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  er..** Note that
242c0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
242d0 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
242e0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74  ite3_step()] bot
242f0 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a  h modify their.*
24300 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
24310 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d  ctions for the m
24320 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66  eaning of "modif
24330 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67  y" in this parag
24340 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64  raph..**.*/.void
24350 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73   sqlite3_progres
24360 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65  s_handler(sqlite
24370 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28  3*, int, int(*)(
24380 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  void*), void*);.
24390 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
243a0 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44   Opening A New D
243b0 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
243c0 6f 6e 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f  on.** CONSTRUCTO
243d0 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  R: sqlite3.**.**
243e0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
243f0 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20   open an SQLite 
24400 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 61 73  database file as
24410 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
24420 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61  e .** filename a
24430 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69  rgument. ^The fi
24440 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20  lename argument 
24450 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
24460 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73  s UTF-8 for.** s
24470 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
24480 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  d sqlite3_open_v
24490 32 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31  2() and as UTF-1
244a0 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  6 in the native 
244b0 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f  byte.** order fo
244c0 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  r sqlite3_open16
244d0 28 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73  (). ^(A [databas
244e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61  e connection] ha
244f0 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a  ndle is usually.
24500 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a  ** returned in *
24510 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e  ppDb, even if an
24520 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20   error occurs.  
24530 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69  The only excepti
24540 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66  on is that.** if
24550 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c   SQLite is unabl
24560 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65  e to allocate me
24570 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
24580 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
24590 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c  t,.** a NULL wil
245a0 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74  l be written int
245b0 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20  o *ppDb instead 
245c0 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  of a pointer to 
245d0 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a  the [sqlite3].**
245e0 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20   object.)^ ^(If 
245f0 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
24600 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63  opened (and/or c
24610 72 65 61 74 65 64 29 20 73 75 63 63 65 73 73 66  reated) successf
24620 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53  ully, then.** [S
24630 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74  QLITE_OK] is ret
24640 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73  urned.  Otherwis
24650 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  e an [error code
24660 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e  ] is returned.)^
24670 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65   ^The.** [sqlite
24680 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b  3_errmsg()] or [
24690 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
246a0 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e  ()] routines can
246b0 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61   be used to obta
246c0 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68  in.** an English
246d0 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72 69   language descri
246e0 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72  ption of the err
246f0 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66  or following a f
24700 61 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a  ailure of any.**
24710 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
24720 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e  open() routines.
24730 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61  .**.** ^The defa
24740 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 77 69 6c  ult encoding wil
24750 6c 20 62 65 20 55 54 46 2d 38 20 66 6f 72 20 64  l be UTF-8 for d
24760 61 74 61 62 61 73 65 73 20 63 72 65 61 74 65 64  atabases created
24770 20 75 73 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65   using.** sqlite
24780 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69  3_open() or sqli
24790 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20  te3_open_v2().  
247a0 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63  ^The default enc
247b0 6f 64 69 6e 67 20 66 6f 72 20 64 61 74 61 62 61  oding for databa
247c0 73 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 75  ses.** created u
247d0 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65  sing sqlite3_ope
247e0 6e 31 36 28 29 20 77 69 6c 6c 20 62 65 20 55 54  n16() will be UT
247f0 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69  F-16 in the nati
24800 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
24810 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20  *.** Whether or 
24820 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63  not an error occ
24830 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f  urs when it is o
24840 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73  pened, resources
24850 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77  .** associated w
24860 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73  ith the [databas
24870 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61  e connection] ha
24880 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72  ndle should be r
24890 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61  eleased by.** pa
248a0 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c  ssing it to [sql
248b0 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68  ite3_close()] wh
248c0 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67  en it is no long
248d0 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a  er required..**.
248e0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  ** The sqlite3_o
248f0 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61  pen_v2() interfa
24900 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71  ce works like sq
24910 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20  lite3_open().** 
24920 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61  except that it a
24930 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 74  ccepts two addit
24940 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73  ional parameters
24950 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
24960 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20  control.** over 
24970 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65  the new database
24980 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28   connection.  ^(
24990 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65  The flags parame
249a0 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  ter to.** sqlite
249b0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20  3_open_v2() can 
249c0 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74  take one of.** t
249d0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72  he following thr
249e0 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f  ee values, optio
249f0 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77  nally combined w
24a00 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ith the .** [SQL
24a10 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
24a20 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ], [SQLITE_OPEN_
24a30 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c  FULLMUTEX], [SQL
24a40 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
24a50 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  ACHE],.** [SQLIT
24a60 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
24a70 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51  CHE], and/or [SQ
24a80 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66  LITE_OPEN_URI] f
24a90 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64  lags:)^.**.** <d
24aa0 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c  l>.** ^(<dt>[SQL
24ab0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
24ac0 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  Y]</dt>.** <dd>T
24ad0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
24ae0 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e  pened in read-on
24af0 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65  ly mode.  If the
24b00 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e   database does n
24b10 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78  ot.** already ex
24b20 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73  ist, an error is
24b30 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29   returned.</dd>)
24b40 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53  ^.**.** ^(<dt>[S
24b50 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
24b60 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  RITE]</dt>.** <d
24b70 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69  d>The database i
24b80 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
24b90 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67  ding and writing
24ba0 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72   if possible, or
24bb0 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79   reading.** only
24bc0 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   if the file is 
24bd0 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20  write protected 
24be0 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  by the operating
24bf0 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74   system.  In eit
24c00 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20  her.** case the 
24c10 64 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c  database must al
24c20 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68  ready exist, oth
24c30 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20  erwise an error 
24c40 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64  is returned.</dd
24c50 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
24c60 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
24c70 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54  DWRITE] | [SQLIT
24c80 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f  E_OPEN_CREATE]</
24c90 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64  dt>.** <dd>The d
24ca0 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
24cb0 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e  d for reading an
24cc0 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69  d writing, and i
24cd0 73 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20  s created if.** 
24ce0 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65  it does not alre
24cf0 61 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 20  ady exist. This 
24d00 69 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  is the behavior 
24d10 74 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75  that is always u
24d20 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  sed for.** sqlit
24d30 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
24d40 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c  lite3_open16().<
24d50 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  /dd>)^.** </dl>.
24d60 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64  **.** If the 3rd
24d70 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
24d80 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
24d90 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68  is not one of th
24da0 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  e.** combination
24db0 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70  s shown above op
24dc0 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65  tionally combine
24dd0 64 20 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20  d with other.** 
24de0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
24df0 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f  DONLY | SQLITE_O
24e00 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74  PEN_* bits].** t
24e10 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
24e20 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
24e30 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51  *.** ^If the [SQ
24e40 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
24e50 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20  X] flag is set, 
24e60 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
24e70 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
24e80 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c  opens in the mul
24e90 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61  ti-thread [threa
24ea0 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f  ding mode] as lo
24eb0 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65  ng as the single
24ec0 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20  -thread.** mode 
24ed0 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74  has not been set
24ee0 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65   at compile-time
24ef0 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20   or start-time. 
24f00 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c   ^If the.** [SQL
24f10 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54  ITE_OPEN_FULLMUT
24f20 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20  EX] flag is set 
24f30 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
24f40 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65  e connection ope
24f50 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72  ns.** in the ser
24f60 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69  ialized [threadi
24f70 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20  ng mode] unless 
24f80 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61  single-thread wa
24f90 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  s.** previously 
24fa0 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70  selected at comp
24fb0 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72  ile-time or star
24fc0 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20  t-time..** ^The 
24fd0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41  [SQLITE_OPEN_SHA
24fe0 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63  REDCACHE] flag c
24ff0 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61  auses the databa
25000 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f  se connection to
25010 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20   be.** eligible 
25020 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20 63  to use [shared c
25030 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61  ache mode], rega
25040 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
25050 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a  r or not shared.
25060 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62  ** cache is enab
25070 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  led using [sqlit
25080 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64  e3_enable_shared
25090 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65  _cache()].  ^The
250a0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
250b0 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 20 66  _PRIVATECACHE] f
250c0 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64  lag causes the d
250d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
250e0 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72  on to not.** par
250f0 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61  ticipate in [sha
25100 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20  red cache mode] 
25110 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e  even if it is en
25120 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  abled..**.** ^Th
25130 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
25140 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
25150 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e  en_v2() is the n
25160 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  ame of the.** [s
25170 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
25180 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20  ct that defines 
25190 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
251a0 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74  stem interface t
251b0 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64  hat.** the new d
251c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
251d0 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20  on should use.  
251e0 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70  ^If the fourth p
251f0 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61  arameter is.** a
25200 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
25210 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b  en the default [
25220 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
25230 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  ect is used..**.
25240 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e  ** ^If the filen
25250 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a  ame is ":memory:
25260 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74  ", then a privat
25270 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d  e, temporary in-
25280 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a  memory database.
25290 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20 66 6f  ** is created fo
252a0 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  r the connection
252b0 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f  .  ^This in-memo
252c0 72 79 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  ry database will
252d0 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20   vanish when.** 
252e0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
252f0 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65  nection is close
25300 64 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  d.  Future versi
25310 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ons of SQLite mi
25320 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20  ght.** make use 
25330 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70  of additional sp
25340 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20  ecial filenames 
25350 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 20  that begin with 
25360 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 65  the ":" characte
25370 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f  r..** It is reco
25380 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68 65  mmended that whe
25390 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  n a database fil
253a0 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64  ename actually d
253b0 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a  oes begin with.*
253c0 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63 74 65  * a ":" characte
253d0 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65  r you should pre
253e0 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  fix the filename
253f0 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65   with a pathname
25400 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22   such as.** "./"
25410 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75   to avoid ambigu
25420 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ity..**.** ^If t
25430 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61  he filename is a
25440 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20  n empty string, 
25450 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20  then a private, 
25460 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d  temporary.** on-
25470 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69  disk database wi
25480 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20  ll be created.  
25490 5e 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61  ^This private da
254a0 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a  tabase will be.*
254b0 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  * automatically 
254c0 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20  deleted as soon 
254d0 61 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  as the database 
254e0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c  connection is cl
254f0 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52  osed..**.** [[UR
25500 49 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73  I filenames in s
25510 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20  qlite3_open()]] 
25520 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65  <h3>URI Filename
25530 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66  s</h3>.**.** ^If
25540 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20   [URI filename] 
25550 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69  interpretation i
25560 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74  s enabled, and t
25570 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
25580 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77  ment.** begins w
25590 69 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 65  ith "file:", the
255a0 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69  n the filename i
255b0 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
255c0 20 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20   a URI. ^URI.** 
255d0 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72  filename interpr
255e0 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c  etation is enabl
255f0 65 64 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54  ed if the [SQLIT
25600 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67  E_OPEN_URI] flag
25610 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68   is.** set in th
25620 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
25630 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  t to sqlite3_ope
25640 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66 20 69 74  n_v2(), or if it
25650 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61   has.** been ena
25660 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73  bled globally us
25670 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ing the [SQLITE_
25680 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74 69  CONFIG_URI] opti
25690 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  on with the.** [
256a0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
256b0 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62 79 20 74  ] method or by t
256c0 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55  he [SQLITE_USE_U
256d0 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  RI] compile-time
256e0 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f   option..** As o
256f0 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  f SQLite version
25700 20 33 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c 65   3.7.7, URI file
25710 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74  name interpretat
25720 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 66  ion is turned of
25730 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2c  f.** by default,
25740 20 62 75 74 20 66 75 74 75 72 65 20 72 65 6c 65   but future rele
25750 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ases of SQLite m
25760 69 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49 20  ight enable URI 
25770 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65  filename.** inte
25780 72 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64 65  rpretation by de
25790 66 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55 52  fault.  See "[UR
257a0 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f  I filenames]" fo
257b0 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
257c0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
257d0 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73  ** URI filenames
257e0 20 61 72 65 20 70 61 72 73 65 64 20 61 63 63 6f   are parsed acco
257f0 72 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39 38  rding to RFC 398
25800 36 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20 63  6. ^If the URI c
25810 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75  ontains an.** au
25820 74 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69 74  thority, then it
25830 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
25840 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20  an empty string 
25850 6f 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a 2a  or the string .*
25860 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e  * "localhost". ^
25870 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 74 79  If the authority
25880 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79   is not an empty
25890 20 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61   string or "loca
258a0 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65  lhost", an .** e
258b0 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
258c0 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e 20   to the caller. 
258d0 5e 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63 6f  ^The fragment co
258e0 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49  mponent of a URI
258f0 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74  , if .** present
25900 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a  , is ignored..**
25910 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73  .** ^SQLite uses
25920 20 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e   the path compon
25930 65 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20 61  ent of the URI a
25940 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
25950 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77  e disk file.** w
25960 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74 68  hich contains th
25970 65 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66 20  e database. ^If 
25980 74 68 65 20 70 61 74 68 20 62 65 67 69 6e 73 20  the path begins 
25990 77 69 74 68 20 61 20 27 2f 27 20 63 68 61 72 61  with a '/' chara
259a0 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69  cter, .** then i
259b0 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  t is interpreted
259c0 20 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65 20   as an absolute 
259d0 70 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70 61  path. ^If the pa
259e0 74 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 69  th does not begi
259f0 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f 27  n .** with a '/'
25a00 20 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20 74   (meaning that t
25a10 68 65 20 61 75 74 68 6f 72 69 74 79 20 73 65 63  he authority sec
25a20 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 20  tion is omitted 
25a30 66 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a  from the URI).**
25a40 20 74 68 65 6e 20 74 68 65 20 70 61 74 68 20 69   then the path i
25a50 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
25a60 20 61 20 72 65 6c 61 74 69 76 65 20 70 61 74 68   a relative path
25a70 2e 20 0a 2a 2a 20 5e 28 4f 6e 20 77 69 6e 64 6f  . .** ^(On windo
25a80 77 73 2c 20 74 68 65 20 66 69 72 73 74 20 63 6f  ws, the first co
25a90 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62  mponent of an ab
25aa0 73 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a 20  solute path .** 
25ab0 69 73 20 61 20 64 72 69 76 65 20 73 70 65 63 69  is a drive speci
25ac0 66 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22  fication (e.g. "
25ad0 43 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  C:").)^.**.** [[
25ae0 63 6f 72 65 20 55 52 49 20 71 75 65 72 79 20 70  core URI query p
25af0 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54  arameters]].** T
25b00 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  he query compone
25b10 6e 74 20 6f 66 20 61 20 55 52 49 20 6d 61 79 20  nt of a URI may 
25b20 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 74 65  contain paramete
25b30 72 73 20 74 68 61 74 20 61 72 65 20 69 6e 74 65  rs that are inte
25b40 72 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 68 65  rpreted.** eithe
25b50 72 20 62 79 20 53 51 4c 69 74 65 20 69 74 73 65  r by SQLite itse
25b60 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 46 53  lf, or by a [VFS
25b70 20 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 69 6d   | custom VFS im
25b80 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a  plementation]..*
25b90 2a 20 53 51 4c 69 74 65 20 61 6e 64 20 69 74 73  * SQLite and its
25ba0 20 62 75 69 6c 74 2d 69 6e 20 5b 56 46 53 65 73   built-in [VFSes
25bb0 5d 20 69 6e 74 65 72 70 72 65 74 20 74 68 65 0a  ] interpret the.
25bc0 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 71 75 65  ** following que
25bd0 72 79 20 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a  ry parameters:.*
25be0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c  *.** <ul>.**   <
25bf0 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20  li> <b>vfs</b>: 
25c00 5e 54 68 65 20 22 76 66 73 22 20 70 61 72 61 6d  ^The "vfs" param
25c10 65 74 65 72 20 6d 61 79 20 62 65 20 75 73 65 64  eter may be used
25c20 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65 20   to specify the 
25c30 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61  name of.**     a
25c40 20 56 46 53 20 6f 62 6a 65 63 74 20 74 68 61 74   VFS object that
25c50 20 70 72 6f 76 69 64 65 73 20 74 68 65 20 6f 70   provides the op
25c60 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69  erating system i
25c70 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 73 68  nterface that sh
25c80 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20 75  ould.**     be u
25c90 73 65 64 20 74 6f 20 61 63 63 65 73 73 20 74 68  sed to access th
25ca0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
25cb0 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74 68 69  on disk. ^If thi
25cc0 73 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20  s option is set 
25cd0 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70  to.**     an emp
25ce0 74 79 20 73 74 72 69 6e 67 20 74 68 65 20 64 65  ty string the de
25cf0 66 61 75 6c 74 20 56 46 53 20 6f 62 6a 65 63 74  fault VFS object
25d00 20 69 73 20 75 73 65 64 2e 20 5e 53 70 65 63 69   is used. ^Speci
25d10 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e  fying an unknown
25d20 0a 2a 2a 20 20 20 20 20 56 46 53 20 69 73 20 61  .**     VFS is a
25d30 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c  n error. ^If sql
25d40 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
25d50 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 76  s used and the v
25d60 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20  fs option is.** 
25d70 20 20 20 20 70 72 65 73 65 6e 74 2c 20 74 68 65      present, the
25d80 6e 20 74 68 65 20 56 46 53 20 73 70 65 63 69 66  n the VFS specif
25d90 69 65 64 20 62 79 20 74 68 65 20 6f 70 74 69 6f  ied by the optio
25da0 6e 20 74 61 6b 65 73 20 70 72 65 63 65 64 65 6e  n takes preceden
25db0 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74  ce over.**     t
25dc0 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20  he value passed 
25dd0 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  as the fourth pa
25de0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
25df0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a  e3_open_v2()..**
25e00 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f  .**   <li> <b>mo
25e10 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f  de</b>: ^(The mo
25e20 64 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  de parameter may
25e30 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65   be set to eithe
25e40 72 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a  r "ro", "rw",.**
25e50 20 20 20 20 20 22 72 77 63 22 2c 20 6f 72 20 22       "rwc", or "
25e60 6d 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d 70 74  memory". Attempt
25e70 69 6e 67 20 74 6f 20 73 65 74 20 69 74 20 74 6f  ing to set it to
25e80 20 61 6e 79 20 6f 74 68 65 72 20 76 61 6c 75 65   any other value
25e90 20 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20 65 72   is.**     an er
25ea0 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e  ror)^. .**     ^
25eb0 49 66 20 22 72 6f 22 20 69 73 20 73 70 65 63 69  If "ro" is speci
25ec0 66 69 65 64 2c 20 74 68 65 6e 20 74 68 65 20 64  fied, then the d
25ed0 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
25ee0 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20  d for read-only 
25ef0 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20  .**     access, 
25f00 6a 75 73 74 20 61 73 20 69 66 20 74 68 65 20 5b  just as if the [
25f10 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
25f20 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64 20 62  ONLY] flag had b
25f30 65 65 6e 20 73 65 74 20 69 6e 20 74 68 65 20 0a  een set in the .
25f40 2a 2a 20 20 20 20 20 74 68 69 72 64 20 61 72 67  **     third arg
25f50 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
25f60 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 49 66 20  _open_v2(). ^If 
25f70 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20  the mode option 
25f80 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20  is set to .**   
25f90 20 20 22 72 77 22 2c 20 74 68 65 6e 20 74 68 65    "rw", then the
25fa0 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
25fb0 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 77 72 69  ned for read-wri
25fc0 74 65 20 28 62 75 74 20 6e 6f 74 20 63 72 65 61  te (but not crea
25fd0 74 65 29 20 0a 2a 2a 20 20 20 20 20 61 63 63 65  te) .**     acce
25fe0 73 73 2c 20 61 73 20 69 66 20 53 51 4c 49 54 45  ss, as if SQLITE
25ff0 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20  _OPEN_READWRITE 
26000 28 62 75 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f  (but not SQLITE_
26010 4f 50 45 4e 5f 43 52 45 41 54 45 29 20 68 61 64  OPEN_CREATE) had
26020 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20 73 65   .**     been se
26030 74 2e 20 5e 56 61 6c 75 65 20 22 72 77 63 22 20  t. ^Value "rwc" 
26040 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f  is equivalent to
26050 20 73 65 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a   setting both .*
26060 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45  *     SQLITE_OPE
26070 4e 5f 52 45 41 44 57 52 49 54 45 20 61 6e 64 20  N_READWRITE and 
26080 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
26090 54 45 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 64  TE.  ^If the mod
260a0 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20  e option is.**  
260b0 20 20 20 73 65 74 20 74 6f 20 22 6d 65 6d 6f 72     set to "memor
260c0 79 22 20 74 68 65 6e 20 61 20 70 75 72 65 20 5b  y" then a pure [
260d0 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61  in-memory databa
260e0 73 65 5d 20 74 68 61 74 20 6e 65 76 65 72 20 72  se] that never r
260f0 65 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72 20 77  eads.**     or w
26100 72 69 74 65 73 20 66 72 6f 6d 20 64 69 73 6b 20  rites from disk 
26110 69 73 20 75 73 65 64 2e 20 5e 49 74 20 69 73 20  is used. ^It is 
26120 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70 65 63  an error to spec
26130 69 66 79 20 61 20 76 61 6c 75 65 20 66 6f 72 0a  ify a value for.
26140 2a 2a 20 20 20 20 20 74 68 65 20 6d 6f 64 65 20  **     the mode 
26150 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 20 69  parameter that i
26160 73 20 6c 65 73 73 20 72 65 73 74 72 69 63 74 69  s less restricti
26170 76 65 20 74 68 61 6e 20 74 68 61 74 20 73 70 65  ve than that spe
26180 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20  cified by.**    
26190 20 74 68 65 20 66 6c 61 67 73 20 70 61 73 73 65   the flags passe
261a0 64 20 69 6e 20 74 68 65 20 74 68 69 72 64 20 70  d in the third p
261b0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
261c0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a  te3_open_v2()..*
261d0 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63  *.**   <li> <b>c
261e0 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63  ache</b>: ^The c
261f0 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d  ache parameter m
26200 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74  ay be set to eit
26210 68 65 72 20 22 73 68 61 72 65 64 22 20 6f 72 0a  her "shared" or.
26220 2a 2a 20 20 20 20 20 22 70 72 69 76 61 74 65 22  **     "private"
26230 2e 20 5e 53 65 74 74 69 6e 67 20 69 74 20 74 6f  . ^Setting it to
26240 20 22 73 68 61 72 65 64 22 20 69 73 20 65 71 75   "shared" is equ
26250 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69  ivalent to setti
26260 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 53 51  ng the.**     SQ
26270 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
26280 43 41 43 48 45 20 62 69 74 20 69 6e 20 74 68 65  CACHE bit in the
26290 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
262a0 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20  passed to.**    
262b0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
262c0 28 29 2e 20 5e 53 65 74 74 69 6e 67 20 74 68 65  (). ^Setting the
262d0 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72   cache parameter
262e0 20 74 6f 20 22 70 72 69 76 61 74 65 22 20 69 73   to "private" is
262f0 20 0a 2a 2a 20 20 20 20 20 65 71 75 69 76 61 6c   .**     equival
26300 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74  ent to setting t
26310 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  he SQLITE_OPEN_P
26320 52 49 56 41 54 45 43 41 43 48 45 20 62 69 74 2e  RIVATECACHE bit.
26330 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73 71 6c 69  .**     ^If sqli
26340 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
26350 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 22 63   used and the "c
26360 61 63 68 65 22 20 70 61 72 61 6d 65 74 65 72 20  ache" parameter 
26370 69 73 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a  is present in.**
26380 20 20 20 20 20 61 20 55 52 49 20 66 69 6c 65 6e       a URI filen
26390 61 6d 65 2c 20 69 74 73 20 76 61 6c 75 65 20 6f  ame, its value o
263a0 76 65 72 72 69 64 65 73 20 61 6e 79 20 62 65 68  verrides any beh
263b0 61 76 69 6f 72 20 72 65 71 75 65 73 74 65 64 20  avior requested 
263c0 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20  by setting.**   
263d0 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52    SQLITE_OPEN_PR
263e0 49 56 41 54 45 43 41 43 48 45 20 6f 72 20 53 51  IVATECACHE or SQ
263f0 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
26400 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 0a 2a  CACHE flag..**.*
26410 2a 20 20 3c 6c 69 3e 20 3c 62 3e 70 73 6f 77 3c  *  <li> <b>psow<
26420 2f 62 3e 3a 20 5e 54 68 65 20 70 73 6f 77 20 70  /b>: ^The psow p
26430 61 72 61 6d 65 74 65 72 20 69 6e 64 69 63 61 74  arameter indicat
26440 65 73 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  es whether or no
26450 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 5b 70 6f  t the.**     [po
26460 77 65 72 73 61 66 65 20 6f 76 65 72 77 72 69 74  wersafe overwrit
26470 65 5d 20 70 72 6f 70 65 72 74 79 20 64 6f 65 73  e] property does
26480 20 6f 72 20 64 6f 65 73 20 6e 6f 74 20 61 70 70   or does not app
26490 6c 79 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20  ly to the.**    
264a0 20 73 74 6f 72 61 67 65 20 6d 65 64 69 61 20 6f   storage media o
264b0 6e 20 77 68 69 63 68 20 74 68 65 20 64 61 74 61  n which the data
264c0 62 61 73 65 20 66 69 6c 65 20 72 65 73 69 64 65  base file reside
264d0 73 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c  s..**.**  <li> <
264e0 62 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e 54  b>nolock</b>: ^T
264f0 68 65 20 6e 6f 6c 6f 63 6b 20 70 61 72 61 6d 65  he nolock parame
26500 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e  ter is a boolean
26510 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
26520 0a 2a 2a 20 20 20 20 20 77 68 69 63 68 20 69 66  .**     which if
26530 20 73 65 74 20 64 69 73 61 62 6c 65 73 20 66 69   set disables fi
26540 6c 65 20 6c 6f 63 6b 69 6e 67 20 69 6e 20 72 6f  le locking in ro
26550 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 20 6d  llback journal m
26560 6f 64 65 73 2e 20 20 54 68 69 73 0a 2a 2a 20 20  odes.  This.**  
26570 20 20 20 69 73 20 75 73 65 66 75 6c 20 66 6f 72     is useful for
26580 20 61 63 63 65 73 73 69 6e 67 20 61 20 64 61 74   accessing a dat
26590 61 62 61 73 65 20 6f 6e 20 61 20 66 69 6c 65 73  abase on a files
265a0 79 73 74 65 6d 20 74 68 61 74 20 64 6f 65 73 20  ystem that does 
265b0 6e 6f 74 0a 2a 2a 20 20 20 20 20 73 75 70 70 6f  not.**     suppo
265c0 72 74 20 6c 6f 63 6b 69 6e 67 2e 20 20 43 61 75  rt locking.  Cau
265d0 74 69 6f 6e 3a 20 20 44 61 74 61 62 61 73 65 20  tion:  Database 
265e0 63 6f 72 72 75 70 74 69 6f 6e 20 6d 69 67 68 74  corruption might
265f0 20 72 65 73 75 6c 74 20 69 66 20 74 77 6f 0a 2a   result if two.*
26600 2a 20 20 20 20 20 6f 72 20 6d 6f 72 65 20 70 72  *     or more pr
26610 6f 63 65 73 73 65 73 20 77 72 69 74 65 20 74 6f  ocesses write to
26620 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
26630 73 65 20 61 6e 64 20 61 6e 79 20 6f 6e 65 20 6f  se and any one o
26640 66 20 74 68 6f 73 65 0a 2a 2a 20 20 20 20 20 70  f those.**     p
26650 72 6f 63 65 73 73 65 73 20 75 73 65 73 20 6e 6f  rocesses uses no
26660 6c 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c  lock=1..**.**  <
26670 6c 69 3e 20 3c 62 3e 69 6d 6d 75 74 61 62 6c 65  li> <b>immutable
26680 3c 2f 62 3e 3a 20 5e 54 68 65 20 69 6d 6d 75 74  </b>: ^The immut
26690 61 62 6c 65 20 70 61 72 61 6d 65 74 65 72 20 69  able parameter i
266a0 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72  s a boolean quer
266b0 79 0a 2a 2a 20 20 20 20 20 70 61 72 61 6d 65 74  y.**     paramet
266c0 65 72 20 74 68 61 74 20 69 6e 64 69 63 61 74 65  er that indicate
266d0 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62  s that the datab
266e0 61 73 65 20 66 69 6c 65 20 69 73 20 73 74 6f 72  ase file is stor
266f0 65 64 20 6f 6e 0a 2a 2a 20 20 20 20 20 72 65 61  ed on.**     rea
26700 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 2e 20 20 5e  d-only media.  ^
26710 57 68 65 6e 20 69 6d 6d 75 74 61 62 6c 65 20 69  When immutable i
26720 73 20 73 65 74 2c 20 53 51 4c 69 74 65 20 61 73  s set, SQLite as
26730 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a  sumes that the.*
26740 2a 20 20 20 20 20 64 61 74 61 62 61 73 65 20 66  *     database f
26750 69 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 63 68  ile cannot be ch
26760 61 6e 67 65 64 2c 20 65 76 65 6e 20 62 79 20 61  anged, even by a
26770 20 70 72 6f 63 65 73 73 20 77 69 74 68 20 68 69   process with hi
26780 67 68 65 72 0a 2a 2a 20 20 20 20 20 70 72 69 76  gher.**     priv
26790 69 6c 65 67 65 2c 20 61 6e 64 20 73 6f 20 74 68  ilege, and so th
267a0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
267b0 65 6e 65 64 20 72 65 61 64 2d 6f 6e 6c 79 20 61  ened read-only a
267c0 6e 64 20 61 6c 6c 20 6c 6f 63 6b 69 6e 67 0a 2a  nd all locking.*
267d0 2a 20 20 20 20 20 61 6e 64 20 63 68 61 6e 67 65  *     and change
267e0 20 64 65 74 65 63 74 69 6f 6e 20 69 73 20 64 69   detection is di
267f0 73 61 62 6c 65 64 2e 20 20 43 61 75 74 69 6f 6e  sabled.  Caution
26800 3a 20 53 65 74 74 69 6e 67 20 74 68 65 20 69 6d  : Setting the im
26810 6d 75 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20 70  mutable.**     p
26820 72 6f 70 65 72 74 79 20 6f 6e 20 61 20 64 61 74  roperty on a dat
26830 61 62 61 73 65 20 66 69 6c 65 20 74 68 61 74 20  abase file that 
26840 64 6f 65 73 20 69 6e 20 66 61 63 74 20 63 68 61  does in fact cha
26850 6e 67 65 20 63 61 6e 20 72 65 73 75 6c 74 0a 2a  nge can result.*
26860 2a 20 20 20 20 20 69 6e 20 69 6e 63 6f 72 72 65  *     in incorre
26870 63 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 73  ct query results
26880 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f   and/or [SQLITE_
26890 43 4f 52 52 55 50 54 5d 20 65 72 72 6f 72 73 2e  CORRUPT] errors.
268a0 0a 2a 2a 20 20 20 20 20 53 65 65 20 61 6c 73 6f  .**     See also
268b0 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  : [SQLITE_IOCAP_
268c0 49 4d 4d 55 54 41 42 4c 45 5d 2e 0a 2a 2a 20 20  IMMUTABLE]..**  
268d0 20 20 20 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a       .** </ul>.*
268e0 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e 67  *.** ^Specifying
268f0 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61   an unknown para
26900 6d 65 74 65 72 20 69 6e 20 74 68 65 20 71 75 65  meter in the que
26910 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  ry component of 
26920 61 20 55 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a  a URI is not an.
26930 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75 74 75 72  ** error.  Futur
26940 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
26950 4c 69 74 65 20 6d 69 67 68 74 20 75 6e 64 65 72  Lite might under
26960 73 74 61 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c  stand additional
26970 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65   query.** parame
26980 74 65 72 73 2e 20 20 53 65 65 20 22 5b 71 75 65  ters.  See "[que
26990 72 79 20 70 61 72 61 6d 65 74 65 72 73 20 77 69  ry parameters wi
269a0 74 68 20 73 70 65 63 69 61 6c 20 6d 65 61 6e 69  th special meani
269b0 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d 22 20 66  ng to SQLite]" f
269c0 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c  or.** additional
269d0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
269e0 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61  .** [[URI filena
269f0 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68  me examples]] <h
26a00 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65  3>URI filename e
26a10 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a  xamples</h3>.**.
26a20 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72  ** <table border
26a30 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65  ="1" align=cente
26a40 72 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e  r cellpadding=5>
26a50 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49  .** <tr><th> URI
26a60 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20   filenames <th> 
26a70 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c  Results.** <tr><
26a80 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62  td> file:data.db
26a90 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
26aa0 20 20 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65     Open the file
26ab0 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68   "data.db" in th
26ac0 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74  e current direct
26ad0 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ory..** <tr><td>
26ae0 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64   file:/home/fred
26af0 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20  /data.db<br>.** 
26b00 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f           file://
26b10 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
26b20 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20  db <br> .**     
26b30 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61       file://loca
26b40 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f  lhost/home/fred/
26b50 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64  data.db <br> <td
26b60 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f  > .**          O
26b70 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  pen the database
26b80 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65   file "/home/fre
26b90 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c  d/data.db"..** <
26ba0 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64  tr><td> file://d
26bb0 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65  arkstar/home/fre
26bc0 64 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a  d/data.db <td> .
26bd0 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65  **          An e
26be0 72 72 6f 72 2e 20 22 64 61 72 6b 73 74 61 72 22  rror. "darkstar"
26bf0 20 69 73 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e   is not a recogn
26c00 69 7a 65 64 20 61 75 74 68 6f 72 69 74 79 2e 0a  ized authority..
26c10 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65  ** <tr><td style
26c20 3d 22 77 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f  ="white-space:no
26c30 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20  wrap"> .**      
26c40 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44      file:///C:/D
26c50 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e 64 25 32  ocuments%20and%2
26c60 30 53 65 74 74 69 6e 67 73 2f 66 72 65 64 2f 44  0Settings/fred/D
26c70 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a  esktop/data.db.*
26c80 2a 20 20 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f  *     <td> Windo
26c90 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68  ws only: Open th
26ca0 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22  e file "data.db"
26cb0 20 6f 6e 20 66 72 65 64 27 73 20 64 65 73 6b 74   on fred's deskt
26cc0 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20  op on drive.**  
26cd0 20 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65          C:. Note
26ce0 20 74 68 61 74 20 74 68 65 20 25 32 30 20 65 73   that the %20 es
26cf0 63 61 70 69 6e 67 20 69 6e 20 74 68 69 73 20 65  caping in this e
26d00 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73 74  xample is not st
26d10 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20  rictly .**      
26d20 20 20 20 20 6e 65 63 65 73 73 61 72 79 20 2d 20      necessary - 
26d30 73 70 61 63 65 20 63 68 61 72 61 63 74 65 72 73  space characters
26d40 20 63 61 6e 20 62 65 20 75 73 65 64 20 6c 69 74   can be used lit
26d50 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20  erally.**       
26d60 20 20 20 69 6e 20 55 52 49 20 66 69 6c 65 6e 61     in URI filena
26d70 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  mes..** <tr><td>
26d80 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f   file:data.db?mo
26d90 64 65 3d 72 6f 26 63 61 63 68 65 3d 70 72 69 76  de=ro&cache=priv
26da0 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  ate <td> .**    
26db0 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20        Open file 
26dc0 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65  "data.db" in the
26dd0 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f   current directo
26de0 72 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79  ry for read-only
26df0 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20   access..**     
26e00 20 20 20 20 20 52 65 67 61 72 64 6c 65 73 73 20       Regardless 
26e10 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
26e20 74 20 73 68 61 72 65 64 2d 63 61 63 68 65 20 6d  t shared-cache m
26e30 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20 62  ode is enabled b
26e40 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65  y.**          de
26e50 66 61 75 6c 74 2c 20 75 73 65 20 61 20 70 72 69  fault, use a pri
26e60 76 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c  vate cache..** <
26e70 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f  tr><td> file:/ho
26e80 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3f  me/fred/data.db?
26e90 76 66 73 3d 75 6e 69 78 2d 64 6f 74 66 69 6c 65  vfs=unix-dotfile
26ea0 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20   <td>.**        
26eb0 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f    Open file "/ho
26ec0 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22  me/fred/data.db"
26ed0 2e 20 55 73 65 20 74 68 65 20 73 70 65 63 69 61  . Use the specia
26ee0 6c 20 56 46 53 20 22 75 6e 69 78 2d 64 6f 74 66  l VFS "unix-dotf
26ef0 69 6c 65 22 0a 2a 2a 20 20 20 20 20 20 20 20 20  ile".**         
26f00 20 74 68 61 74 20 75 73 65 73 20 64 6f 74 2d 66   that uses dot-f
26f10 69 6c 65 73 20 69 6e 20 70 6c 61 63 65 20 6f 66  iles in place of
26f20 20 70 6f 73 69 78 20 61 64 76 69 73 6f 72 79 20   posix advisory 
26f30 6c 6f 63 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 72 3e  locking..** <tr>
26f40 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64  <td> file:data.d
26f50 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20  b?mode=readonly 
26f60 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
26f70 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 72 65 61    An error. "rea
26f80 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61 20  donly" is not a 
26f90 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72  valid option for
26fa0 20 74 68 65 20 22 6d 6f 64 65 22 20 70 61 72 61   the "mode" para
26fb0 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c  meter..** </tabl
26fc0 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65  e>.**.** ^URI he
26fd0 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65  xadecimal escape
26fe0 20 73 65 71 75 65 6e 63 65 73 20 28 25 48 48 29   sequences (%HH)
26ff0 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 77   are supported w
27000 69 74 68 69 6e 20 74 68 65 20 70 61 74 68 20 61  ithin the path a
27010 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70  nd.** query comp
27020 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55 52 49 2e  onents of a URI.
27030 20 41 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65   A hexadecimal e
27040 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 20 63  scape sequence c
27050 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20  onsists of a.** 
27060 70 65 72 63 65 6e 74 20 73 69 67 6e 20 2d 20 22  percent sign - "
27070 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79  %" - followed by
27080 20 65 78 61 63 74 6c 79 20 74 77 6f 20 68 65 78   exactly two hex
27090 61 64 65 63 69 6d 61 6c 20 64 69 67 69 74 73 20  adecimal digits 
270a0 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e 67 20 61  .** specifying a
270b0 6e 20 6f 63 74 65 74 20 76 61 6c 75 65 2e 20 5e  n octet value. ^
270c0 42 65 66 6f 72 65 20 74 68 65 20 70 61 74 68 20  Before the path 
270d0 6f 72 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  or query compone
270e0 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20  nts of a.** URI 
270f0 66 69 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e 74  filename are int
27100 65 72 70 72 65 74 65 64 2c 20 74 68 65 79 20 61  erpreted, they a
27110 72 65 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67  re encoded using
27120 20 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a   UTF-8 and all .
27130 2a 2a 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65  ** hexadecimal e
27140 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20  scape sequences 
27150 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 73 69  replaced by a si
27160 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e 74 61 69  ngle byte contai
27170 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72  ning the.** corr
27180 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e  esponding octet.
27190 20 49 66 20 74 68 69 73 20 70 72 6f 63 65 73 73   If this process
271a0 20 67 65 6e 65 72 61 74 65 73 20 61 6e 20 69 6e   generates an in
271b0 76 61 6c 69 64 20 55 54 46 2d 38 20 65 6e 63 6f  valid UTF-8 enco
271c0 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73  ding,.** the res
271d0 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
271e0 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74  ed..**.** <b>Not
271f0 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65  e to Windows use
27200 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63  rs:</b>  The enc
27210 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74  oding used for t
27220 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
27230 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74  ment.** of sqlit
27240 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
27250 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
27260 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e  must be UTF-8, n
27270 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63  ot whatever.** c
27280 6f 64 65 70 61 67 65 20 69 73 20 63 75 72 72 65  odepage is curre
27290 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46  ntly defined.  F
272a0 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e  ilenames contain
272b0 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61  ing internationa
272c0 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20  l.** characters 
272d0 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
272e0 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72  d to UTF-8 prior
272f0 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d   to passing them
27300 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33   into.** sqlite3
27310 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74  _open() or sqlit
27320 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a  e3_open_v2()..**
27330 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57  .** <b>Note to W
27340 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 20 75  indows Runtime u
27350 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74  sers:</b>  The t
27360 65 6d 70 6f 72 61 72 79 20 64 69 72 65 63 74 6f  emporary directo
27370 72 79 20 6d 75 73 74 20 62 65 20 73 65 74 0a 2a  ry must be set.*
27380 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69  * prior to calli
27390 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ng sqlite3_open(
273a0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  ) or sqlite3_ope
273b0 6e 5f 76 32 28 29 2e 20 20 4f 74 68 65 72 77 69  n_v2().  Otherwi
273c0 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66  se, various.** f
273d0 65 61 74 75 72 65 73 20 74 68 61 74 20 72 65 71  eatures that req
273e0 75 69 72 65 20 74 68 65 20 75 73 65 20 6f 66 20  uire the use of 
273f0 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 20  temporary files 
27400 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20  may fail..**.** 
27410 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
27420 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72  e3_temp_director
27430 79 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  y].*/.int sqlite
27440 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20  3_open(.  const 
27450 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  char *filename, 
27460 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
27470 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a  lename (UTF-8) *
27480 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
27490 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db          /* O
274a0 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
274b0 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  ndle */.);.int s
274c0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20  qlite3_open16(. 
274d0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c   const void *fil
274e0 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61  ename,   /* Data
274f0 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55  base filename (U
27500 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69  TF-16) */.  sqli
27510 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20  te3 **ppDb      
27520 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
27530 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
27540 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
27550 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20  pen_v2(.  const 
27560 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  char *filename, 
27570 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
27580 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a  lename (UTF-8) *
27590 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
275a0 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db,         /* O
275b0 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
275c0 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c  ndle */.  int fl
275d0 61 67 73 2c 20 20 20 20 20 20 20 20 20 20 20 20  ags,            
275e0 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20    /* Flags */.  
275f0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73  const char *zVfs
27600 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20          /* Name 
27610 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f  of VFS module to
27620 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a   use */.);../*.*
27630 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61  * CAPI3REF: Obta
27640 69 6e 20 56 61 6c 75 65 73 20 46 6f 72 20 55 52  in Values For UR
27650 49 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a  I Parameters.**.
27660 2a 2a 20 54 68 65 73 65 20 61 72 65 20 75 74 69  ** These are uti
27670 6c 69 74 79 20 72 6f 75 74 69 6e 65 73 2c 20 75  lity routines, u
27680 73 65 66 75 6c 20 74 6f 20 56 46 53 20 69 6d 70  seful to VFS imp
27690 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68  lementations, th
276a0 61 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73  at check.** to s
276b0 65 65 20 69 66 20 61 20 64 61 74 61 62 61 73 65  ee if a database
276c0 20 66 69 6c 65 20 77 61 73 20 61 20 55 52 49 20   file was a URI 
276d0 74 68 61 74 20 63 6f 6e 74 61 69 6e 65 64 20 61  that contained a
276e0 20 73 70 65 63 69 66 69 63 20 71 75 65 72 79 20   specific query 
276f0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 61  .** parameter, a
27700 6e 64 20 69 66 20 73 6f 20 6f 62 74 61 69 6e 73  nd if so obtains
27710 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
27720 61 74 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  at query paramet
27730 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69  er..**.** If F i
27740 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  s the database f
27750 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20  ilename pointer 
27760 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20  passed into the 
27770 78 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f  xOpen() method o
27780 66 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c  f .** a VFS impl
27790 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20  ementation when 
277a0 74 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65  the flags parame
277b0 74 65 72 20 74 6f 20 78 4f 70 65 6e 28 29 20 68  ter to xOpen() h
277c0 61 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f  as one or .** mo
277d0 72 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54  re of the [SQLIT
277e0 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b  E_OPEN_URI] or [
277f0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
27800 5f 44 42 5d 20 62 69 74 73 20 73 65 74 20 61 6e  _DB] bits set an
27810 64 0a 2a 2a 20 50 20 69 73 20 74 68 65 20 6e 61  d.** P is the na
27820 6d 65 20 6f 66 20 74 68 65 20 71 75 65 72 79 20  me of the query 
27830 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a  parameter, then.
27840 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70  ** sqlite3_uri_p
27850 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65  arameter(F,P) re
27860 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20  turns the value 
27870 6f 66 20 74 68 65 20 50 0a 2a 2a 20 70 61 72 61  of the P.** para
27880 6d 65 74 65 72 20 69 66 20 69 74 20 65 78 69 73  meter if it exis
27890 74 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69  ts or a NULL poi
278a0 6e 74 65 72 20 69 66 20 50 20 64 6f 65 73 20 6e  nter if P does n
278b0 6f 74 20 61 70 70 65 61 72 20 61 73 20 61 20 0a  ot appear as a .
278c0 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  ** query paramet
278d0 65 72 20 6f 6e 20 46 2e 20 20 49 66 20 50 20 69  er on F.  If P i
278e0 73 20 61 20 71 75 65 72 79 20 70 61 72 61 6d 65  s a query parame
278f0 74 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20  ter of F.** has 
27900 6e 6f 20 65 78 70 6c 69 63 69 74 20 76 61 6c 75  no explicit valu
27910 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  e, then sqlite3_
27920 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c  uri_parameter(F,
27930 50 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20  P) returns.** a 
27940 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d  pointer to an em
27950 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  pty string..**.*
27960 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72  * The sqlite3_ur
27970 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29  i_boolean(F,P,B)
27980 20 72 6f 75 74 69 6e 65 20 61 73 73 75 6d 65 73   routine assumes
27990 20 74 68 61 74 20 50 20 69 73 20 61 20 62 6f 6f   that P is a boo
279a0 6c 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65  lean.** paramete
279b0 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 72  r and returns tr
279c0 75 65 20 28 31 29 20 6f 72 20 66 61 6c 73 65 20  ue (1) or false 
279d0 28 30 29 20 61 63 63 6f 72 64 69 6e 67 20 74 6f  (0) according to
279e0 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66   the value.** of
279f0 20 50 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33   P.  The sqlite3
27a00 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50  _uri_boolean(F,P
27a10 2c 42 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ,B) routine retu
27a20 72 6e 73 20 74 72 75 65 20 28 31 29 20 69 66 20  rns true (1) if 
27a30 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  the.** value of 
27a40 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20  query parameter 
27a50 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 79 65 73  P is one of "yes
27a60 22 2c 20 22 74 72 75 65 22 2c 20 6f 72 20 22 6f  ", "true", or "o
27a70 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73  n" in any.** cas
27a80 65 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75  e or if the valu
27a90 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20  e begins with a 
27aa0 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e  non-zero number.
27ab0 20 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65    The .** sqlite
27ac0 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c  3_uri_boolean(F,
27ad0 50 2c 42 29 20 72 6f 75 74 69 6e 65 73 20 72 65  P,B) routines re
27ae0 74 75 72 6e 73 20 66 61 6c 73 65 20 28 30 29 20  turns false (0) 
27af0 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 0a  if the value of.
27b00 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  ** query paramet
27b10 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22  er P is one of "
27b20 6e 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72  no", "false", or
27b30 20 22 6f 66 66 22 20 69 6e 20 61 6e 79 20 63 61   "off" in any ca
27b40 73 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20  se or.** if the 
27b50 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74  value begins wit
27b60 68 20 61 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f  h a numeric zero
27b70 2e 20 20 49 66 20 50 20 69 73 20 6e 6f 74 20 61  .  If P is not a
27b80 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65   query.** parame
27b90 74 65 72 20 6f 6e 20 46 20 6f 72 20 69 66 20 74  ter on F or if t
27ba0 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73  he value of P is
27bb0 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68 20   does not match 
27bc0 61 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62  any of the.** ab
27bd0 6f 76 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ove, then sqlite
27be0 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c  3_uri_boolean(F,
27bf0 50 2c 42 29 20 72 65 74 75 72 6e 73 20 28 42 21  P,B) returns (B!
27c00 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  =0)..**.** The s
27c10 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34  qlite3_uri_int64
27c20 28 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e 65 20  (F,P,D) routine 
27c30 63 6f 6e 76 65 72 74 73 20 74 68 65 20 76 61 6c  converts the val
27c40 75 65 20 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a  ue of P into a.*
27c50 2a 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  * 64-bit signed 
27c60 69 6e 74 65 67 65 72 20 61 6e 64 20 72 65 74 75  integer and retu
27c70 72 6e 73 20 74 68 61 74 20 69 6e 74 65 67 65 72  rns that integer
27c80 2c 20 6f 72 20 44 20 69 66 20 50 20 64 6f 65 73  , or D if P does
27c90 20 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20   not.** exist.  
27ca0 49 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  If the value of 
27cb0 50 20 69 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f  P is something o
27cc0 74 68 65 72 20 74 68 61 6e 20 61 6e 20 69 6e 74  ther than an int
27cd0 65 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65  eger, then.** ze
27ce0 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  ro is returned..
27cf0 2a 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73 20 61  ** .** If F is a
27d00 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74   NULL pointer, t
27d10 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  hen sqlite3_uri_
27d20 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72  parameter(F,P) r
27d30 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a  eturns NULL and.
27d40 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  ** sqlite3_uri_b
27d50 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65  oolean(F,P,B) re
27d60 74 75 72 6e 73 20 42 2e 20 20 49 66 20 46 20 69  turns B.  If F i
27d70 73 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69  s not a NULL poi
27d80 6e 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e  nter and.** is n
27d90 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69  ot a database fi
27da0 6c 65 20 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e  le pathname poin
27db0 74 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20  ter that SQLite 
27dc0 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20  passed into the 
27dd0 78 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74  xOpen.** VFS met
27de0 68 6f 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65  hod, then the be
27df0 68 61 76 69 6f 72 20 6f 66 20 74 68 69 73 20 72  havior of this r
27e00 6f 75 74 69 6e 65 20 69 73 20 75 6e 64 65 66 69  outine is undefi
27e10 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79  ned and probably
27e20 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 2e  .** undesirable.
27e30 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
27e40 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61  sqlite3_uri_para
27e50 6d 65 74 65 72 28 63 6f 6e 73 74 20 63 68 61 72  meter(const char
27e60 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e   *zFilename, con
27e70 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 29  st char *zParam)
27e80 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 75 72  ;.int sqlite3_ur
27e90 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 20  i_boolean(const 
27ea0 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e  char *zFile, con
27eb0 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 2c  st char *zParam,
27ec0 20 69 6e 74 20 62 44 65 66 61 75 6c 74 29 3b 0a   int bDefault);.
27ed0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
27ee0 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28  lite3_uri_int64(
27ef0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e  const char*, con
27f00 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65  st char*, sqlite
27f10 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a  3_int64);.../*.*
27f20 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f  * CAPI3REF: Erro
27f30 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73  r Codes And Mess
27f40 61 67 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ages.** METHOD: 
27f50 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 49  sqlite3.**.** ^I
27f60 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
27f70 74 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20  t sqlite3_* API 
27f80 63 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 20  call associated 
27f90 77 69 74 68 20 0a 2a 2a 20 5b 64 61 74 61 62 61  with .** [databa
27fa0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
27fb0 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 20 74 68   failed, then th
27fc0 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  e sqlite3_errcod
27fd0 65 28 44 29 20 69 6e 74 65 72 66 61 63 65 0a 2a  e(D) interface.*
27fe0 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  * returns the nu
27ff0 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f  meric [result co
28000 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64  de] or [extended
28010 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f   result code] fo
28020 72 20 74 68 61 74 0a 2a 2a 20 41 50 49 20 63 61  r that.** API ca
28030 6c 6c 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6d 6f  ll..** If the mo
28040 73 74 20 72 65 63 65 6e 74 20 41 50 49 20 63 61  st recent API ca
28050 6c 6c 20 77 61 73 20 73 75 63 63 65 73 73 66 75  ll was successfu
28060 6c 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72  l,.** then the r
28070 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d  eturn value from
28080 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65   sqlite3_errcode
28090 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  () is undefined.
280a0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
280b0 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64  _extended_errcod
280c0 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  e().** interface
280d0 20 69 73 20 74 68 65 20 73 61 6d 65 20 65 78 63   is the same exc
280e0 65 70 74 20 74 68 61 74 20 69 74 20 61 6c 77 61  ept that it alwa
280f0 79 73 20 72 65 74 75 72 6e 73 20 74 68 65 20 0a  ys returns the .
28100 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
28110 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20 77  ult code] even w
28120 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73  hen extended res
28130 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a  ult codes are.**
28140 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a   disabled..**.**
28150 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72   ^The sqlite3_er
28160 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74  rmsg() and sqlit
28170 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65  e3_errmsg16() re
28180 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e  turn English-lan
28190 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68  guage.** text th
281a0 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65  at describes the
281b0 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65   error, as eithe
281c0 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  r UTF-8 or UTF-1
281d0 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  6 respectively..
281e0 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68  ** ^(Memory to h
281f0 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65  old the error me
28200 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
28210 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c  managed internal
28220 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  ly..** The appli
28230 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20  cation does not 
28240 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62  need to worry ab
28250 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68 65 20  out freeing the 
28260 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76  result..** Howev
28270 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74  er, the error st
28280 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76  ring might be ov
28290 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61  erwritten or dea
282a0 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73  llocated by.** s
282b0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
282c0 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  to other SQLite 
282d0 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74 69  interface functi
282e0 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ons.)^.**.** ^Th
282f0 65 20 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72  e sqlite3_errstr
28300 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
28310 75 72 6e 73 20 74 68 65 20 45 6e 67 6c 69 73 68  urns the English
28320 2d 6c 61 6e 67 75 61 67 65 20 74 65 78 74 0a 2a  -language text.*
28330 2a 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73  * that describes
28340 20 74 68 65 20 5b 72 65 73 75 6c 74 20 63 6f 64   the [result cod
28350 65 5d 2c 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a  e], as UTF-8..**
28360 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c   ^(Memory to hol
28370 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  d the error mess
28380 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61  age string is ma
28390 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  naged internally
283a0 0a 2a 2a 20 61 6e 64 20 6d 75 73 74 20 6e 6f 74  .** and must not
283b0 20 62 65 20 66 72 65 65 64 20 62 79 20 74 68 65   be freed by the
283c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a   application)^..
283d0 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73  **.** When the s
283e0 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61  erialized [threa
283f0 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e  ding mode] is in
28400 20 75 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62   use, it might b
28410 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68  e the.** case th
28420 61 74 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f  at a second erro
28430 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65  r occurs on a se
28440 70 61 72 61 74 65 20 74 68 72 65 61 64 20 69 6e  parate thread in
28450 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20   between.** the 
28460 74 69 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73  time of the firs
28470 74 20 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20  t error and the 
28480 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e  call to these in
28490 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65  terfaces..** Whe
284a0 6e 20 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20  n that happens, 
284b0 74 68 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72  the second error
284c0 20 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65   will be reporte
284d0 64 20 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a  d since these.**
284e0 20 69 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61   interfaces alwa
284f0 79 73 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f  ys report the mo
28500 73 74 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74  st recent result
28510 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74  .  To avoid.** t
28520 68 69 73 2c 20 65 61 63 68 20 74 68 72 65 61 64  his, each thread
28530 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c   can obtain excl
28540 75 73 69 76 65 20 75 73 65 20 6f 66 20 74 68 65  usive use of the
28550 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
28560 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69  ction] D.** by i
28570 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33  nvoking [sqlite3
28580 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73  _mutex_enter]([s
28590 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d  qlite3_db_mutex]
285a0 28 44 29 29 20 62 65 66 6f 72 65 20 62 65 67 69  (D)) before begi
285b0 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20  nning.** to use 
285c0 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b  D and invoking [
285d0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65  sqlite3_mutex_le
285e0 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62  ave]([sqlite3_db
285f0 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 66 74 65  _mutex](D)) afte
28600 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74  r.** all calls t
28610 6f 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 73  o the interfaces
28620 20 6c 69 73 74 65 64 20 68 65 72 65 20 61 72 65   listed here are
28630 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a   completed..**.*
28640 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63  * If an interfac
28650 65 20 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c  e fails with SQL
28660 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74  ITE_MISUSE, that
28670 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72   means the inter
28680 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f  face.** was invo
28690 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20  ked incorrectly 
286a0 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  by the applicati
286b0 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73  on.  In that cas
286c0 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20  e, the.** error 
286d0 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65  code and message
286e0 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20   may or may not 
286f0 62 65 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73  be set..*/.int s
28700 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73  qlite3_errcode(s
28710 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 69 6e 74  qlite3 *db);.int
28720 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
28730 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65  d_errcode(sqlite
28740 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68  3 *db);.const ch
28750 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d  ar *sqlite3_errm
28760 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f  sg(sqlite3*);.co
28770 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
28780 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74  3_errmsg16(sqlit
28790 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  e3*);.const char
287a0 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72   *sqlite3_errstr
287b0 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  (int);../*.** CA
287c0 50 49 33 52 45 46 3a 20 50 72 65 70 61 72 65 64  PI3REF: Prepared
287d0 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63   Statement Objec
287e0 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  t.** KEYWORDS: {
287f0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
28800 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74  nt} {prepared st
28810 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20  atements}.**.** 
28820 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
28830 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65  his object repre
28840 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53  sents a single S
28850 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  QL statement tha
28860 74 0a 2a 2a 20 68 61 73 20 62 65 65 6e 20 63 6f  t.** has been co
28870 6d 70 69 6c 65 64 20 69 6e 74 6f 20 62 69 6e 61  mpiled into bina
28880 72 79 20 66 6f 72 6d 20 61 6e 64 20 69 73 20 72  ry form and is r
28890 65 61 64 79 20 74 6f 20 62 65 20 65 76 61 6c 75  eady to be evalu
288a0 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e  ated..**.** Thin
288b0 6b 20 6f 66 20 65 61 63 68 20 53 51 4c 20 73 74  k of each SQL st
288c0 61 74 65 6d 65 6e 74 20 61 73 20 61 20 73 65 70  atement as a sep
288d0 61 72 61 74 65 20 63 6f 6d 70 75 74 65 72 20 70  arate computer p
288e0 72 6f 67 72 61 6d 2e 20 20 54 68 65 0a 2a 2a 20  rogram.  The.** 
288f0 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78  original SQL tex
28900 74 20 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  t is source code
28910 2e 20 20 41 20 70 72 65 70 61 72 65 64 20 73 74  .  A prepared st
28920 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 0a  atement object .
28930 2a 2a 20 69 73 20 74 68 65 20 63 6f 6d 70 69 6c  ** is the compil
28940 65 64 20 6f 62 6a 65 63 74 20 63 6f 64 65 2e 20  ed object code. 
28950 20 41 6c 6c 20 53 51 4c 20 6d 75 73 74 20 62 65   All SQL must be
28960 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20   converted into 
28970 61 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74  a.** prepared st
28980 61 74 65 6d 65 6e 74 20 62 65 66 6f 72 65 20 69  atement before i
28990 74 20 63 61 6e 20 62 65 20 72 75 6e 2e 0a 2a 2a  t can be run..**
289a0 0a 2a 2a 20 54 68 65 20 6c 69 66 65 2d 63 79 63  .** The life-cyc
289b0 6c 65 20 6f 66 20 61 20 70 72 65 70 61 72 65 64  le of a prepared
289c0 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63   statement objec
289d0 74 20 75 73 75 61 6c 6c 79 20 67 6f 65 73 20 6c  t usually goes l
289e0 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20  ike this:.**.** 
289f0 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65  <ol>.** <li> Cre
28a00 61 74 65 20 74 68 65 20 70 72 65 70 61 72 65 64  ate the prepared
28a10 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63   statement objec
28a20 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
28a30 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2e 0a  _prepare_v2()]..
28a40 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c  ** <li> Bind val
28a50 75 65 73 20 74 6f 20 5b 70 61 72 61 6d 65 74 65  ues to [paramete
28a60 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71  rs] using the sq
28a70 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a  lite3_bind_*().*
28a80 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65  *      interface
28a90 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74  s..** <li> Run t
28aa0 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e  he SQL by callin
28ab0 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
28ac0 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74  )] one or more t
28ad0 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65  imes..** <li> Re
28ae0 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64  set the prepared
28af0 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
28b00 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
28b10 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a  )] then go back.
28b20 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70 20  **      to step 
28b30 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f  2.  Do this zero
28b40 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a   or more times..
28b50 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20  ** <li> Destroy 
28b60 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67  the object using
28b70 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
28b80 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a  ze()]..** </ol>.
28b90 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
28ba0 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73  t sqlite3_stmt s
28bb0 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a  qlite3_stmt;../*
28bc0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75  .** CAPI3REF: Ru
28bd0 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a  n-time Limits.**
28be0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
28bf0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e  .**.** ^(This in
28c00 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74  terface allows t
28c10 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f  he size of vario
28c20 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f  us constructs to
28c30 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f   be limited.** o
28c40 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62  n a connection b
28c50 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73  y connection bas
28c60 69 73 2e 20 20 54 68 65 20 66 69 72 73 74 20 70  is.  The first p
28c70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a  arameter is the.
28c80 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
28c90 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c  nection] whose l
28ca0 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20 73 65  imit is to be se
28cb0 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54  t or queried.  T
28cc0 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72  he.** second par
28cd0 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66  ameter is one of
28ce0 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65   the [limit cate
28cf0 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64 65 66  gories] that def
28d00 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f  ine a.** class o
28d10 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20  f constructs to 
28d20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e  be size limited.
28d30 20 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61    The third para
28d40 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
28d50 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68  new limit for th
28d60 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a  at construct.)^.
28d70 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65  **.** ^If the ne
28d80 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67  w limit is a neg
28d90 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68  ative number, th
28da0 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61  e limit is uncha
28db0 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65  nged..** ^(For e
28dc0 61 63 68 20 6c 69 6d 69 74 20 63 61 74 65 67 6f  ach limit catego
28dd0 72 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ry SQLITE_LIMIT_
28de0 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72  <i>NAME</i> ther
28df0 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69  e is a .** [limi
28e00 74 73 20 7c 20 68 61 72 64 20 75 70 70 65 72 20  ts | hard upper 
28e10 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74  bound].** set at
28e20 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79   compile-time by
28e30 20 61 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f   a C preprocesso
28e40 72 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a  r macro called.*
28e50 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49  * [limits | SQLI
28e60 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f  TE_MAX_<i>NAME</
28e70 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c  i>]..** (The "_L
28e80 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61  IMIT_" in the na
28e90 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f  me is changed to
28ea0 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20   "_MAX_".))^.** 
28eb0 5e 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63  ^Attempts to inc
28ec0 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62  rease a limit ab
28ed0 6f 76 65 20 69 74 73 20 68 61 72 64 20 75 70 70  ove its hard upp
28ee0 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20  er bound are.** 
28ef0 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74  silently truncat
28f00 65 64 20 74 6f 20 74 68 65 20 68 61 72 64 20 75  ed to the hard u
28f10 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a  pper bound..**.*
28f20 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20 6f 66  * ^Regardless of
28f30 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
28f40 74 68 65 20 6c 69 6d 69 74 20 77 61 73 20 63 68  the limit was ch
28f50 61 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b  anged, the .** [
28f60 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
28f70 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
28f80 6e 73 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c  ns the prior val
28f90 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e  ue of the limit.
28fa0 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66  .** ^Hence, to f
28fb0 69 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74 20  ind the current 
28fc0 76 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69 74  value of a limit
28fd0 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 69 6e   without changin
28fe0 67 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20  g it,.** simply 
28ff0 69 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e 74 65  invoke this inte
29000 72 66 61 63 65 20 77 69 74 68 20 74 68 65 20 74  rface with the t
29010 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 73  hird parameter s
29020 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20  et to -1..**.** 
29030 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20  Run-time limits 
29040 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72  are intended for
29050 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74   use in applicat
29060 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65  ions that manage
29070 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f  .** both their o
29080 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  wn internal data
29090 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61  base and also da
290a0 74 61 62 61 73 65 73 20 74 68 61 74 20 61 72 65  tabases that are
290b0 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62   controlled.** b
290c0 79 20 75 6e 74 72 75 73 74 65 64 20 65 78 74 65  y untrusted exte
290d0 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41  rnal sources.  A
290e0 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63  n example applic
290f0 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61  ation might be a
29100 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65 72 20  .** web browser 
29110 74 68 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e  that has its own
29120 20 64 61 74 61 62 61 73 65 73 20 66 6f 72 20 73   databases for s
29130 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61  toring history a
29140 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64  nd.** separate d
29150 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c  atabases control
29160 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72 69 70  led by JavaScrip
29170 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64  t applications d
29180 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66  ownloaded.** off
29190 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20   the Internet.  
291a0 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  The internal dat
291b0 61 62 61 73 65 73 20 63 61 6e 20 62 65 20 67 69  abases can be gi
291c0 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65  ven the.** large
291d0 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73  , default limits
291e0 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e  .  Databases man
291f0 61 67 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c  aged by external
29200 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20   sources can.** 
29210 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d  be given much sm
29220 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73  aller limits des
29230 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74  igned to prevent
29240 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72   a denial of ser
29250 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20  vice.** attack. 
29260 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68   Developers migh
29270 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75  t also want to u
29280 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  se the [sqlite3_
29290 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
292a0 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74  ].** interface t
292b0 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f  o further contro
292c0 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e  l untrusted SQL.
292d0 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68    The size of th
292e0 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72  e database.** cr
292f0 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72  eated by an untr
29300 75 73 74 65 64 20 73 63 72 69 70 74 20 63 61 6e  usted script can
29310 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73   be contained us
29320 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f  ing the.** [max_
29330 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41  page_count] [PRA
29340 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  GMA]..**.** New 
29350 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63  run-time limit c
29360 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65  ategories may be
29370 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
29380 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e   releases..*/.in
29390 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28  t sqlite3_limit(
293a0 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64  sqlite3*, int id
293b0 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a  , int newVal);..
293c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
293d0 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43  Run-Time Limit C
293e0 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59  ategories.** KEY
293f0 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61  WORDS: {limit ca
29400 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20  tegory} {*limit 
29410 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a  categories}.**.*
29420 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
29430 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73  s define various
29440 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d   performance lim
29450 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20  its.** that can 
29460 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72 75  be lowered at ru
29470 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 71  n-time using [sq
29480 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a  lite3_limit()]..
29490 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73 20  ** The synopsis 
294a0 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 20  of the meanings 
294b0 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c  of the various l
294c0 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20 62  imits is shown b
294d0 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f  elow..** Additio
294e0 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  nal information 
294f0 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74 20  is available at 
29500 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73  [limits | Limits
29510 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a   in SQLite]..**.
29520 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c  ** <dl>.** [[SQL
29530 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
29540 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
29550 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74  LIMIT_LENGTH</dt
29560 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
29570 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79  imum size of any
29580 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20   string or BLOB 
29590 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c 20 69 6e  or table row, in
295a0 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a   bytes.<dd>)^.**
295b0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
295c0 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20  IT_SQL_LENGTH]] 
295d0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
295e0 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64  IT_SQL_LENGTH</d
295f0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
29600 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
29610 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
29620 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e  , in bytes.</dd>
29630 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
29640 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d  E_LIMIT_COLUMN]]
29650 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
29660 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a  MIT_COLUMN</dt>.
29670 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
29680 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  um number of col
29690 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20  umns in a table 
296a0 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e  definition or in
296b0 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73   the.** result s
296c0 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d  et of a [SELECT]
296d0 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20   or the maximum 
296e0 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
296f0 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a  s in an index.**
29700 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20   or in an ORDER 
29710 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63  BY or GROUP BY c
29720 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  lause.</dd>)^.**
29730 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
29740 49 54 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d 20  IT_EXPR_DEPTH]] 
29750 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
29760 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64  IT_EXPR_DEPTH</d
29770 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
29780 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74  ximum depth of t
29790 68 65 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e  he parse tree on
297a0 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e   any expression.
297b0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
297c0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d  SQLITE_LIMIT_COM
297d0 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20 5e  POUND_SELECT]] ^
297e0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
297f0 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
29800 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  T</dt>.** <dd>Th
29810 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
29820 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63   of terms in a c
29830 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73  ompound SELECT s
29840 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e  tatement.</dd>)^
29850 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
29860 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d 20  LIMIT_VDBE_OP]] 
29870 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
29880 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a  IT_VDBE_OP</dt>.
29890 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
298a0 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73  um number of ins
298b0 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 76  tructions in a v
298c0 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 70  irtual machine p
298d0 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74  rogram.** used t
298e0 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53  o implement an S
298f0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49  QL statement.  I
29900 66 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  f [sqlite3_prepa
29910 72 65 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 74  re_v2()] or.** t
29920 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20 74 72  he equivalent tr
29930 69 65 73 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ies to allocate 
29940 73 70 61 63 65 20 66 6f 72 20 6d 6f 72 65 20 74  space for more t
29950 68 61 6e 20 74 68 69 73 20 6d 61 6e 79 20 6f 70  han this many op
29960 63 6f 64 65 73 0a 2a 2a 20 69 6e 20 61 20 73 69  codes.** in a si
29970 6e 67 6c 65 20 70 72 65 70 61 72 65 64 20 73 74  ngle prepared st
29980 61 74 65 6d 65 6e 74 2c 20 61 6e 20 53 51 4c 49  atement, an SQLI
29990 54 45 5f 4e 4f 4d 45 4d 20 65 72 72 6f 72 20 69  TE_NOMEM error i
299a0 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e  s returned.</dd>
299b0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
299c0 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e  E_LIMIT_FUNCTION
299d0 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  _ARG]] ^(<dt>SQL
299e0 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
299f0 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c  ON_ARG</dt>.** <
29a00 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
29a10 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
29a20 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e  ts on a function
29a30 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
29a40 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54  [SQLITE_LIMIT_AT
29a50 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53  TACHED]] ^(<dt>S
29a60 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41  QLITE_LIMIT_ATTA
29a70 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  CHED</dt>.** <dd
29a80 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
29a90 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20 7c  ber of [ATTACH |
29aa0 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
29ab0 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a  ses].)^</dd>.**.
29ac0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
29ad0 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
29ae0 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74  ENGTH]].** ^(<dt
29af0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49  >SQLITE_LIMIT_LI
29b00 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54  KE_PATTERN_LENGT
29b10 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
29b20 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  e maximum length
29b30 20 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e 20   of the pattern 
29b40 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
29b50 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c  [LIKE] or.** [GL
29b60 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f  OB] operators.</
29b70 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
29b80 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
29b90 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20  BLE_NUMBER]].** 
29ba0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
29bb0 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
29bc0 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  ER</dt>.** <dd>T
29bd0 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78  he maximum index
29be0 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b   number of any [
29bf0 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e  parameter] in an
29c00 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29   SQL statement.)
29c10 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
29c20 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44  _LIMIT_TRIGGER_D
29c30 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  EPTH]] ^(<dt>SQL
29c40 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45  ITE_LIMIT_TRIGGE
29c50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20  R_DEPTH</dt>.** 
29c60 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
29c70 64 65 70 74 68 20 6f 66 20 72 65 63 75 72 73 69  depth of recursi
29c80 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73 2e  on for triggers.
29c90 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
29ca0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52  SQLITE_LIMIT_WOR
29cb0 4b 45 52 5f 54 48 52 45 41 44 53 5d 5d 20 5e 28  KER_THREADS]] ^(
29cc0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
29cd0 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 3c  _WORKER_THREADS<
29ce0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
29cf0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
29d00 66 20 61 75 78 69 6c 69 61 72 79 20 77 6f 72 6b  f auxiliary work
29d10 65 72 20 74 68 72 65 61 64 73 20 74 68 61 74 20  er threads that 
29d20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 70 72 65  a single.** [pre
29d30 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
29d40 20 6d 61 79 20 73 74 61 72 74 2e 3c 2f 64 64 3e   may start.</dd>
29d50 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23  )^.** </dl>.*/.#
29d60 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
29d70 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 20 20  MIT_LENGTH      
29d80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0a                0.
29d90 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
29da0 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20  IMIT_SQL_LENGTH 
29db0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
29dc0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
29dd0 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20  LIMIT_COLUMN    
29de0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
29df0 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
29e00 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54  _LIMIT_EXPR_DEPT
29e10 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
29e20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   3.#define SQLIT
29e30 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44  E_LIMIT_COMPOUND
29e40 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20  _SELECT         
29e50 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
29e60 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50  TE_LIMIT_VDBE_OP
29e70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
29e80 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c     5.#define SQL
29e90 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
29ea0 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20 20 20  ON_ARG          
29eb0 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51      6.#define SQ
29ec0 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43  LITE_LIMIT_ATTAC
29ed0 48 45 44 20 20 20 20 20 20 20 20 20 20 20 20 20  HED             
29ee0 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53       7.#define S
29ef0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45  QLITE_LIMIT_LIKE
29f00 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20  _PATTERN_LENGTH 
29f10 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20        8.#define 
29f20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
29f30 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20  IABLE_NUMBER    
29f40 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65         9.#define
29f50 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52   SQLITE_LIMIT_TR
29f60 49 47 47 45 52 5f 44 45 50 54 48 20 20 20 20 20  IGGER_DEPTH     
29f70 20 20 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e         10.#defin
29f80 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57  e SQLITE_LIMIT_W
29f90 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 20 20 20  ORKER_THREADS   
29fa0 20 20 20 20 20 20 20 20 31 31 0a 0a 0a 2f 2a 0a          11.../*.
29fb0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d  ** CAPI3REF: Com
29fc0 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74  piling An SQL St
29fd0 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f  atement.** KEYWO
29fe0 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d  RDS: {SQL statem
29ff0 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a  ent compiler}.**
2a000 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2a010 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a  .** CONSTRUCTOR:
2a020 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2a030 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61  .** To execute a
2a040 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74 20  n SQL query, it 
2a050 6d 75 73 74 20 66 69 72 73 74 20 62 65 20 63 6f  must first be co
2a060 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79  mpiled into a by
2a070 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72  te-code.** progr
2a080 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20  am using one of 
2a090 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
2a0a0 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
2a0b0 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20  argument, "db", 
2a0c0 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  is a [database c
2a0d0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69  onnection] obtai
2a0e0 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72  ned from a.** pr
2a0f0 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63  ior successful c
2a100 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2a110 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
2a120 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a  3_open_v2()] or.
2a130 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ** [sqlite3_open
2a140 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74 61  16()].  The data
2a150 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2a160 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62 65  must not have be
2a170 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a  en closed..**.**
2a180 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
2a190 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73  ment, "zSql", is
2a1a0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74   the statement t
2a1b0 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65  o be compiled, e
2a1c0 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74  ncoded.** as eit
2a1d0 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46  her UTF-8 or UTF
2a1e0 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65  -16.  The sqlite
2a1f0 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64 20  3_prepare() and 
2a200 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2a210 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  v2().** interfac
2a220 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e  es use UTF-8, an
2a230 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
2a240 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65  e16() and sqlite
2a250 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
2a260 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 0a  .** use UTF-16..
2a270 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 42  **.** ^If the nB
2a280 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  yte argument is 
2a290 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 7a  negative, then z
2a2a0 53 71 6c 20 69 73 20 72 65 61 64 20 75 70 20 74  Sql is read up t
2a2b0 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a  o the.** first z
2a2c0 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero terminator. 
2a2d0 5e 49 66 20 6e 42 79 74 65 20 69 73 20 70 6f 73  ^If nByte is pos
2a2e0 69 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69  itive, then it i
2a2f0 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
2a300 6f 66 20 62 79 74 65 73 20 72 65 61 64 20 66 72  of bytes read fr
2a310 6f 6d 20 7a 53 71 6c 2e 20 20 5e 49 66 20 6e 42  om zSql.  ^If nB
2a320 79 74 65 20 69 73 20 7a 65 72 6f 2c 20 74 68 65  yte is zero, the
2a330 6e 20 6e 6f 20 70 72 65 70 61 72 65 64 0a 2a 2a  n no prepared.**
2a340 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 67 65   statement is ge
2a350 6e 65 72 61 74 65 64 2e 0a 2a 2a 20 49 66 20 74  nerated..** If t
2a360 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 20  he caller knows 
2a370 74 68 61 74 20 74 68 65 20 73 75 70 70 6c 69 65  that the supplie
2a380 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d  d string is nul-
2a390 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e  terminated, then
2a3a0 0a 2a 2a 20 74 68 65 72 65 20 69 73 20 61 20 73  .** there is a s
2a3b0 6d 61 6c 6c 20 70 65 72 66 6f 72 6d 61 6e 63 65  mall performance
2a3c0 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20 70 61   advantage to pa
2a3d0 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70  ssing an nByte p
2a3e0 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a  arameter that.**
2a3f0 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
2a400 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 69  f bytes in the i
2a410 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69  nput string <i>i
2a420 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20  ncluding</i>.** 
2a430 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74  the nul-terminat
2a440 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a  or..**.** ^If pz
2a450 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  Tail is not NULL
2a460 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73   then *pzTail is
2a470 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74   made to point t
2a480 6f 20 74 68 65 20 66 69 72 73 74 20 62 79 74 65  o the first byte
2a490 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65 6e 64  .** past the end
2a4a0 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 53 51   of the first SQ
2a4b0 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a  L statement in z
2a4c0 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74  Sql.  These rout
2a4d0 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d  ines only.** com
2a4e0 70 69 6c 65 20 74 68 65 20 66 69 72 73 74 20 73  pile the first s
2a4f0 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c  tatement in zSql
2a500 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20  , so *pzTail is 
2a510 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f  left pointing to
2a520 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 6e 73  .** what remains
2a530 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a   uncompiled..**.
2a540 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c  ** ^*ppStmt is l
2a550 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20  eft pointing to 
2a560 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70  a compiled [prep
2a570 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2a580 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65  that can be.** e
2a590 78 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73  xecuted using [s
2a5a0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20  qlite3_step()]. 
2a5b0 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 61 6e   ^If there is an
2a5c0 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20   error, *ppStmt 
2a5d0 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c  is set.** to NUL
2a5e0 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e 70 75  L.  ^If the inpu
2a5f0 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20  t text contains 
2a600 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20 69  no SQL (if the i
2a610 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79  nput is an empty
2a620 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20  .** string or a 
2a630 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70  comment) then *p
2a640 70 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20  pStmt is set to 
2a650 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c  NULL..** The cal
2a660 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69  ling procedure i
2a670 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
2a680 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63  r deleting the c
2a690 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73  ompiled.** SQL s
2a6a0 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b  tatement using [
2a6b0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2a6c0 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 61 73  ()] after it has
2a6d0 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69   finished with i
2a6e0 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79  t..** ppStmt may
2a6f0 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a   not be NULL..**
2a700 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c  .** ^On success,
2a710 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65   the sqlite3_pre
2a720 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20 6f 66  pare() family of
2a730 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
2a740 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a   [SQLITE_OK];.**
2a750 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65   otherwise an [e
2a760 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
2a770 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  turned..**.** Th
2a780 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
2a790 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74  e_v2() and sqlit
2a7a0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2a7b0 29 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  ) interfaces are
2a7c0 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20  .** recommended 
2a7d0 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67  for all new prog
2a7e0 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c  rams. The two ol
2a7f0 64 65 72 20 69 6e 74 65 72 66 61 63 65 73 20 61  der interfaces a
2a800 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66  re retained.** f
2a810 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  or backwards com
2a820 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20  patibility, but 
2a830 74 68 65 69 72 20 75 73 65 20 69 73 20 64 69 73  their use is dis
2a840 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e  couraged..** ^In
2a850 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
2a860 61 63 65 73 2c 20 74 68 65 20 70 72 65 70 61 72  aces, the prepar
2a870 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  ed statement.** 
2a880 74 68 61 74 20 69 73 20 72 65 74 75 72 6e 65 64  that is returned
2a890 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73   (the [sqlite3_s
2a8a0 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e  tmt] object) con
2a8b0 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20  tains a copy of 
2a8c0 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20  the.** original 
2a8d0 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63  SQL text. This c
2a8e0 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74  auses the [sqlit
2a8f0 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72  e3_step()] inter
2a900 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76  face to.** behav
2a910 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e  e differently in
2a920 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a   three ways:.**.
2a930 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a  ** <ol>.** <li>.
2a940 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61 62  ** ^If the datab
2a950 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67  ase schema chang
2a960 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72  es, instead of r
2a970 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45  eturning [SQLITE
2a980 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a  _SCHEMA] as it.*
2a990 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f  * always used to
2a9a0 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74   do, [sqlite3_st
2a9b0 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d  ep()] will autom
2a9c0 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69  atically recompi
2a9d0 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74  le the SQL.** st
2a9e0 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20  atement and try 
2a9f0 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e  to run it again.
2aa00 20 41 73 20 6d 61 6e 79 20 61 73 20 5b 53 51 4c   As many as [SQL
2aa10 49 54 45 5f 4d 41 58 5f 53 43 48 45 4d 41 5f 52  ITE_MAX_SCHEMA_R
2aa20 45 54 52 59 5d 0a 2a 2a 20 72 65 74 72 69 65 73  ETRY].** retries
2aa30 20 77 69 6c 6c 20 6f 63 63 75 72 20 62 65 66 6f   will occur befo
2aa40 72 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  re sqlite3_step(
2aa50 29 20 67 69 76 65 73 20 75 70 20 61 6e 64 20 72  ) gives up and r
2aa60 65 74 75 72 6e 73 20 61 6e 20 65 72 72 6f 72 2e  eturns an error.
2aa70 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20  .** </li>.**.** 
2aa80 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e  <li>.** ^When an
2aa90 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b   error occurs, [
2aaa0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2aab0 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20  will return one 
2aac0 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a  of the detailed.
2aad0 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ** [error codes]
2aae0 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72   or [extended er
2aaf0 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68  ror codes].  ^Th
2ab00 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f  e legacy behavio
2ab10 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73  r was that.** [s
2ab20 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
2ab30 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e  ould only return
2ab40 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49   a generic [SQLI
2ab50 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74  TE_ERROR] result
2ab60 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65   code.** and the
2ab70 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75   application wou
2ab80 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20  ld have to make 
2ab90 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f  a second call to
2aba0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2abb0 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74  )].** in order t
2abc0 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72  o find the under
2abd0 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74  lying cause of t
2abe0 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68  he problem. With
2abf0 20 74 68 65 20 22 76 32 22 20 70 72 65 70 61 72   the "v2" prepar
2ac00 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c  e.** interfaces,
2ac10 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
2ac20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65  reason for the e
2ac30 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
2ac40 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a   immediately..**
2ac50 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   </li>.**.** <li
2ac60 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65  >.** ^If the spe
2ac70 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f 75 6e  cific value boun
2ac80 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 20  d to [parameter 
2ac90 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  | host parameter
2aca0 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45  ] in the .** WHE
2acb0 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68 74 20  RE clause might 
2acc0 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 63 68  influence the ch
2acd0 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c  oice of query pl
2ace0 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65 6d 65  an for a stateme
2acf0 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  nt,.** then the 
2ad00 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62  statement will b
2ad10 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
2ad20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69  recompiled, as i
2ad30 66 20 74 68 65 72 65 20 68 61 64 20 62 65 65 6e  f there had been
2ad40 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20 63 68   .** a schema ch
2ad50 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66 69 72  ange, on the fir
2ad60 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  st  [sqlite3_ste
2ad70 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77  p()] call follow
2ad80 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a  ing any change.*
2ad90 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  * to the [sqlite
2ada0 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 62 69  3_bind_text | bi
2adb0 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61 74 20  ndings] of that 
2adc0 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a  [parameter]. .**
2add0 20 5e 54 68 65 20 73 70 65 63 69 66 69 63 20 76   ^The specific v
2ade0 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d 63 6c  alue of WHERE-cl
2adf0 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65 72 5d  ause [parameter]
2ae00 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65   might influence
2ae10 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20   the .** choice 
2ae20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 69 66  of query plan if
2ae30 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
2ae40 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e 64 20  s the left-hand 
2ae50 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d  side of a [LIKE]
2ae60 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70  .** or [GLOB] op
2ae70 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74 68 65  erator or if the
2ae80 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 63 6f   parameter is co
2ae90 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69 6e 64  mpared to an ind
2aea0 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61  exed column.** a
2aeb0 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45  nd the [SQLITE_E
2aec0 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20 63 6f 6d  NABLE_STAT3] com
2aed0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
2aee0 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20   is enabled..** 
2aef0 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a  </li>.** </ol>.*
2af00 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  /.int sqlite3_pr
2af10 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33  epare(.  sqlite3
2af20 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
2af30 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
2af40 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
2af50 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  har *zSql,      
2af60 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
2af70 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  t, UTF-8 encoded
2af80 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
2af90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2afa0 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
2afb0 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
2afc0 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
2afd0 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
2afe0 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
2aff0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2b000 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c  st char **pzTail
2b010 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
2b020 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
2b030 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
2b040 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
2b050 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73  _prepare_v2(.  s
2b060 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
2b070 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
2b080 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
2b090 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
2b0a0 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
2b0b0 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65  atement, UTF-8 e
2b0c0 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
2b0d0 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
2b0e0 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
2b0f0 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
2b100 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
2b110 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
2b120 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
2b130 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
2b140 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a  .  const char **
2b150 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
2b160 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
2b170 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
2b180 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
2b190 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2b1a0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
2b1b0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
2b1c0 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
2b1d0 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
2b1e0 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
2b1f0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
2b200 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  F-16 encoded */.
2b210 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
2b220 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
2b230 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
2b240 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
2b250 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
2b260 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
2b270 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
2b280 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
2b290 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  oid **pzTail    
2b2a0 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
2b2b0 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
2b2c0 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
2b2d0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
2b2e0 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c  pare16_v2(.  sql
2b2f0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
2b300 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
2b310 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2b320 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20  st void *zSql,  
2b330 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
2b340 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e  ement, UTF-16 en
2b350 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
2b360 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
2b370 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
2b380 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
2b390 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
2b3a0 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
2b3b0 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
2b3c0 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
2b3d0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70    const void **p
2b3e0 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
2b3f0 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
2b400 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
2b410 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  Sql */.);../*.**
2b420 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 72 69   CAPI3REF: Retri
2b430 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20  eving Statement 
2b440 53 51 4c 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  SQL.** METHOD: s
2b450 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
2b460 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73  * ^The sqlite3_s
2b470 71 6c 28 50 29 20 69 6e 74 65 72 66 61 63 65 20  ql(P) interface 
2b480 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
2b490 72 20 74 6f 20 61 20 63 6f 70 79 20 6f 66 20 74  r to a copy of t
2b4a0 68 65 20 55 54 46 2d 38 0a 2a 2a 20 53 51 4c 20  he UTF-8.** SQL 
2b4b0 74 65 78 74 20 75 73 65 64 20 74 6f 20 63 72 65  text used to cre
2b4c0 61 74 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  ate [prepared st
2b4d0 61 74 65 6d 65 6e 74 5d 20 50 20 69 66 20 50 20  atement] P if P 
2b4e0 77 61 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62  was.** created b
2b4f0 79 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65  y either [sqlite
2b500 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
2b510 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
2b520 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 20  are16_v2()]..** 
2b530 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 70  ^The sqlite3_exp
2b540 61 6e 64 65 64 5f 73 71 6c 28 50 29 20 69 6e 74  anded_sql(P) int
2b550 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
2b560 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 55 54   pointer to a UT
2b570 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f  F-8.** string co
2b580 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 53 51 4c  ntaining the SQL
2b590 20 74 65 78 74 20 6f 66 20 70 72 65 70 61 72 65   text of prepare
2b5a0 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20 77 69  d statement P wi
2b5b0 74 68 0a 2a 2a 20 5b 62 6f 75 6e 64 20 70 61 72  th.** [bound par
2b5c0 61 6d 65 74 65 72 73 5d 20 65 78 70 61 6e 64 65  ameters] expande
2b5d0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65  d..**.** ^(For e
2b5e0 78 61 6d 70 6c 65 2c 20 69 66 20 61 20 70 72 65  xample, if a pre
2b5f0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2b600 69 73 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  is created using
2b610 20 74 68 65 20 53 51 4c 0a 2a 2a 20 74 65 78 74   the SQL.** text
2b620 20 22 53 45 4c 45 43 54 20 24 61 62 63 2c 3a 78   "SELECT $abc,:x
2b630 79 7a 22 20 61 6e 64 20 69 66 20 70 61 72 61 6d  yz" and if param
2b640 65 74 65 72 20 24 61 62 63 20 69 73 20 62 6f 75  eter $abc is bou
2b650 6e 64 20 74 6f 20 69 6e 74 65 67 65 72 20 32 33  nd to integer 23
2b660 34 35 0a 2a 2a 20 61 6e 64 20 70 61 72 61 6d 65  45.** and parame
2b670 74 65 72 20 3a 78 79 7a 20 69 73 20 75 6e 62 6f  ter :xyz is unbo
2b680 75 6e 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  und, then sqlite
2b690 33 5f 73 71 6c 28 29 20 77 69 6c 6c 20 72 65 74  3_sql() will ret
2b6a0 75 72 6e 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69  urn.** the origi
2b6b0 6e 61 6c 20 73 74 72 69 6e 67 2c 20 22 53 45 4c  nal string, "SEL
2b6c0 45 43 54 20 24 61 62 63 2c 3a 78 79 7a 22 20 62  ECT $abc,:xyz" b
2b6d0 75 74 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e  ut sqlite3_expan
2b6e0 64 65 64 5f 73 71 6c 28 29 0a 2a 2a 20 77 69 6c  ded_sql().** wil
2b6f0 6c 20 72 65 74 75 72 6e 20 22 53 45 4c 45 43 54  l return "SELECT
2b700 20 32 33 34 35 2c 4e 55 4c 4c 22 2e 29 5e 0a 2a   2345,NULL".)^.*
2b710 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2b720 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 29  3_expanded_sql()
2b730 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2b740 6e 73 20 4e 55 4c 4c 20 69 66 20 69 6e 73 75 66  ns NULL if insuf
2b750 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 0a 2a  ficient memory.*
2b760 2a 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 74  * is available t
2b770 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c  o hold the resul
2b780 74 2c 20 6f 72 20 69 66 20 74 68 65 20 72 65 73  t, or if the res
2b790 75 6c 74 20 77 6f 75 6c 64 20 65 78 63 65 65 64  ult would exceed
2b7a0 20 74 68 65 0a 2a 2a 20 74 68 65 20 6d 61 78 69   the.** the maxi
2b7b0 6d 75 6d 20 73 74 72 69 6e 67 20 6c 65 6e 67 74  mum string lengt
2b7c0 68 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20  h determined by 
2b7d0 74 68 65 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  the [SQLITE_LIMI
2b7e0 54 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 0a 2a 2a  T_LENGTH]..**.**
2b7f0 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 54 52   ^The [SQLITE_TR
2b800 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20  ACE_SIZE_LIMIT] 
2b810 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
2b820 69 6f 6e 20 6c 69 6d 69 74 73 20 74 68 65 20 73  ion limits the s
2b830 69 7a 65 20 6f 66 0a 2a 2a 20 62 6f 75 6e 64 20  ize of.** bound 
2b840 70 61 72 61 6d 65 74 65 72 20 65 78 70 61 6e 73  parameter expans
2b850 69 6f 6e 73 2e 20 20 5e 54 68 65 20 5b 53 51 4c  ions.  ^The [SQL
2b860 49 54 45 5f 4f 4d 49 54 5f 54 52 41 43 45 5d 20  ITE_OMIT_TRACE] 
2b870 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20  compile-time.** 
2b880 6f 70 74 69 6f 6e 20 63 61 75 73 65 73 20 73 71  option causes sq
2b890 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73  lite3_expanded_s
2b8a0 71 6c 28 29 20 74 6f 20 61 6c 77 61 79 73 20 72  ql() to always r
2b8b0 65 74 75 72 6e 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  eturn NULL..**.*
2b8c0 2a 20 5e 54 68 65 20 73 74 72 69 6e 67 20 72 65  * ^The string re
2b8d0 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
2b8e0 33 5f 73 71 6c 28 50 29 20 69 73 20 6d 61 6e 61  3_sql(P) is mana
2b8f0 67 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 6e  ged by SQLite an
2b900 64 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  d is.** automati
2b910 63 61 6c 6c 79 20 66 72 65 65 64 20 77 68 65 6e  cally freed when
2b920 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
2b930 61 74 65 6d 65 6e 74 20 69 73 20 66 69 6e 61 6c  atement is final
2b940 69 7a 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 74  ized..** ^The st
2b950 72 69 6e 67 20 72 65 74 75 72 6e 65 64 20 62 79  ring returned by
2b960 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65   sqlite3_expande
2b970 64 5f 73 71 6c 28 50 29 2c 20 6f 6e 20 74 68 65  d_sql(P), on the
2b980 20 6f 74 68 65 72 20 68 61 6e 64 2c 0a 2a 2a 20   other hand,.** 
2b990 69 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  is obtained from
2b9a0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
2b9b0 28 29 5d 20 61 6e 64 20 6d 75 73 74 20 62 65 20  ()] and must be 
2b9c0 66 72 65 65 20 62 79 20 74 68 65 20 61 70 70 6c  free by the appl
2b9d0 69 63 61 74 69 6f 6e 0a 2a 2a 20 62 79 20 70 61  ication.** by pa
2b9e0 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c  ssing it to [sql
2b9f0 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2f  ite3_free()]..*/
2ba00 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
2ba10 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33  ite3_sql(sqlite3
2ba20 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 63  _stmt *pStmt);.c
2ba30 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 78 70  har *sqlite3_exp
2ba40 61 6e 64 65 64 5f 73 71 6c 28 73 71 6c 69 74 65  anded_sql(sqlite
2ba50 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
2ba60 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2ba70 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e   Determine If An
2ba80 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 57   SQL Statement W
2ba90 72 69 74 65 73 20 54 68 65 20 44 61 74 61 62 61  rites The Databa
2baa0 73 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  se.** METHOD: sq
2bab0 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
2bac0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74   ^The sqlite3_st
2bad0 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20 69  mt_readonly(X) i
2bae0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2baf0 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29   true (non-zero)
2bb00 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20   if.** and only 
2bb10 69 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  if the [prepared
2bb20 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61   statement] X ma
2bb30 6b 65 73 20 6e 6f 20 64 69 72 65 63 74 20 63 68  kes no direct ch
2bb40 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20  anges to.** the 
2bb50 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64  content of the d
2bb60 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a  atabase file..**
2bb70 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 61  .** Note that [a
2bb80 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2bb90 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
2bba0 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c  ] or.** [virtual
2bbb0 20 74 61 62 6c 65 73 5d 20 6d 69 67 68 74 20 63   tables] might c
2bbc0 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61  hange the databa
2bbd0 73 65 20 69 6e 64 69 72 65 63 74 6c 79 20 61 73  se indirectly as
2bbe0 20 61 20 73 69 64 65 20 65 66 66 65 63 74 2e 20   a side effect. 
2bbf0 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70   .** ^(For examp
2bc00 6c 65 2c 20 69 66 20 61 6e 20 61 70 70 6c 69 63  le, if an applic
2bc10 61 74 69 6f 6e 20 64 65 66 69 6e 65 73 20 61 20  ation defines a 
2bc20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c 28 29  function "eval()
2bc30 22 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73  " that .** calls
2bc40 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
2bc50 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c  ], then the foll
2bc60 6f 77 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d  owing SQL statem
2bc70 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61  ent would.** cha
2bc80 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  nge the database
2bc90 20 66 69 6c 65 20 74 68 72 6f 75 67 68 20 73 69   file through si
2bca0 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a  de-effects:.**.*
2bcb0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
2bcc0 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54  re>.**    SELECT
2bcd0 20 65 76 61 6c 28 27 44 45 4c 45 54 45 20 46 52   eval('DELETE FR
2bce0 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20 74 32 3b  OM t1') FROM t2;
2bcf0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
2bd00 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75  kquote>.**.** Bu
2bd10 74 20 62 65 63 61 75 73 65 20 74 68 65 20 5b 53  t because the [S
2bd20 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
2bd30 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65   does not change
2bd40 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
2bd50 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20  le.** directly, 
2bd60 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
2bd70 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20 73 74  donly() would st
2bd80 69 6c 6c 20 72 65 74 75 72 6e 20 74 72 75 65 2e  ill return true.
2bd90 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61  )^.**.** ^Transa
2bda0 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74  ction control st
2bdb0 61 74 65 6d 65 6e 74 73 20 73 75 63 68 20 61 73  atements such as
2bdc0 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49   [BEGIN], [COMMI
2bdd0 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a  T], [ROLLBACK],.
2bde0 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20  ** [SAVEPOINT], 
2bdf0 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20 63 61  and [RELEASE] ca
2be00 75 73 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  use sqlite3_stmt
2be10 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72  _readonly() to r
2be20 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73  eturn true,.** s
2be30 69 6e 63 65 20 74 68 65 20 73 74 61 74 65 6d 65  ince the stateme
2be40 6e 74 73 20 74 68 65 6d 73 65 6c 76 65 73 20 64  nts themselves d
2be50 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d  o not actually m
2be60 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62 61  odify the databa
2be70 73 65 20 62 75 74 0a 2a 2a 20 72 61 74 68 65 72  se but.** rather
2be80 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68   they control th
2be90 65 20 74 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e  e timing of when
2bea0 20 6f 74 68 65 72 20 73 74 61 74 65 6d 65 6e 74   other statement
2beb0 73 20 6d 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a  s modify the .**
2bec0 20 64 61 74 61 62 61 73 65 2e 20 20 5e 54 68 65   database.  ^The
2bed0 20 5b 41 54 54 41 43 48 5d 20 61 6e 64 20 5b 44   [ATTACH] and [D
2bee0 45 54 41 43 48 5d 20 73 74 61 74 65 6d 65 6e 74  ETACH] statement
2bef0 73 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20  s also cause.** 
2bf00 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
2bf10 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72  donly() to retur
2bf20 6e 20 74 72 75 65 20 73 69 6e 63 65 2c 20 77 68  n true since, wh
2bf30 69 6c 65 20 74 68 6f 73 65 20 73 74 61 74 65 6d  ile those statem
2bf40 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74  ents.** change t
2bf50 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
2bf60 20 6f 66 20 61 20 64 61 74 61 62 61 73 65 20 63   of a database c
2bf70 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65 79 20  onnection, they 
2bf80 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20  do not make .** 
2bf90 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 63  changes to the c
2bfa0 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61  ontent of the da
2bfb0 74 61 62 61 73 65 20 66 69 6c 65 73 20 6f 6e 20  tabase files on 
2bfc0 64 69 73 6b 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  disk..** ^The sq
2bfd0 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
2bfe0 6e 6c 79 28 29 20 69 6e 74 65 72 66 61 63 65 20  nly() interface 
2bff0 72 65 74 75 72 6e 73 20 74 72 75 65 20 66 6f 72  returns true for
2c000 20 5b 42 45 47 49 4e 5d 20 73 69 6e 63 65 0a 2a   [BEGIN] since.*
2c010 2a 20 5b 42 45 47 49 4e 5d 20 6d 65 72 65 6c 79  * [BEGIN] merely
2c020 20 73 65 74 73 20 69 6e 74 65 72 6e 61 6c 20 66   sets internal f
2c030 6c 61 67 73 2c 20 62 75 74 20 74 68 65 20 5b 42  lags, but the [B
2c040 45 47 49 4e 7c 42 45 47 49 4e 20 49 4d 4d 45 44  EGIN|BEGIN IMMED
2c050 49 41 54 45 5d 20 61 6e 64 0a 2a 2a 20 5b 42 45  IATE] and.** [BE
2c060 47 49 4e 7c 42 45 47 49 4e 20 45 58 43 4c 55 53  GIN|BEGIN EXCLUS
2c070 49 56 45 5d 20 63 6f 6d 6d 61 6e 64 73 20 64 6f  IVE] commands do
2c080 20 74 6f 75 63 68 20 74 68 65 20 64 61 74 61 62   touch the datab
2c090 61 73 65 20 61 6e 64 20 73 6f 0a 2a 2a 20 73 71  ase and so.** sq
2c0a0 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
2c0b0 6e 6c 79 28 29 20 72 65 74 75 72 6e 73 20 66 61  nly() returns fa
2c0c0 6c 73 65 20 66 6f 72 20 74 68 6f 73 65 20 63 6f  lse for those co
2c0d0 6d 6d 61 6e 64 73 2e 0a 2a 2f 0a 69 6e 74 20 73  mmands..*/.int s
2c0e0 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
2c0f0 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73 74 6d  only(sqlite3_stm
2c100 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
2c110 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65  * CAPI3REF: Dete
2c120 72 6d 69 6e 65 20 49 66 20 41 20 50 72 65 70 61  rmine If A Prepa
2c130 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 48 61  red Statement Ha
2c140 73 20 42 65 65 6e 20 52 65 73 65 74 0a 2a 2a 20  s Been Reset.** 
2c150 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
2c160 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  stmt.**.** ^The 
2c170 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73  sqlite3_stmt_bus
2c180 79 28 53 29 20 69 6e 74 65 72 66 61 63 65 20 72  y(S) interface r
2c190 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e  eturns true (non
2c1a0 2d 7a 65 72 6f 29 20 69 66 20 74 68 65 0a 2a 2a  -zero) if the.**
2c1b0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2c1c0 6d 65 6e 74 5d 20 53 20 68 61 73 20 62 65 65 6e  ment] S has been
2c1d0 20 73 74 65 70 70 65 64 20 61 74 20 6c 65 61 73   stepped at leas
2c1e0 74 20 6f 6e 63 65 20 75 73 69 6e 67 20 0a 2a 2a  t once using .**
2c1f0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
2c200 29 5d 20 62 75 74 20 68 61 73 20 6e 65 69 74 68  )] but has neith
2c210 65 72 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65  er run to comple
2c220 74 69 6f 6e 20 28 72 65 74 75 72 6e 65 64 0a 2a  tion (returned.*
2c230 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20  * [SQLITE_DONE] 
2c240 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 74  from [sqlite3_st
2c250 65 70 28 53 29 5d 29 20 6e 6f 72 0a 2a 2a 20 62  ep(S)]) nor.** b
2c260 65 65 6e 20 72 65 73 65 74 20 75 73 69 6e 67 20  een reset using 
2c270 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
2c280 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  )].  ^The sqlite
2c290 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 0a 2a  3_stmt_busy(S).*
2c2a0 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  * interface retu
2c2b0 72 6e 73 20 66 61 6c 73 65 20 69 66 20 53 20 69  rns false if S i
2c2c0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
2c2d0 2e 20 20 49 66 20 53 20 69 73 20 6e 6f 74 20 61  .  If S is not a
2c2e0 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65   .** NULL pointe
2c2f0 72 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70  r and is not a p
2c300 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 69  ointer to a vali
2c310 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
2c320 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74  ement].** object
2c330 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
2c340 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
2c350 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e   and probably un
2c360 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a  desirable..**.**
2c370 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
2c380 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 20 63  can be used in c
2c390 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c 69  ombination [sqli
2c3a0 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d  te3_next_stmt()]
2c3b0 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c  .** to locate al
2c3c0 6c 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  l prepared state
2c3d0 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64  ments associated
2c3e0 20 77 69 74 68 20 61 20 64 61 74 61 62 61 73 65   with a database
2c3f0 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20   .** connection 
2c400 74 68 61 74 20 61 72 65 20 69 6e 20 6e 65 65 64  that are in need
2c410 20 6f 66 20 62 65 69 6e 67 20 72 65 73 65 74 2e   of being reset.
2c420 20 20 54 68 69 73 20 63 61 6e 20 62 65 20 75 73    This can be us
2c430 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d 70  ed,.** for examp
2c440 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74 69  le, in diagnosti
2c450 63 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 73 65  c routines to se
2c460 61 72 63 68 20 66 6f 72 20 70 72 65 70 61 72 65  arch for prepare
2c470 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73  d .** statements
2c480 20 74 68 61 74 20 61 72 65 20 68 6f 6c 64 69 6e   that are holdin
2c490 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  g a transaction 
2c4a0 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  open..*/.int sql
2c4b0 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 73  ite3_stmt_busy(s
2c4c0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
2c4d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2c4e0 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65  Dynamically Type
2c4f0 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a  d Value Object.*
2c500 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f  * KEYWORDS: {pro
2c510 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2c520 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74  alue} {unprotect
2c530 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2c540 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75  }.**.** SQLite u
2c550 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ses the sqlite3_
2c560 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20  value object to 
2c570 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61  represent all va
2c580 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e  lues.** that can
2c590 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20   be stored in a 
2c5a0 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20  database table. 
2c5b0 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61  SQLite uses dyna
2c5c0 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f  mic typing.** fo
2c5d0 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 74 20  r the values it 
2c5e0 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65 73  stores.  ^Values
2c5f0 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74   stored in sqlit
2c600 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
2c610 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67  .** can be integ
2c620 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f  ers, floating po
2c630 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69  int values, stri
2c640 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e  ngs, BLOBs, or N
2c650 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71  ULL..**.** An sq
2c660 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2c670 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 65 72  ct may be either
2c680 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20   "protected" or 
2c690 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a  "unprotected"..*
2c6a0 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65  * Some interface
2c6b0 73 20 72 65 71 75 69 72 65 20 61 20 70 72 6f 74  s require a prot
2c6c0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2c6d0 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65  lue.  Other inte
2c6e0 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61  rfaces.** will a
2c6f0 63 63 65 70 74 20 65 69 74 68 65 72 20 61 20 70  ccept either a p
2c700 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75  rotected or an u
2c710 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
2c720 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65  e3_value..** Eve
2c730 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  ry interface tha
2c740 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 74 65  t accepts sqlite
2c750 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74  3_value argument
2c760 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77  s specifies.** w
2c770 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74  hether or not it
2c780 20 72 65 71 75 69 72 65 73 20 61 20 70 72 6f 74   requires a prot
2c790 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2c7a0 6c 75 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71  lue.  The.** [sq
2c7b0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28  lite3_value_dup(
2c7c0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  )] interface can
2c7d0 20 62 65 20 75 73 65 64 20 74 6f 20 63 6f 6e 73   be used to cons
2c7e0 74 72 75 63 74 20 61 20 6e 65 77 20 0a 2a 2a 20  truct a new .** 
2c7f0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2c800 33 5f 76 61 6c 75 65 20 66 72 6f 6d 20 61 6e 20  3_value from an 
2c810 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2c820 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  te3_value..**.**
2c830 20 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74   The terms "prot
2c840 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72  ected" and "unpr
2c850 6f 74 65 63 74 65 64 22 20 72 65 66 65 72 20 74  otected" refer t
2c860 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  o whether or not
2c870 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68  .** a mutex is h
2c880 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65 72 6e 61  eld.  An interna
2c890 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20  l mutex is held 
2c8a0 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a  for a protected.
2c8b0 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
2c8c0 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d   object but no m
2c8d0 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72  utex is held for
2c8e0 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a   an unprotected.
2c8f0 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
2c900 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c   object.  If SQL
2c910 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
2c920 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72  to be single-thr
2c930 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b  eaded.** (with [
2c940 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
2c950 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73  E=0] and with [s
2c960 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
2c970 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30  e()] returning 0
2c980 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74  ).** or if SQLit
2c990 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20  e is run in one 
2c9a0 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74 65 78  of reduced mutex
2c9b0 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49   modes .** [SQLI
2c9c0 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
2c9d0 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49  THREAD] or [SQLI
2c9e0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
2c9f0 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74  HREAD].** then t
2ca00 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69  here is no disti
2ca10 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70  nction between p
2ca20 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70  rotected and unp
2ca30 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
2ca40 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2ca50 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62  s and they can b
2ca60 65 20 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e  e used interchan
2ca70 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72  geably.  However
2ca80 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d  ,.** for maximum
2ca90 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74   code portabilit
2caa0 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  y it is recommen
2cab0 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61  ded that applica
2cac0 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d  tions.** still m
2cad0 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74  ake the distinct
2cae0 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74  ion between prot
2caf0 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74  ected and unprot
2cb00 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
2cb10 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65  _value objects e
2cb20 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72  ven when not str
2cb30 69 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a  ictly required..
2cb40 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2cb50 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
2cb60 20 74 68 61 74 20 61 72 65 20 70 61 73 73 65 64   that are passed
2cb70 20 61 73 20 70 61 72 61 6d 65 74 65 72 73 20 69   as parameters i
2cb80 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65  nto the.** imple
2cb90 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70  mentation of [ap
2cba0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2cbb0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d  d SQL functions]
2cbc0 20 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a   are protected..
2cbd0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2cbe0 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74  value object ret
2cbf0 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
2cc00 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
2cc10 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63  e()] is unprotec
2cc20 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63  ted..** Unprotec
2cc30 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2cc40 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e  e objects may on
2cc50 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 0a  ly be used with.
2cc60 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  ** [sqlite3_resu
2cc70 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20  lt_value()] and 
2cc80 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61  [sqlite3_bind_va
2cc90 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b  lue()]..** The [
2cca0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
2ccb0 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c  ob | sqlite3_val
2ccc0 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c  ue_type()] famil
2ccd0 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63  y of.** interfac
2cce0 65 73 20 72 65 71 75 69 72 65 20 70 72 6f 74 65  es require prote
2ccf0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2cd00 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74  ue objects..*/.t
2cd10 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
2cd20 6c 69 74 65 33 5f 76 61 6c 75 65 20 73 71 6c 69  lite3_value sqli
2cd30 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a  te3_value;../*.*
2cd40 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20  * CAPI3REF: SQL 
2cd50 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74  Function Context
2cd60 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68   Object.**.** Th
2cd70 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69  e context in whi
2cd80 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69  ch an SQL functi
2cd90 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 20 73  on executes is s
2cda0 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73  tored in an.** s
2cdb0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f  qlite3_context o
2cdc0 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74  bject.  ^A point
2cdd0 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33  er to an sqlite3
2cde0 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a  _context object.
2cdf0 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69 72  ** is always fir
2ce00 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
2ce10 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
2ce20 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
2ce30 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ns]..** The appl
2ce40 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2ce50 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  SQL function imp
2ce60 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c  lementation will
2ce70 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f   pass this.** po
2ce80 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e  inter through in
2ce90 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  to calls to [sql
2cea0 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20  ite3_result_int 
2ceb0 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  | sqlite3_result
2cec0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
2ced0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
2cee0 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  xt()], [sqlite3_
2cef0 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a  user_data()],.**
2cf00 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
2cf10 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20  t_db_handle()], 
2cf20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78  [sqlite3_get_aux
2cf30 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f  data()],.** and/
2cf40 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  or [sqlite3_set_
2cf50 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74  auxdata()]..*/.t
2cf60 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
2cf70 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71  lite3_context sq
2cf80 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a  lite3_context;..
2cf90 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2cfa0 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54  Binding Values T
2cfb0 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  o Prepared State
2cfc0 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  ments.** KEYWORD
2cfd0 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  S: {host paramet
2cfe0 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  er} {host parame
2cff0 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61  ters} {host para
2d000 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b  meter name}.** K
2d010 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61  EYWORDS: {SQL pa
2d020 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61  rameter} {SQL pa
2d030 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d  rameters} {param
2d040 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a  eter binding}.**
2d050 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2d060 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e  _stmt.**.** ^(In
2d070 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
2d080 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20 74 6f  nt text input to
2d090 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2d0a0 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20  e_v2()] and its 
2d0b0 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74  variants,.** lit
2d0c0 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70  erals may be rep
2d0d0 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61 72 61  laced by a [para
2d0e0 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61 74 63  meter] that matc
2d0f0 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f  hes one of follo
2d100 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65  wing.** template
2d110 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
2d120 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e   <li>  ?.** <li>
2d130 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20    ?NNN.** <li>  
2d140 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56  :VVV.** <li>  @V
2d150 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56  VV.** <li>  $VVV
2d160 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
2d170 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74 65 73  In the templates
2d180 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72   above, NNN repr
2d190 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65 67 65  esents an intege
2d1a0 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e  r literal,.** an
2d1b0 64 20 56 56 56 20 72 65 70 72 65 73 65 6e 74 73  d VVV represents
2d1c0 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69 63   an alphanumeric
2d1d0 20 69 64 65 6e 74 69 66 69 65 72 2e 29 5e 20 20   identifier.)^  
2d1e0 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74  ^The values of t
2d1f0 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65  hese.** paramete
2d200 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20  rs (also called 
2d210 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20  "host parameter 
2d220 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70  names" or "SQL p
2d230 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63  arameters").** c
2d240 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67 20  an be set using 
2d250 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
2d260 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65  _*() routines de
2d270 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a  fined here..**.*
2d280 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
2d290 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c  ument to the sql
2d2a0 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
2d2b0 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73  utines is always
2d2c0 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
2d2d0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
2d2e0 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72  mt] object retur
2d2f0 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c  ned from.** [sql
2d300 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2d310 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e  )] or its varian
2d320 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ts..**.** ^The s
2d330 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
2d340 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
2d350 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  he SQL parameter
2d360 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e   to be set..** ^
2d370 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c  The leftmost SQL
2d380 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61   parameter has a
2d390 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e  n index of 1.  ^
2d3a0 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61  When the same na
2d3b0 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d  med.** SQL param
2d3c0 65 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72  eter is used mor
2d3d0 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63  e than once, sec
2d3e0 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65  ond and subseque
2d3f0 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65  nt.** occurrence
2d400 73 20 68 61 76 65 20 74 68 65 20 73 61 6d 65 20  s have the same 
2d410 69 6e 64 65 78 20 61 73 20 74 68 65 20 66 69 72  index as the fir
2d420 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a  st occurrence..*
2d430 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66 6f 72  * ^The index for
2d440 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72   named parameter
2d450 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20  s can be looked 
2d460 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  up using the.** 
2d470 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2d480 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
2d490 20 41 50 49 20 69 66 20 64 65 73 69 72 65 64 2e   API if desired.
2d4a0 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20    ^The index.** 
2d4b0 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d  for "?NNN" param
2d4c0 65 74 65 72 73 20 69 73 20 74 68 65 20 76 61 6c  eters is the val
2d4d0 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54  ue of NNN..** ^T
2d4e0 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73  he NNN value mus
2d4f0 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 20 61  t be between 1 a
2d500 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  nd the [sqlite3_
2d510 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61  limit()].** para
2d520 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49  meter [SQLITE_LI
2d530 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
2d540 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61  BER] (default va
2d550 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a  lue: 999)..**.**
2d560 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75   ^The third argu
2d570 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75  ment is the valu
2d580 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65  e to bind to the
2d590 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e   parameter..** ^
2d5a0 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72  If the third par
2d5b0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
2d5c0 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72  3_bind_text() or
2d5d0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2d5e0 78 74 31 36 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  xt16().** or sql
2d5f0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29  ite3_bind_blob()
2d600 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
2d610 65 72 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72  er then the four
2d620 74 68 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  th parameter.** 
2d630 69 73 20 69 67 6e 6f 72 65 64 20 61 6e 64 20 74  is ignored and t
2d640 68 65 20 65 6e 64 20 72 65 73 75 6c 74 20 69 73  he end result is
2d650 20 74 68 65 20 73 61 6d 65 20 61 73 20 73 71 6c   the same as sql
2d660 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29  ite3_bind_null()
2d670 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f  ..**.** ^(In tho
2d680 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  se routines that
2d690 20 68 61 76 65 20 61 20 66 6f 75 72 74 68 20 61   have a fourth a
2d6a0 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c  rgument, its val
2d6b0 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  ue is the.** num
2d6c0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
2d6d0 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20  the parameter.  
2d6e0 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65  To be clear: the
2d6f0 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a   value is the.**
2d700 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79   number of <u>by
2d710 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76  tes</u> in the v
2d720 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75  alue, not the nu
2d730 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
2d740 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65  rs.)^.** ^If the
2d750 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
2d760 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  r to sqlite3_bin
2d770 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69  d_text() or sqli
2d780 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
2d790 29 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65  ).** is negative
2d7a0 2c 20 74 68 65 6e 20 74 68 65 20 6c 65 6e 67 74  , then the lengt
2d7b0 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20  h of the string 
2d7c0 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  is.** the number
2d7d0 20 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f 20   of bytes up to 
2d7e0 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74  the first zero t
2d7f0 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66  erminator..** If
2d800 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
2d810 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
2d820 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20  _bind_blob() is 
2d830 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 0a 2a  negative, then.*
2d840 2a 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  * the behavior i
2d850 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  s undefined..** 
2d860 49 66 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  If a non-negativ
2d870 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
2d880 65 72 20 69 73 20 70 72 6f 76 69 64 65 64 20 74  er is provided t
2d890 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
2d8a0 65 78 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  ext().** or sqli
2d8b0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
2d8c0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  ) or sqlite3_bin
2d8d0 64 5f 74 65 78 74 36 34 28 29 20 74 68 65 6e 0a  d_text64() then.
2d8e0 2a 2a 20 74 68 61 74 20 70 61 72 61 6d 65 74 65  ** that paramete
2d8f0 72 20 6d 75 73 74 20 62 65 20 74 68 65 20 62 79  r must be the by
2d900 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65  te offset.** whe
2d910 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69  re the NUL termi
2d920 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75  nator would occu
2d930 72 20 61 73 73 75 6d 69 6e 67 20 74 68 65 20 73  r assuming the s
2d940 74 72 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a  tring were NUL.*
2d950 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49  * terminated.  I
2d960 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63  f any NUL charac
2d970 74 65 72 73 20 6f 63 63 75 72 20 61 74 20 62 79  ters occur at by
2d980 74 65 20 6f 66 66 73 65 74 73 20 6c 65 73 73 20  te offsets less 
2d990 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c  than .** the val
2d9a0 75 65 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68  ue of the fourth
2d9b0 20 70 61 72 61 6d 65 74 65 72 20 74 68 65 6e 20   parameter then 
2d9c0 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74  the resulting st
2d9d0 72 69 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a  ring value will.
2d9e0 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64  ** contain embed
2d9f0 64 65 64 20 4e 55 4c 73 2e 20 20 54 68 65 20 72  ded NULs.  The r
2da00 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73  esult of express
2da10 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73  ions involving s
2da20 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65  trings.** with e
2da30 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20  mbedded NULs is 
2da40 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
2da50 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 75   ^The fifth argu
2da60 6d 65 6e 74 20 74 6f 20 74 68 65 20 42 4c 4f 42  ment to the BLOB
2da70 20 61 6e 64 20 73 74 72 69 6e 67 20 62 69 6e 64   and string bind
2da80 69 6e 67 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  ing interfaces.*
2da90 2a 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f  * is a destructo
2daa0 72 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73  r used to dispos
2dab0 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72  e of the BLOB or
2dac0 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72  .** string after
2dad0 20 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69   SQLite has fini
2dae0 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 20 5e  shed with it.  ^
2daf0 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69  The destructor i
2db00 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64  s called.** to d
2db10 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c  ispose of the BL
2db20 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 65 76 65  OB or string eve
2db30 6e 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f  n if the call to
2db40 20 62 69 6e 64 20 41 50 49 20 66 61 69 6c 73 2e   bind API fails.
2db50 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74  .** ^If the fift
2db60 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a  h argument is.**
2db70 20 74 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c   the special val
2db80 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49  ue [SQLITE_STATI
2db90 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  C], then SQLite 
2dba0 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
2dbb0 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
2dbc0 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e  is in static, un
2dbd0 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e  managed space an
2dbe0 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  d does not need 
2dbf0 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20  to be freed..** 
2dc00 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72  ^If the fifth ar
2dc10 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76  gument has the v
2dc20 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41  alue [SQLITE_TRA
2dc30 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a  NSIENT], then.**
2dc40 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74   SQLite makes it
2dc50 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f  s own private co
2dc60 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 20 69  py of the data i
2dc70 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f  mmediately, befo
2dc80 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65  re.** the sqlite
2dc90 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
2dca0 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  ne returns..**.*
2dcb0 2a 20 5e 54 68 65 20 73 69 78 74 68 20 61 72 67  * ^The sixth arg
2dcc0 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
2dcd0 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20 6d  _bind_text64() m
2dce0 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 0a 2a 2a  ust be one of.**
2dcf0 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20   [SQLITE_UTF8], 
2dd00 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20  [SQLITE_UTF16], 
2dd10 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
2dd20 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46  , or [SQLITE_UTF
2dd30 31 36 4c 45 5d 0a 2a 2a 20 74 6f 20 73 70 65 63  16LE].** to spec
2dd40 69 66 79 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ify the encoding
2dd50 20 6f 66 20 74 68 65 20 74 65 78 74 20 69 6e 20   of the text in 
2dd60 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
2dd70 74 65 72 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20  ter.  If.** the 
2dd80 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74  sixth argument t
2dd90 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
2dda0 65 78 74 36 34 28 29 20 69 73 20 6e 6f 74 20 6f  ext64() is not o
2ddb0 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 61 6c 6c  ne of the.** all
2ddc0 6f 77 65 64 20 76 61 6c 75 65 73 20 73 68 6f 77  owed values show
2ddd0 6e 20 61 62 6f 76 65 2c 20 6f 72 20 69 66 20 74  n above, or if t
2dde0 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  he text encoding
2ddf0 20 69 73 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a   is different.**
2de00 20 66 72 6f 6d 20 74 68 65 20 65 6e 63 6f 64 69   from the encodi
2de10 6e 67 20 73 70 65 63 69 66 69 65 64 20 62 79 20  ng specified by 
2de20 74 68 65 20 73 69 78 74 68 20 70 61 72 61 6d 65  the sixth parame
2de30 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 62 65  ter, then the be
2de40 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75 6e 64  havior.** is und
2de50 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
2de60 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
2de70 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69  zeroblob() routi
2de80 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20  ne binds a BLOB 
2de90 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74  of length N that
2dea0 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69  .** is filled wi
2deb0 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a  th zeroes.  ^A z
2dec0 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66  eroblob uses a f
2ded0 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d  ixed amount of m
2dee0 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61  emory.** (just a
2def0 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c  n integer to hol
2df00 64 20 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c  d its size) whil
2df10 65 20 69 74 20 69 73 20 62 65 69 6e 67 20 70 72  e it is being pr
2df20 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f  ocessed..** Zero
2df30 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64  blobs are intend
2df40 65 64 20 74 6f 20 73 65 72 76 65 20 61 73 20 70  ed to serve as p
2df50 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20  laceholders for 
2df60 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63  BLOBs whose.** c
2df70 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20  ontent is later 
2df80 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a  written using.**
2df90 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f   [sqlite3_blob_o
2dfa0 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61  pen | incrementa
2dfb0 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74  l BLOB I/O] rout
2dfc0 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61  ines..** ^A nega
2dfd0 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74  tive value for t
2dfe0 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75  he zeroblob resu
2dff0 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65  lts in a zero-le
2e000 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a  ngth BLOB..**.**
2e010 20 5e 49 66 20 61 6e 79 20 6f 66 20 74 68 65 20   ^If any of the 
2e020 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
2e030 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61   routines are ca
2e040 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c  lled with a NULL
2e050 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20   pointer.** for 
2e060 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2e070 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68  atement] or with
2e080 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74   a prepared stat
2e090 65 6d 65 6e 74 20 66 6f 72 20 77 68 69 63 68 0a  ement for which.
2e0a0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
2e0b0 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c  ()] has been cal
2e0c0 6c 65 64 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c  led more recentl
2e0d0 79 20 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f  y than [sqlite3_
2e0e0 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65  reset()],.** the
2e0f0 6e 20 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20  n the call will 
2e100 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d  return [SQLITE_M
2e110 49 53 55 53 45 5d 2e 20 20 49 66 20 61 6e 79 20  ISUSE].  If any 
2e120 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a  sqlite3_bind_().
2e130 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61  ** routine is pa
2e140 73 73 65 64 20 61 20 5b 70 72 65 70 61 72 65 64  ssed a [prepared
2e150 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
2e160 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69   has been finali
2e170 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75  zed, the.** resu
2e180 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20  lt is undefined 
2e190 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 68 61 72  and probably har
2e1a0 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e  mful..**.** ^Bin
2e1b0 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c  dings are not cl
2e1c0 65 61 72 65 64 20 62 79 20 74 68 65 20 5b 73 71  eared by the [sq
2e1d0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72  lite3_reset()] r
2e1e0 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f  outine..** ^Unbo
2e1f0 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20 61  und parameters a
2e200 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  re interpreted a
2e210 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  s NULL..**.** ^T
2e220 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
2e230 2a 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  * routines retur
2e240 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  n [SQLITE_OK] on
2e250 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a   success or an.*
2e260 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  * [error code] i
2e270 66 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20  f anything goes 
2e280 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49  wrong..** ^[SQLI
2e290 54 45 5f 54 4f 4f 42 49 47 5d 20 6d 69 67 68 74  TE_TOOBIG] might
2e2a0 20 62 65 20 72 65 74 75 72 6e 65 64 20 69 66 20   be returned if 
2e2b0 74 68 65 20 73 69 7a 65 20 6f 66 20 61 20 73 74  the size of a st
2e2c0 72 69 6e 67 20 6f 72 20 42 4c 4f 42 0a 2a 2a 20  ring or BLOB.** 
2e2d0 65 78 63 65 65 64 73 20 6c 69 6d 69 74 73 20 69  exceeds limits i
2e2e0 6d 70 6f 73 65 64 20 62 79 20 5b 73 71 6c 69 74  mposed by [sqlit
2e2f0 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54  e3_limit]([SQLIT
2e300 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 29  E_LIMIT_LENGTH])
2e310 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d   or.** [SQLITE_M
2e320 41 58 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 20 5e  AX_LENGTH]..** ^
2e330 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69  [SQLITE_RANGE] i
2e340 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68  s returned if th
2e350 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69  e parameter.** i
2e360 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72  ndex is out of r
2e370 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f  ange.  ^[SQLITE_
2e380 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e  NOMEM] is return
2e390 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66  ed if malloc() f
2e3a0 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  ails..**.** See 
2e3b0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
2e3c0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
2e3d0 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  unt()],.** [sqli
2e3e0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2e3f0 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20  er_name()], and 
2e400 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2e410 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
2e420 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2e430 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74  _bind_blob(sqlit
2e440 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
2e450 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20  onst void*, int 
2e460 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  n, void(*)(void*
2e470 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  ));.int sqlite3_
2e480 62 69 6e 64 5f 62 6c 6f 62 36 34 28 73 71 6c 69  bind_blob64(sqli
2e490 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
2e4a0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 73 71 6c  const void*, sql
2e4b0 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20  ite3_uint64,.   
2e4c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2e4d0 20 20 20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69       void(*)(voi
2e4e0 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
2e4f0 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71  3_bind_double(sq
2e500 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2e510 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 73  , double);.int s
2e520 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28  qlite3_bind_int(
2e530 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2e540 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71  nt, int);.int sq
2e550 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34  lite3_bind_int64
2e560 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2e570 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  int, sqlite3_int
2e580 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  64);.int sqlite3
2e590 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74  _bind_null(sqlit
2e5a0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a  e3_stmt*, int);.
2e5b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2e5c0 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74  _text(sqlite3_st
2e5d0 6d 74 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68  mt*,int,const ch
2e5e0 61 72 2a 2c 69 6e 74 2c 76 6f 69 64 28 2a 29 28  ar*,int,void(*)(
2e5f0 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c  void*));.int sql
2e600 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
2e610 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2e620 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  int, const void*
2e630 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
2e640 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69  oid*));.int sqli
2e650 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28  te3_bind_text64(
2e660 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2e670 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  nt, const char*,
2e680 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c   sqlite3_uint64,
2e690 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
2e6a0 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 28 2a            void(*
2e6b0 29 28 76 6f 69 64 2a 29 2c 20 75 6e 73 69 67 6e  )(void*), unsign
2e6c0 65 64 20 63 68 61 72 20 65 6e 63 6f 64 69 6e 67  ed char encoding
2e6d0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
2e6e0 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65  ind_value(sqlite
2e6f0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
2e700 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  nst sqlite3_valu
2e710 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
2e720 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73  _bind_zeroblob(s
2e730 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2e740 74 2c 20 69 6e 74 20 6e 29 3b 0a 69 6e 74 20 73  t, int n);.int s
2e750 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f  qlite3_bind_zero
2e760 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 73  blob64(sqlite3_s
2e770 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74  tmt*, int, sqlit
2e780 65 33 5f 75 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a  e3_uint64);../*.
2e790 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
2e7a0 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d  ber Of SQL Param
2e7b0 65 74 65 72 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  eters.** METHOD:
2e7c0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2e7d0 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
2e7e0 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
2e7f0 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72   find the number
2e800 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74   of [SQL paramet
2e810 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72  ers].** in a [pr
2e820 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2e830 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65  ].  SQL paramete
2e840 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66  rs are tokens of
2e850 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22   the.** form "?"
2e860 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22  , "?NNN", ":AAA"
2e870 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41  , "$AAA", or "@A
2e880 41 41 22 20 74 68 61 74 20 73 65 72 76 65 20 61  AA" that serve a
2e890 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72  s.** placeholder
2e8a0 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61  s for values tha
2e8b0 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62  t are [sqlite3_b
2e8c0 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64  ind_blob | bound
2e8d0 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61  ].** to the para
2e8e0 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61 74 65  meters at a late
2e8f0 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28  r time..**.** ^(
2e900 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74  This routine act
2e910 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68  ually returns th
2e920 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c  e index of the l
2e930 61 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73  argest (rightmos
2e940 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e  t).** parameter.
2e950 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65   For all forms e
2e960 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73  xcept ?NNN, this
2e970 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64   will correspond
2e980 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   to the.** numbe
2e990 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61  r of unique para
2e9a0 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61 72 61  meters.  If para
2e9b0 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e  meters of the ?N
2e9c0 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75 73 65 64  NN form are used
2e9d0 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62  ,.** there may b
2e9e0 65 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69  e gaps in the li
2e9f0 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  st.)^.**.** See 
2ea00 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
2ea10 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
2ea20 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _bind()],.** [sq
2ea30 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2ea40 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e  eter_name()], an
2ea50 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  d.** [sqlite3_bi
2ea60 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
2ea70 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ex()]..*/.int sq
2ea80 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2ea90 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74  eter_count(sqlit
2eaa0 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
2eab0 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65  * CAPI3REF: Name
2eac0 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d   Of A Host Param
2ead0 65 74 65 72 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  eter.** METHOD: 
2eae0 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2eaf0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2eb00 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
2eb10 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66 61  ame(P,N) interfa
2eb20 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68  ce returns.** th
2eb30 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d  e name of the N-
2eb40 74 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65  th [SQL paramete
2eb50 72 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61  r] in the [prepa
2eb60 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50  red statement] P
2eb70 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d  ..** ^(SQL param
2eb80 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72  eters of the for
2eb90 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41  m "?NNN" or ":AA
2eba0 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20  A" or "@AAA" or 
2ebb0 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61  "$AAA".** have a
2ebc0 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20 74   name which is t
2ebd0 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22  he string "?NNN"
2ebe0 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40   or ":AAA" or "@
2ebf0 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a  AAA" or "$AAA".*
2ec00 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  * respectively..
2ec10 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  ** In other word
2ec20 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22  s, the initial "
2ec30 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22  :" or "$" or "@"
2ec40 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e   or "?".** is in
2ec50 63 6c 75 64 65 64 20 61 73 20 70 61 72 74 20 6f  cluded as part o
2ec60 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a  f the name.)^.**
2ec70 20 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20   ^Parameters of 
2ec80 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74  the form "?" wit
2ec90 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67  hout a following
2eca0 20 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f   integer have no
2ecb0 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65   name.** and are
2ecc0 20 72 65 66 65 72 72 65 64 20 74 6f 20 61 73 20   referred to as 
2ecd0 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22 61  "nameless" or "a
2ece0 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74  nonymous paramet
2ecf0 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ers"..**.** ^The
2ed00 20 66 69 72 73 74 20 68 6f 73 74 20 70 61 72 61   first host para
2ed10 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64  meter has an ind
2ed20 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a  ex of 1, not 0..
2ed30 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61  **.** ^If the va
2ed40 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66 20  lue N is out of 
2ed50 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20  range or if the 
2ed60 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  N-th parameter i
2ed70 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74  s.** nameless, t
2ed80 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75  hen NULL is retu
2ed90 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75  rned.  ^The retu
2eda0 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a  rned string is.*
2edb0 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d  * always in UTF-
2edc0 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20  8 encoding even 
2edd0 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72  if the named par
2ede0 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72  ameter was.** or
2edf0 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69  iginally specifi
2ee00 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  ed as UTF-16 in 
2ee10 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2ee20 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  16()] or.** [sql
2ee30 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
2ee40 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  2()]..**.** See 
2ee50 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
2ee60 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
2ee70 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _bind()],.** [sq
2ee80 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2ee90 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61  eter_count()], a
2eea0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
2eeb0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
2eec0 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74  dex()]..*/.const
2eed0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62   char *sqlite3_b
2eee0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
2eef0 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
2ef00 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , int);../*.** C
2ef10 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f  API3REF: Index O
2ef20 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57 69  f A Parameter Wi
2ef30 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a  th A Given Name.
2ef40 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2ef50 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52  e3_stmt.**.** ^R
2ef60 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20  eturn the index 
2ef70 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65  of an SQL parame
2ef80 74 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61  ter given its na
2ef90 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64  me.  ^The.** ind
2efa0 65 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  ex value returne
2efb0 64 20 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f  d is suitable fo
2efc0 72 20 75 73 65 20 61 73 20 74 68 65 20 73 65 63  r use as the sec
2efd0 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ond.** parameter
2efe0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e   to [sqlite3_bin
2eff0 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
2f000 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f  ind()].  ^A zero
2f010 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
2f020 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70  if no matching p
2f030 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e  arameter is foun
2f040 64 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74  d.  ^The paramet
2f050 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20  er.** name must 
2f060 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d  be given in UTF-
2f070 38 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72  8 even if the or
2f080 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74  iginal statement
2f090 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65 64  .** was prepared
2f0a0 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78   from UTF-16 tex
2f0b0 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
2f0c0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
2f0d0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
2f0e0 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
2f0f0 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
2f100 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
2f110 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2f120 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a  _count()], and.*
2f130 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2f140 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29  parameter_name()
2f150 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
2f160 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2f170 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73  _index(sqlite3_s
2f180 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  tmt*, const char
2f190 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a   *zName);../*.**
2f1a0 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74   CAPI3REF: Reset
2f1b0 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e   All Bindings On
2f1c0 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
2f1d0 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  ement.** METHOD:
2f1e0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2f1f0 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f  .** ^Contrary to
2f200 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f   the intuition o
2f210 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33  f many, [sqlite3
2f220 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e  _reset()] does n
2f230 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20  ot reset.** the 
2f240 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
2f250 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f  ob | bindings] o
2f260 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
2f270 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73  atement]..** ^Us
2f280 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74  e this routine t
2f290 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74  o reset all host
2f2a0 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e   parameters to N
2f2b0 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ULL..*/.int sqli
2f2c0 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e  te3_clear_bindin
2f2d0 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  gs(sqlite3_stmt*
2f2e0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2f2f0 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f  EF: Number Of Co
2f300 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c  lumns In A Resul
2f310 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  t Set.** METHOD:
2f320 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2f330 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20  .** ^Return the 
2f340 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
2f350 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  s in the result 
2f360 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  set returned by 
2f370 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
2f380 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 49 66   statement]. ^If
2f390 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   this routine re
2f3a0 74 75 72 6e 73 20 30 2c 20 74 68 61 74 20 6d 65  turns 0, that me
2f3b0 61 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 70 72 65  ans the .** [pre
2f3c0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2f3d0 20 72 65 74 75 72 6e 73 20 6e 6f 20 64 61 74 61   returns no data
2f3e0 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e   (for example an
2f3f0 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 20 5e   [UPDATE])..** ^
2f400 48 6f 77 65 76 65 72 2c 20 6a 75 73 74 20 62 65  However, just be
2f410 63 61 75 73 65 20 74 68 69 73 20 72 6f 75 74 69  cause this routi
2f420 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 73  ne returns a pos
2f430 69 74 69 76 65 20 6e 75 6d 62 65 72 20 64 6f 65  itive number doe
2f440 73 20 6e 6f 74 0a 2a 2a 20 6d 65 61 6e 20 74 68  s not.** mean th
2f450 61 74 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 72  at one or more r
2f460 6f 77 73 20 6f 66 20 64 61 74 61 20 77 69 6c 6c  ows of data will
2f470 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 20 5e   be returned.  ^
2f480 41 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65  A SELECT stateme
2f490 6e 74 0a 2a 2a 20 77 69 6c 6c 20 61 6c 77 61 79  nt.** will alway
2f4a0 73 20 68 61 76 65 20 61 20 70 6f 73 69 74 69 76  s have a positiv
2f4b0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
2f4c0 5f 63 6f 75 6e 74 28 29 20 62 75 74 20 64 65 70  _count() but dep
2f4d0 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 0a 2a 2a  ending on the.**
2f4e0 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f   WHERE clause co
2f4f0 6e 73 74 72 61 69 6e 74 73 20 61 6e 64 20 74 68  nstraints and th
2f500 65 20 74 61 62 6c 65 20 63 6f 6e 74 65 6e 74 2c  e table content,
2f510 20 69 74 20 6d 69 67 68 74 20 72 65 74 75 72 6e   it might return
2f520 20 6e 6f 20 72 6f 77 73 2e 0a 2a 2a 0a 2a 2a 20   no rows..**.** 
2f530 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
2f540 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d  e3_data_count()]
2f550 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2f560 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c  column_count(sql
2f570 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
2f580 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2f590 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73  EF: Column Names
2f5a0 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74   In A Result Set
2f5b0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2f5c0 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
2f5d0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
2f5e0 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61  eturn the name a
2f5f0 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72  ssigned to a par
2f600 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a  ticular column.*
2f610 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  * in the result 
2f620 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54  set of a [SELECT
2f630 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54  ] statement.  ^T
2f640 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
2f650 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65  n_name().** inte
2f660 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
2f670 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72  pointer to a zer
2f680 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
2f690 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64  -8 string.** and
2f6a0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2f6b0 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73  name16() returns
2f6c0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
2f6d0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
2f6e0 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  ** UTF-16 string
2f6f0 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 70 61  .  ^The first pa
2f700 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b  rameter is the [
2f710 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2f720 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c  nt].** that impl
2f730 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45  ements the [SELE
2f740 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e  CT] statement. ^
2f750 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
2f760 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63  eter is the.** c
2f770 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e  olumn number.  ^
2f780 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c  The leftmost col
2f790 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e  umn is number 0.
2f7a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75  .**.** ^The retu
2f7b0 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e  rned string poin
2f7c0 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74  ter is valid unt
2f7d0 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b 70  il either the [p
2f7e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2f7f0 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79  t].** is destroy
2f800 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66  ed by [sqlite3_f
2f810 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e  inalize()] or un
2f820 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e  til the statemen
2f830 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c  t is automatical
2f840 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64  ly.** reprepared
2f850 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61   by the first ca
2f860 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
2f870 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72  tep()] for a par
2f880 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f  ticular run.** o
2f890 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74  r until the next
2f8a0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69   call to.** sqli
2f8b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
2f8c0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ) or sqlite3_col
2f8d0 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20  umn_name16() on 
2f8e0 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e  the same column.
2f8f0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  .**.** ^If sqlit
2f900 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c  e3_malloc() fail
2f910 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f  s during the pro
2f920 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65  cessing of eithe
2f930 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f  r routine.** (fo
2f940 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67  r example during
2f950 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72   a conversion fr
2f960 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d  om UTF-8 to UTF-
2f970 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55  16) then a.** NU
2f980 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  LL pointer is re
2f990 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  turned..**.** ^T
2f9a0 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73  he name of a res
2f9b0 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68  ult column is th
2f9c0 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22  e value of the "
2f9d0 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a  AS" clause for.*
2f9e0 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69  * that column, i
2f9f0 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 53  f there is an AS
2fa00 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65   clause.  If the
2fa10 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75  re is no AS clau
2fa20 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e  se.** then the n
2fa30 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  ame of the colum
2fa40 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 64  n is unspecified
2fa50 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20   and may change 
2fa60 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65  from.** one rele
2fa70 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f  ase of SQLite to
2fa80 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f   the next..*/.co
2fa90 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
2faa0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71  3_column_name(sq
2fab0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2fac0 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20   N);.const void 
2fad0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2fae0 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
2faf0 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f  tmt*, int N);../
2fb00 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
2fb10 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e  ource Of Data In
2fb20 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a   A Query Result.
2fb30 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2fb40 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
2fb50 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72  hese routines pr
2fb60 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f  ovide a means to
2fb70 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64   determine the d
2fb80 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20  atabase, table, 
2fb90 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c  and.** table col
2fba0 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68 65 20  umn that is the 
2fbb0 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61 72 74  origin of a part
2fbc0 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20 63 6f  icular result co
2fbd0 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45  lumn in.** [SELE
2fbe0 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  CT] statement..*
2fbf0 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74  * ^The name of t
2fc00 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 20 74  he database or t
2fc10 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63  able or column c
2fc20 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20 61  an be returned a
2fc30 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54  s.** either a UT
2fc40 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74  F-8 or UTF-16 st
2fc50 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61 74  ring.  ^The _dat
2fc60 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20  abase_ routines 
2fc70 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61  return.** the da
2fc80 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65  tabase name, the
2fc90 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65   _table_ routine
2fca0 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 61 62  s return the tab
2fcb0 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20  le name, and.** 
2fcc0 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74  the origin_ rout
2fcd0 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20  ines return the 
2fce0 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20  column name..** 
2fcf0 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
2fd00 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e  ring is valid un
2fd10 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65  til the [prepare
2fd20 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20  d statement] is 
2fd30 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69  destroyed.** usi
2fd40 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
2fd50 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c  lize()] or until
2fd60 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
2fd70 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a  s automatically.
2fd80 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62 79  ** reprepared by
2fd90 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20   the first call 
2fda0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
2fdb0 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63  ()] for a partic
2fdc0 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75  ular run.** or u
2fdd0 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e  ntil the same in
2fde0 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71  formation is req
2fdf0 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20  uested.** again 
2fe00 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20 65  in a different e
2fe10 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e  ncoding..**.** ^
2fe20 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e  The names return
2fe30 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67 69  ed are the origi
2fe40 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e  nal un-aliased n
2fe50 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64  ames of the.** d
2fe60 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20  atabase, table, 
2fe70 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a  and column..**.*
2fe80 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
2fe90 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 20 69  ument to these i
2fea0 6e 74 65 72 66 61 63 65 73 20 69 73 20 61 20 5b  nterfaces is a [
2feb0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2fec0 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66  nt]..** ^These f
2fed0 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
2fee0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75  information abou
2fef0 74 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74  t the Nth result
2ff00 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64   column returned
2ff10 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65   by.** the state
2ff20 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73  ment, where N is
2ff30 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63   the second func
2ff40 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  tion argument..*
2ff50 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74  * ^The left-most
2ff60 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d   column is colum
2ff70 6e 20 30 20 66 6f 72 20 74 68 65 73 65 20 72 6f  n 0 for these ro
2ff80 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49  utines..**.** ^I
2ff90 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
2ffa0 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
2ffb0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e   statement is an
2ffc0 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a   expression or.*
2ffd0 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64 20 69  * subquery and i
2ffe0 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76  s not a column v
2fff0 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f  alue, then all o
30000 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  f these function
30010 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c  s return.** NULL
30020 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  .  ^These routin
30030 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74  e might also ret
30040 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65  urn NULL if a me
30050 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
30060 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e  error.** occurs.
30070 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 74 68    ^Otherwise, th
30080 65 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61  ey return the na
30090 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 63 68  me of the attach
300a0 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  ed database, tab
300b0 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e  le,.** or column
300c0 20 74 68 61 74 20 71 75 65 72 79 20 72 65 73 75   that query resu
300d0 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78  lt column was ex
300e0 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a  tracted from..**
300f0 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 6c 6c  .** ^As with all
30100 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41 50   other SQLite AP
30110 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 65 20  Is, those whose 
30120 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68 20 22  names end with "
30130 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54  16" return.** UT
30140 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72  F-16 encoded str
30150 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f 74 68  ings and the oth
30160 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74  er functions ret
30170 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a  urn UTF-8..**.**
30180 20 5e 54 68 65 73 65 20 41 50 49 73 20 61 72 65   ^These APIs are
30190 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
301a0 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77  if the library w
301b0 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  as compiled with
301c0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
301d0 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45  ENABLE_COLUMN_ME
301e0 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f  TADATA] C-prepro
301f0 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a  cessor symbol..*
30200 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d  *.** If two or m
30210 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c  ore threads call
30220 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20   one or more of 
30230 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
30240 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a  gainst the same.
30250 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ** prepared stat
30260 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e  ement and column
30270 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
30280 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  e then the resul
30290 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69  ts are.** undefi
302a0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77  ned..**.** If tw
302b0 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64  o or more thread
302c0 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f  s call one or mo
302d0 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  re.** [sqlite3_c
302e0 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
302f0 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74  ame | column met
30300 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 65 73  adata interfaces
30310 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d  ].** for the sam
30320 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
30330 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c  ement] and resul
30340 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74  t column.** at t
30350 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65  he same time the
30360 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
30370 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a  e undefined..*/.
30380 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
30390 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
303a0 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ase_name(sqlite3
303b0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
303c0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
303d0 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
303e0 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
303f0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
30400 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
30410 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d  column_table_nam
30420 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
30430 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
30440 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
30450 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71  _table_name16(sq
30460 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
30470 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
30480 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69  lite3_column_ori
30490 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  gin_name(sqlite3
304a0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
304b0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
304c0 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e  _column_origin_n
304d0 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
304e0 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  mt*,int);../*.**
304f0 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61   CAPI3REF: Decla
30500 72 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 20  red Datatype Of 
30510 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a  A Query Result.*
30520 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
30530 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 54  3_stmt.**.** ^(T
30540 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
30550 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 72 65  er is a [prepare
30560 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
30570 20 49 66 20 74 68 69 73 20 73 74 61 74 65 6d 65   If this stateme
30580 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d  nt is a [SELECT]
30590 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74   statement and t
305a0 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
305b0 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64   the.** returned
305c0 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74   result set of t
305d0 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20  hat [SELECT] is 
305e0 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28  a table column (
305f0 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73  not an.** expres
30600 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
30610 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61  ) then the decla
30620 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20  red type of the 
30630 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  table.** column 
30640 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20  is returned.)^  
30650 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  ^If the Nth colu
30660 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  mn of the result
30670 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78   set is an.** ex
30680 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71  pression or subq
30690 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c  uery, then a NUL
306a0 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74  L pointer is ret
306b0 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72  urned..** ^The r
306c0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
306d0 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65  s always UTF-8 e
306e0 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ncoded..**.** ^(
306f0 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76  For example, giv
30700 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
30710 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52  schema:.**.** CR
30720 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 31  EATE TABLE t1(c1
30730 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a   VARIANT);.**.**
30740 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69   and the followi
30750 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  ng statement to 
30760 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a  be compiled:.**.
30770 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31  ** SELECT c1 + 1
30780 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a  , c1 FROM t1;.**
30790 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65  .** this routine
307a0 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68   would return th
307b0 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e  e string "VARIAN
307c0 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e  T" for the secon
307d0 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75  d result.** colu
307e0 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61  mn (i==1), and a
307f0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f   NULL pointer fo
30800 72 20 74 68 65 20 66 69 72 73 74 20 72 65 73 75  r the first resu
30810 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29  lt column (i==0)
30820 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  .)^.**.** ^SQLit
30830 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72  e uses dynamic r
30840 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20  un-time typing. 
30850 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73   ^So just becaus
30860 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73  e a column.** is
30870 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e   declared to con
30880 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61  tain a particula
30890 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20  r type does not 
308a0 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a  mean that the.**
308b0 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20   data stored in 
308c0 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f  that column is o
308d0 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74  f the declared t
308e0 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a  ype.  SQLite is.
308f0 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65  ** strongly type
30900 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e  d, but the typin
30910 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74  g is dynamic not
30920 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a   static.  ^Type.
30930 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64  ** is associated
30940 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c   with individual
30950 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74   values, not wit
30960 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73  h the containers
30970 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64  .** used to hold
30980 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a   those values..*
30990 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
309a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63  lite3_column_dec
309b0 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74  ltype(sqlite3_st
309c0 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
309d0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
309e0 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28  lumn_decltype16(
309f0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
30a00 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
30a10 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e  REF: Evaluate An
30a20 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a   SQL Statement.*
30a30 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
30a40 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 41 66 74  3_stmt.**.** Aft
30a50 65 72 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  er a [prepared s
30a60 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65  tatement] has be
30a70 65 6e 20 70 72 65 70 61 72 65 64 20 75 73 69 6e  en prepared usin
30a80 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c  g either.** [sql
30a90 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
30aa0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
30ab0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f  repare16_v2()] o
30ac0 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67  r one of the leg
30ad0 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
30ae0 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
30af0 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  re()] or [sqlite
30b00 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20  3_prepare16()], 
30b10 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  this function.**
30b20 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
30b30 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
30b40 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68  s to evaluate th
30b50 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a  e statement..**.
30b60 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f  ** The details o
30b70 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  f the behavior o
30b80 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74  f the sqlite3_st
30b90 65 70 28 29 20 69 6e 74 65 72 66 61 63 65 20 64  ep() interface d
30ba0 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74  epend.** on whet
30bb0 68 65 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e  her the statemen
30bc0 74 20 77 61 73 20 70 72 65 70 61 72 65 64 20 75  t was prepared u
30bd0 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22  sing the newer "
30be0 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  v2" interface.**
30bf0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
30c00 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
30c10 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
30c20 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65  2()] or the olde
30c30 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  r legacy.** inte
30c40 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70  rface [sqlite3_p
30c50 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73  repare()] and [s
30c60 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
30c70 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66  ()].  The use of
30c80 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22   the.** new "v2"
30c90 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65   interface is re
30ca0 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65  commended for ne
30cb0 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62  w applications b
30cc0 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a  ut the legacy.**
30cd0 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
30ce0 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73  continue to be s
30cf0 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  upported..**.** 
30d00 5e 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69  ^In the legacy i
30d10 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 65  nterface, the re
30d20 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20  turn value will 
30d30 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  be either [SQLIT
30d40 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c  E_BUSY],.** [SQL
30d50 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49  ITE_DONE], [SQLI
30d60 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45  TE_ROW], [SQLITE
30d70 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c  _ERROR], or [SQL
30d80 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20  ITE_MISUSE]..** 
30d90 5e 57 69 74 68 20 74 68 65 20 22 76 32 22 20 69  ^With the "v2" i
30da0 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66  nterface, any of
30db0 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75   the other [resu
30dc0 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20  lt codes] or.** 
30dd0 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
30de0 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65   codes] might be
30df0 20 72 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c   returned as wel
30e00 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54  l..**.** ^[SQLIT
30e10 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68  E_BUSY] means th
30e20 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20  at the database 
30e30 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c  engine was unabl
30e40 65 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 65  e to acquire the
30e50 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63  .** database loc
30e60 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64  ks it needs to d
30e70 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20  o its job.  ^If 
30e80 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
30e90 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f   a [COMMIT].** o
30ea0 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65  r occurs outside
30eb0 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20   of an explicit 
30ec0 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65  transaction, the
30ed0 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20  n you can retry 
30ee0 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  the.** statement
30ef0 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d  .  If the statem
30f00 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f  ent is not a [CO
30f10 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73  MMIT] and occurs
30f20 20 77 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 78   within an.** ex
30f30 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
30f40 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75  on then you shou
30f50 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20  ld rollback the 
30f60 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f  transaction befo
30f70 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67  re.** continuing
30f80 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ..**.** ^[SQLITE
30f90 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61  _DONE] means tha
30fa0 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  t the statement 
30fb0 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65  has finished exe
30fc0 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73  cuting.** succes
30fd0 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33  sfully.  sqlite3
30fe0 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e  _step() should n
30ff0 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61  ot be called aga
31000 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75  in on this virtu
31010 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69  al.** machine wi
31020 74 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c  thout first call
31030 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
31040 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74  et()] to reset t
31050 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61  he virtual.** ma
31060 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74  chine back to it
31070 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e  s initial state.
31080 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53  .**.** ^If the S
31090 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69  QL statement bei
310a0 6e 67 20 65 78 65 63 75 74 65 64 20 72 65 74 75  ng executed retu
310b0 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68  rns any data, th
310c0 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a  en [SQLITE_ROW].
310d0 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 65  ** is returned e
310e0 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72  ach time a new r
310f0 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20 72 65  ow of data is re
31100 61 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69  ady for processi
31110 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c  ng by the.** cal
31120 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20  ler. The values 
31130 6d 61 79 20 62 65 20 61 63 63 65 73 73 65 64 20  may be accessed 
31140 75 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d  using the [colum
31150 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
31160 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ns]..** sqlite3_
31170 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64  step() is called
31180 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65   again to retrie
31190 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20  ve the next row 
311a0 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e  of data..**.** ^
311b0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d  [SQLITE_ERROR] m
311c0 65 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d  eans that a run-
311d0 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68  time error (such
311e0 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74   as a constraint
311f0 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68  .** violation) h
31200 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71  as occurred.  sq
31210 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f  lite3_step() sho
31220 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65  uld not be calle
31230 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68  d again on.** th
31240 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72  e VM. More infor
31250 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f  mation may be fo
31260 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  und by calling [
31270 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
31280 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20  ]..** ^With the 
31290 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
312a0 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69  , a more specifi
312b0 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f  c error code (fo
312c0 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53  r example,.** [S
312d0 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d  QLITE_INTERRUPT]
312e0 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  , [SQLITE_SCHEMA
312f0 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55  ], [SQLITE_CORRU
31300 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74  PT], and so fort
31310 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74  h).** can be obt
31320 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67  ained by calling
31330 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
31340 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72  )] on the.** [pr
31350 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
31360 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22 76 32 22  ].  ^In the "v2"
31370 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74   interface,.** t
31380 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63  he more specific
31390 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72   error code is r
313a0 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79  eturned directly
313b0 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70   by sqlite3_step
313c0 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54  ()..**.** [SQLIT
313d0 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20  E_MISUSE] means 
313e0 74 68 61 74 20 74 68 65 20 74 68 69 73 20 72 6f  that the this ro
313f0 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64  utine was called
31400 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79   inappropriately
31410 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20  ..** Perhaps it 
31420 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20  was called on a 
31430 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
31440 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a  ent] that has.**
31450 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73   already been [s
31460 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20  qlite3_finalize 
31470 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20  | finalized] or 
31480 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a  on one that had.
31490 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  ** previously re
314a0 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45  turned [SQLITE_E
314b0 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45  RROR] or [SQLITE
314c0 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63  _DONE].  Or it c
314d0 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63  ould.** be the c
314e0 61 73 65 20 74 68 61 74 20 74 68 65 20 73 61 6d  ase that the sam
314f0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
31500 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75  ction is being u
31510 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a  sed by two or.**
31520 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61 74   more threads at
31530 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74   the same moment
31540 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20   in time..**.** 
31550 46 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73  For all versions
31560 20 6f 66 20 53 51 4c 69 74 65 20 75 70 20 74 6f   of SQLite up to
31570 20 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 33   and including 3
31580 2e 36 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20  .6.23.1, a call 
31590 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  to.** [sqlite3_r
315a0 65 73 65 74 28 29 5d 20 77 61 73 20 72 65 71 75  eset()] was requ
315b0 69 72 65 64 20 61 66 74 65 72 20 73 71 6c 69 74  ired after sqlit
315c0 65 33 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e  e3_step() return
315d0 65 64 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f  ed anything.** o
315e0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
315f0 45 5f 52 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e  E_ROW] before an
31600 79 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76  y subsequent inv
31610 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71  ocation of.** sq
31620 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 46  lite3_step().  F
31630 61 69 6c 75 72 65 20 74 6f 20 72 65 73 65 74 20  ailure to reset 
31640 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
31650 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a  tement using .**
31660 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
31670 29 5d 20 77 6f 75 6c 64 20 72 65 73 75 6c 74 20  )] would result 
31680 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49  in an [SQLITE_MI
31690 53 55 53 45 5d 20 72 65 74 75 72 6e 20 66 72 6f  SUSE] return fro
316a0 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65  m.** sqlite3_ste
316b0 70 28 29 2e 20 20 42 75 74 20 61 66 74 65 72 20  p().  But after 
316c0 5b 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e  [version 3.6.23.
316d0 31 5d 20 28 5b 64 61 74 65 6f 66 3a 33 2e 36 2e  1] ([dateof:3.6.
316e0 32 33 2e 31 5d 2c 0a 2a 2a 20 73 71 6c 69 74 65  23.1],.** sqlite
316f0 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a 2a  3_step() began.*
31700 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  * calling [sqlit
31710 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74 6f  e3_reset()] auto
31720 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 69  matically in thi
31730 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20 72  s circumstance r
31740 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65  ather.** than re
31750 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f  turning [SQLITE_
31760 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20 69  MISUSE].  This i
31770 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65 64  s not considered
31780 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79   a compatibility
31790 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75 73  .** break becaus
317a0 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69 6f  e any applicatio
317b0 6e 20 74 68 61 74 20 65 76 65 72 20 72 65 63 65  n that ever rece
317c0 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d  ives an SQLITE_M
317d0 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69  ISUSE error.** i
317e0 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66 69  s broken by defi
317f0 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51  nition.  The [SQ
31800 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45  LITE_OMIT_AUTORE
31810 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  SET] compile-tim
31820 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20  e option.** can 
31830 62 65 20 75 73 65 64 20 74 6f 20 72 65 73 74 6f  be used to resto
31840 72 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65  re the legacy be
31850 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62  havior..**.** <b
31860 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65  >Goofy Interface
31870 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74   Alert:</b> In t
31880 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
31890 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33  ace, the sqlite3
318a0 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61  _step().** API a
318b0 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20  lways returns a 
318c0 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f  generic error co
318d0 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  de, [SQLITE_ERRO
318e0 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e  R], following an
318f0 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72  y.** error other
31900 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55   than [SQLITE_BU
31910 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  SY] and [SQLITE_
31920 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75  MISUSE].  You mu
31930 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69  st call.** [sqli
31940 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
31950 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
31960 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f  e()] in order to
31970 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65   find one of the
31980 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72  .** specific [er
31990 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20  ror codes] that 
319a0 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65 73  better describes
319b0 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57   the error..** W
319c0 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 69  e admit that thi
319d0 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73  s is a goofy des
319e0 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65  ign.  The proble
319f0 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 64  m has been fixed
31a00 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 32  .** with the "v2
31a10 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66  " interface.  If
31a20 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c   you prepare all
31a30 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61   of your SQL sta
31a40 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67  tements.** using
31a50 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33   either [sqlite3
31a60 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
31a70 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
31a80 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65  re16_v2()] inste
31a90 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67  ad.** of the leg
31aa0 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  acy [sqlite3_pre
31ab0 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  pare()] and [sql
31ac0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
31ad0 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a  ] interfaces,.**
31ae0 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73   then the more s
31af0 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63  pecific [error c
31b00 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e  odes] are return
31b10 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62  ed directly.** b
31b20 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  y sqlite3_step()
31b30 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68  .  The use of th
31b40 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
31b50 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e   is recommended.
31b60 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
31b70 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d  step(sqlite3_stm
31b80 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
31b90 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20  3REF: Number of 
31ba0 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73  columns in a res
31bb0 75 6c 74 20 73 65 74 0a 2a 2a 20 4d 45 54 48 4f  ult set.** METHO
31bc0 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
31bd0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
31be0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
31bf0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
31c00 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
31c10 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a   columns in the.
31c20 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f  ** current row o
31c30 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
31c40 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74   of [prepared st
31c50 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e  atement] P..** ^
31c60 49 66 20 70 72 65 70 61 72 65 64 20 73 74 61 74  If prepared stat
31c70 65 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74  ement P does not
31c80 20 68 61 76 65 20 72 65 73 75 6c 74 73 20 72 65   have results re
31c90 61 64 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a  ady to return.**
31ca0 20 28 76 69 61 20 63 61 6c 6c 73 20 74 6f 20 74   (via calls to t
31cb0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
31cc0 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33  mn_int | sqlite3
31cd0 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a  _column_*()] of.
31ce0 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 29 20 74  ** interfaces) t
31cf0 68 65 6e 20 73 71 6c 69 74 65 33 5f 64 61 74 61  hen sqlite3_data
31d00 5f 63 6f 75 6e 74 28 50 29 20 72 65 74 75 72 6e  _count(P) return
31d10 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s 0..** ^The sql
31d20 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
31d30 50 29 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20  P) routine also 
31d40 72 65 74 75 72 6e 73 20 30 20 69 66 20 50 20 69  returns 0 if P i
31d50 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
31d60 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
31d70 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
31d80 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
31d90 30 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75  0 if the previou
31da0 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  s call to.** [sq
31db0 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72  lite3_step](P) r
31dc0 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
31dd0 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c  DONE].  ^The sql
31de0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
31df0 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72  P).** will retur
31e00 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72  n non-zero if pr
31e10 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b  evious call to [
31e20 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29  sqlite3_step](P)
31e30 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51   returned.** [SQ
31e40 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70  LITE_ROW], excep
31e50 74 20 69 6e 20 74 68 65 20 63 61 73 65 20 6f 66  t in the case of
31e60 20 74 68 65 20 5b 50 52 41 47 4d 41 20 69 6e 63   the [PRAGMA inc
31e70 72 65 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d  remental_vacuum]
31e80 0a 2a 2a 20 77 68 65 72 65 20 69 74 20 61 6c 77  .** where it alw
31e90 61 79 73 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  ays returns zero
31ea0 20 73 69 6e 63 65 20 65 61 63 68 20 73 74 65 70   since each step
31eb0 20 6f 66 20 74 68 61 74 20 6d 75 6c 74 69 2d 73   of that multi-s
31ec0 74 65 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65  tep.** pragma re
31ed0 74 75 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20  turns 0 columns 
31ee0 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53  of data..**.** S
31ef0 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
31f00 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29  3_column_count()
31f10 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
31f20 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69  _data_count(sqli
31f30 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
31f40 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
31f50 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44  F: Fundamental D
31f60 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57  atatypes.** KEYW
31f70 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58  ORDS: SQLITE_TEX
31f80 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20  T.**.** ^(Every 
31f90 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20  value in SQLite 
31fa0 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20  has one of five 
31fb0 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61  fundamental data
31fc0 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  types:.**.** <ul
31fd0 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74  >.** <li> 64-bit
31fe0 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
31ff0 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49  ** <li> 64-bit I
32000 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  EEE floating poi
32010 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69  nt number.** <li
32020 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e  > string.** <li>
32030 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55   BLOB.** <li> NU
32040 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  LL.** </ul>)^.**
32050 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
32060 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f  nts are codes fo
32070 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20  r each of those 
32080 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  types..**.** Not
32090 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 49 54  e that the SQLIT
320a0 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20  E_TEXT constant 
320b0 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e  was also used in
320c0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
320d0 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c  2.** for a compl
320e0 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20  etely different 
320f0 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61  meaning.  Softwa
32100 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67  re that links ag
32110 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51  ainst both.** SQ
32120 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61  Lite version 2 a
32130 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  nd SQLite versio
32140 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53  n 3 should use S
32150 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74  QLITE3_TEXT, not
32160 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e  .** SQLITE_TEXT.
32170 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
32180 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64  TE_INTEGER  1.#d
32190 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f  efine SQLITE_FLO
321a0 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20  AT    2.#define 
321b0 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20  SQLITE_BLOB     
321c0 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
321d0 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64  _NULL     5.#ifd
321e0 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23  ef SQLITE_TEXT.#
321f0 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45   undef SQLITE_TE
32200 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e  XT.#else.# defin
32210 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20  e SQLITE_TEXT   
32220 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69    3.#endif.#defi
32230 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20  ne SQLITE3_TEXT 
32240 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      3../*.** CAP
32250 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61  I3REF: Result Va
32260 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72  lues From A Quer
32270 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  y.** KEYWORDS: {
32280 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
32290 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48  nctions}.** METH
322a0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
322b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
322c0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e  utines return in
322d0 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
322e0 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20  a single column 
322f0 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  of the current.*
32300 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20  * result row of 
32310 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 76  a query.  ^In ev
32320 65 72 79 20 63 61 73 65 20 74 68 65 20 66 69 72  ery case the fir
32330 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  st argument is a
32340 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74   pointer.** to t
32350 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
32360 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20  tement] that is 
32370 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20  being evaluated 
32380 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74  (the [sqlite3_st
32390 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73  mt*].** that was
323a0 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b   returned from [
323b0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
323c0 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  v2()] or one of 
323d0 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a  its variants).**
323e0 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
323f0 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
32400 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c  index of the col
32410 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e  umn for which in
32420 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f  formation.** sho
32430 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e  uld be returned.
32440 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63   ^The leftmost c
32450 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73  olumn of the res
32460 75 6c 74 20 73 65 74 20 68 61 73 20 74 68 65 20  ult set has the 
32470 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65  index 0..** ^The
32480 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
32490 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
324a0 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e   can be determin
324b0 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  ed using.** [sql
324c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
324d0 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  t()]..**.** If t
324e0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
324f0 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e   does not curren
32500 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76  tly point to a v
32510 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20  alid row, or if 
32520 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e  the.** column in
32530 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61  dex is out of ra
32540 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20  nge, the result 
32550 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
32560 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
32570 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c  may only be call
32580 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74  ed when the most
32590 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a   recent call to.
325a0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
325b0 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64  ()] has returned
325c0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e   [SQLITE_ROW] an
325d0 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71  d neither.** [sq
325e0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e  lite3_reset()] n
325f0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
32600 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65  lize()] have bee
32610 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75  n called subsequ
32620 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79  ently..** If any
32630 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
32640 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66  es are called af
32650 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ter [sqlite3_res
32660 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  et()] or.** [sql
32670 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
32680 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74   or after [sqlit
32690 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72  e3_step()] has r
326a0 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74  eturned.** somet
326b0 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20  hing other than 
326c0 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68  [SQLITE_ROW], th
326d0 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
326e0 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b  defined..** If [
326f0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
32700 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
32710 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
32720 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20  _finalize()].** 
32730 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  are called from 
32740 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65  a different thre
32750 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20  ad while any of 
32760 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a  these routines.*
32770 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74  * are pending, t
32780 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
32790 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
327a0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
327b0 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
327c0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
327d0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  the.** [SQLITE_I
327e0 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70  NTEGER | datatyp
327f0 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20  e code] for the 
32800 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 70  initial data typ
32810 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75  e.** of the resu
32820 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65  lt column.  ^The
32830 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20   returned value 
32840 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  is one of [SQLIT
32850 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b  E_INTEGER],.** [
32860 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b  SQLITE_FLOAT], [
32870 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53  SQLITE_TEXT], [S
32880 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20  QLITE_BLOB], or 
32890 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20  [SQLITE_NULL].  
328a0 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74  The value.** ret
328b0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
328c0 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69  _column_type() i
328d0 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75  s only meaningfu
328e0 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20  l if no type.** 
328f0 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65  conversions have
32900 20 6f 63 63 75 72 72 65 64 20 61 73 20 64 65 73   occurred as des
32910 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41  cribed below.  A
32920 66 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76  fter a type conv
32930 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76  ersion,.** the v
32940 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
32950 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
32960 74 79 70 65 28 29 20 69 73 20 75 6e 64 65 66 69  type() is undefi
32970 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20  ned.  Future.** 
32980 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
32990 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68  te may change th
329a0 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71  e behavior of sq
329b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
329c0 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  e().** following
329d0 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
329e0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  on..**.** ^If th
329f0 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c  e result is a BL
32a00 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69  OB or UTF-8 stri
32a10 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69  ng then the sqli
32a20 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
32a30 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65  ().** routine re
32a40 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
32a50 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
32a60 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  t BLOB or string
32a70 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
32a80 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36 20  ult is a UTF-16 
32a90 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c  string, then sql
32aa0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
32ab0 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20  s() converts.** 
32ac0 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54  the string to UT
32ad0 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74  F-8 and then ret
32ae0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
32af0 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66  of bytes..** ^If
32b00 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
32b10 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74   numeric value t
32b20 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
32b30 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a  mn_bytes() uses.
32b40 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  ** [sqlite3_snpr
32b50 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65  intf()] to conve
32b60 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f  rt that value to
32b70 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20   a UTF-8 string 
32b80 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  and returns.** t
32b90 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
32ba0 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e  es in that strin
32bb0 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
32bc0 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68  sult is NULL, th
32bd0 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
32be0 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75 72 6e  n_bytes() return
32bf0 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49  s zero..**.** ^I
32c00 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
32c10 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36  a BLOB or UTF-16
32c20 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65   string then the
32c30 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
32c40 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75  bytes16().** rou
32c50 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
32c60 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
32c70 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72   in that BLOB or
32c80 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
32c90 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
32ca0 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20 74 68  UTF-8 string, th
32cb0 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
32cc0 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f 6e 76  n_bytes16() conv
32cd0 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69  erts.** the stri
32ce0 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61 6e 64  ng to UTF-16 and
32cf0 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68   then returns th
32d00 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
32d10 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  s..** ^If the re
32d20 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69  sult is a numeri
32d30 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c  c value then sql
32d40 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
32d50 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73  s16() uses.** [s
32d60 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
32d70 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  )] to convert th
32d80 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54  at value to a UT
32d90 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e 64 20  F-16 string and 
32da0 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
32db0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
32dc0 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  n that string..*
32dd0 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
32de0 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73   is NULL, then s
32df0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
32e00 74 65 73 31 36 28 29 20 72 65 74 75 72 6e 73 20  tes16() returns 
32e10 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  zero..**.** ^The
32e20 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
32e30 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
32e40 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64  umn_bytes()] and
32e50 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f   .** [sqlite3_co
32e60 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20  lumn_bytes16()] 
32e70 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74  do not include t
32e80 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
32e90 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64 0a 2a  ors at the end.*
32ea0 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e  * of the string.
32eb0 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a 20    ^For clarity: 
32ec0 74 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  the values retur
32ed0 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
32ee0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
32ef0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
32f00 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
32f10 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62 65 72  ] are the number
32f20 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20   of.** bytes in 
32f30 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20  the string, not 
32f40 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
32f50 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  aracters..**.** 
32f60 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65  ^Strings returne
32f70 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
32f80 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73  umn_text() and s
32f90 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
32fa0 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20  xt16(),.** even 
32fb0 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61  empty strings, a
32fc0 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74  re always zero-t
32fd0 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65  erminated.  ^The
32fe0 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65   return.** value
32ff0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f   from sqlite3_co
33000 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20  lumn_blob() for 
33010 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c  a zero-length BL
33020 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  OB is a NULL poi
33030 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 57  nter..**.** <b>W
33040 61 72 6e 69 6e 67 3a 3c 2f 62 3e 20 5e 54 68 65  arning:</b> ^The
33050 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
33060 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
33070 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
33080 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74  an.** [unprotect
33090 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
330a0 5d 20 6f 62 6a 65 63 74 2e 20 20 49 6e 20 61 20  ] object.  In a 
330b0 6d 75 6c 74 69 74 68 72 65 61 64 65 64 20 65 6e  multithreaded en
330c0 76 69 72 6f 6e 6d 65 6e 74 2c 0a 2a 2a 20 61 6e  vironment,.** an
330d0 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
330e0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
330f0 74 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73  t may only be us
33100 65 64 20 73 61 66 65 6c 79 20 77 69 74 68 0a 2a  ed safely with.*
33110 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
33120 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71  value()] and [sq
33130 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
33140 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65  ue()]..** If the
33150 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
33160 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
33170 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ect returned by.
33180 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
33190 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75  mn_value()] is u
331a0 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72  sed in any other
331b0 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20   way, including 
331c0 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74  calls.** to rout
331d0 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74  ines like [sqlit
331e0 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c  e3_value_int()],
331f0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
33200 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b  text()],.** or [
33210 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
33220 74 65 73 28 29 5d 2c 20 74 68 65 20 62 65 68 61  tes()], the beha
33230 76 69 6f 72 20 69 73 20 6e 6f 74 20 74 68 72 65  vior is not thre
33240 61 64 73 61 66 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  adsafe..**.** Th
33250 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74  ese routines att
33260 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20  empt to convert 
33270 74 68 65 20 76 61 6c 75 65 20 77 68 65 72 65 20  the value where 
33280 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46  appropriate.  ^F
33290 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69  or.** example, i
332a0 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72  f the internal r
332b0 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73  epresentation is
332c0 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78   FLOAT and a tex
332d0 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72  t result.** is r
332e0 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74  equested, [sqlit
332f0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69  e3_snprintf()] i
33300 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c  s used internall
33310 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65  y to perform the
33320 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61  .** conversion a
33330 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e  utomatically.  ^
33340 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74  (The following t
33350 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65  able details the
33360 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20   conversions.** 
33370 74 68 61 74 20 61 72 65 20 61 70 70 6c 69 65 64  that are applied
33380 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
33390 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62  ote>.** <table b
333a0 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74  order="1">.** <t
333b0 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c  r><th> Internal<
333c0 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71  br>Type <th> Req
333d0 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c  uested<br>Type <
333e0 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a  th>  Conversion.
333f0 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  **.** <tr><td>  
33400 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54  NULL    <td> INT
33410 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75  EGER   <td> Resu
33420 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c  lt is 0.** <tr><
33430 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
33440 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
33450 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a   Result is 0.0.*
33460 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
33470 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20      <td>   TEXT 
33480 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
33490 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
334a0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
334b0 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  LL    <td>   BLO
334c0 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  B    <td> Result
334d0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
334e0 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49  er.** <tr><td> I
334f0 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c  NTEGER  <td>  FL
33500 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76  OAT    <td> Conv
33510 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72  ert from integer
33520 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72   to float.** <tr
33530 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
33540 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
33550 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69  d> ASCII renderi
33560 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65  ng of the intege
33570 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  r.** <tr><td> IN
33580 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c  TEGER  <td>   BL
33590 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20  OB    <td> Same 
335a0 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54  as INTEGER->TEXT
335b0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
335c0 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  OAT   <td> INTEG
335d0 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d  ER   <td> [CAST]
335e0 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c   to INTEGER.** <
335f0 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
33600 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
33610 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65  <td> ASCII rende
33620 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61  ring of the floa
33630 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  t.** <tr><td>  F
33640 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c  LOAT   <td>   BL
33650 4f 42 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54  OB    <td> [CAST
33660 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a 20 3c 74 72  ] to BLOB.** <tr
33670 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
33680 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
33690 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54  d> [CAST] to INT
336a0 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  EGER.** <tr><td>
336b0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20    TEXT    <td>  
336c0 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43  FLOAT    <td> [C
336d0 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20  AST] to REAL.** 
336e0 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
336f0 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
33700 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a   <td> No change.
33710 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
33720 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  B    <td> INTEGE
33730 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20  R   <td> [CAST] 
33740 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74  to INTEGER.** <t
33750 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
33760 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
33770 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45  td> [CAST] to RE
33780 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  AL.** <tr><td>  
33790 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54  BLOB    <td>   T
337a0 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20  EXT    <td> Add 
337b0 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  a zero terminato
337c0 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c  r if needed.** <
337d0 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f  /table>.** </blo
337e0 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a  ckquote>)^.**.**
337f0 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20   Note that when 
33800 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73  type conversions
33810 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73   occur, pointers
33820 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 69   returned by pri
33830 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73  or.** calls to s
33840 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
33850 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f  ob(), sqlite3_co
33860 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64  lumn_text(), and
33870 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  /or.** sqlite3_c
33880 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d  olumn_text16() m
33890 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65  ay be invalidate
338a0 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65  d..** Type conve
338b0 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74  rsions and point
338c0 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73  er invalidations
338d0 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20   might occur.** 
338e0 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  in the following
338f0 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75   cases:.**.** <u
33900 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  l>.** <li> The i
33910 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
33920 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c  s a BLOB and sql
33930 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
33940 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
33950 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
33960 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  t16() is called.
33970 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61    A zero-termina
33980 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20  tor might.**    
33990 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64    need to be add
339a0 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67  ed to the string
339b0 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  .</li>.** <li> T
339c0 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
339d0 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 74  nt is UTF-8 text
339e0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
339f0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72  umn_bytes16() or
33a00 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
33a10 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
33a20 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65   is called.  The
33a30 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65   content must be
33a40 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20   converted.**   
33a50 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c     to UTF-16.</l
33a60 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  i>.** <li> The i
33a70 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
33a80 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e  s UTF-16 text an
33a90 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
33aa0 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20  _bytes() or.**  
33ab0 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
33ac0 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c  mn_text() is cal
33ad0 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e  led.  The conten
33ae0 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  t must be conver
33af0 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55  ted.**      to U
33b00 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  TF-8.</li>.** </
33b10 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65  ul>.**.** ^Conve
33b20 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55  rsions between U
33b30 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d  TF-16be and UTF-
33b40 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20  16le are always 
33b50 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e  done in place an
33b60 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61  d do.** not inva
33b70 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 70  lidate a prior p
33b80 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f  ointer, though o
33b90 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e  f course the con
33ba0 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66  tent of the buff
33bb0 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70  er.** that the p
33bc0 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 65 66  rior pointer ref
33bd0 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 61 76  erences will hav
33be0 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e  e been modified.
33bf0 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a    Other kinds.**
33c00 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61   of conversion a
33c10 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65  re done in place
33c20 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73   when it is poss
33c30 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69  ible, but someti
33c40 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20  mes they.** are 
33c50 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64  not possible and
33c60 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20   in those cases 
33c70 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61  prior pointers a
33c80 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a  re invalidated..
33c90 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74  **.** The safest
33ca0 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e   policy is to in
33cb0 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69  voke these routi
33cc0 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66  nes.** in one of
33cd0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77   the following w
33ce0 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ays:.**.** <ul>.
33cf0 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
33d00 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f  column_text() fo
33d10 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
33d20 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
33d30 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71  </li>.**  <li>sq
33d40 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
33d50 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  b() followed by 
33d60 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
33d70 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20  ytes()</li>.**  
33d80 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
33d90 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c  mn_text16() foll
33da0 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
33db0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
33dc0 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  </li>.** </ul>.*
33dd0 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f  *.** In other wo
33de0 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20  rds, you should 
33df0 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  call sqlite3_col
33e00 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73  umn_text(),.** s
33e10 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
33e20 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33  ob(), or sqlite3
33e30 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
33e40 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20   first to force 
33e50 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e  the result.** in
33e60 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 20 66  to the desired f
33e70 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f  ormat, then invo
33e80 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ke sqlite3_colum
33e90 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20  n_bytes() or.** 
33ea0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
33eb0 79 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64  ytes16() to find
33ec0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
33ed0 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74   result.  Do not
33ee0 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f   mix calls.** to
33ef0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
33f00 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65  text() or sqlite
33f10 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
33f20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  with calls to.**
33f30 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
33f40 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64  bytes16(), and d
33f50 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20  o not mix calls 
33f60 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
33f70 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69  n_text16().** wi
33f80 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  th calls to sqli
33f90 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
33fa0 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70  ()..**.** ^The p
33fb0 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
33fc0 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c   are valid until
33fd0 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
33fe0 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20  on occurs as.** 
33ff0 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c  described above,
34000 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74   or until [sqlit
34010 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73  e3_step()] or [s
34020 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
34030 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  or.** [sqlite3_f
34040 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61  inalize()] is ca
34050 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f  lled.  ^The memo
34060 72 79 20 73 70 61 63 65 20 75 73 65 64 20 74 6f  ry space used to
34070 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a   hold strings.**
34080 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72   and BLOBs is fr
34090 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  eed automaticall
340a0 79 2e 20 20 44 6f 20 3c 65 6d 3e 6e 6f 74 3c 2f  y.  Do <em>not</
340b0 65 6d 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69  em> pass the poi
340c0 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a  nters returned.*
340d0 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
340e0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20  column_blob()], 
340f0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
34100 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e  text()], etc. in
34110 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  to.** [sqlite3_f
34120 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ree()]..**.** ^(
34130 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  If a memory allo
34140 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63  cation error occ
34150 75 72 73 20 64 75 72 69 6e 67 20 74 68 65 20 65  urs during the e
34160 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79  valuation of any
34170 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75  .** of these rou
34180 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74  tines, a default
34190 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e   value is return
341a0 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74  ed.  The default
341b0 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74   value.** is eit
341c0 68 65 72 20 74 68 65 20 69 6e 74 65 67 65 72 20  her the integer 
341d0 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20  0, the floating 
341e0 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30  point number 0.0
341f0 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70  , or a NULL.** p
34200 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75  ointer.  Subsequ
34210 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ent calls to [sq
34220 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
34230 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20   will return.** 
34240 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29  [SQLITE_NOMEM].)
34250 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20  ^.*/.const void 
34260 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
34270 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
34280 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
34290 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
342a0 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f  n_bytes(sqlite3_
342b0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
342c0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
342d0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c  lumn_bytes16(sql
342e0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
342f0 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71  iCol);.double sq
34300 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75  lite3_column_dou
34310 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ble(sqlite3_stmt
34320 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
34330 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
34340 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  _int(sqlite3_stm
34350 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73  t*, int iCol);.s
34360 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
34370 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36  ite3_column_int6
34380 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
34390 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73   int iCol);.cons
343a0 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20  t unsigned char 
343b0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
343c0 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  text(sqlite3_stm
343d0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63  t*, int iCol);.c
343e0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
343f0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
34400 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
34410 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
34420 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
34430 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  pe(sqlite3_stmt*
34440 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c  , int iCol);.sql
34450 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69  ite3_value *sqli
34460 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
34470 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
34480 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a  int iCol);../*.*
34490 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 73 74  * CAPI3REF: Dest
344a0 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 20 53  roy A Prepared S
344b0 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
344c0 2a 2a 20 44 45 53 54 52 55 43 54 4f 52 3a 20 73  ** DESTRUCTOR: s
344d0 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
344e0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66  * ^The sqlite3_f
344f0 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69  inalize() functi
34500 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20  on is called to 
34510 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72  delete a [prepar
34520 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
34530 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72  * ^If the most r
34540 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e  ecent evaluation
34550 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   of the statemen
34560 74 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f  t encountered no
34570 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 66   errors.** or if
34580 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
34590 73 20 6e 65 76 65 72 20 62 65 65 6e 20 65 76 61  s never been eva
345a0 6c 75 61 74 65 64 2c 20 74 68 65 6e 20 73 71 6c  luated, then sql
345b0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20  ite3_finalize() 
345c0 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54  returns.** SQLIT
345d0 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d  E_OK.  ^If the m
345e0 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75  ost recent evalu
345f0 61 74 69 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65  ation of stateme
34600 6e 74 20 53 20 66 61 69 6c 65 64 2c 20 74 68 65  nt S failed, the
34610 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e  n.** sqlite3_fin
34620 61 6c 69 7a 65 28 53 29 20 72 65 74 75 72 6e 73  alize(S) returns
34630 20 74 68 65 20 61 70 70 72 6f 70 72 69 61 74 65   the appropriate
34640 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72   [error code] or
34650 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 65 72  .** [extended er
34660 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a  ror code]..**.**
34670 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69   ^The sqlite3_fi
34680 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75 74 69 6e  nalize(S) routin
34690 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  e can be called 
346a0 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72  at any point dur
346b0 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20  ing.** the life 
346c0 63 79 63 6c 65 20 6f 66 20 5b 70 72 65 70 61 72  cycle of [prepar
346d0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a  ed statement] S:
346e0 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74 61 74 65  .** before state
346f0 6d 65 6e 74 20 53 20 69 73 20 65 76 65 72 20 65  ment S is ever e
34700 76 61 6c 75 61 74 65 64 2c 20 61 66 74 65 72 0a  valuated, after.
34710 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63  ** one or more c
34720 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
34730 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72 20 61 66  _reset()], or af
34740 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20  ter any call.** 
34750 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
34760 28 29 5d 20 72 65 67 61 72 64 6c 65 73 73 20 6f  ()] regardless o
34770 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
34780 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
34790 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20  as.** completed 
347a0 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  execution..**.**
347b0 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74   ^Invoking sqlit
347c0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e  e3_finalize() on
347d0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
347e0 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f  is a harmless no
347f0 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  -op..**.** The a
34800 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
34810 66 69 6e 61 6c 69 7a 65 20 65 76 65 72 79 20 5b  finalize every [
34820 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
34830 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  nt] in order to 
34840 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63  avoid.** resourc
34850 65 20 6c 65 61 6b 73 2e 20 20 49 74 20 69 73 20  e leaks.  It is 
34860 61 20 67 72 69 65 76 6f 75 73 20 65 72 72 6f 72  a grievous error
34870 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61   for the applica
34880 74 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f 20 75  tion to try to u
34890 73 65 0a 2a 2a 20 61 20 70 72 65 70 61 72 65 64  se.** a prepared
348a0 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72   statement after
348b0 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e   it has been fin
348c0 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75 73 65  alized.  Any use
348d0 20 6f 66 20 61 20 70 72 65 70 61 72 65 64 0a 2a   of a prepared.*
348e0 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65  * statement afte
348f0 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69  r it has been fi
34900 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72 65 73 75  nalized can resu
34910 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  lt in undefined 
34920 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62  and.** undesirab
34930 6c 65 20 62 65 68 61 76 69 6f 72 20 73 75 63 68  le behavior such
34940 20 61 73 20 73 65 67 66 61 75 6c 74 73 20 61 6e   as segfaults an
34950 64 20 68 65 61 70 20 63 6f 72 72 75 70 74 69 6f  d heap corruptio
34960 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  n..*/.int sqlite
34970 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74  3_finalize(sqlit
34980 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
34990 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
349a0 3a 20 52 65 73 65 74 20 41 20 50 72 65 70 61 72  : Reset A Prepar
349b0 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  ed Statement Obj
349c0 65 63 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ect.** METHOD: s
349d0 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
349e0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
349f0 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  set() function i
34a00 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65  s called to rese
34a10 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  t a [prepared st
34a20 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65  atement].** obje
34a30 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69  ct back to its i
34a40 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65  nitial state, re
34a50 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65  ady to be re-exe
34a60 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53  cuted..** ^Any S
34a70 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72  QL statement var
34a80 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20  iables that had 
34a90 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20  values bound to 
34aa0 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68  them using.** th
34ab0 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
34ac0 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62  blob | sqlite3_b
34ad0 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74  ind_*() API] ret
34ae0 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73  ain their values
34af0 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65  ..** Use [sqlite
34b00 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73  3_clear_bindings
34b10 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65  ()] to reset the
34b20 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a   bindings..**.**
34b30 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72   ^The [sqlite3_r
34b40 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61  eset(S)] interfa
34b50 63 65 20 72 65 73 65 74 73 20 74 68 65 20 5b 70  ce resets the [p
34b60 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
34b70 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20  t] S.** back to 
34b80 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66  the beginning of
34b90 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a   its program..**
34ba0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  .** ^If the most
34bb0 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20   recent call to 
34bc0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
34bd0 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72  ] for the.** [pr
34be0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
34bf0 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51  ] S returned [SQ
34c00 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51  LITE_ROW] or [SQ
34c10 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f  LITE_DONE],.** o
34c20 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74  r if [sqlite3_st
34c30 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72  ep(S)] has never
34c40 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c   before been cal
34c50 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65  led on S,.** the
34c60 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  n [sqlite3_reset
34c70 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51  (S)] returns [SQ
34c80 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20  LITE_OK]..**.** 
34c90 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
34ca0 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ent call to [sql
34cb0 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f  ite3_step(S)] fo
34cc0 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  r the.** [prepar
34cd0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
34ce0 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72  indicated an err
34cf0 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c  or, then.** [sql
34d00 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72  ite3_reset(S)] r
34d10 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70  eturns an approp
34d20 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64  riate [error cod
34d30 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  e]..**.** ^The [
34d40 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
34d50 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73  ] interface does
34d60 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
34d70 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79  values.** of any
34d80 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
34d90 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e  lob|bindings] on
34da0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
34db0 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a  tatement] S..*/.
34dc0 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65  int sqlite3_rese
34dd0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
34de0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
34df0 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20  API3REF: Create 
34e00 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20  Or Redefine SQL 
34e10 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59  Functions.** KEY
34e20 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e  WORDS: {function
34e30 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e   creation routin
34e40 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  es}.** KEYWORDS:
34e50 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   {application-de
34e60 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
34e70 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  on}.** KEYWORDS:
34e80 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   {application-de
34e90 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
34ea0 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ons}.** METHOD: 
34eb0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
34ec0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 28  hese functions (
34ed0 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f  collectively kno
34ee0 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20  wn as "function 
34ef0 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  creation routine
34f00 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20  s").** are used 
34f10 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74  to add SQL funct
34f20 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74  ions or aggregat
34f30 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e  es or to redefin
34f40 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a  e the behavior.*
34f50 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51  * of existing SQ
34f60 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61  L functions or a
34f70 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 20  ggregates.  The 
34f80 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 73  only differences
34f90 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73   between.** thes
34fa0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 74  e routines are t
34fb0 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  he text encoding
34fc0 20 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a   expected for.**
34fd0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
34fe0 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65 20  meter (the name 
34ff0 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  of the function 
35000 62 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a 2a  being created).*
35010 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73 65 6e  * and the presen
35020 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f 66  ce or absence of
35030 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 63 61   a destructor ca
35040 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68  llback for.** th
35050 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  e application da
35060 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  ta pointer..**.*
35070 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72  * ^The first par
35080 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 64  ameter is the [d
35090 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
350a0 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65  on] to which the
350b0 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   SQL.** function
350c0 20 69 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e   is to be added.
350d0 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63 61    ^If an applica
350e0 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20 74  tion uses more t
350f0 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65  han one database
35100 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  .** connection t
35110 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  hen application-
35120 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
35130 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64  tions must be ad
35140 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64  ded.** to each d
35150 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
35160 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a  on separately..*
35170 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64  *.** ^The second
35180 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
35190 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51  e name of the SQ
351a0 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  L function to be
351b0 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72   created or.** r
351c0 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20  edefined.  ^The 
351d0 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61  length of the na
351e0 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f  me is limited to
351f0 20 32 35 35 20 62 79 74 65 73 20 69 6e 20 61 20   255 bytes in a 
35200 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65  UTF-8.** represe
35210 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69  ntation, exclusi
35220 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74  ve of the zero-t
35230 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74  erminator.  ^Not
35240 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 0a  e that the name.
35250 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20  ** length limit 
35260 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74 65  is in UTF-8 byte
35270 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65 72  s, not character
35280 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79 74  s nor UTF-16 byt
35290 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74  es.  .** ^Any at
352a0 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20  tempt to create 
352b0 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  a function with 
352c0 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a  a longer name.**
352d0 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20   will result in 
352e0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
352f0 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a  being returned..
35300 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64  **.** ^The third
35310 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67   parameter (nArg
35320 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62  ).** is the numb
35330 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
35340 74 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e  that the SQL fun
35350 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
35360 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 66  egate takes. ^If
35370 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20   this parameter 
35380 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20  is -1, then the 
35390 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
353a0 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79  ** aggregate may
353b0 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72   take any number
353c0 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65   of arguments be
353d0 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20  tween 0 and the 
353e0 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20  limit.** set by 
353f0 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28  [sqlite3_limit](
35400 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55  [SQLITE_LIMIT_FU
35410 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49  NCTION_ARG]).  I
35420 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70  f the third.** p
35430 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73  arameter is less
35440 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61   than -1 or grea
35450 74 65 72 20 74 68 61 6e 20 31 32 37 20 74 68 65  ter than 127 the
35460 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
35470 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a  s.** undefined..
35480 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74  **.** ^The fourt
35490 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65  h parameter, eTe
354a0 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 73  xtRep, specifies
354b0 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45   what.** [SQLITE
354c0 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63  _UTF8 | text enc
354d0 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20  oding] this SQL 
354e0 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73  function prefers
354f0 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61   for.** its para
35500 6d 65 74 65 72 73 2e 20 20 54 68 65 20 61 70 70  meters.  The app
35510 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
35520 73 65 74 20 74 68 69 73 20 70 61 72 61 6d 65 74  set this paramet
35530 65 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45  er to.** [SQLITE
35540 5f 55 54 46 31 36 4c 45 5d 20 69 66 20 74 68 65  _UTF16LE] if the
35550 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
35560 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73  entation invokes
35570 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61   .** [sqlite3_va
35580 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 5d 20  lue_text16le()] 
35590 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 20  on an input, or 
355a0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
355b0 20 69 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65   if the.** imple
355c0 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65  mentation invoke
355d0 73 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  s [sqlite3_value
355e0 5f 74 65 78 74 31 36 62 65 28 29 5d 20 6f 6e 20  _text16be()] on 
355f0 61 6e 20 69 6e 70 75 74 2c 20 6f 72 0a 2a 2a 20  an input, or.** 
35600 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 69  [SQLITE_UTF16] i
35610 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  f [sqlite3_value
35620 5f 74 65 78 74 31 36 28 29 5d 20 69 73 20 75 73  _text16()] is us
35630 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  ed, or [SQLITE_U
35640 54 46 38 5d 0a 2a 2a 20 6f 74 68 65 72 77 69 73  TF8].** otherwis
35650 65 2e 20 20 5e 54 68 65 20 73 61 6d 65 20 53 51  e.  ^The same SQ
35660 4c 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62  L function may b
35670 65 20 72 65 67 69 73 74 65 72 65 64 20 6d 75 6c  e registered mul
35680 74 69 70 6c 65 20 74 69 6d 65 73 20 75 73 69 6e  tiple times usin
35690 67 0a 2a 2a 20 64 69 66 66 65 72 65 6e 74 20 70  g.** different p
356a0 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e  referred text en
356b0 63 6f 64 69 6e 67 73 2c 20 77 69 74 68 20 64 69  codings, with di
356c0 66 66 65 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e  fferent implemen
356d0 74 61 74 69 6f 6e 73 20 66 6f 72 0a 2a 2a 20 65  tations for.** e
356e0 61 63 68 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a  ach encoding..**
356f0 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20   ^When multiple 
35700 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
35710 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
35720 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62  tion are availab
35730 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69  le, SQLite.** wi
35740 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20  ll pick the one 
35750 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68  that involves th
35760 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f  e least amount o
35770 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f  f data conversio
35780 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f  n..**.** ^The fo
35790 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6d  urth parameter m
357a0 61 79 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 62 65  ay optionally be
357b0 20 4f 52 65 64 20 77 69 74 68 20 5b 53 51 4c 49   ORed with [SQLI
357c0 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43  TE_DETERMINISTIC
357d0 5d 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 74  ].** to signal t
357e0 68 61 74 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  hat the function
357f0 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74   will always ret
35800 75 72 6e 20 74 68 65 20 73 61 6d 65 20 72 65 73  urn the same res
35810 75 6c 74 20 67 69 76 65 6e 0a 2a 2a 20 74 68 65  ult given.** the
35820 20 73 61 6d 65 20 69 6e 70 75 74 73 20 77 69 74   same inputs wit
35830 68 69 6e 20 61 20 73 69 6e 67 6c 65 20 53 51 4c  hin a single SQL
35840 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 4d 6f 73   statement.  Mos
35850 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  t SQL functions 
35860 61 72 65 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 69  are.** determini
35870 73 74 69 63 2e 20 20 54 68 65 20 62 75 69 6c 74  stic.  The built
35880 2d 69 6e 20 5b 72 61 6e 64 6f 6d 28 29 5d 20 53  -in [random()] S
35890 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61  QL function is a
358a0 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 61 0a 2a  n example of a.*
358b0 2a 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  * function that 
358c0 69 73 20 6e 6f 74 20 64 65 74 65 72 6d 69 6e 69  is not determini
358d0 73 74 69 63 2e 20 20 54 68 65 20 53 51 4c 69 74  stic.  The SQLit
358e0 65 20 71 75 65 72 79 20 70 6c 61 6e 6e 65 72 20  e query planner 
358f0 69 73 20 61 62 6c 65 20 74 6f 0a 2a 2a 20 70 65  is able to.** pe
35900 72 66 6f 72 6d 20 61 64 64 69 74 69 6f 6e 61 6c  rform additional
35910 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20 6f   optimizations o
35920 6e 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 20  n deterministic 
35930 66 75 6e 63 74 69 6f 6e 73 2c 20 73 6f 20 75 73  functions, so us
35940 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c  e.** of the [SQL
35950 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49  ITE_DETERMINISTI
35960 43 5d 20 66 6c 61 67 20 69 73 20 72 65 63 6f 6d  C] flag is recom
35970 6d 65 6e 64 65 64 20 77 68 65 72 65 20 70 6f 73  mended where pos
35980 73 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  sible..**.** ^(T
35990 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74  he fifth paramet
359a0 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61  er is an arbitra
359b0 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65  ry pointer.  The
359c0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
359d0 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69  of the.** functi
359e0 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65  on can gain acce
359f0 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74  ss to this point
35a00 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  er using [sqlite
35a10 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29  3_user_data()].)
35a20 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78  ^.**.** ^The six
35a30 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e 64 20  th, seventh and 
35a40 65 69 67 68 74 68 20 70 61 72 61 6d 65 74 65 72  eighth parameter
35a50 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20  s, xFunc, xStep 
35a60 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a  and xFinal, are.
35a70 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43  ** pointers to C
35a80 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69  -language functi
35a90 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  ons that impleme
35aa0 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nt the SQL funct
35ab0 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
35ac0 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53  ate. ^A scalar S
35ad0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  QL function requ
35ae0 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  ires an implemen
35af0 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46  tation of the xF
35b00 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  unc.** callback 
35b10 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74  only; NULL point
35b20 65 72 73 20 6d 75 73 74 20 62 65 20 70 61 73 73  ers must be pass
35b30 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70 20  ed as the xStep 
35b40 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61  and xFinal.** pa
35b50 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 67  rameters. ^An ag
35b60 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
35b70 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e  tion requires an
35b80 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
35b90 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20  of xStep.** and 
35ba0 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20  xFinal and NULL 
35bb0 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 65 20  pointer must be 
35bc0 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63  passed for xFunc
35bd0 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20  . ^To delete an 
35be0 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20  existing.** SQL 
35bf0 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72  function or aggr
35c00 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c  egate, pass NULL
35c10 20 70 6f 69 6e 74 65 72 73 20 66 6f 72 20 61 6c   pointers for al
35c20 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e  l three function
35c30 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a  .** callbacks..*
35c40 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e 69  *.** ^(If the ni
35c50 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  nth parameter to
35c60 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
35c70 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69 73  function_v2() is
35c80 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68   not NULL,.** th
35c90 65 6e 20 69 74 20 69 73 20 64 65 73 74 72 75 63  en it is destruc
35ca0 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c  tor for the appl
35cb0 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69  ication data poi
35cc0 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65  nter. .** The de
35cd0 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e 76 6f  structor is invo
35ce0 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66 75 6e  ked when the fun
35cf0 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64  ction is deleted
35d00 2c 20 65 69 74 68 65 72 20 62 79 20 62 65 69 6e  , either by bein
35d10 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20  g.** overloaded 
35d20 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61 74 61  or when the data
35d30 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
35d40 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68  closes.)^.** ^Th
35d50 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20  e destructor is 
35d60 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20  also invoked if 
35d70 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73  the call to.** s
35d80 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
35d90 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c  nction_v2() fail
35da0 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20  s..** ^When the 
35db0 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62  destructor callb
35dc0 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e 74 68  ack of the tenth
35dd0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 6e   parameter is in
35de0 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20  voked, it.** is 
35df0 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c 65 20  passed a single 
35e00 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
35e10 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
35e20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
35e30 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68 69   .** pointer whi
35e40 63 68 20 77 61 73 20 74 68 65 20 66 69 66 74 68  ch was the fifth
35e50 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
35e60 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
35e70 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  ction_v2()..**.*
35e80 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74  * ^It is permitt
35e90 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d  ed to register m
35ea0 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e  ultiple implemen
35eb0 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  tations of the s
35ec0 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73  ame.** functions
35ed0 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e   with the same n
35ee0 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 74  ame but with eit
35ef0 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75  her differing nu
35f00 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75  mbers of.** argu
35f10 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69  ments or differi
35f20 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 65 78  ng preferred tex
35f30 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53  t encodings.  ^S
35f40 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a  QLite will use.*
35f50 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  * the implementa
35f60 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63  tion that most c
35f70 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74  losely matches t
35f80 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20  he way in which 
35f90 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74  the.** SQL funct
35fa0 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41  ion is used.  ^A
35fb0 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
35fc0 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20  entation with a 
35fd0 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20  non-negative.** 
35fe0 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72 20 69  nArg parameter i
35ff0 73 20 61 20 62 65 74 74 65 72 20 6d 61 74 63 68  s a better match
36000 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e   than a function
36010 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
36020 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69  with.** a negati
36030 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e  ve nArg.  ^A fun
36040 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
36050 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65  preferred text e
36060 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68  ncoding.** match
36070 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
36080 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65  encoding is a be
36090 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68  tter.** match th
360a0 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68  an a function wh
360b0 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ere the encoding
360c0 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20   is different.  
360d0 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20  .** ^A function 
360e0 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69  where the encodi
360f0 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73  ng difference is
36100 20 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65   between UTF16le
36110 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20   and UTF16be.** 
36120 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63  is a closer matc
36130 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
36140 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f  n where the enco
36150 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20  ding difference 
36160 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54  is.** between UT
36170 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a  F8 and UTF16..**
36180 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75  .** ^Built-in fu
36190 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f  nctions may be o
361a0 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77  verloaded by new
361b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
361c0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a  ined functions..
361d0 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63  **.** ^An applic
361e0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
361f0 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74  nction is permit
36200 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65  ted to call othe
36210 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65  r.** SQLite inte
36220 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72  rfaces.  However
36230 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73  , such calls mus
36240 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74  t not.** close t
36250 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
36260 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c  ection nor final
36270 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68 65  ize or reset the
36280 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
36290 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20  tement in which 
362a0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  the function is 
362b0 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20  running..*/.int 
362c0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
362d0 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74  unction(.  sqlit
362e0 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20  e3 *db,.  const 
362f0 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e  char *zFunctionN
36300 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c  ame,.  int nArg,
36310 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
36320 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20  .  void *pApp,. 
36330 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73   void (*xFunc)(s
36340 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
36350 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
36360 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
36370 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f  Step)(sqlite3_co
36380 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
36390 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
363a0 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71  oid (*xFinal)(sq
363b0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a  lite3_context*).
363c0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
363d0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
363e0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
363f0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
36400 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20  FunctionName,.  
36410 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20  int nArg,.  int 
36420 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64  eTextRep,.  void
36430 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28   *pApp,.  void (
36440 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xFunc)(sqlite3_
36450 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
36460 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
36470 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73   void (*xStep)(s
36480 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
36490 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
364a0 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
364b0 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63  Final)(sqlite3_c
364c0 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20  ontext*).);.int 
364d0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
364e0 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71  unction_v2(.  sq
364f0 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e  lite3 *db,.  con
36500 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69  st char *zFuncti
36510 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41  onName,.  int nA
36520 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  rg,.  int eTextR
36530 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70  ep,.  void *pApp
36540 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63  ,.  void (*xFunc
36550 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
36560 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
36570 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
36580 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33  (*xStep)(sqlite3
36590 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
365a0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
365b0 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29    void (*xFinal)
365c0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
365d0 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73  *),.  void(*xDes
365e0 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a  troy)(void*).);.
365f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
36600 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a   Text Encodings.
36610 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
36620 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65  tant define inte
36630 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 20 72  ger codes that r
36640 65 70 72 65 73 65 6e 74 20 74 68 65 20 76 61 72  epresent the var
36650 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63  ious.** text enc
36660 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64  odings supported
36670 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23   by SQLite..*/.#
36680 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
36690 46 38 20 20 20 20 20 20 20 20 20 20 20 31 20 20  F8           1  
366a0 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 33 37 35 31    /* IMP: R-3751
366b0 34 2d 33 35 35 36 36 20 2a 2f 0a 23 64 65 66 69  4-35566 */.#defi
366c0 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  ne SQLITE_UTF16L
366d0 45 20 20 20 20 20 20 20 20 32 20 20 20 20 2f 2a  E        2    /*
366e0 20 49 4d 50 3a 20 52 2d 30 33 33 37 31 2d 33 37   IMP: R-03371-37
366f0 36 33 37 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  637 */.#define S
36700 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20 20  QLITE_UTF16BE   
36710 20 20 20 20 20 33 20 20 20 20 2f 2a 20 49 4d 50       3    /* IMP
36720 3a 20 52 2d 35 31 39 37 31 2d 33 34 31 35 34 20  : R-51971-34154 
36730 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
36740 45 5f 55 54 46 31 36 20 20 20 20 20 20 20 20 20  E_UTF16         
36750 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74   4    /* Use nat
36760 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a  ive byte order *
36770 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
36780 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20 20 20  _ANY            
36790 35 20 20 20 20 2f 2a 20 44 65 70 72 65 63 61 74  5    /* Deprecat
367a0 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
367b0 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e  LITE_UTF16_ALIGN
367c0 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69  ED  8    /* sqli
367d0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
367e0 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a  tion only */../*
367f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75  .** CAPI3REF: Fu
36800 6e 63 74 69 6f 6e 20 46 6c 61 67 73 0a 2a 2a 0a  nction Flags.**.
36810 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
36820 74 73 20 6d 61 79 20 62 65 20 4f 52 65 64 20 74  ts may be ORed t
36830 6f 67 65 74 68 65 72 20 77 69 74 68 20 74 68 65  ogether with the
36840 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46   .** [SQLITE_UTF
36850 38 20 7c 20 70 72 65 66 65 72 72 65 64 20 74 65  8 | preferred te
36860 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 61 73 20  xt encoding] as 
36870 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  the fourth argum
36880 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74  ent.** to [sqlit
36890 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
368a0 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  on()], [sqlite3_
368b0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
368c0 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  6()], or.** [sql
368d0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
368e0 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 23  tion_v2()]..*/.#
368f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
36900 54 45 52 4d 49 4e 49 53 54 49 43 20 20 20 20 30  TERMINISTIC    0
36910 78 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  x800../*.** CAPI
36920 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 65 64  3REF: Deprecated
36930 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45   Functions.** DE
36940 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54  PRECATED.**.** T
36950 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61  hese functions a
36960 72 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e  re [deprecated].
36970 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61    In order to ma
36980 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61  intain.** backwa
36990 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
369a0 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64  y with older cod
369b0 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  e, these functio
369c0 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20  ns continue .** 
369d0 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e  to be supported.
369e0 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61    However, new a
369f0 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
36a00 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20  ld avoid.** the 
36a10 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e  use of these fun
36a20 63 74 69 6f 6e 73 2e 20 20 54 6f 20 65 6e 63 6f  ctions.  To enco
36a30 75 72 61 67 65 20 70 72 6f 67 72 61 6d 6d 65 72  urage programmer
36a40 73 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68  s to avoid.** th
36a50 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77  ese functions, w
36a60 65 20 77 69 6c 6c 20 6e 6f 74 20 65 78 70 6c 61  e will not expla
36a70 69 6e 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e  in what they do.
36a80 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  .*/.#ifndef SQLI
36a90 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54  TE_OMIT_DEPRECAT
36aa0 45 44 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  ED.SQLITE_DEPREC
36ab0 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
36ac0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74  _aggregate_count
36ad0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
36ae0 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  *);.SQLITE_DEPRE
36af0 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
36b00 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74 65  3_expired(sqlite
36b10 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45  3_stmt*);.SQLITE
36b20 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
36b30 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72  sqlite3_transfer
36b40 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65  _bindings(sqlite
36b50 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33  3_stmt*, sqlite3
36b60 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  _stmt*);.SQLITE_
36b70 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
36b80 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65  qlite3_global_re
36b90 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c  cover(void);.SQL
36ba0 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 76  ITE_DEPRECATED v
36bb0 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65  oid sqlite3_thre
36bc0 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29  ad_cleanup(void)
36bd0 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
36be0 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
36bf0 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69  memory_alarm(voi
36c00 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
36c10 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 0a 20  e3_int64,int),. 
36c20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
36c30 20 20 20 20 20 76 6f 69 64 2a 2c 73 71 6c 69 74       void*,sqlit
36c40 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69  e3_int64);.#endi
36c50 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
36c60 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c  F: Obtaining SQL
36c70 20 56 61 6c 75 65 73 0a 2a 2a 20 4d 45 54 48 4f   Values.** METHO
36c80 44 3a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  D: sqlite3_value
36c90 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e  .**.** The C-lan
36ca0 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61  guage implementa
36cb0 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63  tion of SQL func
36cc0 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
36cd0 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69  ates uses.** thi
36ce0 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61  s set of interfa
36cf0 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61  ce routines to a
36d00 63 63 65 73 73 20 74 68 65 20 70 61 72 61 6d 65  ccess the parame
36d10 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a  ter values on.**
36d20 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72   the function or
36d30 20 61 67 67 72 65 67 61 74 65 2e 20 20 0a 2a 2a   aggregate.  .**
36d40 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66  .** The xFunc (f
36d50 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69  or scalar functi
36d60 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28 66  ons) or xStep (f
36d70 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 20 70  or aggregates) p
36d80 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20  arameters.** to 
36d90 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
36da0 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20  function()] and 
36db0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
36dc0 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a  function16()].**
36dd0 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b   define callback
36de0 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  s that implement
36df0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
36e00 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
36e10 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20 70 61  s..** The 3rd pa
36e20 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65  rameter to these
36e30 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e   callbacks is an
36e40 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
36e50 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63  rs to.** [protec
36e60 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
36e70 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65  e] objects.  The
36e80 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74  re is one [sqlit
36e90 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
36ea0 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72   for.** each par
36eb0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53 51  ameter to the SQ
36ec0 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65  L function.  The
36ed0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
36ee0 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61  used to.** extra
36ef0 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74  ct values from t
36f00 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
36f10 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a  e] objects..**.*
36f20 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
36f30 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20   work only with 
36f40 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
36f50 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
36f60 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70  s..** Any attemp
36f70 74 20 74 6f 20 75 73 65 20 74 68 65 73 65 20 72  t to use these r
36f80 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75  outines on an [u
36f90 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
36fa0 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a  e3_value].** obj
36fb0 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75  ect results in u
36fc0 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f  ndefined behavio
36fd0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  r..**.** ^These 
36fe0 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75  routines work ju
36ff0 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72  st like the corr
37000 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d  esponding [colum
37010 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
37020 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 68  ns].** except th
37030 61 74 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  at these routine
37040 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20  s take a single 
37050 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
37060 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
37070 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74  .** pointer inst
37080 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65  ead of a [sqlite
37090 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72  3_stmt*] pointer
370a0 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20   and an integer 
370b0 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a  column number..*
370c0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
370d0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
370e0 20 69 6e 74 65 72 66 61 63 65 20 65 78 74 72 61   interface extra
370f0 63 74 73 20 61 20 55 54 46 2d 31 36 20 73 74 72  cts a UTF-16 str
37100 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61  ing.** in the na
37110 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20  tive byte-order 
37120 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68  of the host mach
37130 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71  ine.  ^The.** sq
37140 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
37150 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74  16be() and sqlit
37160 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
37170 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  e() interfaces.*
37180 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d 31 36  * extract UTF-16
37190 20 73 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d   strings as big-
371a0 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c  endian and littl
371b0 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74  e-endian respect
371c0 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  ively..**.** ^(T
371d0 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
371e0 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20  _numeric_type() 
371f0 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70  interface attemp
37200 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e  ts to apply.** n
37210 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79 20  umeric affinity 
37220 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54  to the value.  T
37230 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61  his means that a
37240 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20  n attempt is.** 
37250 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20  made to convert 
37260 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20  the value to an 
37270 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74  integer or float
37280 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a  ing point.  If.*
37290 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73  * such a convers
372a0 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20  ion is possible 
372b0 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20  without loss of 
372c0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20  information (in 
372d0 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20  other.** words, 
372e0 69 66 20 74 68 65 20 76 61 6c 75 65 20 69 73 20  if the value is 
372f0 61 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f  a string that lo
37300 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65  oks like a numbe
37310 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63  r).** then the c
37320 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72  onversion is per
37330 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69  formed.  Otherwi
37340 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e  se no conversion
37350 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20   occurs..** The 
37360 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20  [SQLITE_INTEGER 
37370 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66 74 65  | datatype] afte
37380 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20  r conversion is 
37390 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a  returned.)^.**.*
373a0 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70 61 72  * Please pay par
373b0 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f  ticular attentio
373c0 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20 74 68  n to the fact th
373d0 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72  at the pointer r
373e0 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  eturned.** from 
373f0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
37400 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  lob()], [sqlite3
37410 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20  _value_text()], 
37420 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  or.** [sqlite3_v
37430 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63  alue_text16()] c
37440 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65  an be invalidate
37450 64 20 62 79 20 61 20 73 75 62 73 65 71 75 65 6e  d by a subsequen
37460 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  t call to.** [sq
37470 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
37480 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  s()], [sqlite3_v
37490 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c  alue_bytes16()],
374a0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
374b0 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b  text()],.** or [
374c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
374d0 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  xt16()]..**.** T
374e0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75  hese routines mu
374f0 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
37500 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
37510 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20  d as.** the SQL 
37520 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75  function that su
37530 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69  pplied the [sqli
37540 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61  te3_value*] para
37550 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63 6f 6e 73 74  meters..*/.const
37560 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
37570 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65  alue_blob(sqlite
37580 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
37590 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
375a0 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  es(sqlite3_value
375b0 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
375c0 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71  value_bytes16(sq
375d0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64  lite3_value*);.d
375e0 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61  ouble sqlite3_va
375f0 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  lue_double(sqlit
37600 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
37610 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
37620 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t(sqlite3_value*
37630 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
37640 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69   sqlite3_value_i
37650 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c  nt64(sqlite3_val
37660 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69  ue*);.const unsi
37670 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74  gned char *sqlit
37680 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71  e3_value_text(sq
37690 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63  lite3_value*);.c
376a0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
376b0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
376c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
376d0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
376e0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
376f0 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  6le(sqlite3_valu
37700 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  e*);.const void 
37710 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
37720 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f  ext16be(sqlite3_
37730 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
37740 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28  ite3_value_type(
37750 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
37760 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
37770 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28  ue_numeric_type(
37780 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
37790 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
377a0 3a 20 46 69 6e 64 69 6e 67 20 54 68 65 20 53 75  : Finding The Su
377b0 62 74 79 70 65 20 4f 66 20 53 51 4c 20 56 61 6c  btype Of SQL Val
377c0 75 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ues.** METHOD: s
377d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a  qlite3_value.**.
377e0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76  ** The sqlite3_v
377f0 61 6c 75 65 5f 73 75 62 74 79 70 65 28 56 29 20  alue_subtype(V) 
37800 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
37810 20 74 68 65 20 73 75 62 74 79 70 65 20 66 6f 72   the subtype for
37820 0a 2a 2a 20 61 6e 20 5b 61 70 70 6c 69 63 61 74  .** an [applicat
37830 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
37840 66 75 6e 63 74 69 6f 6e 5d 20 61 72 67 75 6d 65  function] argume
37850 6e 74 20 56 2e 20 20 54 68 65 20 73 75 62 74 79  nt V.  The subty
37860 70 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  pe.** informatio
37870 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
37880 20 70 61 73 73 20 61 20 6c 69 6d 69 74 65 64 20   pass a limited 
37890 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 74 65 78  amount of contex
378a0 74 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 53 51  t from.** one SQ
378b0 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 61 6e  L function to an
378c0 6f 74 68 65 72 2e 20 20 55 73 65 20 74 68 65 20  other.  Use the 
378d0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
378e0 73 75 62 74 79 70 65 28 29 5d 0a 2a 2a 20 72 6f  subtype()].** ro
378f0 75 74 69 6e 65 20 74 6f 20 73 65 74 20 74 68 65  utine to set the
37900 20 73 75 62 74 79 70 65 20 66 6f 72 20 74 68 65   subtype for the
37910 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
37920 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e   an SQL function
37930 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d  ..**.** SQLite m
37940 61 6b 65 73 20 6e 6f 20 75 73 65 20 6f 66 20 73  akes no use of s
37950 75 62 74 79 70 65 20 69 74 73 65 6c 66 2e 20 20  ubtype itself.  
37960 49 74 20 6d 65 72 65 6c 79 20 70 61 73 73 65 73  It merely passes
37970 20 74 68 65 20 73 75 62 74 79 70 65 0a 2a 2a 20   the subtype.** 
37980 66 72 6f 6d 20 74 68 65 20 72 65 73 75 6c 74 20  from the result 
37990 6f 66 20 6f 6e 65 20 5b 61 70 70 6c 69 63 61 74  of one [applicat
379a0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
379b0 66 75 6e 63 74 69 6f 6e 5d 20 69 6e 74 6f 20 74  function] into t
379c0 68 65 0a 2a 2a 20 69 6e 70 75 74 20 6f 66 20 61  he.** input of a
379d0 6e 6f 74 68 65 72 2e 0a 2a 2f 0a 75 6e 73 69 67  nother..*/.unsig
379e0 6e 65 64 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  ned int sqlite3_
379f0 76 61 6c 75 65 5f 73 75 62 74 79 70 65 28 73 71  value_subtype(sq
37a00 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a  lite3_value*);..
37a10 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
37a20 43 6f 70 79 20 41 6e 64 20 46 72 65 65 20 53 51  Copy And Free SQ
37a30 4c 20 56 61 6c 75 65 73 0a 2a 2a 20 4d 45 54 48  L Values.** METH
37a40 4f 44 3a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  OD: sqlite3_valu
37a50 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  e.**.** ^The sql
37a60 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 56  ite3_value_dup(V
37a70 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65  ) interface make
37a80 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
37a90 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a  [sqlite3_value].
37aa0 2a 2a 20 6f 62 6a 65 63 74 20 44 20 61 6e 64 20  ** object D and 
37ab0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
37ac0 72 20 74 6f 20 74 68 61 74 20 63 6f 70 79 2e 20  r to that copy. 
37ad0 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76   ^The [sqlite3_v
37ae0 61 6c 75 65 5d 20 72 65 74 75 72 6e 65 64 0a 2a  alue] returned.*
37af0 2a 20 69 73 20 61 20 5b 70 72 6f 74 65 63 74 65  * is a [protecte
37b00 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
37b10 20 6f 62 6a 65 63 74 20 65 76 65 6e 20 69 66 20   object even if 
37b20 74 68 65 20 69 6e 70 75 74 20 69 73 20 6e 6f 74  the input is not
37b30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
37b40 33 5f 76 61 6c 75 65 5f 64 75 70 28 56 29 20 69  3_value_dup(V) i
37b50 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
37b60 20 4e 55 4c 4c 20 69 66 20 56 20 69 73 20 4e 55   NULL if V is NU
37b70 4c 4c 20 6f 72 20 69 66 20 61 0a 2a 2a 20 6d 65  LL or if a.** me
37b80 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
37b90 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fails..**.** ^Th
37ba0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
37bb0 66 72 65 65 28 56 29 20 69 6e 74 65 72 66 61 63  free(V) interfac
37bc0 65 20 66 72 65 65 73 20 61 6e 20 5b 73 71 6c 69  e frees an [sqli
37bd0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
37be0 74 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  t.** previously 
37bf0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
37c00 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70  qlite3_value_dup
37c10 28 29 5d 2e 20 20 5e 49 66 20 56 20 69 73 20 61  ()].  ^If V is a
37c20 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
37c30 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 76 61   then sqlite3_va
37c40 6c 75 65 5f 66 72 65 65 28 56 29 20 69 73 20 61  lue_free(V) is a
37c50 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e   harmless no-op.
37c60 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75  .*/.sqlite3_valu
37c70 65 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e *sqlite3_value
37c80 5f 64 75 70 28 63 6f 6e 73 74 20 73 71 6c 69 74  _dup(const sqlit
37c90 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64  e3_value*);.void
37ca0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 66   sqlite3_value_f
37cb0 72 65 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ree(sqlite3_valu
37cc0 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  e*);../*.** CAPI
37cd0 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67  3REF: Obtain Agg
37ce0 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20  regate Function 
37cf0 43 6f 6e 74 65 78 74 0a 2a 2a 20 4d 45 54 48 4f  Context.** METHO
37d00 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  D: sqlite3_conte
37d10 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65  xt.**.** Impleme
37d20 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61 67 67 72  ntations of aggr
37d30 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
37d40 6f 6e 73 20 75 73 65 20 74 68 69 73 0a 2a 2a 20  ons use this.** 
37d50 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63  routine to alloc
37d60 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73  ate memory for s
37d70 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 61  toring their sta
37d80 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  te..**.** ^The f
37d90 69 72 73 74 20 74 69 6d 65 20 74 68 65 20 73 71  irst time the sq
37da0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
37db0 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75  context(C,N) rou
37dc0 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 0a  tine is called .
37dd0 2a 2a 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  ** for a particu
37de0 6c 61 72 20 61 67 67 72 65 67 61 74 65 20 66 75  lar aggregate fu
37df0 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a  nction, SQLite.*
37e00 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66  * allocates N of
37e10 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20   memory, zeroes 
37e20 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c  out that memory,
37e30 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70   and returns a p
37e40 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ointer.** to the
37e50 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e   new memory. ^On
37e60 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73   second and subs
37e70 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a  equent calls to.
37e80 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  ** sqlite3_aggre
37e90 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66  gate_context() f
37ea0 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67 67 72  or the same aggr
37eb0 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69  egate function i
37ec0 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20  nstance,.** the 
37ed0 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 20 72  same buffer is r
37ee0 65 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 74 65  eturned.  Sqlite
37ef0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
37f00 65 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c  ext() is normall
37f10 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65  y.** called once
37f20 20 66 6f 72 20 65 61 63 68 20 69 6e 76 6f 63 61   for each invoca
37f30 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 74 65  tion of the xSte
37f40 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74  p callback and t
37f50 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20  hen one.** last 
37f60 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20 78 46  time when the xF
37f70 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73  inal callback is
37f80 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65   invoked.  ^(Whe
37f90 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a  n no rows match.
37fa0 2a 2a 20 61 6e 20 61 67 67 72 65 67 61 74 65 20  ** an aggregate 
37fb0 71 75 65 72 79 2c 20 74 68 65 20 78 53 74 65 70  query, the xStep
37fc0 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74  () callback of t
37fd0 68 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  he aggregate fun
37fe0 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65  ction.** impleme
37ff0 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 65 72  ntation is never
38000 20 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e   called and xFin
38010 61 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 20 65  al() is called e
38020 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20  xactly once..** 
38030 49 6e 20 74 68 6f 73 65 20 63 61 73 65 73 2c 20  In those cases, 
38040 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
38050 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 67 68  e_context() migh
38060 74 20 62 65 20 63 61 6c 6c 65 64 20 66 6f 72 20  t be called for 
38070 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d  the.** first tim
38080 65 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 78 46  e from within xF
38090 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20  inal().)^.**.** 
380a0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67  ^The sqlite3_agg
380b0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
380c0 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ,N) routine retu
380d0 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
380e0 65 72 20 0a 2a 2a 20 77 68 65 6e 20 66 69 72 73  er .** when firs
380f0 74 20 63 61 6c 6c 65 64 20 69 66 20 4e 20 69 73  t called if N is
38100 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71   less than or eq
38110 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69  ual to zero or i
38120 66 20 61 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  f a memory.** al
38130 6c 6f 63 61 74 65 20 65 72 72 6f 72 20 6f 63 63  locate error occ
38140 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  urs..**.** ^(The
38150 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63 65   amount of space
38160 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71   allocated by sq
38170 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
38180 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69 73 0a  context(C,N) is.
38190 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79  ** determined by
381a0 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72   the N parameter
381b0 20 6f 6e 20 66 69 72 73 74 20 73 75 63 63 65 73   on first succes
381c0 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e  sful call.  Chan
381d0 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75  ging the.** valu
381e0 65 20 6f 66 20 4e 20 69 6e 20 73 75 62 73 65 71  e of N in subseq
381f0 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c  uent call to sql
38200 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
38210 6f 6e 74 65 78 74 28 29 20 77 69 74 68 69 6e 0a  ontext() within.
38220 2a 2a 20 74 68 65 20 73 61 6d 65 20 61 67 67 72  ** the same aggr
38230 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69  egate function i
38240 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74  nstance will not
38250 20 72 65 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f   resize the memo
38260 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  ry.** allocation
38270 2e 29 5e 20 20 57 69 74 68 69 6e 20 74 68 65 20  .)^  Within the 
38280 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 2c  xFinal callback,
38290 20 69 74 20 69 73 20 63 75 73 74 6f 6d 61 72 79   it is customary
382a0 20 74 6f 20 73 65 74 0a 2a 2a 20 4e 3d 30 20 69   to set.** N=0 i
382b0 6e 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  n calls to sqlit
382c0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
382d0 74 65 78 74 28 43 2c 4e 29 20 73 6f 20 74 68 61  text(C,N) so tha
382e0 74 20 6e 6f 20 0a 2a 2a 20 70 6f 69 6e 74 6c 65  t no .** pointle
382f0 73 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ss memory alloca
38300 74 69 6f 6e 73 20 6f 63 63 75 72 2e 0a 2a 2a 0a  tions occur..**.
38310 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d  ** ^SQLite autom
38320 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74  atically frees t
38330 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
38340 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74  ted by .** sqlit
38350 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
38360 74 65 78 74 28 29 20 77 68 65 6e 20 74 68 65 20  text() when the 
38370 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79 20  aggregate query 
38380 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a  concludes..**.**
38390 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
383a0 65 74 65 72 20 6d 75 73 74 20 62 65 20 61 20 63  eter must be a c
383b0 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  opy of the.** [s
383c0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c  qlite3_context |
383d0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f   SQL function co
383e0 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 74  ntext] that is t
383f0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
38400 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53 74  er.** to the xSt
38410 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c  ep or xFinal cal
38420 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68  lback routine th
38430 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  at implements th
38440 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 66  e aggregate.** f
38450 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  unction..**.** T
38460 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74  his routine must
38470 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
38480 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
38490 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20  in which.** the 
384a0 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
384b0 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
384c0 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  g..*/.void *sqli
384d0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
384e0 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f  ntext(sqlite3_co
384f0 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74  ntext*, int nByt
38500 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  es);../*.** CAPI
38510 33 52 45 46 3a 20 55 73 65 72 20 44 61 74 61 20  3REF: User Data 
38520 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  For Functions.**
38530 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
38540 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 5e  _context.**.** ^
38550 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72  The sqlite3_user
38560 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  _data() interfac
38570 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79  e returns a copy
38580 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74   of.** the point
38590 65 72 20 74 68 61 74 20 77 61 73 20 74 68 65 20  er that was the 
385a0 70 55 73 65 72 44 61 74 61 20 70 61 72 61 6d 65  pUserData parame
385b0 74 65 72 20 28 74 68 65 20 35 74 68 20 70 61 72  ter (the 5th par
385c0 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68  ameter).** of th
385d0 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
385e0 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a  e_function()].**
385f0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
38600 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
38610 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  )] routines that
38620 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72   originally.** r
38630 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70  egistered the ap
38640 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
38650 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  d function..**.*
38660 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d  * This routine m
38670 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
38680 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
38690 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74  ad in which.** t
386a0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
386b0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
386c0 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76  is running..*/.v
386d0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 73 65  oid *sqlite3_use
386e0 72 5f 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63  r_data(sqlite3_c
386f0 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  ontext*);../*.**
38700 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62   CAPI3REF: Datab
38710 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46  ase Connection F
38720 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  or Functions.** 
38730 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
38740 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 5e 54  context.**.** ^T
38750 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  he sqlite3_conte
38760 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69  xt_db_handle() i
38770 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
38780 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
38790 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  e pointer to the
387a0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
387b0 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20  ction] (the 1st 
387c0 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66  parameter).** of
387d0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
387e0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
387f0 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
38800 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _crea