/ Hex Artifact Content
Login

Artifact 8872d1f5e0f04bd441620ea6db856a84de219798a5d385b862a54d27892d68e8:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 64 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a  ed to operate..*
04e0: 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66  *.** The name of
04f0: 20 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72   this file under
0500: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d   configuration m
0510: 61 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71  anagement is "sq
0520: 6c 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54  lite.h.in"..** T
0530: 68 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65  he makefile make
0540: 73 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61  s some minor cha
0550: 6e 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c  nges to this fil
0560: 65 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72  e (such as inser
0570: 74 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73  ting.** the vers
0580: 69 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20  ion number) and 
0590: 63 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65  changes its name
05a0: 20 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20   to "sqlite3.h" 
05b0: 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68  as.** part of th
05c0: 65 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e  e build process.
05d0: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  .*/.#ifndef SQLI
05e0: 54 45 33 5f 48 0a 23 64 65 66 69 6e 65 20 53 51  TE3_H.#define SQ
05f0: 4c 49 54 45 33 5f 48 0a 23 69 6e 63 6c 75 64 65  LITE3_H.#include
0600: 20 3c 73 74 64 61 72 67 2e 68 3e 20 20 20 20 20   <stdarg.h>     
0610: 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72 20 74 68  /* Needed for th
0620: 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 66 20  e definition of 
0630: 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a  va_list */../*.*
0640: 2a 20 4d 61 6b 65 20 73 75 72 65 20 77 65 20 63  * Make sure we c
0650: 61 6e 20 63 61 6c 6c 20 74 68 69 73 20 73 74 75  an call this stu
0660: 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a  ff from C++..*/.
0670: 23 69 66 64 65 66 20 5f 5f 63 70 6c 75 73 70 6c  #ifdef __cpluspl
0680: 75 73 0a 65 78 74 65 72 6e 20 22 43 22 20 7b 0a  us.extern "C" {.
0690: 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 50  #endif.../*.** P
06a0: 72 6f 76 69 64 65 20 74 68 65 20 61 62 69 6c 69  rovide the abili
06b0: 74 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 6c  ty to override l
06c0: 69 6e 6b 61 67 65 20 66 65 61 74 75 72 65 73 20  inkage features 
06d0: 6f 66 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  of the interface
06e0: 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c  ..*/.#ifndef SQL
06f0: 49 54 45 5f 45 58 54 45 52 4e 0a 23 20 64 65 66  ITE_EXTERN.# def
0700: 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 54 45 52  ine SQLITE_EXTER
0710: 4e 20 65 78 74 65 72 6e 0a 23 65 6e 64 69 66 0a  N extern.#endif.
0720: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 41  #ifndef SQLITE_A
0730: 50 49 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  PI.# define SQLI
0740: 54 45 5f 41 50 49 0a 23 65 6e 64 69 66 0a 23 69  TE_API.#endif.#i
0750: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 43 44 45  fndef SQLITE_CDE
0760: 43 4c 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  CL.# define SQLI
0770: 54 45 5f 43 44 45 43 4c 0a 23 65 6e 64 69 66 0a  TE_CDECL.#endif.
0780: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 41  #ifndef SQLITE_A
0790: 50 49 43 41 4c 4c 0a 23 20 64 65 66 69 6e 65 20  PICALL.# define 
07a0: 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a 23  SQLITE_APICALL.#
07b0: 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51  endif.#ifndef SQ
07c0: 4c 49 54 45 5f 53 54 44 43 41 4c 4c 0a 23 20 64  LITE_STDCALL.# d
07d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 44  efine SQLITE_STD
07e0: 43 41 4c 4c 20 53 51 4c 49 54 45 5f 41 50 49 43  CALL SQLITE_APIC
07f0: 41 4c 4c 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64  ALL.#endif.#ifnd
0800: 65 66 20 53 51 4c 49 54 45 5f 43 41 4c 4c 42 41  ef SQLITE_CALLBA
0810: 43 4b 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  CK.# define SQLI
0820: 54 45 5f 43 41 4c 4c 42 41 43 4b 0a 23 65 6e 64  TE_CALLBACK.#end
0830: 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  if.#ifndef SQLIT
0840: 45 5f 53 59 53 41 50 49 0a 23 20 64 65 66 69 6e  E_SYSAPI.# defin
0850: 65 20 53 51 4c 49 54 45 5f 53 59 53 41 50 49 0a  e SQLITE_SYSAPI.
0860: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68  #endif../*.** Th
0870: 65 73 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73  ese no-op macros
0880: 20 61 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f   are used in fro
0890: 6e 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73  nt of interfaces
08a0: 20 74 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a   to mark those.*
08b0: 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 73 20  * interfaces as 
08c0: 65 69 74 68 65 72 20 64 65 70 72 65 63 61 74 65  either deprecate
08d0: 64 20 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61  d or experimenta
08e0: 6c 2e 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74  l.  New applicat
08f0: 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e  ions.** should n
0900: 6f 74 20 75 73 65 20 64 65 70 72 65 63 61 74 65  ot use deprecate
0910: 64 20 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74  d interfaces - t
0920: 68 65 79 20 61 72 65 20 73 75 70 70 6f 72 74 65  hey are supporte
0930: 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a  d for backwards.
0940: 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ** compatibility
0950: 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69 63 61 74   only.  Applicat
0960: 69 6f 6e 20 77 72 69 74 65 72 73 20 73 68 6f 75  ion writers shou
0970: 6c 64 20 62 65 20 61 77 61 72 65 20 74 68 61 74  ld be aware that
0980: 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e 74 61 6c  .** experimental
0990: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
09a0: 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
09b0: 65 20 69 6e 20 70 6f 69 6e 74 20 72 65 6c 65 61  e in point relea
09c0: 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ses..**.** These
09d0: 20 6d 61 63 72 6f 73 20 75 73 65 64 20 74 6f 20   macros used to 
09e0: 72 65 73 6f 6c 76 65 20 74 6f 20 76 61 72 69 6f  resolve to vario
09f0: 75 73 20 6b 69 6e 64 73 20 6f 66 20 63 6f 6d 70  us kinds of comp
0a00: 69 6c 65 72 20 6d 61 67 69 63 20 74 68 61 74 0a  iler magic that.
0a10: 2a 2a 20 77 6f 75 6c 64 20 67 65 6e 65 72 61 74  ** would generat
0a20: 65 20 77 61 72 6e 69 6e 67 20 6d 65 73 73 61 67  e warning messag
0a30: 65 73 20 77 68 65 6e 20 74 68 65 79 20 77 65 72  es when they wer
0a40: 65 20 75 73 65 64 2e 20 20 42 75 74 20 74 68 61  e used.  But tha
0a50: 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72 20 6d 61  t.** compiler ma
0a60: 67 69 63 20 65 6e 64 65 64 20 75 70 20 67 65 6e  gic ended up gen
0a70: 65 72 61 74 69 6e 67 20 73 75 63 68 20 61 20 66  erating such a f
0a80: 6c 75 72 72 79 20 6f 66 20 62 75 67 20 72 65 70  lurry of bug rep
0a90: 6f 72 74 73 0a 2a 2a 20 74 68 61 74 20 77 65 20  orts.** that we 
0aa0: 68 61 76 65 20 74 61 6b 65 6e 20 69 74 20 61 6c  have taken it al
0ab0: 6c 20 6f 75 74 20 61 6e 64 20 67 6f 6e 65 20 62  l out and gone b
0ac0: 61 63 6b 20 74 6f 20 75 73 69 6e 67 20 73 69 6d  ack to using sim
0ad0: 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72  ple.** noop macr
0ae0: 6f 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  os..*/.#define S
0af0: 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
0b00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
0b10: 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a  EXPERIMENTAL../*
0b20: 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68 65 73 65  .** Ensure these
0b30: 20 73 79 6d 62 6f 6c 73 20 77 65 72 65 20 6e 6f   symbols were no
0b40: 74 20 64 65 66 69 6e 65 64 20 62 79 20 73 6f 6d  t defined by som
0b50: 65 20 70 72 65 76 69 6f 75 73 20 68 65 61 64 65  e previous heade
0b60: 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65  r file..*/.#ifde
0b70: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0b80: 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f  .# undef SQLITE_
0b90: 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69 66 0a 23  VERSION.#endif.#
0ba0: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52  ifdef SQLITE_VER
0bb0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 20 75 6e  SION_NUMBER.# un
0bc0: 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49  def SQLITE_VERSI
0bd0: 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e 64 69 66  ON_NUMBER.#endif
0be0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
0bf0: 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 4c  : Compile-Time L
0c00: 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e  ibrary Version N
0c10: 75 6d 62 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54  umbers.**.** ^(T
0c20: 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  he [SQLITE_VERSI
0c30: 4f 4e 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  ON] C preprocess
0c40: 6f 72 20 6d 61 63 72 6f 20 69 6e 20 74 68 65 20  or macro in the 
0c50: 73 71 6c 69 74 65 33 2e 68 20 68 65 61 64 65 72  sqlite3.h header
0c60: 0a 2a 2a 20 65 76 61 6c 75 61 74 65 73 20 74 6f  .** evaluates to
0c70: 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
0c80: 6c 20 74 68 61 74 20 69 73 20 74 68 65 20 53 51  l that is the SQ
0c90: 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 69 6e 20  Lite version in 
0ca0: 74 68 65 0a 2a 2a 20 66 6f 72 6d 61 74 20 22 58  the.** format "X
0cb0: 2e 59 2e 5a 22 20 77 68 65 72 65 20 58 20 69 73  .Y.Z" where X is
0cc0: 20 74 68 65 20 6d 61 6a 6f 72 20 76 65 72 73 69   the major versi
0cd0: 6f 6e 20 6e 75 6d 62 65 72 20 28 61 6c 77 61 79  on number (alway
0ce0: 73 20 33 20 66 6f 72 0a 2a 2a 20 53 51 4c 69 74  s 3 for.** SQLit
0cf0: 65 33 29 20 61 6e 64 20 59 20 69 73 20 74 68 65  e3) and Y is the
0d00: 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f 6e 20 6e   minor version n
0d10: 75 6d 62 65 72 20 61 6e 64 20 5a 20 69 73 20 74  umber and Z is t
0d20: 68 65 20 72 65 6c 65 61 73 65 20 6e 75 6d 62 65  he release numbe
0d30: 72 2e 29 5e 0a 2a 2a 20 5e 28 54 68 65 20 5b 53  r.)^.** ^(The [S
0d40: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
0d50: 4d 42 45 52 5d 20 43 20 70 72 65 70 72 6f 63 65  MBER] C preproce
0d60: 73 73 6f 72 20 6d 61 63 72 6f 20 72 65 73 6f 6c  ssor macro resol
0d70: 76 65 73 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ves to an intege
0d80: 72 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 76 61  r.** with the va
0d90: 6c 75 65 20 28 58 2a 31 30 30 30 30 30 30 20 2b  lue (X*1000000 +
0da0: 20 59 2a 31 30 30 30 20 2b 20 5a 29 20 77 68 65   Y*1000 + Z) whe
0db0: 72 65 20 58 2c 20 59 2c 20 61 6e 64 20 5a 20 61  re X, Y, and Z a
0dc0: 72 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 6e  re the same.** n
0dd0: 75 6d 62 65 72 73 20 75 73 65 64 20 69 6e 20 5b  umbers used in [
0de0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2e  SQLITE_VERSION].
0df0: 29 5e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  )^.** The SQLITE
0e00: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20  _VERSION_NUMBER 
0e10: 66 6f 72 20 61 6e 79 20 67 69 76 65 6e 20 72 65  for any given re
0e20: 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20  lease of SQLite 
0e30: 77 69 6c 6c 20 61 6c 73 6f 0a 2a 2a 20 62 65 20  will also.** be 
0e40: 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20  larger than the 
0e50: 72 65 6c 65 61 73 65 20 66 72 6f 6d 20 77 68 69  release from whi
0e60: 63 68 20 69 74 20 69 73 20 64 65 72 69 76 65 64  ch it is derived
0e70: 2e 20 20 45 69 74 68 65 72 20 59 20 77 69 6c 6c  .  Either Y will
0e80: 0a 2a 2a 20 62 65 20 68 65 6c 64 20 63 6f 6e 73  .** be held cons
0e90: 74 61 6e 74 20 61 6e 64 20 5a 20 77 69 6c 6c 20  tant and Z will 
0ea0: 62 65 20 69 6e 63 72 65 6d 65 6e 74 65 64 20 6f  be incremented o
0eb0: 72 20 65 6c 73 65 20 59 20 77 69 6c 6c 20 62 65  r else Y will be
0ec0: 20 69 6e 63 72 65 6d 65 6e 74 65 64 0a 2a 2a 20   incremented.** 
0ed0: 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 72 65  and Z will be re
0ee0: 73 65 74 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a  set to zero..**.
0ef0: 2a 2a 20 53 69 6e 63 65 20 5b 76 65 72 73 69 6f  ** Since [versio
0f00: 6e 20 33 2e 36 2e 31 38 5d 20 28 5b 64 61 74 65  n 3.6.18] ([date
0f10: 6f 66 3a 33 2e 36 2e 31 38 5d 29 2c 20 0a 2a 2a  of:3.6.18]), .**
0f20: 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 63   SQLite source c
0f30: 6f 64 65 20 68 61 73 20 62 65 65 6e 20 73 74 6f  ode has been sto
0f40: 72 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 3c 61  red in the.** <a
0f50: 20 68 72 65 66 3d 22 68 74 74 70 3a 2f 2f 77 77   href="http://ww
0f60: 77 2e 66 6f 73 73 69 6c 2d 73 63 6d 2e 6f 72 67  w.fossil-scm.org
0f70: 2f 22 3e 46 6f 73 73 69 6c 20 63 6f 6e 66 69 67  /">Fossil config
0f80: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65  uration manageme
0f90: 6e 74 0a 2a 2a 20 73 79 73 74 65 6d 3c 2f 61 3e  nt.** system</a>
0fa0: 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 53  .  ^The SQLITE_S
0fb0: 4f 55 52 43 45 5f 49 44 20 6d 61 63 72 6f 20 65  OURCE_ID macro e
0fc0: 76 61 6c 75 61 74 65 73 20 74 6f 0a 2a 2a 20 61  valuates to.** a
0fd0: 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 64   string which id
0fe0: 65 6e 74 69 66 69 65 73 20 61 20 70 61 72 74 69  entifies a parti
0ff0: 63 75 6c 61 72 20 63 68 65 63 6b 2d 69 6e 20 6f  cular check-in o
1000: 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 74 68  f SQLite.** with
1010: 69 6e 20 69 74 73 20 63 6f 6e 66 69 67 75 72 61  in its configura
1020: 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20  tion management 
1030: 73 79 73 74 65 6d 2e 20 20 5e 54 68 65 20 53 51  system.  ^The SQ
1040: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 0a 2a  LITE_SOURCE_ID.*
1050: 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e  * string contain
1060: 73 20 74 68 65 20 64 61 74 65 20 61 6e 64 20 74  s the date and t
1070: 69 6d 65 20 6f 66 20 74 68 65 20 63 68 65 63 6b  ime of the check
1080: 2d 69 6e 20 28 55 54 43 29 20 61 6e 64 20 61 20  -in (UTC) and a 
1090: 53 48 41 31 0a 2a 2a 20 6f 72 20 53 48 41 33 2d  SHA1.** or SHA3-
10a0: 32 35 36 20 68 61 73 68 20 6f 66 20 74 68 65 20  256 hash of the 
10b0: 65 6e 74 69 72 65 20 73 6f 75 72 63 65 20 74 72  entire source tr
10c0: 65 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ee..**.** See al
10d0: 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62  so: [sqlite3_lib
10e0: 76 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b  version()],.** [
10f0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1100: 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73  on_number()], [s
1110: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28  qlite3_sourceid(
1120: 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76  )],.** [sqlite_v
1130: 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  ersion()] and [s
1140: 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28  qlite_source_id(
1150: 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  )]..*/.#define S
1160: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20  QLITE_VERSION   
1170: 20 20 20 20 20 22 2d 2d 56 45 52 53 2d 2d 22 0a       "--VERS--".
1180: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
1190: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 2d 2d  ERSION_NUMBER --
11a0: 56 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d 2d  VERSION-NUMBER--
11b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
11c0: 53 4f 55 52 43 45 5f 49 44 20 20 20 20 20 20 22  SOURCE_ID      "
11d0: 2d 2d 53 4f 55 52 43 45 2d 49 44 2d 2d 22 0a 0a  --SOURCE-ID--"..
11e0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
11f0: 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79  Run-Time Library
1200: 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73   Version Numbers
1210: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71  .** KEYWORDS: sq
1220: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 20 73 71  lite3_version sq
1230: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 0a 2a  lite3_sourceid.*
1240: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 72  *.** These inter
1250: 66 61 63 65 73 20 70 72 6f 76 69 64 65 20 74 68  faces provide th
1260: 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69  e same informati
1270: 6f 6e 20 61 73 20 74 68 65 20 5b 53 51 4c 49 54  on as the [SQLIT
1280: 45 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b  E_VERSION],.** [
1290: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
12a0: 55 4d 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51 4c  UMBER], and [SQL
12b0: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43  ITE_SOURCE_ID] C
12c0: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
12d0: 63 72 6f 73 0a 2a 2a 20 62 75 74 20 61 72 65 20  cros.** but are 
12e0: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
12f0: 74 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74  the library inst
1300: 65 61 64 20 6f 66 20 74 68 65 20 68 65 61 64 65  ead of the heade
1310: 72 20 66 69 6c 65 2e 20 20 5e 28 43 61 75 74 69  r file.  ^(Cauti
1320: 6f 75 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d 65  ous.** programme
1330: 72 73 20 6d 69 67 68 74 20 69 6e 63 6c 75 64 65  rs might include
1340: 20 61 73 73 65 72 74 28 29 20 73 74 61 74 65 6d   assert() statem
1350: 65 6e 74 73 20 69 6e 20 74 68 65 69 72 20 61 70  ents in their ap
1360: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20  plication to.** 
1370: 76 65 72 69 66 79 20 74 68 61 74 20 76 61 6c 75  verify that valu
1380: 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  es returned by t
1390: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
13a0: 6d 61 74 63 68 20 74 68 65 20 6d 61 63 72 6f 73  match the macros
13b0: 20 69 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64 65   in.** the heade
13c0: 72 2c 20 61 6e 64 20 74 68 75 73 20 65 6e 73 75  r, and thus ensu
13d0: 72 65 20 74 68 61 74 20 74 68 65 20 61 70 70 6c  re that the appl
13e0: 69 63 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f  ication is.** co
13f0: 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 61 74 63  mpiled with matc
1400: 68 69 6e 67 20 6c 69 62 72 61 72 79 20 61 6e 64  hing library and
1410: 20 68 65 61 64 65 72 20 66 69 6c 65 73 2e 0a 2a   header files..*
1420: 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1430: 3e 3c 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72 74  ><pre>.** assert
1440: 28 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  ( sqlite3_libver
1450: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d 53  sion_number()==S
1460: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
1470: 4d 42 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65 72  MBER );.** asser
1480: 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65  t( strcmp(sqlite
1490: 33 5f 73 6f 75 72 63 65 69 64 28 29 2c 53 51 4c  3_sourceid(),SQL
14a0: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 29 3d 3d  ITE_SOURCE_ID)==
14b0: 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20  0 );.** assert( 
14c0: 73 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 6c  strcmp(sqlite3_l
14d0: 69 62 76 65 72 73 69 6f 6e 28 29 2c 53 51 4c 49  ibversion(),SQLI
14e0: 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d 30 20 29  TE_VERSION)==0 )
14f0: 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
1500: 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a  ckquote>)^.**.**
1510: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 65   ^The sqlite3_ve
1520: 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63  rsion[] string c
1530: 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61 69 6e 73  onstant contains
1540: 20 74 68 65 20 74 65 78 74 20 6f 66 20 5b 53 51   the text of [SQ
1550: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a  LITE_VERSION].**
1560: 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65 20 73 71   macro.  ^The sq
1570: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1580: 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  () function retu
1590: 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
15a0: 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68 65 20 73   the.** to the s
15b0: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
15c0: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74   string constant
15d0: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c  .  The sqlite3_l
15e0: 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a 2a 20 66  ibversion().** f
15f0: 75 6e 63 74 69 6f 6e 20 69 73 20 70 72 6f 76 69  unction is provi
1600: 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 44  ded for use in D
1610: 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c 20 75 73  LLs since DLL us
1620: 65 72 73 20 75 73 75 61 6c 6c 79 20 64 6f 20 6e  ers usually do n
1630: 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69 72 65 63  ot have.** direc
1640: 74 20 61 63 63 65 73 73 20 74 6f 20 73 74 72 69  t access to stri
1650: 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20 77 69 74  ng constants wit
1660: 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20 20 5e 54  hin the DLL.  ^T
1670: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c 69  he.** sqlite3_li
1680: 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28  bversion_number(
1690: 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ) function retur
16a0: 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 65 71  ns an integer eq
16b0: 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54  ual to.** [SQLIT
16c0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
16d0: 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  ].  ^The sqlite3
16e0: 5f 73 6f 75 72 63 65 69 64 28 29 20 66 75 6e 63  _sourceid() func
16f0: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 0a 2a 2a  tion returns .**
1700: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
1710: 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20  string constant 
1720: 77 68 6f 73 65 20 76 61 6c 75 65 20 69 73 20 74  whose value is t
1730: 68 65 20 73 61 6d 65 20 61 73 20 74 68 65 20 0a  he same as the .
1740: 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43  ** [SQLITE_SOURC
1750: 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f 63 65  E_ID] C preproce
1760: 73 73 6f 72 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a  ssor macro..**.*
1770: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
1780: 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d 20 61  ite_version()] a
1790: 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75 72 63  nd [sqlite_sourc
17a0: 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49  e_id()]..*/.SQLI
17b0: 54 45 5f 45 58 54 45 52 4e 20 63 6f 6e 73 74 20  TE_EXTERN const 
17c0: 63 68 61 72 20 73 71 6c 69 74 65 33 5f 76 65 72  char sqlite3_ver
17d0: 73 69 6f 6e 5b 5d 3b 0a 63 6f 6e 73 74 20 63 68  sion[];.const ch
17e0: 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62 76  ar *sqlite3_libv
17f0: 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 63 6f  ersion(void);.co
1800: 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
1810: 33 5f 73 6f 75 72 63 65 69 64 28 76 6f 69 64 29  3_sourceid(void)
1820: 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69  ;.int sqlite3_li
1830: 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28  bversion_number(
1840: 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  void);../*.** CA
1850: 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65  PI3REF: Run-Time
1860: 20 4c 69 62 72 61 72 79 20 43 6f 6d 70 69 6c 61   Library Compila
1870: 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 44 69 61  tion Options Dia
1880: 67 6e 6f 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 5e  gnostics.**.** ^
1890: 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  The sqlite3_comp
18a0: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
18b0: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
18c0: 73 20 30 20 6f 72 20 31 20 0a 2a 2a 20 69 6e 64  s 0 or 1 .** ind
18d0: 69 63 61 74 69 6e 67 20 77 68 65 74 68 65 72 20  icating whether 
18e0: 74 68 65 20 73 70 65 63 69 66 69 65 64 20 6f 70  the specified op
18f0: 74 69 6f 6e 20 77 61 73 20 64 65 66 69 6e 65 64  tion was defined
1900: 20 61 74 20 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20   at .** compile 
1910: 74 69 6d 65 2e 20 20 5e 54 68 65 20 53 51 4c 49  time.  ^The SQLI
1920: 54 45 5f 20 70 72 65 66 69 78 20 6d 61 79 20 62  TE_ prefix may b
1930: 65 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74  e omitted from t
1940: 68 65 20 0a 2a 2a 20 6f 70 74 69 6f 6e 20 6e 61  he .** option na
1950: 6d 65 20 70 61 73 73 65 64 20 74 6f 20 73 71 6c  me passed to sql
1960: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
1970: 6f 6e 5f 75 73 65 64 28 29 2e 20 20 0a 2a 2a 0a  on_used().  .**.
1980: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1990: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65  compileoption_ge
19a0: 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 6c 6c  t() function all
19b0: 6f 77 73 20 69 74 65 72 61 74 69 6e 67 0a 2a 2a  ows iterating.**
19c0: 20 6f 76 65 72 20 74 68 65 20 6c 69 73 74 20 6f   over the list o
19d0: 66 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 77  f options that w
19e0: 65 72 65 20 64 65 66 69 6e 65 64 20 61 74 20 63  ere defined at c
19f0: 6f 6d 70 69 6c 65 20 74 69 6d 65 20 62 79 0a 2a  ompile time by.*
1a00: 2a 20 72 65 74 75 72 6e 69 6e 67 20 74 68 65 20  * returning the 
1a10: 4e 2d 74 68 20 63 6f 6d 70 69 6c 65 20 74 69 6d  N-th compile tim
1a20: 65 20 6f 70 74 69 6f 6e 20 73 74 72 69 6e 67 2e  e option string.
1a30: 20 20 5e 49 66 20 4e 20 69 73 20 6f 75 74 20 6f    ^If N is out o
1a40: 66 20 72 61 6e 67 65 2c 0a 2a 2a 20 73 71 6c 69  f range,.** sqli
1a50: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
1a60: 6e 5f 67 65 74 28 29 20 72 65 74 75 72 6e 73 20  n_get() returns 
1a70: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
1a80: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 0a 2a   ^The SQLITE_ .*
1a90: 2a 20 70 72 65 66 69 78 20 69 73 20 6f 6d 69 74  * prefix is omit
1aa0: 74 65 64 20 66 72 6f 6d 20 61 6e 79 20 73 74 72  ted from any str
1ab0: 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
1ac0: 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d   .** sqlite3_com
1ad0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29  pileoption_get()
1ae0: 2e 0a 2a 2a 0a 2a 2a 20 5e 53 75 70 70 6f 72 74  ..**.** ^Support
1af0: 20 66 6f 72 20 74 68 65 20 64 69 61 67 6e 6f 73   for the diagnos
1b00: 74 69 63 20 66 75 6e 63 74 69 6f 6e 73 20 73 71  tic functions sq
1b10: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1b20: 69 6f 6e 5f 75 73 65 64 28 29 0a 2a 2a 20 61 6e  ion_used().** an
1b30: 64 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  d sqlite3_compil
1b40: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 6d 61  eoption_get() ma
1b50: 79 20 62 65 20 6f 6d 69 74 74 65 64 20 62 79 20  y be omitted by 
1b60: 73 70 65 63 69 66 79 69 6e 67 20 74 68 65 20 0a  specifying the .
1b70: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  ** [SQLITE_OMIT_
1b80: 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49  COMPILEOPTION_DI
1b90: 41 47 53 5d 20 6f 70 74 69 6f 6e 20 61 74 20 63  AGS] option at c
1ba0: 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 0a 2a 2a 0a  ompile time..**.
1bb0: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 53 51 4c  ** See also: SQL
1bc0: 20 66 75 6e 63 74 69 6f 6e 73 20 5b 73 71 6c 69   functions [sqli
1bd0: 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  te_compileoption
1be0: 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20  _used()] and.** 
1bf0: 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f  [sqlite_compileo
1c00: 70 74 69 6f 6e 5f 67 65 74 28 29 5d 20 61 6e 64  ption_get()] and
1c10: 20 74 68 65 20 5b 63 6f 6d 70 69 6c 65 5f 6f 70   the [compile_op
1c20: 74 69 6f 6e 73 20 70 72 61 67 6d 61 5d 2e 0a 2a  tions pragma]..*
1c30: 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  /.#ifndef SQLITE
1c40: 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54  _OMIT_COMPILEOPT
1c50: 49 4f 4e 5f 44 49 41 47 53 0a 69 6e 74 20 73 71  ION_DIAGS.int sq
1c60: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1c70: 69 6f 6e 5f 75 73 65 64 28 63 6f 6e 73 74 20 63  ion_used(const c
1c80: 68 61 72 20 2a 7a 4f 70 74 4e 61 6d 65 29 3b 0a  har *zOptName);.
1c90: 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
1ca0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
1cb0: 6e 5f 67 65 74 28 69 6e 74 20 4e 29 3b 0a 23 65  n_get(int N);.#e
1cc0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
1cd0: 33 52 45 46 3a 20 54 65 73 74 20 54 6f 20 53 65  3REF: Test To Se
1ce0: 65 20 49 66 20 54 68 65 20 4c 69 62 72 61 72 79  e If The Library
1cf0: 20 49 73 20 54 68 72 65 61 64 73 61 66 65 0a 2a   Is Threadsafe.*
1d00: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1d10: 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 20 66  3_threadsafe() f
1d20: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1d30: 7a 65 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79  zero if and only
1d40: 20 69 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61   if.** SQLite wa
1d50: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
1d60: 6d 75 74 65 78 69 6e 67 20 63 6f 64 65 20 6f 6d  mutexing code om
1d70: 69 74 74 65 64 20 64 75 65 20 74 6f 20 74 68 65  itted due to the
1d80: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  .** [SQLITE_THRE
1d90: 41 44 53 41 46 45 5d 20 63 6f 6d 70 69 6c 65 2d  ADSAFE] compile-
1da0: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 62 65 69 6e  time option bein
1db0: 67 20 73 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a  g set to 0..**.*
1dc0: 2a 20 53 51 4c 69 74 65 20 63 61 6e 20 62 65 20  * SQLite can be 
1dd0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6f 72  compiled with or
1de0: 20 77 69 74 68 6f 75 74 20 6d 75 74 65 78 65 73   without mutexes
1df0: 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b  .  When.** the [
1e00: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1e10: 45 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f  E] C preprocesso
1e20: 72 20 6d 61 63 72 6f 20 69 73 20 31 20 6f 72 20  r macro is 1 or 
1e30: 32 2c 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72  2, mutexes.** ar
1e40: 65 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 53 51  e enabled and SQ
1e50: 4c 69 74 65 20 69 73 20 74 68 72 65 61 64 73 61  Lite is threadsa
1e60: 66 65 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a  fe.  When the.**
1e70: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
1e80: 41 46 45 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c  AFE] macro is 0,
1e90: 20 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73   .** the mutexes
1ea0: 20 61 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 57   are omitted.  W
1eb0: 69 74 68 6f 75 74 20 74 68 65 20 6d 75 74 65 78  ithout the mutex
1ec0: 65 73 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 61  es, it is not sa
1ed0: 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c  fe.** to use SQL
1ee0: 69 74 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79  ite concurrently
1ef0: 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20   from more than 
1f00: 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a  one thread..**.*
1f10: 2a 20 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78  * Enabling mutex
1f20: 65 73 20 69 6e 63 75 72 73 20 61 20 6d 65 61 73  es incurs a meas
1f30: 75 72 61 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e  urable performan
1f40: 63 65 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53  ce penalty..** S
1f50: 6f 20 69 66 20 73 70 65 65 64 20 69 73 20 6f 66  o if speed is of
1f60: 20 75 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e   utmost importan
1f70: 63 65 2c 20 69 74 20 6d 61 6b 65 73 20 73 65 6e  ce, it makes sen
1f80: 73 65 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a  se to disable.**
1f90: 20 74 68 65 20 6d 75 74 65 78 65 73 2e 20 20 42   the mutexes.  B
1fa0: 75 74 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73  ut for maximum s
1fb0: 61 66 65 74 79 2c 20 6d 75 74 65 78 65 73 20 73  afety, mutexes s
1fc0: 68 6f 75 6c 64 20 62 65 20 65 6e 61 62 6c 65 64  hould be enabled
1fd0: 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  ..** ^The defaul
1fe0: 74 20 62 65 68 61 76 69 6f 72 20 69 73 20 66 6f  t behavior is fo
1ff0: 72 20 6d 75 74 65 78 65 73 20 74 6f 20 62 65 20  r mutexes to be 
2000: 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  enabled..**.** T
2010: 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61  his interface ca
2020: 6e 20 62 65 20 75 73 65 64 20 62 79 20 61 6e 20  n be used by an 
2030: 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 6d  application to m
2040: 61 6b 65 20 73 75 72 65 20 74 68 61 74 20 74 68  ake sure that th
2050: 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20  e.** version of 
2060: 53 51 4c 69 74 65 20 74 68 61 74 20 69 74 20 69  SQLite that it i
2070: 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73  s linking agains
2080: 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  t was compiled w
2090: 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 73 69 72  ith.** the desir
20a0: 65 64 20 73 65 74 74 69 6e 67 20 6f 66 20 74 68  ed setting of th
20b0: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
20c0: 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a  SAFE] macro..**.
20d0: 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
20e0: 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f  e only reports o
20f0: 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69  n the compile-ti
2100: 6d 65 20 6d 75 74 65 78 20 73 65 74 74 69 6e 67  me mutex setting
2110: 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  .** of the [SQLI
2120: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 66  TE_THREADSAFE] f
2130: 6c 61 67 2e 20 20 49 66 20 53 51 4c 69 74 65 20  lag.  If SQLite 
2140: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
2150: 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48 52 45 41  .** SQLITE_THREA
2160: 44 53 41 46 45 3d 31 20 6f 72 20 3d 32 20 74 68  DSAFE=1 or =2 th
2170: 65 6e 20 6d 75 74 65 78 65 73 20 61 72 65 20 65  en mutexes are e
2180: 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  nabled by defaul
2190: 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20  t but.** can be 
21a0: 66 75 6c 6c 79 20 6f 72 20 70 61 72 74 69 61 6c  fully or partial
21b0: 6c 79 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e  ly disabled usin
21c0: 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  g a call to [sql
21d0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a  ite3_config()].*
21e0: 2a 20 77 69 74 68 20 74 68 65 20 76 65 72 62 73  * with the verbs
21f0: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
2200: 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b  SINGLETHREAD], [
2210: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
2220: 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f  LTITHREAD],.** o
2230: 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  r [SQLITE_CONFIG
2240: 5f 53 45 52 49 41 4c 49 5a 45 44 5d 2e 20 20 5e  _SERIALIZED].  ^
2250: 28 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75  (The return valu
2260: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c 69  e of the.** sqli
2270: 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29  te3_threadsafe()
2280: 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 20   function shows 
2290: 6f 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c 65  only the compile
22a0: 2d 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f 66  -time setting of
22b0: 0a 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65 74  .** thread safet
22c0: 79 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74  y, not any run-t
22d0: 69 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20 74  ime changes to t
22e0: 68 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64 65  hat setting made
22f0: 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   by.** sqlite3_c
2300: 6f 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68 65  onfig(). In othe
2310: 72 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65 74  r words, the ret
2320: 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  urn value from s
2330: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
2340: 65 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61 6e  e().** is unchan
2350: 67 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f 20  ged by calls to 
2360: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
2370: 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68  .)^.**.** See th
2380: 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  e [threading mod
2390: 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  e] documentation
23a0: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
23b0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
23c0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65  int sqlite3_thre
23d0: 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f  adsafe(void);../
23e0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
23f0: 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
2400: 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59  on Handle.** KEY
2410: 57 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65  WORDS: {database
2420: 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61   connection} {da
2430: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2440: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f  ns}.**.** Each o
2450: 70 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62  pen SQLite datab
2460: 61 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74  ase is represent
2470: 65 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20  ed by a pointer 
2480: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
2490: 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20  f.** the opaque 
24a0: 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20  structure named 
24b0: 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69  "sqlite3".  It i
24c0: 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e  s useful to thin
24d0: 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a  k of an sqlite3.
24e0: 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e  ** pointer as an
24f0: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73   object.  The [s
2500: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
2510: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
2520: 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
2530: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69  te3_open_v2()] i
2540: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 74  nterfaces are it
2550: 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20  s constructors, 
2560: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  and [sqlite3_clo
2570: 73 65 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  se()].** and [sq
2580: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
2590: 5d 20 61 72 65 20 69 74 73 20 64 65 73 74 72 75  ] are its destru
25a0: 63 74 6f 72 73 2e 20 20 54 68 65 72 65 20 61 72  ctors.  There ar
25b0: 65 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20  e many other.** 
25c0: 69 6e 74 65 72 66 61 63 65 73 20 28 73 75 63 68  interfaces (such
25d0: 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   as.** [sqlite3_
25e0: 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b  prepare_v2()], [
25f0: 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2600: 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a  unction()], and.
2610: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ** [sqlite3_busy
2620: 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20 6e  _timeout()] to n
2630: 61 6d 65 20 62 75 74 20 74 68 72 65 65 29 20 74  ame but three) t
2640: 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73 20  hat are methods 
2650: 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33  on an.** sqlite3
2660: 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65   object..*/.type
2670: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
2680: 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a  e3 sqlite3;../*.
2690: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34 2d  ** CAPI3REF: 64-
26a0: 42 69 74 20 49 6e 74 65 67 65 72 20 54 79 70 65  Bit Integer Type
26b0: 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73  s.** KEYWORDS: s
26c0: 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69  qlite_int64 sqli
26d0: 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20  te_uint64.**.** 
26e0: 42 65 63 61 75 73 65 20 74 68 65 72 65 20 69 73  Because there is
26f0: 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f   no cross-platfo
2700: 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69 66  rm way to specif
2710: 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72  y 64-bit integer
2720: 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65   types.** SQLite
2730: 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64 65   includes typede
2740: 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73 69  fs for 64-bit si
2750: 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e 65  gned and unsigne
2760: 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a  d integers..**.*
2770: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  * The sqlite3_in
2780: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t64 and sqlite3_
2790: 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 20 70  uint64 are the p
27a0: 72 65 66 65 72 72 65 64 20 74 79 70 65 20 64 65  referred type de
27b0: 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68  finitions..** Th
27c0: 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 61  e sqlite_int64 a
27d0: 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  nd sqlite_uint64
27e0: 20 74 79 70 65 73 20 61 72 65 20 73 75 70 70 6f   types are suppo
27f0: 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  rted for backwar
2800: 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  ds.** compatibil
2810: 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ity only..**.** 
2820: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  ^The sqlite3_int
2830: 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 69 6e  64 and sqlite_in
2840: 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73 74  t64 types can st
2850: 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  ore integer valu
2860: 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 2d 39  es.** between -9
2870: 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38  2233720368547758
2880: 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37 32 30  08 and +92233720
2890: 33 36 38 35 34 37 37 35 38 30 37 20 69 6e 63 6c  36854775807 incl
28a0: 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a 2a 20  usive.  ^The.** 
28b0: 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61  sqlite3_uint64 a
28c0: 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  nd sqlite_uint64
28d0: 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72 65   types can store
28e0: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
28f0: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e  .** between 0 an
2900: 64 20 2b 31 38 34 34 36 37 34 34 30 37 33 37 30  d +1844674407370
2910: 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73 69 76  9551615 inclusiv
2920: 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c  e..*/.#ifdef SQL
2930: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a 20  ITE_INT64_TYPE. 
2940: 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f   typedef SQLITE_
2950: 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74  INT64_TYPE sqlit
2960: 65 5f 69 6e 74 36 34 3b 0a 23 20 69 66 64 65 66  e_int64;.# ifdef
2970: 20 53 51 4c 49 54 45 5f 55 49 4e 54 36 34 5f 54   SQLITE_UINT64_T
2980: 59 50 45 0a 20 20 20 20 74 79 70 65 64 65 66 20  YPE.    typedef 
2990: 53 51 4c 49 54 45 5f 55 49 4e 54 36 34 5f 54 59  SQLITE_UINT64_TY
29a0: 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  PE sqlite_uint64
29b0: 3b 0a 23 20 65 6c 73 65 20 20 0a 20 20 20 20 74  ;.# else  .    t
29c0: 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20  ypedef unsigned 
29d0: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
29e0: 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b  E sqlite_uint64;
29f0: 0a 23 20 65 6e 64 69 66 0a 23 65 6c 69 66 20 64  .# endif.#elif d
2a00: 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29  efined(_MSC_VER)
2a10: 20 7c 7c 20 64 65 66 69 6e 65 64 28 5f 5f 42 4f   || defined(__BO
2a20: 52 4c 41 4e 44 43 5f 5f 29 0a 20 20 74 79 70 65  RLANDC__).  type
2a30: 64 65 66 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69  def __int64 sqli
2a40: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
2a50: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 5f 5f 69  def unsigned __i
2a60: 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74  nt64 sqlite_uint
2a70: 36 34 3b 0a 23 65 6c 73 65 0a 20 20 74 79 70 65  64;.#else.  type
2a80: 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e  def long long in
2a90: 74 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  t sqlite_int64;.
2aa0: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
2ab0: 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74  ed long long int
2ac0: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a   sqlite_uint64;.
2ad0: 23 65 6e 64 69 66 0a 74 79 70 65 64 65 66 20 73  #endif.typedef s
2ae0: 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69  qlite_int64 sqli
2af0: 74 65 33 5f 69 6e 74 36 34 3b 0a 74 79 70 65 64  te3_int64;.typed
2b00: 65 66 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  ef sqlite_uint64
2b10: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 3b   sqlite3_uint64;
2b20: 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70 69  ../*.** If compi
2b30: 6c 69 6e 67 20 66 6f 72 20 61 20 70 72 6f 63 65  ling for a proce
2b40: 73 73 6f 72 20 74 68 61 74 20 6c 61 63 6b 73 20  ssor that lacks 
2b50: 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 73  floating point s
2b60: 75 70 70 6f 72 74 2c 0a 2a 2a 20 73 75 62 73 74  upport,.** subst
2b70: 69 74 75 74 65 20 69 6e 74 65 67 65 72 20 66 6f  itute integer fo
2b80: 72 20 66 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e 74  r floating-point
2b90: 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49  ..*/.#ifdef SQLI
2ba0: 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47  TE_OMIT_FLOATING
2bb0: 5f 50 4f 49 4e 54 0a 23 20 64 65 66 69 6e 65 20  _POINT.# define 
2bc0: 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 69  double sqlite3_i
2bd0: 6e 74 36 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  nt64.#endif../*.
2be0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6c 6f  ** CAPI3REF: Clo
2bf0: 73 69 6e 67 20 41 20 44 61 74 61 62 61 73 65 20  sing A Database 
2c00: 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 44 45  Connection.** DE
2c10: 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65  STRUCTOR: sqlite
2c20: 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  3.**.** ^The sql
2c30: 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64  ite3_close() and
2c40: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76   sqlite3_close_v
2c50: 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65  2() routines are
2c60: 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a 2a 20   destructors.** 
2c70: 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33  for the [sqlite3
2c80: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 43 61  ] object..** ^Ca
2c90: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
2ca0: 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74  lose() and sqlit
2cb0: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 65  e3_close_v2() re
2cc0: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
2cd0: 20 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69   if.** the [sqli
2ce0: 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 73  te3] object is s
2cf0: 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74  uccessfully dest
2d00: 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73  royed and all as
2d10: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f  sociated.** reso
2d20: 75 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f  urces are deallo
2d30: 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  cated..**.** ^If
2d40: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2d50: 6e 6e 65 63 74 69 6f 6e 20 69 73 20 61 73 73 6f  nnection is asso
2d60: 63 69 61 74 65 64 20 77 69 74 68 20 75 6e 66 69  ciated with unfi
2d70: 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64  nalized prepared
2d80: 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 6f  .** statements o
2d90: 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c  r unfinished sql
2da0: 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65  ite3_backup obje
2db0: 63 74 73 20 74 68 65 6e 20 73 71 6c 69 74 65 33  cts then sqlite3
2dc0: 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c  _close().** will
2dd0: 20 6c 65 61 76 65 20 74 68 65 20 64 61 74 61 62   leave the datab
2de0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
2df0: 70 65 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 5b  pen and return [
2e00: 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a  SQLITE_BUSY]..**
2e10: 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f   ^If sqlite3_clo
2e20: 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65  se_v2() is calle
2e30: 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a  d with unfinaliz
2e40: 65 64 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ed prepared stat
2e50: 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 2f 6f 72  ements.** and/or
2e60: 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c 69   unfinished sqli
2e70: 74 65 33 5f 62 61 63 6b 75 70 73 2c 20 74 68 65  te3_backups, the
2e80: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
2e90: 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 63 6f 6d 65  onnection become
2ea0: 73 0a 2a 2a 20 61 6e 20 75 6e 75 73 61 62 6c 65  s.** an unusable
2eb0: 20 22 7a 6f 6d 62 69 65 22 20 77 68 69 63 68 20   "zombie" which 
2ec0: 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c  will automatical
2ed0: 6c 79 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  ly be deallocate
2ee0: 64 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 6c 61  d when the.** la
2ef0: 73 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74  st prepared stat
2f00: 65 6d 65 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a  ement is finaliz
2f10: 65 64 20 6f 72 20 74 68 65 20 6c 61 73 74 20 73  ed or the last s
2f20: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 69 73  qlite3_backup is
2f30: 0a 2a 2a 20 66 69 6e 69 73 68 65 64 2e 20 20 54  .** finished.  T
2f40: 68 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  he sqlite3_close
2f50: 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20  _v2() interface 
2f60: 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  is intended for 
2f70: 75 73 65 20 77 69 74 68 0a 2a 2a 20 68 6f 73 74  use with.** host
2f80: 20 6c 61 6e 67 75 61 67 65 73 20 74 68 61 74 20   languages that 
2f90: 61 72 65 20 67 61 72 62 61 67 65 20 63 6f 6c 6c  are garbage coll
2fa0: 65 63 74 65 64 2c 20 61 6e 64 20 77 68 65 72 65  ected, and where
2fb0: 20 74 68 65 20 6f 72 64 65 72 20 69 6e 20 77 68   the order in wh
2fc0: 69 63 68 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f  ich.** destructo
2fd0: 72 73 20 61 72 65 20 63 61 6c 6c 65 64 20 69 73  rs are called is
2fe0: 20 61 72 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a   arbitrary..**.*
2ff0: 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  * Applications s
3000: 68 6f 75 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66  hould [sqlite3_f
3010: 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69  inalize | finali
3020: 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70 61 72 65  ze] all [prepare
3030: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a  d statements],.*
3040: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  * [sqlite3_blob_
3050: 63 6c 6f 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61  close | close] a
3060: 6c 6c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73  ll [BLOB handles
3070: 5d 2c 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69  ], and .** [sqli
3080: 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73  te3_backup_finis
3090: 68 20 7c 20 66 69 6e 69 73 68 5d 20 61 6c 6c 20  h | finish] all 
30a0: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d  [sqlite3_backup]
30b0: 20 6f 62 6a 65 63 74 73 20 61 73 73 6f 63 69 61   objects associa
30c0: 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ted.** with the 
30d0: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
30e0: 20 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70   prior to attemp
30f0: 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68  ting to close th
3100: 65 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a  e object.  ^If.*
3110: 2a 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f  * sqlite3_close_
3120: 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20 6f  v2() is called o
3130: 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  n a [database co
3140: 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 73  nnection] that s
3150: 74 69 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75 74 73  till has.** outs
3160: 74 61 6e 64 69 6e 67 20 5b 70 72 65 70 61 72 65  tanding [prepare
3170: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b  d statements], [
3180: 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61  BLOB handles], a
3190: 6e 64 2f 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  nd/or.** [sqlite
31a0: 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74  3_backup] object
31b0: 73 20 74 68 65 6e 20 69 74 20 72 65 74 75 72 6e  s then it return
31c0: 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 61 6e  s [SQLITE_OK] an
31d0: 64 20 74 68 65 20 64 65 61 6c 6c 6f 63 61 74 69  d the deallocati
31e0: 6f 6e 0a 2a 2a 20 6f 66 20 72 65 73 6f 75 72 63  on.** of resourc
31f0: 65 73 20 69 73 20 64 65 66 65 72 72 65 64 20 75  es is deferred u
3200: 6e 74 69 6c 20 61 6c 6c 20 5b 70 72 65 70 61 72  ntil all [prepar
3210: 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20  ed statements], 
3220: 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 0a  [BLOB handles],.
3230: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
3240: 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20  backup] objects 
3250: 61 72 65 20 61 6c 73 6f 20 64 65 73 74 72 6f 79  are also destroy
3260: 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ed..**.** ^If an
3270: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
3280: 74 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 77  t is destroyed w
3290: 68 69 6c 65 20 61 20 74 72 61 6e 73 61 63 74 69  hile a transacti
32a0: 6f 6e 20 69 73 20 6f 70 65 6e 2c 0a 2a 2a 20 74  on is open,.** t
32b0: 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69  he transaction i
32c0: 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  s automatically 
32d0: 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a  rolled back..**.
32e0: 2a 2a 20 54 68 65 20 43 20 70 61 72 61 6d 65 74  ** The C paramet
32f0: 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  er to [sqlite3_c
3300: 6c 6f 73 65 28 43 29 5d 20 61 6e 64 20 5b 73 71  lose(C)] and [sq
3310: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 43  lite3_close_v2(C
3320: 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69  )].** must be ei
3330: 74 68 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70  ther a NULL.** p
3340: 6f 69 6e 74 65 72 20 6f 72 20 61 6e 20 5b 73 71  ointer or an [sq
3350: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 6f  lite3] object po
3360: 69 6e 74 65 72 20 6f 62 74 61 69 6e 65 64 0a 2a  inter obtained.*
3370: 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
3380: 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
3390: 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 0a  3_open16()], or.
33a0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ** [sqlite3_open
33b0: 5f 76 32 28 29 5d 2c 20 61 6e 64 20 6e 6f 74 20  _v2()], and not 
33c0: 70 72 65 76 69 6f 75 73 6c 79 20 63 6c 6f 73 65  previously close
33d0: 64 2e 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73  d..** ^Calling s
33e0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 6f  qlite3_close() o
33f0: 72 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f  r sqlite3_close_
3400: 76 32 28 29 20 77 69 74 68 20 61 20 4e 55 4c 4c  v2() with a NULL
3410: 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 61 72 67 75   pointer.** argu
3420: 6d 65 6e 74 20 69 73 20 61 20 68 61 72 6d 6c 65  ment is a harmle
3430: 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 69 6e 74  ss no-op..*/.int
3440: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 73   sqlite3_close(s
3450: 71 6c 69 74 65 33 2a 29 3b 0a 69 6e 74 20 73 71  qlite3*);.int sq
3460: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 73  lite3_close_v2(s
3470: 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
3480: 20 54 68 65 20 74 79 70 65 20 66 6f 72 20 61 20   The type for a 
3490: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
34a0: 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 6c 65  n..** This is le
34b0: 67 61 63 79 20 61 6e 64 20 64 65 70 72 65 63 61  gacy and depreca
34c0: 74 65 64 2e 20 20 49 74 20 69 73 20 69 6e 63 6c  ted.  It is incl
34d0: 75 64 65 64 20 66 6f 72 20 68 69 73 74 6f 72 69  uded for histori
34e0: 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69  cal.** compatibi
34f0: 6c 69 74 79 20 61 6e 64 20 69 73 20 6e 6f 74 20  lity and is not 
3500: 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74  documented..*/.t
3510: 79 70 65 64 65 66 20 69 6e 74 20 28 2a 73 71 6c  ypedef int (*sql
3520: 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76  ite3_callback)(v
3530: 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c  oid*,int,char**,
3540: 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a   char**);../*.**
3550: 20 43 41 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53   CAPI3REF: One-S
3560: 74 65 70 20 51 75 65 72 79 20 45 78 65 63 75 74  tep Query Execut
3570: 69 6f 6e 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a  ion Interface.**
3580: 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
3590: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
35a0: 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66  e3_exec() interf
35b0: 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e 69  ace is a conveni
35c0: 65 6e 63 65 20 77 72 61 70 70 65 72 20 61 72 6f  ence wrapper aro
35d0: 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  und.** [sqlite3_
35e0: 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b  prepare_v2()], [
35f0: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c  sqlite3_step()],
3600: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 69   and [sqlite3_fi
3610: 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74 68  nalize()],.** th
3620: 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70 70  at allows an app
3630: 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e 20  lication to run 
3640: 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d 65  multiple stateme
3650: 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77 69  nts of SQL.** wi
3660: 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f 20  thout having to 
3670: 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20 63  use a lot of C c
3680: 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ode. .**.** ^The
3690: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
36a0: 69 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20 7a  interface runs z
36b0: 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46 2d  ero or more UTF-
36c0: 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73 65  8 encoded,.** se
36d0: 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65  micolon-separate
36e0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
36f0: 70 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73 20  passed into its 
3700: 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a 2a  2nd argument,.**
3710: 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74 20   in the context 
3720: 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  of the [database
3730: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61 73   connection] pas
3740: 73 65 64 20 69 6e 20 61 73 20 69 74 73 20 31 73  sed in as its 1s
3750: 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20  t.** argument.  
3760: 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ^If the callback
3770: 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68 65   function of the
3780: 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f   3rd argument to
3790: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
37a0: 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  () is not NULL, 
37b0: 74 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f 6b  then it is invok
37c0: 65 64 20 66 6f 72 20 65 61 63 68 20 72 65 73 75  ed for each resu
37d0: 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e 67  lt row.** coming
37e0: 20 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61 6c   out of the eval
37f0: 75 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  uated SQL statem
3800: 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68 20  ents.  ^The 4th 
3810: 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73  argument to.** s
3820: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3830: 20 72 65 6c 61 79 65 64 20 74 68 72 6f 75 67 68   relayed through
3840: 20 74 6f 20 74 68 65 20 31 73 74 20 61 72 67 75   to the 1st argu
3850: 6d 65 6e 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20  ment of each.** 
3860: 63 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 63 61 74  callback invocat
3870: 69 6f 6e 2e 20 20 5e 49 66 20 74 68 65 20 63 61  ion.  ^If the ca
3880: 6c 6c 62 61 63 6b 20 70 6f 69 6e 74 65 72 20 74  llback pointer t
3890: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
38a0: 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  .** is NULL, the
38b0: 6e 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 20 69 73  n no callback is
38c0: 20 65 76 65 72 20 69 6e 76 6f 6b 65 64 20 61 6e   ever invoked an
38d0: 64 20 72 65 73 75 6c 74 20 72 6f 77 73 20 61 72  d result rows ar
38e0: 65 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a  e.** ignored..**
38f0: 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72 6f 72  .** ^If an error
3900: 20 6f 63 63 75 72 73 20 77 68 69 6c 65 20 65 76   occurs while ev
3910: 61 6c 75 61 74 69 6e 67 20 74 68 65 20 53 51 4c  aluating the SQL
3920: 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73   statements pass
3930: 65 64 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74  ed into.** sqlit
3940: 65 33 5f 65 78 65 63 28 29 2c 20 74 68 65 6e 20  e3_exec(), then 
3950: 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65  execution of the
3960: 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 6d 65   current stateme
3970: 6e 74 20 73 74 6f 70 73 20 61 6e 64 0a 2a 2a 20  nt stops and.** 
3980: 73 75 62 73 65 71 75 65 6e 74 20 73 74 61 74 65  subsequent state
3990: 6d 65 6e 74 73 20 61 72 65 20 73 6b 69 70 70 65  ments are skippe
39a0: 64 2e 20 20 5e 49 66 20 74 68 65 20 35 74 68 20  d.  ^If the 5th 
39b0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
39c0: 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69  ite3_exec().** i
39d0: 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20  s not NULL then 
39e0: 61 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 61 67  any error messag
39f0: 65 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74  e is written int
3a00: 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
3a10: 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  d.** from [sqlit
3a20: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64  e3_malloc()] and
3a30: 20 70 61 73 73 65 64 20 62 61 63 6b 20 74 68 72   passed back thr
3a40: 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72  ough the 5th par
3a50: 61 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f 20 61 76  ameter..** To av
3a60: 6f 69 64 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 73  oid memory leaks
3a70: 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  , the applicatio
3a80: 6e 20 73 68 6f 75 6c 64 20 69 6e 76 6f 6b 65 20  n should invoke 
3a90: 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
3aa0: 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72 20 6d 65 73  .** on error mes
3ab0: 73 61 67 65 20 73 74 72 69 6e 67 73 20 72 65 74  sage strings ret
3ac0: 75 72 6e 65 64 20 74 68 72 6f 75 67 68 20 74 68  urned through th
3ad0: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
3ae0: 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78  of.** sqlite3_ex
3af0: 65 63 28 29 20 61 66 74 65 72 20 74 68 65 20 65  ec() after the e
3b00: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
3b10: 69 6e 67 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72  ing is no longer
3b20: 20 6e 65 65 64 65 64 2e 0a 2a 2a 20 5e 49 66 20   needed..** ^If 
3b30: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
3b40: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
3b50: 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  c() is not NULL 
3b60: 61 6e 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a  and no errors.**
3b70: 20 6f 63 63 75 72 2c 20 74 68 65 6e 20 73 71 6c   occur, then sql
3b80: 69 74 65 33 5f 65 78 65 63 28 29 20 73 65 74 73  ite3_exec() sets
3b90: 20 74 68 65 20 70 6f 69 6e 74 65 72 20 69 6e 20   the pointer in 
3ba0: 69 74 73 20 35 74 68 20 70 61 72 61 6d 65 74 65  its 5th paramete
3bb0: 72 20 74 6f 0a 2a 2a 20 4e 55 4c 4c 20 62 65 66  r to.** NULL bef
3bc0: 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a  ore returning..*
3bd0: 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 73 71 6c 69  *.** ^If an sqli
3be0: 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62  te3_exec() callb
3bf0: 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ack returns non-
3c00: 7a 65 72 6f 2c 20 74 68 65 20 73 71 6c 69 74 65  zero, the sqlite
3c10: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 72 6f 75 74  3_exec().** rout
3c20: 69 6e 65 20 72 65 74 75 72 6e 73 20 53 51 4c 49  ine returns SQLI
3c30: 54 45 5f 41 42 4f 52 54 20 77 69 74 68 6f 75 74  TE_ABORT without
3c40: 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 63 61   invoking the ca
3c50: 6c 6c 62 61 63 6b 20 61 67 61 69 6e 20 61 6e 64  llback again and
3c60: 0a 2a 2a 20 77 69 74 68 6f 75 74 20 72 75 6e 6e  .** without runn
3c70: 69 6e 67 20 61 6e 79 20 73 75 62 73 65 71 75 65  ing any subseque
3c80: 6e 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  nt SQL statement
3c90: 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 32 6e  s..**.** ^The 2n
3ca0: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  d argument to th
3cb0: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3cc0: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
3cd0: 6f 6e 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  on is the.** num
3ce0: 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
3cf0: 6e 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 5e  n the result.  ^
3d00: 54 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74  The 3rd argument
3d10: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
3d20: 65 78 65 63 28 29 0a 2a 2a 20 63 61 6c 6c 62 61  exec().** callba
3d30: 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  ck is an array o
3d40: 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74  f pointers to st
3d50: 72 69 6e 67 73 20 6f 62 74 61 69 6e 65 64 20 61  rings obtained a
3d60: 73 20 69 66 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71  s if from.** [sq
3d70: 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
3d80: 74 28 29 5d 2c 20 6f 6e 65 20 66 6f 72 20 65 61  t()], one for ea
3d90: 63 68 20 63 6f 6c 75 6d 6e 2e 20 20 5e 49 66 20  ch column.  ^If 
3da0: 61 6e 20 65 6c 65 6d 65 6e 74 20 6f 66 20 61 0a  an element of a.
3db0: 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 69 73  ** result row is
3dc0: 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 63   NULL then the c
3dd0: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 73 74 72  orresponding str
3de0: 69 6e 67 20 70 6f 69 6e 74 65 72 20 66 6f 72 20  ing pointer for 
3df0: 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65  the.** sqlite3_e
3e00: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69  xec() callback i
3e10: 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
3e20: 2e 20 20 5e 54 68 65 20 34 74 68 20 61 72 67 75  .  ^The 4th argu
3e30: 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 73  ment to the.** s
3e40: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61  qlite3_exec() ca
3e50: 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72  llback is an arr
3e60: 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
3e70: 6f 20 73 74 72 69 6e 67 73 20 77 68 65 72 65 20  o strings where 
3e80: 65 61 63 68 0a 2a 2a 20 65 6e 74 72 79 20 72 65  each.** entry re
3e90: 70 72 65 73 65 6e 74 73 20 74 68 65 20 6e 61 6d  presents the nam
3ea0: 65 20 6f 66 20 63 6f 72 72 65 73 70 6f 6e 64 69  e of correspondi
3eb0: 6e 67 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  ng result column
3ec0: 20 61 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20   as obtained.** 
3ed0: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f  from [sqlite3_co
3ee0: 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a  lumn_name()]..**
3ef0: 0a 2a 2a 20 5e 49 66 20 74 68 65 20 32 6e 64 20  .** ^If the 2nd 
3f00: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
3f10: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 61  ite3_exec() is a
3f20: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 61   NULL pointer, a
3f30: 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 61   pointer.** to a
3f40: 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20  n empty string, 
3f50: 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74 68 61  or a pointer tha
3f60: 74 20 63 6f 6e 74 61 69 6e 73 20 6f 6e 6c 79 20  t contains only 
3f70: 77 68 69 74 65 73 70 61 63 65 20 61 6e 64 2f 6f  whitespace and/o
3f80: 72 20 0a 2a 2a 20 53 51 4c 20 63 6f 6d 6d 65 6e  r .** SQL commen
3f90: 74 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51 4c 20  ts, then no SQL 
3fa0: 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 65  statements are e
3fb0: 76 61 6c 75 61 74 65 64 20 61 6e 64 20 74 68 65  valuated and the
3fc0: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20   database.** is 
3fd0: 6e 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a  not changed..**.
3fe0: 2a 2a 20 52 65 73 74 72 69 63 74 69 6f 6e 73 3a  ** Restrictions:
3ff0: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
4000: 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74  li> The applicat
4010: 69 6f 6e 20 6d 75 73 74 20 65 6e 73 75 72 65 20  ion must ensure 
4020: 74 68 61 74 20 74 68 65 20 31 73 74 20 70 61 72  that the 1st par
4030: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
4040: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 20 20 20 20  3_exec().**     
4050: 20 69 73 20 61 20 76 61 6c 69 64 20 61 6e 64 20   is a valid and 
4060: 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63  open [database c
4070: 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c  onnection]..** <
4080: 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74  li> The applicat
4090: 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f  ion must not clo
40a0: 73 65 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  se the [database
40b0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65   connection] spe
40c0: 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20  cified by.**    
40d0: 20 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65    the 1st parame
40e0: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
40f0: 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69  xec() while sqli
4100: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75  te3_exec() is ru
4110: 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e 20 54  nning..** <li> T
4120: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
4130: 75 73 74 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74  ust not modify t
4140: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
4150: 20 74 65 78 74 20 70 61 73 73 65 64 20 69 6e 74   text passed int
4160: 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 32 6e  o.**      the 2n
4170: 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73  d parameter of s
4180: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68  qlite3_exec() wh
4190: 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  ile sqlite3_exec
41a0: 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  () is running..*
41b0: 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69 6e 74 20 73  * </ul>.*/.int s
41c0: 71 6c 69 74 65 33 5f 65 78 65 63 28 0a 20 20 73  qlite3_exec(.  s
41d0: 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 20 20  qlite3*,        
41e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41f0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20            /* An 
4200: 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f  open database */
4210: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  .  const char *s
4220: 71 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  ql,             
4230: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
4240: 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75   SQL to be evalu
4250: 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  ated */.  int (*
4260: 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c  callback)(void*,
4270: 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a  int,char**,char*
4280: 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b  *),  /* Callback
4290: 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76   function */.  v
42a0: 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20  oid *,          
42b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
42c0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 31 73 74            /* 1st
42d0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c   argument to cal
42e0: 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72 20  lback */.  char 
42f0: 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20 20 20  **errmsg        
4300: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4310: 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d        /* Error m
4320: 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  sg written here 
4330: 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
4340: 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 43 6f  I3REF: Result Co
4350: 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  des.** KEYWORDS:
4360: 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 20 64 65   {result code de
4370: 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a  finitions}.**.**
4380: 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e   Many SQLite fun
4390: 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e  ctions return an
43a0: 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20   integer result 
43b0: 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65  code from the se
43c0: 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20  t shown.** here 
43d0: 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69  in order to indi
43e0: 63 61 74 65 20 73 75 63 63 65 73 73 20 6f 72 20  cate success or 
43f0: 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e  failure..**.** N
4400: 65 77 20 65 72 72 6f 72 20 63 6f 64 65 73 20 6d  ew error codes m
4410: 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
4420: 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
4430: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20  f SQLite..**.** 
4440: 53 65 65 20 61 6c 73 6f 3a 20 5b 65 78 74 65 6e  See also: [exten
4450: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20  ded result code 
4460: 64 65 66 69 6e 69 74 69 6f 6e 73 5d 0a 2a 2f 0a  definitions].*/.
4470: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
4480: 4b 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20  K           0   
4490: 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20 72 65  /* Successful re
44a0: 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e  sult */./* begin
44b0: 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f  ning-of-error-co
44c0: 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  des */.#define S
44d0: 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20 20 20  QLITE_ERROR     
44e0: 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20 65 72     1   /* SQL er
44f0: 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67 20 64  ror or missing d
4500: 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69  atabase */.#defi
4510: 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 4e  ne SQLITE_INTERN
4520: 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20 49 6e  AL     2   /* In
4530: 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65 72 72  ternal logic err
4540: 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a 2f 0a  or in SQLite */.
4550: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50  #define SQLITE_P
4560: 45 52 4d 20 20 20 20 20 20 20 20 20 33 20 20 20  ERM         3   
4570: 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d 69 73  /* Access permis
4580: 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23  sion denied */.#
4590: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42  define SQLITE_AB
45a0: 4f 52 54 20 20 20 20 20 20 20 20 34 20 20 20 2f  ORT        4   /
45b0: 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69  * Callback routi
45c0: 6e 65 20 72 65 71 75 65 73 74 65 64 20 61 6e 20  ne requested an 
45d0: 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69 6e 65  abort */.#define
45e0: 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 20   SQLITE_BUSY    
45f0: 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68 65 20       5   /* The 
4600: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73  database file is
4610: 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69   locked */.#defi
4620: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44  ne SQLITE_LOCKED
4630: 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20 41 20         6   /* A 
4640: 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64 61 74  table in the dat
4650: 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65 64 20  abase is locked 
4660: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4670: 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 37  E_NOMEM        7
4680: 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28 29     /* A malloc()
4690: 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65 66 69   failed */.#defi
46a0: 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e  ne SQLITE_READON
46b0: 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20 41 74  LY     8   /* At
46c0: 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65 20 61  tempt to write a
46d0: 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61 62 61   readonly databa
46e0: 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  se */.#define SQ
46f0: 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 20 20  LITE_INTERRUPT  
4700: 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61 74 69    9   /* Operati
4710: 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20 62 79  on terminated by
4720: 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
4730: 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65 20 53  pt()*/.#define S
4740: 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20 20 20  QLITE_IOERR     
4750: 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65 20 6b    10   /* Some k
4760: 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f 4f 20  ind of disk I/O 
4770: 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64 20 2a  error occurred *
4780: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4790: 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31 31 20  _CORRUPT     11 
47a0: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
47b0: 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69 73 20  e disk image is 
47c0: 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 64 65  malformed */.#de
47d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 46  fine SQLITE_NOTF
47e0: 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f 2a 20  OUND    12   /* 
47f0: 55 6e 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65 20 69  Unknown opcode i
4800: 6e 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63  n sqlite3_file_c
4810: 6f 6e 74 72 6f 6c 28 29 20 2a 2f 0a 23 64 65 66  ontrol() */.#def
4820: 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20  ine SQLITE_FULL 
4830: 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 49         13   /* I
4840: 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65 64 20  nsertion failed 
4850: 62 65 63 61 75 73 65 20 64 61 74 61 62 61 73 65  because database
4860: 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66   is full */.#def
4870: 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f  ine SQLITE_CANTO
4880: 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a 20 55  PEN    14   /* U
4890: 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68  nable to open th
48a0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
48b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
48c0: 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35  E_PROTOCOL    15
48d0: 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 6c     /* Database l
48e0: 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72  ock protocol err
48f0: 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  or */.#define SQ
4900: 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20 20 20  LITE_EMPTY      
4910: 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73   16   /* Databas
4920: 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64  e is empty */.#d
4930: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 43 48  efine SQLITE_SCH
4940: 45 4d 41 20 20 20 20 20 20 31 37 20 20 20 2f 2a  EMA      17   /*
4950: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 73 63   The database sc
4960: 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a  hema changed */.
4970: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
4980: 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20 20 20  OOBIG      18   
4990: 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f  /* String or BLO
49a0: 42 20 65 78 63 65 65 64 73 20 73 69 7a 65 20 6c  B exceeds size l
49b0: 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20  imit */.#define 
49c0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
49d0: 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f 72 74  T  19   /* Abort
49e0: 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 61 69   due to constrai
49f0: 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a  nt violation */.
4a00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
4a10: 49 53 4d 41 54 43 48 20 20 20 20 32 30 20 20 20  ISMATCH    20   
4a20: 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d 69 73  /* Data type mis
4a30: 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65  match */.#define
4a40: 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 20   SQLITE_MISUSE  
4a50: 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 62 72      21   /* Libr
4a60: 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72 72 65  ary used incorre
4a70: 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ctly */.#define 
4a80: 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20  SQLITE_NOLFS    
4a90: 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65 73 20     22   /* Uses 
4aa0: 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f 74 20  OS features not 
4ab0: 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73  supported on hos
4ac0: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
4ad0: 49 54 45 5f 41 55 54 48 20 20 20 20 20 20 20 20  ITE_AUTH        
4ae0: 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a  23   /* Authoriz
4af0: 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a  ation denied */.
4b00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
4b10: 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20 20 20  ORMAT      24   
4b20: 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64 61 74  /* Auxiliary dat
4b30: 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65 72 72  abase format err
4b40: 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  or */.#define SQ
4b50: 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20 20 20  LITE_RANGE      
4b60: 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70 61 72   25   /* 2nd par
4b70: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
4b80: 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20 72 61  3_bind out of ra
4b90: 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nge */.#define S
4ba0: 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20 20 20  QLITE_NOTADB    
4bb0: 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f    26   /* File o
4bc0: 70 65 6e 65 64 20 74 68 61 74 20 69 73 20 6e 6f  pened that is no
4bd0: 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  t a database fil
4be0: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
4bf0: 49 54 45 5f 4e 4f 54 49 43 45 20 20 20 20 20 20  ITE_NOTICE      
4c00: 32 37 20 20 20 2f 2a 20 4e 6f 74 69 66 69 63 61  27   /* Notifica
4c10: 74 69 6f 6e 73 20 66 72 6f 6d 20 73 71 6c 69 74  tions from sqlit
4c20: 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64 65 66  e3_log() */.#def
4c30: 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e 49  ine SQLITE_WARNI
4c40: 4e 47 20 20 20 20 20 32 38 20 20 20 2f 2a 20 57  NG     28   /* W
4c50: 61 72 6e 69 6e 67 73 20 66 72 6f 6d 20 73 71 6c  arnings from sql
4c60: 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64  ite3_log() */.#d
4c70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57  efine SQLITE_ROW
4c80: 20 20 20 20 20 20 20 20 20 31 30 30 20 20 2f 2a           100  /*
4c90: 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
4ca0: 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f 77 20  has another row 
4cb0: 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65  ready */.#define
4cc0: 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20   SQLITE_DONE    
4cd0: 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71 6c 69      101  /* sqli
4ce0: 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 66  te3_step() has f
4cf0: 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e  inished executin
4d00: 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65  g */./* end-of-e
4d10: 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f  rror-codes */../
4d20: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
4d30: 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43  xtended Result C
4d40: 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  odes.** KEYWORDS
4d50: 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75  : {extended resu
4d60: 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69  lt code definiti
4d70: 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74  ons}.**.** In it
4d80: 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67  s default config
4d90: 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20  uration, SQLite 
4da0: 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74  API routines ret
4db0: 75 72 6e 20 6f 6e 65 20 6f 66 20 33 30 20 69 6e  urn one of 30 in
4dc0: 74 65 67 65 72 0a 2a 2a 20 5b 72 65 73 75 6c 74  teger.** [result
4dd0: 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65   codes].  Howeve
4de0: 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 61  r, experience ha
4df0: 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e  s shown that man
4e00: 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65  y of.** these re
4e10: 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74  sult codes are t
4e20: 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65  oo coarse-graine
4e30: 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20  d.  They do not 
4e40: 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75  provide as.** mu
4e50: 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  ch information a
4e60: 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73  bout problems as
4e70: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
4e80: 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20  ht like.  In an 
4e90: 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64  effort to.** add
4ea0: 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72  ress this, newer
4eb0: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
4ec0: 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33  ite (version 3.3
4ed0: 2e 38 20 5b 64 61 74 65 6f 66 3a 33 2e 33 2e 38  .8 [dateof:3.3.8
4ee0: 5d 0a 2a 2a 20 61 6e 64 20 6c 61 74 65 72 29 20  ].** and later) 
4ef0: 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f  include.** suppo
4f00: 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  rt for additiona
4f10: 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 74  l result codes t
4f20: 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 65  hat provide more
4f30: 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d   detailed inform
4f40: 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65  ation.** about e
4f50: 72 72 6f 72 73 2e 20 54 68 65 73 65 20 5b 65 78  rrors. These [ex
4f60: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
4f70: 64 65 73 5d 20 61 72 65 20 65 6e 61 62 6c 65 64  des] are enabled
4f80: 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20   or disabled.** 
4f90: 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62 61 73  on a per databas
4fa0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73  e connection bas
4fb0: 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  is using the.** 
4fc0: 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65  [sqlite3_extende
4fd0: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
4fe0: 5d 20 41 50 49 2e 20 20 4f 72 2c 20 74 68 65 20  ] API.  Or, the 
4ff0: 65 78 74 65 6e 64 65 64 20 63 6f 64 65 20 66 6f  extended code fo
5000: 72 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20 72 65  r.** the most re
5010: 63 65 6e 74 20 65 72 72 6f 72 20 63 61 6e 20 62  cent error can b
5020: 65 20 6f 62 74 61 69 6e 65 64 20 75 73 69 6e 67  e obtained using
5030: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74  .** [sqlite3_ext
5040: 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 5d  ended_errcode()]
5050: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
5060: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20  ITE_IOERR_READ  
5070: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5080: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c  ITE_IOERR | (1<<
5090: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
50a0: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
50b0: 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  EAD        (SQLI
50c0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38  TE_IOERR | (2<<8
50d0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
50e0: 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20  E_IOERR_WRITE   
50f0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5100: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29  E_IOERR | (3<<8)
5110: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5120: 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20  _IOERR_FSYNC    
5130: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5140: 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29  _IOERR | (4<<8))
5150: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5160: 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20  IOERR_DIR_FSYNC 
5170: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5180: 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a  IOERR | (5<<8)).
5190: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
51a0: 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20  OERR_TRUNCATE   
51b0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
51c0: 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23  OERR | (6<<8)).#
51d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
51e0: 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20  ERR_FSTAT       
51f0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5200: 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64  ERR | (7<<8)).#d
5210: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5220: 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20  RR_UNLOCK       
5230: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5240: 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65  RR | (8<<8)).#de
5250: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5260: 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_RDLOCK        
5270: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5280: 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66  R | (9<<8)).#def
5290: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
52a0: 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
52b0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
52c0: 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66   | (10<<8)).#def
52d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
52e0: 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20  _BLOCKED        
52f0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5300: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66   | (11<<8)).#def
5310: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5320: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20  _NOMEM          
5330: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5340: 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66   | (12<<8)).#def
5350: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5360: 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20  _ACCESS         
5370: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5380: 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66   | (13<<8)).#def
5390: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
53a0: 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f  _CHECKRESERVEDLO
53b0: 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52  CK (SQLITE_IOERR
53c0: 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66   | (14<<8)).#def
53d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
53e0: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  _LOCK           
53f0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5400: 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66   | (15<<8)).#def
5410: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5420: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20  _CLOSE          
5430: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5440: 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66   | (16<<8)).#def
5450: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5460: 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20  _DIR_CLOSE      
5470: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5480: 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66   | (17<<8)).#def
5490: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
54a0: 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20  _SHMOPEN        
54b0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
54c0: 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66   | (18<<8)).#def
54d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
54e0: 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20  _SHMSIZE        
54f0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5500: 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66   | (19<<8)).#def
5510: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5520: 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20  _SHMLOCK        
5530: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5540: 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66   | (20<<8)).#def
5550: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5560: 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20  _SHMMAP         
5570: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5580: 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66   | (21<<8)).#def
5590: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
55a0: 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20  _SEEK           
55b0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
55c0: 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66   | (22<<8)).#def
55d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
55e0: 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20  _DELETE_NOENT   
55f0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5600: 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66   | (23<<8)).#def
5610: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5620: 5f 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20  _MMAP           
5630: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5640: 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66   | (24<<8)).#def
5650: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5660: 5f 47 45 54 54 45 4d 50 50 41 54 48 20 20 20 20  _GETTEMPPATH    
5670: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5680: 20 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66   | (25<<8)).#def
5690: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
56a0: 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20  _CONVPATH       
56b0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
56c0: 20 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66   | (26<<8)).#def
56d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
56e0: 5f 56 4e 4f 44 45 20 20 20 20 20 20 20 20 20 20  _VNODE          
56f0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5700: 20 7c 20 28 32 37 3c 3c 38 29 29 0a 23 64 65 66   | (27<<8)).#def
5710: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5720: 5f 41 55 54 48 20 20 20 20 20 20 20 20 20 20 20  _AUTH           
5730: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5740: 20 7c 20 28 32 38 3c 3c 38 29 29 0a 23 64 65 66   | (28<<8)).#def
5750: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
5760: 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20  D_SHAREDCACHE   
5770: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45     (SQLITE_LOCKE
5780: 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65  D |  (1<<8)).#de
5790: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
57a0: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20  _RECOVERY       
57b0: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
57c0: 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64     |  (1<<8)).#d
57d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
57e0: 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20 20  Y_SNAPSHOT      
57f0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53       (SQLITE_BUS
5800: 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23  Y   |  (2<<8)).#
5810: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
5820: 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52  NTOPEN_NOTEMPDIR
5830: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
5840: 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29  NTOPEN | (1<<8))
5850: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5860: 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20  CANTOPEN_ISDIR  
5870: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5880: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38  CANTOPEN | (2<<8
5890: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
58a0: 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50  E_CANTOPEN_FULLP
58b0: 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54  ATH       (SQLIT
58c0: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c  E_CANTOPEN | (3<
58d0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
58e0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e  ITE_CANTOPEN_CON
58f0: 56 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c  VPATH       (SQL
5900: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
5910: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
5920: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54  QLITE_CORRUPT_VT
5930: 41 42 20 20 20 20 20 20 20 20 20 20 20 20 28 53  AB            (S
5940: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20  QLITE_CORRUPT | 
5950: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
5960: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f  SQLITE_READONLY_
5970: 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 28  RECOVERY       (
5980: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
5990: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
59a0: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
59b0: 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20  Y_CANTLOCK      
59c0: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   (SQLITE_READONL
59d0: 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  Y | (2<<8)).#def
59e0: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
59f0: 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20  NLY_ROLLBACK    
5a00: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f     (SQLITE_READO
5a10: 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64  NLY | (3<<8)).#d
5a20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
5a30: 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20 20 20  DONLY_DBMOVED   
5a40: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
5a50: 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29 29 0a  DONLY | (4<<8)).
5a60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
5a70: 42 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20  BORT_ROLLBACK   
5a80: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41         (SQLITE_A
5a90: 42 4f 52 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23  BORT | (2<<8)).#
5aa0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5ab0: 4e 53 54 52 41 49 4e 54 5f 43 48 45 43 4b 20 20  NSTRAINT_CHECK  
5ac0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5ad0: 4e 53 54 52 41 49 4e 54 20 7c 20 28 31 3c 3c 38  NSTRAINT | (1<<8
5ae0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5af0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 4f 4d  E_CONSTRAINT_COM
5b00: 4d 49 54 48 4f 4f 4b 20 20 20 28 53 51 4c 49 54  MITHOOK   (SQLIT
5b10: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5b20: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
5b30: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5b40: 5f 46 4f 52 45 49 47 4e 4b 45 59 20 20 20 28 53  _FOREIGNKEY   (S
5b50: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5b60: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69   | (3<<8)).#defi
5b70: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5b80: 41 49 4e 54 5f 46 55 4e 43 54 49 4f 4e 20 20 20  AINT_FUNCTION   
5b90: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5ba0: 41 49 4e 54 20 7c 20 28 34 3c 3c 38 29 29 0a 23  AINT | (4<<8)).#
5bb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5bc0: 4e 53 54 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c  NSTRAINT_NOTNULL
5bd0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5be0: 4e 53 54 52 41 49 4e 54 20 7c 20 28 35 3c 3c 38  NSTRAINT | (5<<8
5bf0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5c00: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 50 52 49  E_CONSTRAINT_PRI
5c10: 4d 41 52 59 4b 45 59 20 20 20 28 53 51 4c 49 54  MARYKEY   (SQLIT
5c20: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5c30: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
5c40: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5c50: 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 28 53  _TRIGGER      (S
5c60: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5c70: 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69   | (7<<8)).#defi
5c80: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5c90: 41 49 4e 54 5f 55 4e 49 51 55 45 20 20 20 20 20  AINT_UNIQUE     
5ca0: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5cb0: 41 49 4e 54 20 7c 20 28 38 3c 3c 38 29 29 0a 23  AINT | (8<<8)).#
5cc0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5cd0: 4e 53 54 52 41 49 4e 54 5f 56 54 41 42 20 20 20  NSTRAINT_VTAB   
5ce0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5cf0: 4e 53 54 52 41 49 4e 54 20 7c 20 28 39 3c 3c 38  NSTRAINT | (9<<8
5d00: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5d10: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 52 4f 57  E_CONSTRAINT_ROW
5d20: 49 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  ID        (SQLIT
5d30: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 28 31  E_CONSTRAINT |(1
5d40: 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  0<<8)).#define S
5d50: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43  QLITE_NOTICE_REC
5d60: 4f 56 45 52 5f 57 41 4c 20 20 20 20 20 20 28 53  OVER_WAL      (S
5d70: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28  QLITE_NOTICE | (
5d80: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5d90: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43  QLITE_NOTICE_REC
5da0: 4f 56 45 52 5f 52 4f 4c 4c 42 41 43 4b 20 28 53  OVER_ROLLBACK (S
5db0: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28  QLITE_NOTICE | (
5dc0: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
5dd0: 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 5f 41 55  QLITE_WARNING_AU
5de0: 54 4f 49 4e 44 45 58 20 20 20 20 20 20 20 28 53  TOINDEX       (S
5df0: 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 7c 20  QLITE_WARNING | 
5e00: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
5e10: 53 51 4c 49 54 45 5f 41 55 54 48 5f 55 53 45 52  SQLITE_AUTH_USER
5e20: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28                 (
5e30: 53 51 4c 49 54 45 5f 41 55 54 48 20 7c 20 28 31  SQLITE_AUTH | (1
5e40: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5e50: 4c 49 54 45 5f 4f 4b 5f 4c 4f 41 44 5f 50 45 52  LITE_OK_LOAD_PER
5e60: 4d 41 4e 45 4e 54 4c 59 20 20 20 20 20 28 53 51  MANENTLY     (SQ
5e70: 4c 49 54 45 5f 4f 4b 20 7c 20 28 31 3c 3c 38 29  LITE_OK | (1<<8)
5e80: 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  )../*.** CAPI3RE
5e90: 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69 6c  F: Flags For Fil
5ea0: 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e  e Open Operation
5eb0: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69  s.**.** These bi
5ec0: 74 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 74  t values are int
5ed0: 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e  ended for use in
5ee0: 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72 61   the.** 3rd para
5ef0: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  meter to the [sq
5f00: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
5f10: 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a 2a   interface and.*
5f20: 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70 61 72  * in the 4th par
5f30: 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ameter to the [s
5f40: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
5f50: 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23 64 65  ] method..*/.#de
5f60: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5f70: 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20  _READONLY       
5f80: 20 20 30 78 30 30 30 30 30 30 30 31 20 20 2f 2a    0x00000001  /*
5f90: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
5fa0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
5fb0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5fc0: 5f 52 45 41 44 57 52 49 54 45 20 20 20 20 20 20  _READWRITE      
5fd0: 20 20 30 78 30 30 30 30 30 30 30 32 20 20 2f 2a    0x00000002  /*
5fe0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
5ff0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
6000: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6010: 5f 43 52 45 41 54 45 20 20 20 20 20 20 20 20 20  _CREATE         
6020: 20 20 30 78 30 30 30 30 30 30 30 34 20 20 2f 2a    0x00000004  /*
6030: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
6040: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
6050: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6060: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20  _DELETEONCLOSE  
6070: 20 20 30 78 30 30 30 30 30 30 30 38 20 20 2f 2a    0x00000008  /*
6080: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6090: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
60a0: 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 20  _EXCLUSIVE      
60b0: 20 20 30 78 30 30 30 30 30 30 31 30 20 20 2f 2a    0x00000010  /*
60c0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
60d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
60e0: 5f 41 55 54 4f 50 52 4f 58 59 20 20 20 20 20 20  _AUTOPROXY      
60f0: 20 20 30 78 30 30 30 30 30 30 32 30 20 20 2f 2a    0x00000020  /*
6100: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6110: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6120: 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 20 20  _URI            
6130: 20 20 30 78 30 30 30 30 30 30 34 30 20 20 2f 2a    0x00000040  /*
6140: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
6150: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
6160: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6170: 5f 4d 45 4d 4f 52 59 20 20 20 20 20 20 20 20 20  _MEMORY         
6180: 20 20 30 78 30 30 30 30 30 30 38 30 20 20 2f 2a    0x00000080  /*
6190: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
61a0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
61b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
61c0: 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20  _MAIN_DB        
61d0: 20 20 30 78 30 30 30 30 30 31 30 30 20 20 2f 2a    0x00000100  /*
61e0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
61f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6200: 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20  _TEMP_DB        
6210: 20 20 30 78 30 30 30 30 30 32 30 30 20 20 2f 2a    0x00000200  /*
6220: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6230: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6240: 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20  _TRANSIENT_DB   
6250: 20 20 30 78 30 30 30 30 30 34 30 30 20 20 2f 2a    0x00000400  /*
6260: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6270: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6280: 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20  _MAIN_JOURNAL   
6290: 20 20 30 78 30 30 30 30 30 38 30 30 20 20 2f 2a    0x00000800  /*
62a0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
62b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
62c0: 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20  _TEMP_JOURNAL   
62d0: 20 20 30 78 30 30 30 30 31 30 30 30 20 20 2f 2a    0x00001000  /*
62e0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
62f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6300: 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20  _SUBJOURNAL     
6310: 20 20 30 78 30 30 30 30 32 30 30 30 20 20 2f 2a    0x00002000  /*
6320: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6330: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6340: 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20  _MASTER_JOURNAL 
6350: 20 20 30 78 30 30 30 30 34 30 30 30 20 20 2f 2a    0x00004000  /*
6360: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6370: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6380: 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20  _NOMUTEX        
6390: 20 20 30 78 30 30 30 30 38 30 30 30 20 20 2f 2a    0x00008000  /*
63a0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
63b0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
63c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
63d0: 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20  _FULLMUTEX      
63e0: 20 20 30 78 30 30 30 31 30 30 30 30 20 20 2f 2a    0x00010000  /*
63f0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
6400: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
6410: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6420: 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20  _SHAREDCACHE    
6430: 20 20 30 78 30 30 30 32 30 30 30 30 20 20 2f 2a    0x00020000  /*
6440: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
6450: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
6460: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6470: 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 20 20  _PRIVATECACHE   
6480: 20 20 30 78 30 30 30 34 30 30 30 30 20 20 2f 2a    0x00040000  /*
6490: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
64a0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
64b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
64c0: 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20  _WAL            
64d0: 20 20 30 78 30 30 30 38 30 30 30 30 20 20 2f 2a    0x00080000  /*
64e0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a   VFS only */../*
64f0: 20 52 65 73 65 72 76 65 64 3a 20 20 20 20 20 20   Reserved:      
6500: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6510: 20 20 20 30 78 30 30 46 30 30 30 30 30 20 2a 2f     0x00F00000 */
6520: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
6530: 3a 20 44 65 76 69 63 65 20 43 68 61 72 61 63 74  : Device Charact
6540: 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54  eristics.**.** T
6550: 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63  he xDeviceCharac
6560: 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64  teristics method
6570: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
6580: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  _io_methods].** 
6590: 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73 20 61  object returns a
65a0: 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
65b0: 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66 20 74  is a vector of t
65c0: 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75  hese.** bit valu
65d0: 65 73 20 65 78 70 72 65 73 73 69 6e 67 20 49 2f  es expressing I/
65e0: 4f 20 63 68 61 72 61 63 74 65 72 69 73 74 69 63  O characteristic
65f0: 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73 74  s of the mass st
6600: 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 20  orage.** device 
6610: 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20 66  that holds the f
6620: 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73 71  ile that the [sq
6630: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
6640: 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a  ].** refers to..
6650: 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  **.** The SQLITE
6660: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72  _IOCAP_ATOMIC pr
6670: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
6680: 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a  t all writes of.
6690: 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20  ** any size are 
66a0: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
66b0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
66c0: 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65  nnn values.** me
66d0: 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f  an that writes o
66e0: 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72  f blocks that ar
66f0: 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73  e nnn bytes in s
6700: 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61  ize and.** are a
6710: 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64  ligned to an add
6720: 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e  ress which is an
6730: 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c   integer multipl
6740: 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20  e of.** nnn are 
6750: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
6760: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
6770: 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e  PPEND value mean
6780: 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64  s.** that when d
6790: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20  ata is appended 
67a0: 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64  to a file, the d
67b0: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a  ata is appended.
67c0: 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68  ** first then th
67d0: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69  e size of the fi
67e0: 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20  le is extended, 
67f0: 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a  never the other.
6800: 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20  ** way around.  
6810: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
6820: 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70  _SEQUENTIAL prop
6830: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a  erty means that.
6840: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ** information i
6850: 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73  s written to dis
6860: 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72  k in the same or
6870: 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20  der as calls.** 
6880: 74 6f 20 78 57 72 69 74 65 28 29 2e 20 20 54 68  to xWrite().  Th
6890: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50  e SQLITE_IOCAP_P
68a0: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
68b0: 54 45 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  TE property mean
68c0: 73 20 74 68 61 74 0a 2a 2a 20 61 66 74 65 72 20  s that.** after 
68d0: 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77 69 6e 67  reboot following
68e0: 20 61 20 63 72 61 73 68 20 6f 72 20 70 6f 77 65   a crash or powe
68f0: 72 20 6c 6f 73 73 2c 20 74 68 65 20 6f 6e 6c 79  r loss, the only
6900: 20 62 79 74 65 73 20 69 6e 20 61 0a 2a 2a 20 66   bytes in a.** f
6910: 69 6c 65 20 74 68 61 74 20 77 65 72 65 20 77 72  ile that were wr
6920: 69 74 74 65 6e 20 61 74 20 74 68 65 20 61 70 70  itten at the app
6930: 6c 69 63 61 74 69 6f 6e 20 6c 65 76 65 6c 20 6d  lication level m
6940: 69 67 68 74 20 68 61 76 65 20 63 68 61 6e 67 65  ight have change
6950: 64 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 61 64  d.** and that ad
6960: 6a 61 63 65 6e 74 20 62 79 74 65 73 2c 20 65 76  jacent bytes, ev
6970: 65 6e 20 62 79 74 65 73 20 77 69 74 68 69 6e 20  en bytes within 
6980: 74 68 65 20 73 61 6d 65 20 73 65 63 74 6f 72 20  the same sector 
6990: 61 72 65 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65  are.** guarantee
69a0: 64 20 74 6f 20 62 65 20 75 6e 63 68 61 6e 67 65  d to be unchange
69b0: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  d.  The SQLITE_I
69c0: 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45  OCAP_UNDELETABLE
69d0: 5f 57 48 45 4e 5f 4f 50 45 4e 0a 2a 2a 20 66 6c  _WHEN_OPEN.** fl
69e0: 61 67 20 69 6e 64 69 63 61 74 65 73 20 74 68 61  ag indicates tha
69f0: 74 20 61 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20  t a file cannot 
6a00: 62 65 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  be deleted when 
6a10: 6f 70 65 6e 2e 20 20 54 68 65 0a 2a 2a 20 53 51  open.  The.** SQ
6a20: 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54  LITE_IOCAP_IMMUT
6a30: 41 42 4c 45 20 66 6c 61 67 20 69 6e 64 69 63 61  ABLE flag indica
6a40: 74 65 73 20 74 68 61 74 20 74 68 65 20 66 69 6c  tes that the fil
6a50: 65 20 69 73 20 6f 6e 0a 2a 2a 20 72 65 61 64 2d  e is on.** read-
6a60: 6f 6e 6c 79 20 6d 65 64 69 61 20 61 6e 64 20 63  only media and c
6a70: 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64  annot be changed
6a80: 20 65 76 65 6e 20 62 79 20 70 72 6f 63 65 73 73   even by process
6a90: 65 73 20 77 69 74 68 0a 2a 2a 20 65 6c 65 76 61  es with.** eleva
6aa0: 74 65 64 20 70 72 69 76 69 6c 65 67 65 73 2e 0a  ted privileges..
6ab0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6ac0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20  E_IOCAP_ATOMIC  
6ad0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
6ae0: 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e  x00000001.#defin
6af0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6b00: 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20 20  TOMIC512        
6b10: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32        0x00000002
6b20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6b30: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20  IOCAP_ATOMIC1K  
6b40: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6b50: 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20  0000004.#define 
6b60: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6b70: 4d 49 43 32 4b 20 20 20 20 20 20 20 20 20 20 20  MIC2K           
6b80: 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0a 23      0x00000008.#
6b90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6ba0: 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20  CAP_ATOMIC4K    
6bb0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6bc0: 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51  00010.#define SQ
6bd0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6be0: 43 38 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  C8K             
6bf0: 20 20 30 78 30 30 30 30 30 30 32 30 0a 23 64 65    0x00000020.#de
6c00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6c10: 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20  P_ATOMIC16K     
6c20: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6c30: 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  040.#define SQLI
6c40: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33  TE_IOCAP_ATOMIC3
6c50: 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  2K              
6c60: 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 69  0x00000080.#defi
6c70: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6c80: 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20  ATOMIC64K       
6c90: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30         0x0000010
6ca0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6cb0: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45  _IOCAP_SAFE_APPE
6cc0: 4e 44 20 20 20 20 20 20 20 20 20 20 20 20 30 78  ND            0x
6cd0: 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65  00000200.#define
6ce0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45   SQLITE_IOCAP_SE
6cf0: 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20 20 20  QUENTIAL        
6d00: 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 0a       0x00000400.
6d10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6d20: 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45  OCAP_UNDELETABLE
6d30: 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30  _WHEN_OPEN  0x00
6d40: 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53  000800.#define S
6d50: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45  QLITE_IOCAP_POWE
6d60: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20  RSAFE_OVERWRITE 
6d70: 20 20 20 30 78 30 30 30 30 31 30 30 30 0a 23 64     0x00001000.#d
6d80: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6d90: 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 20 20 20  AP_IMMUTABLE    
6da0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6db0: 32 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  2000../*.** CAPI
6dc0: 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69  3REF: File Locki
6dd0: 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20  ng Levels.**.** 
6de0: 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20  SQLite uses one 
6df0: 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72  of these integer
6e00: 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73   values as the s
6e10: 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e  econd.** argumen
6e20: 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61  t to calls it ma
6e30: 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b  kes to the xLock
6e40: 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29  () and xUnlock()
6e50: 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61   methods.** of a
6e60: 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  n [sqlite3_io_me
6e70: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a  thods] object..*
6e80: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6e90: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20  _LOCK_NONE      
6ea0: 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
6eb0: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
6ec0: 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
6ed0: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45  e SQLITE_LOCK_RE
6ee0: 53 45 52 56 45 44 20 20 20 20 20 20 32 0a 23 64  SERVED      2.#d
6ef0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
6f00: 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20  K_PENDING       
6f10: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
6f20: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20  _LOCK_EXCLUSIVE 
6f30: 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      4../*.** CAP
6f40: 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69  I3REF: Synchroni
6f50: 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67  zation Type Flag
6f60: 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c  s.**.** When SQL
6f70: 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20  ite invokes the 
6f80: 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f  xSync() method o
6f90: 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  f an.** [sqlite3
6fa0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
6fb0: 65 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f  ect it uses a co
6fc0: 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20  mbination of.** 
6fd0: 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61  these integer va
6fe0: 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f  lues as the seco
6ff0: 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  nd argument..**.
7000: 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49  ** When the SQLI
7010: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
7020: 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69   flag is used, i
7030: 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  t means that the
7040: 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69  .** sync operati
7050: 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f  on only needs to
7060: 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d   flush data to m
7070: 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e  ass storage.  In
7080: 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  ode.** informati
7090: 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66  on need not be f
70a0: 6c 75 73 68 65 64 2e 20 49 66 20 74 68 65 20 6c  lushed. If the l
70b0: 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 6f  ower four bits o
70c0: 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71  f the flag.** eq
70d0: 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ual SQLITE_SYNC_
70e0: 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61  NORMAL, that mea
70f0: 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c  ns to use normal
7100: 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69   fsync() semanti
7110: 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f  cs..** If the lo
7120: 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 65 71  wer four bits eq
7130: 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ual SQLITE_SYNC_
7140: 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73  FULL, that means
7150: 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f  .** to use Mac O
7160: 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79  S X style fullsy
7170: 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73  nc instead of fs
7180: 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20  ync()..**.** Do 
7190: 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74 68 65 20  not confuse the 
71a0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
71b0: 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59  AL and SQLITE_SY
71c0: 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a  NC_FULL flags.**
71d0: 20 77 69 74 68 20 74 68 65 20 5b 50 52 41 47 4d   with the [PRAGM
71e0: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e  A synchronous]=N
71f0: 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47 4d  ORMAL and [PRAGM
7200: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46  A synchronous]=F
7210: 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73 2e  ULL.** settings.
7220: 20 20 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e 6f    The [synchrono
7230: 75 73 20 70 72 61 67 6d 61 5d 20 64 65 74 65 72  us pragma] deter
7240: 6d 69 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c 73  mines when calls
7250: 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e 63   to the.** xSync
7260: 20 56 46 53 20 6d 65 74 68 6f 64 20 6f 63 63 75   VFS method occu
7270: 72 20 61 6e 64 20 61 70 70 6c 69 65 73 20 75 6e  r and applies un
7280: 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20 61  iformly across a
7290: 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a  ll platforms..**
72a0: 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   The SQLITE_SYNC
72b0: 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49  _NORMAL and SQLI
72c0: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61  TE_SYNC_FULL fla
72d0: 67 73 20 64 65 74 65 72 6d 69 6e 65 20 68 6f 77  gs determine how
72e0: 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63 20 6f 72  .** energetic or
72f0: 20 72 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f 72   rigorous or for
7300: 63 65 66 75 6c 20 74 68 65 20 73 79 6e 63 20 6f  ceful the sync o
7310: 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20 61 6e  perations are an
7320: 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 61  d.** only make a
7330: 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 20 4d   difference on M
7340: 61 63 20 4f 53 58 20 66 6f 72 20 74 68 65 20 64  ac OSX for the d
7350: 65 66 61 75 6c 74 20 53 51 4c 69 74 65 20 63 6f  efault SQLite co
7360: 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70 61  de..** (Third-pa
7370: 72 74 79 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  rty VFS implemen
7380: 74 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 61 6c  tations might al
7390: 73 6f 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74  so make the dist
73a0: 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65  inction.** betwe
73b0: 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  en SQLITE_SYNC_N
73c0: 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45  ORMAL and SQLITE
73d0: 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 20  _SYNC_FULL, but 
73e0: 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 65  among the.** ope
73f0: 72 61 74 69 6e 67 20 73 79 73 74 65 6d 73 20 6e  rating systems n
7400: 61 74 69 76 65 6c 79 20 73 75 70 70 6f 72 74 65  atively supporte
7410: 64 20 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e 6c  d by SQLite, onl
7420: 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61 72  y Mac OSX.** car
7430: 65 73 20 61 62 6f 75 74 20 74 68 65 20 64 69 66  es about the dif
7440: 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65  ference.).*/.#de
7450: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43  fine SQLITE_SYNC
7460: 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30  _NORMAL        0
7470: 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53  x00002.#define S
7480: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
7490: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 33           0x00003
74a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
74b0: 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20  SYNC_DATAONLY   
74c0: 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a     0x00010../*.*
74d0: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49  * CAPI3REF: OS I
74e0: 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69  nterface Open Fi
74f0: 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20  le Handle.**.** 
7500: 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  An [sqlite3_file
7510: 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65  ] object represe
7520: 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  nts an open file
7530: 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c   in the .** [sql
7540: 69 74 65 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e  ite3_vfs | OS in
7550: 74 65 72 66 61 63 65 20 6c 61 79 65 72 5d 2e 20  terface layer]. 
7560: 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69   Individual OS i
7570: 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c  nterface.** impl
7580: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c  ementations will
7590: 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63  .** want to subc
75a0: 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74  lass this object
75b0: 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64   by appending ad
75c0: 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a  ditional fields.
75d0: 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e  ** for their own
75e0: 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68   use.  The pMeth
75f0: 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61 20 70  ods entry is a p
7600: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
7610: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
7620: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74  ods] object that
7630: 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73   defines methods
7640: 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a   for performing.
7650: 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e  ** I/O operation
7660: 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69  s on the open fi
7670: 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  le..*/.typedef s
7680: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69  truct sqlite3_fi
7690: 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b  le sqlite3_file;
76a0: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
76b0: 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73  file {.  const s
76c0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
76d0: 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f  _methods *pMetho
76e0: 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  ds;  /* Methods 
76f0: 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  for an open file
7700: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
7710: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
7720: 66 61 63 65 20 46 69 6c 65 20 56 69 72 74 75 61  face File Virtua
7730: 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74  l Methods Object
7740: 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c  .**.** Every fil
7750: 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20  e opened by the 
7760: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
7770: 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c  en] method popul
7780: 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  ates an.** [sqli
7790: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
77a0: 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f   (or, more commo
77b0: 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73 20  nly, a subclass 
77c0: 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
77d0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29  e3_file] object)
77e0: 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20   with a pointer 
77f0: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
7800: 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a  f this object..*
7810: 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65  * This object de
7820: 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f 64  fines the method
7830: 73 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72  s used to perfor
7840: 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74  m various operat
7850: 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20  ions.** against 
7860: 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 65  the open file re
7870: 70 72 65 73 65 6e 74 65 64 20 62 79 20 74 68 65  presented by the
7880: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
7890: 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66  object..**.** If
78a0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
78b0: 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20  s.xOpen] method 
78c0: 73 65 74 73 20 74 68 65 20 73 71 6c 69 74 65 33  sets the sqlite3
78d0: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65  _file.pMethods e
78e0: 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 20  lement .** to a 
78f0: 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  non-NULL pointer
7900: 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74  , then the sqlit
7910: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 43  e3_io_methods.xC
7920: 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d  lose method.** m
7930: 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 76  ay be invoked ev
7940: 65 6e 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74  en if the [sqlit
7950: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 72 65  e3_vfs.xOpen] re
7960: 70 6f 72 74 65 64 20 74 68 61 74 20 69 74 20 66  ported that it f
7970: 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f  ailed.  The.** o
7980: 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 65 76 65  nly way to preve
7990: 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c  nt a call to xCl
79a0: 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  ose following a 
79b0: 66 61 69 6c 65 64 20 5b 73 71 6c 69 74 65 33 5f  failed [sqlite3_
79c0: 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73  vfs.xOpen].** is
79d0: 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65   for the [sqlite
79e0: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74 6f 20  3_vfs.xOpen] to 
79f0: 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f  set the sqlite3_
7a00: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c  file.pMethods el
7a10: 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c  ement.** to NULL
7a20: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67  ..**.** The flag
7a30: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53  s argument to xS
7a40: 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f  ync may be one o
7a50: 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  f [SQLITE_SYNC_N
7a60: 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51  ORMAL] or.** [SQ
7a70: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e  LITE_SYNC_FULL].
7a80: 20 20 54 68 65 20 66 69 72 73 74 20 63 68 6f 69    The first choi
7a90: 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c  ce is the normal
7aa0: 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65   fsync()..** The
7ab0: 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69   second choice i
7ac0: 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73 74 79  s a Mac OS X sty
7ad0: 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68  le fullsync.  Th
7ae0: 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  e [SQLITE_SYNC_D
7af0: 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67  ATAONLY].** flag
7b00: 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20   may be ORed in 
7b10: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  to indicate that
7b20: 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f   only the data o
7b30: 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e  f the file.** an
7b40: 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20  d not its inode 
7b50: 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63  needs to be sync
7b60: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  ed..**.** The in
7b70: 74 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20  teger values to 
7b80: 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c  xLock() and xUnl
7b90: 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66  ock() are one of
7ba0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
7bb0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f   [SQLITE_LOCK_NO
7bc0: 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  NE],.** <li> [SQ
7bd0: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
7be0: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
7bf0: 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44  TE_LOCK_RESERVED
7c00: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
7c10: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d  TE_LOCK_PENDING]
7c20: 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  , or.** <li> [SQ
7c30: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53  LITE_LOCK_EXCLUS
7c40: 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  IVE]..** </ul>.*
7c50: 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61  * xLock() increa
7c60: 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55  ses the lock. xU
7c70: 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65  nlock() decrease
7c80: 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54  s the lock..** T
7c90: 68 65 20 78 43 68 65 63 6b 52 65 73 65 72 76 65  he xCheckReserve
7ca0: 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63  dLock() method c
7cb0: 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e  hecks whether an
7cc0: 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  y database conne
7cd0: 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72  ction,.** either
7ce0: 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73   in this process
7cf0: 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65   or in some othe
7d00: 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f  r process, is ho
7d10: 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56 45 44  lding a RESERVED
7d20: 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72  ,.** PENDING, or
7d30: 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20   EXCLUSIVE lock 
7d40: 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74  on the file.  It
7d50: 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a   returns true.**
7d60: 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20   if such a lock 
7d70: 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65  exists and false
7d80: 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a   otherwise..**.*
7d90: 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  * The xFileContr
7da0: 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61  ol() method is a
7db0: 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61   generic interfa
7dc0: 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63  ce that allows c
7dd0: 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70  ustom.** VFS imp
7de0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20  lementations to 
7df0: 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c  directly control
7e00: 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73   an open file us
7e10: 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ing the.** [sqli
7e20: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
7e30: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ()] interface.  
7e40: 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20  The second "op" 
7e50: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a  argument is an.*
7e60: 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65  * integer opcode
7e70: 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67  .  The third arg
7e80: 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72  ument is a gener
7e90: 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e  ic pointer inten
7ea0: 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20  ded to.** point 
7eb0: 74 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 74  to a structure t
7ec0: 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20  hat may contain 
7ed0: 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61  arguments or spa
7ee0: 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a  ce in which to.*
7ef0: 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 76  * write return v
7f00: 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61  alues.  Potentia
7f10: 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65  l uses for xFile
7f20: 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20  Control() might 
7f30: 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  be.** functions 
7f40: 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69  to enable blocki
7f50: 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69  ng locks with ti
7f60: 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67  meouts, to chang
7f70: 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67  e the.** locking
7f80: 20 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 65   strategy (for e
7f90: 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f  xample to use do
7fa0: 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74  t-file locks), t
7fb0: 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f  o inquire.** abo
7fc0: 75 74 20 74 68 65 20 73 74 61 74 75 73 20 6f 66  ut the status of
7fd0: 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62   a lock, or to b
7fe0: 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73  reak stale locks
7ff0: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a  .  The SQLite.**
8000: 20 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 61   core reserves a
8010: 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20  ll opcodes less 
8020: 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73  than 100 for its
8030: 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b   own use..** A [
8040: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63  file control opc
8050: 6f 64 65 73 20 7c 20 6c 69 73 74 20 6f 66 20 6f  odes | list of o
8060: 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61  pcodes] less tha
8070: 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c 61 62  n 100 is availab
8080: 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  le..** Applicati
8090: 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65 20  ons that define 
80a0: 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f  a custom xFileCo
80b0: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f  ntrol method sho
80c0: 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73 0a  uld use opcodes.
80d0: 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  ** greater than 
80e0: 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e  100 to avoid con
80f0: 66 6c 69 63 74 73 2e 20 20 56 46 53 20 69 6d 70  flicts.  VFS imp
8100: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f  lementations sho
8110: 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  uld.** return [S
8120: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20  QLITE_NOTFOUND] 
8130: 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  for file control
8140: 20 6f 70 63 6f 64 65 73 20 74 68 61 74 20 74 68   opcodes that th
8150: 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63  ey do not.** rec
8160: 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  ognize..**.** Th
8170: 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29 20  e xSectorSize() 
8180: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 74  method returns t
8190: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 6f  he sector size o
81a0: 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 20  f the.** device 
81b0: 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20 74  that underlies t
81c0: 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73 65  he file.  The se
81d0: 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68 65  ctor size is the
81e0: 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74  .** minimum writ
81f0: 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 65  e that can be pe
8200: 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 20  rformed without 
8210: 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74  disturbing.** ot
8220: 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68 65  her bytes in the
8230: 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65 76   file.  The xDev
8240: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
8250: 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72  cs().** method r
8260: 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65 63  eturns a bit vec
8270: 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20 62  tor describing b
8280: 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65 0a  ehaviors of the.
8290: 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 65  ** underlying de
82a0: 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  vice:.**.** <ul>
82b0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
82c0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a  _IOCAP_ATOMIC].*
82d0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
82e0: 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a  OCAP_ATOMIC512].
82f0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8300: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a  IOCAP_ATOMIC1K].
8310: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8320: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a  IOCAP_ATOMIC2K].
8330: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8340: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a  IOCAP_ATOMIC4K].
8350: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8360: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a  IOCAP_ATOMIC8K].
8370: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8380: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d  IOCAP_ATOMIC16K]
8390: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
83a0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b  _IOCAP_ATOMIC32K
83b0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
83c0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34  E_IOCAP_ATOMIC64
83d0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
83e0: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
83f0: 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  PEND].** <li> [S
8400: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
8410: 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  ENTIAL].** <li> 
8420: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e  [SQLITE_IOCAP_UN
8430: 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f  DELETABLE_WHEN_O
8440: 50 45 4e 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  PEN].** <li> [SQ
8450: 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52  LITE_IOCAP_POWER
8460: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 0a  SAFE_OVERWRITE].
8470: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8480: 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 5d  IOCAP_IMMUTABLE]
8490: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
84a0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
84b0: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79  _ATOMIC property
84c0: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20   means that all 
84d0: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79  writes of.** any
84e0: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63   size are atomic
84f0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
8500: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61  CAP_ATOMICnnn va
8510: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61  lues.** mean tha
8520: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63  t writes of bloc
8530: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20  ks that are nnn 
8540: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
8550: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64  d.** are aligned
8560: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77   to an address w
8570: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67  hich is an integ
8580: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a  er multiple of.*
8590: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63  * nnn are atomic
85a0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
85b0: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
85c0: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74  value means.** t
85d0: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73  hat when data is
85e0: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66   appended to a f
85f0: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73  ile, the data is
8600: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72   appended.** fir
8610: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65  st then the size
8620: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   of the file is 
8630: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20  extended, never 
8640: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79  the other.** way
8650: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51   around.  The SQ
8660: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
8670: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d  NTIAL property m
8680: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66  eans that.** inf
8690: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74  ormation is writ
86a0: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74  ten to disk in t
86b0: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73  he same order as
86c0: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72   calls.** to xWr
86d0: 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ite()..**.** If 
86e0: 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73 20  xRead() returns 
86f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f  SQLITE_IOERR_SHO
8700: 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20  RT_READ it must 
8710: 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20  also fill.** in 
8720: 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69  the unread porti
8730: 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66 65  ons of the buffe
8740: 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41  r with zeros.  A
8750: 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69   VFS that.** fai
8760: 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20  ls to zero-fill 
8770: 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68  short reads migh
8780: 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20  t seem to work. 
8790: 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69   However,.** fai
87a0: 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c  lure to zero-fil
87b0: 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77 69  l short reads wi
87c0: 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65  ll eventually le
87d0: 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73  ad to.** databas
87e0: 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f  e corruption..*/
87f0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
8800: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
8810: 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ds sqlite3_io_me
8820: 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
8830: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
8840: 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
8850: 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73  n;.  int (*xClos
8860: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
8870: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64  );.  int (*xRead
8880: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8890: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74   void*, int iAmt
88a0: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
88b0: 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a  iOfst);.  int (*
88c0: 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f  xWrite)(sqlite3_
88d0: 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  file*, const voi
88e0: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71  d*, int iAmt, sq
88f0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
8900: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75  t);.  int (*xTru
8910: 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66  ncate)(sqlite3_f
8920: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
8930: 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74  t64 size);.  int
8940: 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65   (*xSync)(sqlite
8950: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61  3_file*, int fla
8960: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  gs);.  int (*xFi
8970: 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f  leSize)(sqlite3_
8980: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
8990: 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20  nt64 *pSize);.  
89a0: 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c  int (*xLock)(sql
89b0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29  ite3_file*, int)
89c0: 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63  ;.  int (*xUnloc
89d0: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
89e0: 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a  , int);.  int (*
89f0: 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f  xCheckReservedLo
8a00: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
8a10: 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29  *, int *pResOut)
8a20: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43  ;.  int (*xFileC
8a30: 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f  ontrol)(sqlite3_
8a40: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76  file*, int op, v
8a50: 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e  oid *pArg);.  in
8a60: 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29  t (*xSectorSize)
8a70: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
8a80: 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65  .  int (*xDevice
8a90: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 29  Characteristics)
8aa0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
8ab0: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62  .  /* Methods ab
8ac0: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f  ove are valid fo
8ad0: 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20  r version 1 */. 
8ae0: 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29 28   int (*xShmMap)(
8af0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8b00: 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73 7a  nt iPg, int pgsz
8b10: 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61  , int, void vola
8b20: 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28  tile**);.  int (
8b30: 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74  *xShmLock)(sqlit
8b40: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66  e3_file*, int of
8b50: 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74  fset, int n, int
8b60: 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64 20   flags);.  void 
8b70: 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28 73  (*xShmBarrier)(s
8b80: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
8b90: 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70   int (*xShmUnmap
8ba0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8bb0: 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67 29   int deleteFlag)
8bc0: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
8bd0: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
8be0: 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a  or version 2 */.
8bf0: 20 20 69 6e 74 20 28 2a 78 46 65 74 63 68 29 28    int (*xFetch)(
8c00: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
8c10: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
8c20: 73 74 2c 20 69 6e 74 20 69 41 6d 74 2c 20 76 6f  st, int iAmt, vo
8c30: 69 64 20 2a 2a 70 70 29 3b 0a 20 20 69 6e 74 20  id **pp);.  int 
8c40: 28 2a 78 55 6e 66 65 74 63 68 29 28 73 71 6c 69  (*xUnfetch)(sqli
8c50: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
8c60: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20  e3_int64 iOfst, 
8c70: 76 6f 69 64 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d  void *p);.  /* M
8c80: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
8c90: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69   valid for versi
8ca0: 6f 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20 41 64 64  on 3 */.  /* Add
8cb0: 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20  itional methods 
8cc0: 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
8cd0: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
8ce0: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
8cf0: 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20  I3REF: Standard 
8d00: 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63  File Control Opc
8d10: 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  odes.** KEYWORDS
8d20: 3a 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  : {file control 
8d30: 6f 70 63 6f 64 65 73 7d 20 7b 66 69 6c 65 20 63  opcodes} {file c
8d40: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 7d 0a 2a  ontrol opcode}.*
8d50: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67  *.** These integ
8d60: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  er constants are
8d70: 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65   opcodes for the
8d80: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
8d90: 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  thod.** of the [
8da0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
8db0: 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66  ds] object and f
8dc0: 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  or the [sqlite3_
8dd0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a  file_control()].
8de0: 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  ** interface..**
8df0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
8e00: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c  [[SQLITE_FCNTL_L
8e10: 4f 43 4b 53 54 41 54 45 5d 5d 0a 2a 2a 20 54 68  OCKSTATE]].** Th
8e20: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
8e30: 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64  LOCKSTATE] opcod
8e40: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65  e is used for de
8e50: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a  bugging.  This.*
8e60: 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20  * opcode causes 
8e70: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
8e80: 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65   method to write
8e90: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
8ea0: 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63  te of.** the loc
8eb0: 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  k (one of [SQLIT
8ec0: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53  E_LOCK_NONE], [S
8ed0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
8ee0: 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c  D],.** [SQLITE_L
8ef0: 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b  OCK_RESERVED], [
8f00: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
8f10: 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  ING], or [SQLITE
8f20: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d  _LOCK_EXCLUSIVE]
8f30: 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74  ).** into an int
8f40: 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41  eger that the pA
8f50: 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  rg argument poin
8f60: 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61  ts to. This capa
8f70: 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65  bility.** is use
8f80: 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67  d during testing
8f90: 20 61 6e 64 20 69 73 20 6f 6e 6c 79 20 61 76 61   and is only ava
8fa0: 69 6c 61 62 6c 65 20 77 68 65 6e 20 74 68 65 20  ilable when the 
8fb0: 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 63  SQLITE_TEST.** c
8fc0: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
8fd0: 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  on is used..**.*
8fe0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
8ff0: 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d  CNTL_SIZE_HINT]]
9000: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
9010: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d  FCNTL_SIZE_HINT]
9020: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
9030: 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67 69 76  by SQLite to giv
9040: 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79  e the VFS.** lay
9050: 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68 6f 77  er a hint of how
9060: 20 6c 61 72 67 65 20 74 68 65 20 64 61 74 61 62   large the datab
9070: 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 67 72  ase file will gr
9080: 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e 67 20  ow to be during 
9090: 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74  the.** current t
90a0: 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68 69  ransaction.  Thi
90b0: 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20 67 75  s hint is not gu
90c0: 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 61  aranteed to be a
90d0: 63 63 75 72 61 74 65 20 62 75 74 20 69 74 0a 2a  ccurate but it.*
90e0: 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65  * is often close
90f0: 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e  .  The underlyin
9100: 67 20 56 46 53 20 6d 69 67 68 74 20 63 68 6f 6f  g VFS might choo
9110: 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74  se to preallocat
9120: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  e database.** fi
9130: 6c 65 20 73 70 61 63 65 20 62 61 73 65 64 20 6f  le space based o
9140: 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e 20 6f  n this hint in o
9150: 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77 72 69  rder to help wri
9160: 74 65 73 20 74 6f 20 74 68 65 20 64 61 74 61 62  tes to the datab
9170: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20  ase.** file run 
9180: 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  faster..**.** <l
9190: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
91a0: 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a  _CHUNK_SIZE]].**
91b0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
91c0: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f  TL_CHUNK_SIZE] o
91d0: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
91e0: 20 72 65 71 75 65 73 74 20 74 68 61 74 20 74 68   request that th
91f0: 65 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73  e VFS.** extends
9200: 20 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74   and truncates t
9210: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
9220: 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20   in chunks of a 
9230: 73 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a  size specified.*
9240: 2a 20 62 79 20 74 68 65 20 75 73 65 72 2e 20 54  * by the user. T
9250: 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
9260: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  nt to [sqlite3_f
9270: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73  ile_control()] s
9280: 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20  hould .** point 
9290: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74  to an integer (t
92a0: 79 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e  ype int) contain
92b0: 69 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e  ing the new chun
92c0: 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a  k-size to use.**
92d0: 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74   for the nominat
92e0: 65 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c  ed database. All
92f0: 6f 63 61 74 69 6e 67 20 64 61 74 61 62 61 73 65  ocating database
9300: 20 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c   file space in l
9310: 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28  arge.** chunks (
9320: 73 61 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d  say 1MB at a tim
9330: 65 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66  e), may reduce f
9340: 69 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d  ile-system fragm
9350: 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20  entation and.** 
9360: 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61  improve performa
9370: 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74  nce on some syst
9380: 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ems..**.** <li>[
9390: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49  [SQLITE_FCNTL_FI
93a0: 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20  LE_POINTER]].** 
93b0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
93c0: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20  L_FILE_POINTER] 
93d0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
93e0: 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74  o obtain a point
93f0: 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  er.** to the [sq
9400: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
9410: 63 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ct associated wi
9420: 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  th a particular 
9430: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
9440: 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 61 6c 73  ection.  See als
9450: 6f 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  o [SQLITE_FCNTL_
9460: 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d  JOURNAL_POINTER]
9470: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
9480: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e  LITE_FCNTL_JOURN
9490: 41 4c 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20  AL_POINTER]].** 
94a0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
94b0: 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45  L_JOURNAL_POINTE
94c0: 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  R] opcode is use
94d0: 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f  d to obtain a po
94e0: 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
94f0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
9500: 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 64  bject associated
9510: 20 77 69 74 68 20 74 68 65 20 6a 6f 75 72 6e 61   with the journa
9520: 6c 20 66 69 6c 65 20 28 65 69 74 68 65 72 0a 2a  l file (either.*
9530: 2a 20 74 68 65 20 5b 72 6f 6c 6c 62 61 63 6b 20  * the [rollback 
9540: 6a 6f 75 72 6e 61 6c 5d 20 6f 72 20 74 68 65 20  journal] or the 
9550: 5b 77 72 69 74 65 2d 61 68 65 61 64 20 6c 6f 67  [write-ahead log
9560: 5d 29 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  ]) for a particu
9570: 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  lar database.** 
9580: 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65  connection.  See
9590: 20 61 6c 73 6f 20 5b 53 51 4c 49 54 45 5f 46 43   also [SQLITE_FC
95a0: 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52  NTL_FILE_POINTER
95b0: 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  ]..**.** <li>[[S
95c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
95d0: 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20 4e 6f  _OMITTED]].** No
95e0: 20 6c 6f 6e 67 65 72 20 69 6e 20 75 73 65 2e 0a   longer in use..
95f0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9600: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 5d 0a  TE_FCNTL_SYNC]].
9610: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
9620: 43 4e 54 4c 5f 53 59 4e 43 5d 20 6f 70 63 6f 64  CNTL_SYNC] opcod
9630: 65 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 69  e is generated i
9640: 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c  nternally by SQL
9650: 69 74 65 20 61 6e 64 0a 2a 2a 20 73 65 6e 74 20  ite and.** sent 
9660: 74 6f 20 74 68 65 20 56 46 53 20 69 6d 6d 65 64  to the VFS immed
9670: 69 61 74 65 6c 79 20 62 65 66 6f 72 65 20 74 68  iately before th
9680: 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 69  e xSync method i
9690: 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 0a 2a  s invoked on a.*
96a0: 2a 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  * database file 
96b0: 64 65 73 63 72 69 70 74 6f 72 2e 20 4f 72 2c 20  descriptor. Or, 
96c0: 69 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74  if the xSync met
96d0: 68 6f 64 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b  hod is not invok
96e0: 65 64 20 0a 2a 2a 20 62 65 63 61 75 73 65 20 74  ed .** because t
96f0: 68 65 20 75 73 65 72 20 68 61 73 20 63 6f 6e 66  he user has conf
9700: 69 67 75 72 65 64 20 53 51 4c 69 74 65 20 77 69  igured SQLite wi
9710: 74 68 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 73  th .** [PRAGMA s
9720: 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41  ynchronous | PRA
9730: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d  GMA synchronous=
9740: 4f 46 46 5d 20 69 74 20 69 73 20 69 6e 76 6f 6b  OFF] it is invok
9750: 65 64 20 69 6e 20 70 6c 61 63 65 20 0a 2a 2a 20  ed in place .** 
9760: 6f 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74  of the xSync met
9770: 68 6f 64 2e 20 49 6e 20 6d 6f 73 74 20 63 61 73  hod. In most cas
9780: 65 73 2c 20 74 68 65 20 70 6f 69 6e 74 65 72 20  es, the pointer 
9790: 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20  argument passed 
97a0: 77 69 74 68 0a 2a 2a 20 74 68 69 73 20 66 69 6c  with.** this fil
97b0: 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 4e 55 4c  e-control is NUL
97c0: 4c 2e 20 48 6f 77 65 76 65 72 2c 20 69 66 20 74  L. However, if t
97d0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
97e0: 20 69 73 20 62 65 69 6e 67 20 73 79 6e 63 65 64   is being synced
97f0: 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 61  .** as part of a
9800: 20 6d 75 6c 74 69 2d 64 61 74 61 62 61 73 65 20   multi-database 
9810: 63 6f 6d 6d 69 74 2c 20 74 68 65 20 61 72 67 75  commit, the argu
9820: 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 20 61  ment points to a
9830: 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a   nul-terminated.
9840: 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69  ** string contai
9850: 6e 69 6e 67 20 74 68 65 20 74 72 61 6e 73 61 63  ning the transac
9860: 74 69 6f 6e 73 20 6d 61 73 74 65 72 2d 6a 6f 75  tions master-jou
9870: 72 6e 61 6c 20 66 69 6c 65 20 6e 61 6d 65 2e 20  rnal file name. 
9880: 56 46 53 65 73 20 74 68 61 74 20 0a 2a 2a 20 64  VFSes that .** d
9890: 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20  o not need this 
98a0: 73 69 67 6e 61 6c 20 73 68 6f 75 6c 64 20 73 69  signal should si
98b0: 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68  lently ignore th
98c0: 69 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69  is opcode. Appli
98d0: 63 61 74 69 6f 6e 73 20 0a 2a 2a 20 73 68 6f 75  cations .** shou
98e0: 6c 64 20 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c  ld not call [sql
98f0: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
9900: 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f  l()] with this o
9910: 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73  pcode as doing s
9920: 6f 20 6d 61 79 20 0a 2a 2a 20 64 69 73 72 75 70  o may .** disrup
9930: 74 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20  t the operation 
9940: 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a  of the specializ
9950: 65 64 20 56 46 53 65 73 20 74 68 61 74 20 64 6f  ed VFSes that do
9960: 20 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a   require it.  .*
9970: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9980: 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50  E_FCNTL_COMMIT_P
9990: 48 41 53 45 54 57 4f 5d 5d 0a 2a 2a 20 54 68 65  HASETWO]].** The
99a0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43   [SQLITE_FCNTL_C
99b0: 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 20  OMMIT_PHASETWO] 
99c0: 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61  opcode is genera
99d0: 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62  ted internally b
99e0: 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20  y SQLite.** and 
99f0: 73 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20  sent to the VFS 
9a00: 61 66 74 65 72 20 61 20 74 72 61 6e 73 61 63 74  after a transact
9a10: 69 6f 6e 20 68 61 73 20 62 65 65 6e 20 63 6f 6d  ion has been com
9a20: 6d 69 74 74 65 64 20 69 6d 6d 65 64 69 61 74 65  mitted immediate
9a30: 6c 79 0a 2a 2a 20 62 75 74 20 62 65 66 6f 72 65  ly.** but before
9a40: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
9a50: 20 75 6e 6c 6f 63 6b 65 64 2e 20 56 46 53 65 73   unlocked. VFSes
9a60: 20 74 68 61 74 20 64 6f 20 6e 6f 74 20 6e 65 65   that do not nee
9a70: 64 20 74 68 69 73 20 73 69 67 6e 61 6c 0a 2a 2a  d this signal.**
9a80: 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79   should silently
9a90: 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63   ignore this opc
9aa0: 6f 64 65 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e  ode. Application
9ab0: 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c  s should not cal
9ac0: 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  l.** [sqlite3_fi
9ad0: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69  le_control()] wi
9ae0: 74 68 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61  th this opcode a
9af0: 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64  s doing so may d
9b00: 69 73 72 75 70 74 20 74 68 65 20 0a 2a 2a 20 6f  isrupt the .** o
9b10: 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  peration of the 
9b20: 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65  specialized VFSe
9b30: 73 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72  s that do requir
9b40: 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c  e it.  .**.** <l
9b50: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
9b60: 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d  _WIN32_AV_RETRY]
9b70: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
9b80: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56  E_FCNTL_WIN32_AV
9b90: 5f 52 45 54 52 59 5d 20 6f 70 63 6f 64 65 20 69  _RETRY] opcode i
9ba0: 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67  s used to config
9bb0: 75 72 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a  ure automatic.**
9bc0: 20 72 65 74 72 79 20 63 6f 75 6e 74 73 20 61 6e   retry counts an
9bd0: 64 20 69 6e 74 65 72 76 61 6c 73 20 66 6f 72 20  d intervals for 
9be0: 63 65 72 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f  certain disk I/O
9bf0: 20 6f 70 65 72 61 74 69 6f 6e 73 20 66 6f 72 20   operations for 
9c00: 74 68 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b  the.** windows [
9c10: 56 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f  VFS] in order to
9c20: 20 70 72 6f 76 69 64 65 20 72 6f 62 75 73 74 6e   provide robustn
9c30: 65 73 73 20 69 6e 20 74 68 65 20 70 72 65 73 65  ess in the prese
9c40: 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76  nce of.** anti-v
9c50: 69 72 75 73 20 70 72 6f 67 72 61 6d 73 2e 20 20  irus programs.  
9c60: 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20  By default, the 
9c70: 77 69 6e 64 6f 77 73 20 56 46 53 20 77 69 6c 6c  windows VFS will
9c80: 20 72 65 74 72 79 20 66 69 6c 65 20 72 65 61 64   retry file read
9c90: 2c 0a 2a 2a 20 66 69 6c 65 20 77 72 69 74 65 2c  ,.** file write,
9ca0: 20 61 6e 64 20 66 69 6c 65 20 64 65 6c 65 74 65   and file delete
9cb0: 20 6f 70 65 72 61 74 69 6f 6e 73 20 75 70 20 74   operations up t
9cc0: 6f 20 31 30 20 74 69 6d 65 73 2c 20 77 69 74 68  o 10 times, with
9cd0: 20 61 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32   a delay.** of 2
9ce0: 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62  5 milliseconds b
9cf0: 65 66 6f 72 65 20 74 68 65 20 66 69 72 73 74 20  efore the first 
9d00: 72 65 74 72 79 20 61 6e 64 20 77 69 74 68 20 74  retry and with t
9d10: 68 65 20 64 65 6c 61 79 20 69 6e 63 72 65 61 73  he delay increas
9d20: 69 6e 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64  ing.** by an add
9d30: 69 74 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69  itional 25 milli
9d40: 73 65 63 6f 6e 64 73 20 77 69 74 68 20 65 61 63  seconds with eac
9d50: 68 20 73 75 62 73 65 71 75 65 6e 74 20 72 65 74  h subsequent ret
9d60: 72 79 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63  ry.  This.** opc
9d70: 6f 64 65 20 61 6c 6c 6f 77 73 20 74 68 65 73 65  ode allows these
9d80: 20 74 77 6f 20 76 61 6c 75 65 73 20 28 31 30 20   two values (10 
9d90: 72 65 74 72 69 65 73 20 61 6e 64 20 32 35 20 6d  retries and 25 m
9da0: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 64  illiseconds of d
9db0: 65 6c 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61  elay).** to be a
9dc0: 64 6a 75 73 74 65 64 2e 20 20 54 68 65 20 76 61  djusted.  The va
9dd0: 6c 75 65 73 20 61 72 65 20 63 68 61 6e 67 65 64  lues are changed
9de0: 20 66 6f 72 20 61 6c 6c 20 64 61 74 61 62 61 73   for all databas
9df0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a  e connections.**
9e00: 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65   within the same
9e10: 20 70 72 6f 63 65 73 73 2e 20 20 54 68 65 20 61   process.  The a
9e20: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
9e30: 6e 74 65 72 20 74 6f 20 61 6e 20 61 72 72 61 79  nter to an array
9e40: 20 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67   of two.** integ
9e50: 65 72 73 20 77 68 65 72 65 20 74 68 65 20 66 69  ers where the fi
9e60: 72 73 74 20 69 6e 74 65 67 65 72 20 69 73 20 74  rst integer is t
9e70: 68 65 20 6e 65 77 20 72 65 74 72 79 20 63 6f 75  he new retry cou
9e80: 6e 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  nt and the secon
9e90: 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 69 73 20  d.** integer is 
9ea0: 74 68 65 20 64 65 6c 61 79 2e 20 20 49 66 20 65  the delay.  If e
9eb0: 69 74 68 65 72 20 69 6e 74 65 67 65 72 20 69 73  ither integer is
9ec0: 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
9ed0: 74 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69  the setting.** i
9ee0: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 62 75  s not changed bu
9ef0: 74 20 69 6e 73 74 65 61 64 20 74 68 65 20 70 72  t instead the pr
9f00: 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 61  ior value of tha
9f10: 74 20 73 65 74 74 69 6e 67 20 69 73 20 77 72 69  t setting is wri
9f20: 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65  tten.** into the
9f30: 20 61 72 72 61 79 20 65 6e 74 72 79 2c 20 61 6c   array entry, al
9f40: 6c 6f 77 69 6e 67 20 74 68 65 20 63 75 72 72 65  lowing the curre
9f50: 6e 74 20 72 65 74 72 79 20 73 65 74 74 69 6e 67  nt retry setting
9f60: 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72  s to be.** inter
9f70: 72 6f 67 61 74 65 64 2e 20 20 54 68 65 20 7a 44  rogated.  The zD
9f80: 62 4e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  bName parameter 
9f90: 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a  is ignored..**.*
9fa0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
9fb0: 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c  CNTL_PERSIST_WAL
9fc0: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
9fd0: 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54  TE_FCNTL_PERSIST
9fe0: 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20  _WAL] opcode is 
9ff0: 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71  used to set or q
a000: 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73  uery the.** pers
a010: 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72  istent [WAL | Wr
a020: 69 74 65 20 41 68 65 61 64 20 4c 6f 67 5d 20 73  ite Ahead Log] s
a030: 65 74 74 69 6e 67 2e 20 20 42 79 20 64 65 66 61  etting.  By defa
a040: 75 6c 74 2c 20 74 68 65 20 61 75 78 69 6c 69 61  ult, the auxilia
a050: 72 79 0a 2a 2a 20 77 72 69 74 65 20 61 68 65 61  ry.** write ahea
a060: 64 20 6c 6f 67 20 61 6e 64 20 73 68 61 72 65 64  d log and shared
a070: 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 75 73   memory files us
a080: 65 64 20 66 6f 72 20 74 72 61 6e 73 61 63 74 69  ed for transacti
a090: 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72  on control.** ar
a0a0: 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
a0b0: 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65  deleted when the
a0c0: 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65 63 74 69   latest connecti
a0d0: 6f 6e 20 74 6f 20 74 68 65 20 64 61 74 61 62 61  on to the databa
a0e0: 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53  se.** closes.  S
a0f0: 65 74 74 69 6e 67 20 70 65 72 73 69 73 74 65 6e  etting persisten
a100: 74 20 57 41 4c 20 6d 6f 64 65 20 63 61 75 73 65  t WAL mode cause
a110: 73 20 74 68 6f 73 65 20 66 69 6c 65 73 20 74 6f  s those files to
a120: 20 70 65 72 73 69 73 74 20 61 66 74 65 72 0a 2a   persist after.*
a130: 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72 73 69 73  * close.  Persis
a140: 74 69 6e 67 20 74 68 65 20 66 69 6c 65 73 20 69  ting the files i
a150: 73 20 75 73 65 66 75 6c 20 77 68 65 6e 20 6f 74  s useful when ot
a160: 68 65 72 20 70 72 6f 63 65 73 73 65 73 20 74 68  her processes th
a170: 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76  at do not.** hav
a180: 65 20 77 72 69 74 65 20 70 65 72 6d 69 73 73 69  e write permissi
a190: 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72 65 63 74  on on the direct
a1a0: 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  ory containing t
a1b0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
a1c0: 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64   want.** to read
a1d0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
a1e0: 6c 65 2c 20 61 73 20 74 68 65 20 57 41 4c 20 61  le, as the WAL a
a1f0: 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79  nd shared memory
a200: 20 66 69 6c 65 73 20 6d 75 73 74 20 65 78 69 73   files must exis
a210: 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f  t.** in order fo
a220: 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74  r the database t
a230: 6f 20 62 65 20 72 65 61 64 61 62 6c 65 2e 20 20  o be readable.  
a240: 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
a250: 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  eter to.** [sqli
a260: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
a270: 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63  ()] for this opc
a280: 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20  ode should be a 
a290: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
a2a0: 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69  teger..** That i
a2b0: 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f 20 64  nteger is 0 to d
a2c0: 69 73 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e  isable persisten
a2d0: 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20  t WAL mode or 1 
a2e0: 74 6f 20 65 6e 61 62 6c 65 20 70 65 72 73 69 73  to enable persis
a2f0: 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65  tent.** WAL mode
a300: 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65  .  If the intege
a310: 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74  r is -1, then it
a320: 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20   is overwritten 
a330: 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74  with the current
a340: 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69 73 74 65  .** WAL persiste
a350: 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a  nce setting..**.
a360: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
a370: 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f  FCNTL_POWERSAFE_
a380: 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e  OVERWRITE]].** ^
a390: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
a3a0: 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  L_POWERSAFE_OVER
a3b0: 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73  WRITE] opcode is
a3c0: 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20   used to set or 
a3d0: 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72  query the.** per
a3e0: 73 69 73 74 65 6e 74 20 22 70 6f 77 65 72 73 61  sistent "powersa
a3f0: 66 65 2d 6f 76 65 72 77 72 69 74 65 22 20 6f 72  fe-overwrite" or
a400: 20 22 50 53 4f 57 22 20 73 65 74 74 69 6e 67 2e   "PSOW" setting.
a410: 20 20 54 68 65 20 50 53 4f 57 20 73 65 74 74 69    The PSOW setti
a420: 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73  ng.** determines
a430: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43   the [SQLITE_IOC
a440: 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  AP_POWERSAFE_OVE
a450: 52 57 52 49 54 45 5d 20 62 69 74 20 6f 66 20 74  RWRITE] bit of t
a460: 68 65 0a 2a 2a 20 78 44 65 76 69 63 65 43 68 61  he.** xDeviceCha
a470: 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74  racteristics met
a480: 68 6f 64 73 2e 20 54 68 65 20 66 6f 75 72 74 68  hods. The fourth
a490: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
a4a0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
a4b0: 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68  ontrol()] for th
a4c0: 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64  is opcode should
a4d0: 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   be a pointer to
a4e0: 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20   an integer..** 
a4f0: 54 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20  That integer is 
a500: 30 20 74 6f 20 64 69 73 61 62 6c 65 20 7a 65 72  0 to disable zer
a510: 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 6f 72  o-damage mode or
a520: 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 7a 65 72   1 to enable zer
a530: 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65  o-damage.** mode
a540: 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65  .  If the intege
a550: 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74  r is -1, then it
a560: 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20   is overwritten 
a570: 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74  with the current
a580: 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20  .** zero-damage 
a590: 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a  mode setting..**
a5a0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
a5b0: 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45  _FCNTL_OVERWRITE
a5c0: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
a5d0: 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49  TE_FCNTL_OVERWRI
a5e0: 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6e  TE] opcode is in
a5f0: 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20  voked by SQLite 
a600: 61 66 74 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a  after opening.**
a610: 20 61 20 77 72 69 74 65 20 74 72 61 6e 73 61 63   a write transac
a620: 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63 61 74 65  tion to indicate
a630: 20 74 68 61 74 2c 20 75 6e 6c 65 73 73 20 69 74   that, unless it
a640: 20 69 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20   is rolled back 
a650: 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73  for some.** reas
a660: 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72 65 20 64  on, the entire d
a670: 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c  atabase file wil
a680: 6c 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e  l be overwritten
a690: 20 62 79 20 74 68 65 20 63 75 72 72 65 6e 74 20   by the current 
a6a0: 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e  .** transaction.
a6b0: 20 54 68 69 73 20 69 73 20 75 73 65 64 20 62 79   This is used by
a6c0: 20 56 41 43 55 55 4d 20 6f 70 65 72 61 74 69 6f   VACUUM operatio
a6d0: 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ns..**.** <li>[[
a6e0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53  SQLITE_FCNTL_VFS
a6f0: 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  NAME]].** ^The [
a700: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53  SQLITE_FCNTL_VFS
a710: 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e  NAME] opcode can
a720: 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61   be used to obta
a730: 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 0a  in the names of.
a740: 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73 5d 20 69  ** all [VFSes] i
a750: 6e 20 74 68 65 20 56 46 53 20 73 74 61 63 6b 2e  n the VFS stack.
a760: 20 20 54 68 65 20 6e 61 6d 65 73 20 61 72 65 20    The names are 
a770: 6f 66 20 61 6c 6c 20 56 46 53 20 73 68 69 6d 73  of all VFS shims
a780: 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 69 6e 61   and the.** fina
a790: 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 56  l bottom-level V
a7a0: 46 53 20 61 72 65 20 77 72 69 74 74 65 6e 20 69  FS are written i
a7b0: 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69  nto memory obtai
a7c0: 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71  ned from .** [sq
a7d0: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
a7e0: 61 6e 64 20 74 68 65 20 72 65 73 75 6c 74 20 69  and the result i
a7f0: 73 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20  s stored in the 
a800: 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65 0a 2a  char* variable.*
a810: 2a 20 74 68 61 74 20 74 68 65 20 66 6f 75 72 74  * that the fourt
a820: 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 5b  h parameter of [
a830: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
a840: 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74 73 20 74  trol()] points t
a850: 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 65 72  o..** The caller
a860: 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
a870: 66 6f 72 20 66 72 65 65 69 6e 67 20 74 68 65 20  for freeing the 
a880: 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64 6f 6e 65  memory when done
a890: 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a 20 61 6c  .  As with.** al
a8a0: 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61  l file-control a
a8b0: 63 74 69 6f 6e 73 2c 20 74 68 65 72 65 20 69 73  ctions, there is
a8c0: 20 6e 6f 20 67 75 61 72 61 6e 74 65 65 20 74 68   no guarantee th
a8d0: 61 74 20 74 68 69 73 20 77 69 6c 6c 20 61 63 74  at this will act
a8e0: 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 74  ually.** do anyt
a8f0: 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72 73 20 73  hing.  Callers s
a900: 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c 69 7a 65  hould initialize
a910: 20 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61   the char* varia
a920: 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a  ble to a NULL.**
a930: 20 70 6f 69 6e 74 65 72 20 69 6e 20 63 61 73 65   pointer in case
a940: 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72   this file-contr
a950: 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d  ol is not implem
a960: 65 6e 74 65 64 2e 20 20 54 68 69 73 20 66 69 6c  ented.  This fil
a970: 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20  e-control.** is 
a980: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 64 69 61  intended for dia
a990: 67 6e 6f 73 74 69 63 20 75 73 65 20 6f 6e 6c 79  gnostic use only
a9a0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
a9b0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50  LITE_FCNTL_VFS_P
a9c0: 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65  OINTER]].** ^The
a9d0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56   [SQLITE_FCNTL_V
a9e0: 46 53 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f  FS_POINTER] opco
a9f0: 64 65 20 66 69 6e 64 73 20 61 20 70 6f 69 6e 74  de finds a point
aa00: 65 72 20 74 6f 20 74 68 65 20 74 6f 70 2d 6c 65  er to the top-le
aa10: 76 65 6c 0a 2a 2a 20 5b 56 46 53 65 73 5d 20 63  vel.** [VFSes] c
aa20: 75 72 72 65 6e 74 6c 79 20 69 6e 20 75 73 65 2e  urrently in use.
aa30: 20 20 5e 28 54 68 65 20 61 72 67 75 6d 65 6e 74    ^(The argument
aa40: 20 58 20 69 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   X in.** sqlite3
aa50: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 64 62  _file_control(db
aa60: 2c 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46  ,SQLITE_FCNTL_VF
aa70: 53 5f 50 4f 49 4e 54 45 52 2c 58 29 20 6d 75 73  S_POINTER,X) mus
aa80: 74 20 62 65 0a 2a 2a 20 6f 66 20 74 79 70 65 20  t be.** of type 
aa90: 22 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 2a  "[sqlite3_vfs] *
aaa0: 2a 22 2e 20 20 54 68 69 73 20 6f 70 63 6f 64 65  *".  This opcode
aab0: 73 20 77 69 6c 6c 20 73 65 74 20 2a 58 0a 2a 2a  s will set *X.**
aac0: 20 74 6f 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   to a pointer to
aad0: 20 74 68 65 20 74 6f 70 2d 6c 65 76 65 6c 20 56   the top-level V
aae0: 46 53 2e 29 5e 0a 2a 2a 20 5e 57 68 65 6e 20 74  FS.)^.** ^When t
aaf0: 68 65 72 65 20 61 72 65 20 6d 75 6c 74 69 70 6c  here are multipl
ab00: 65 20 56 46 53 20 73 68 69 6d 73 20 69 6e 20 74  e VFS shims in t
ab10: 68 65 20 73 74 61 63 6b 2c 20 74 68 69 73 20 6f  he stack, this o
ab20: 70 63 6f 64 65 20 66 69 6e 64 73 20 74 68 65 0a  pcode finds the.
ab30: 2a 2a 20 75 70 70 65 72 2d 6d 6f 73 74 20 73 68  ** upper-most sh
ab40: 69 6d 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c  im only..**.** <
ab50: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
ab60: 4c 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57  L_PRAGMA]].** ^W
ab70: 68 65 6e 65 76 65 72 20 61 20 5b 50 52 41 47 4d  henever a [PRAGM
ab80: 41 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  A] statement is 
ab90: 70 61 72 73 65 64 2c 20 61 6e 20 5b 53 51 4c 49  parsed, an [SQLI
aba0: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
abb0: 20 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f   .** file contro
abc0: 6c 20 69 73 20 73 65 6e 74 20 74 6f 20 74 68 65  l is sent to the
abd0: 20 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66   open [sqlite3_f
abe0: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 63 6f 72 72  ile] object corr
abf0: 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20  esponding.** to 
ac00: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
ac10: 65 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 70  e to which the p
ac20: 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20  ragma statement 
ac30: 72 65 66 65 72 73 2e 20 5e 54 68 65 20 61 72 67  refers. ^The arg
ac40: 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20  ument.** to the 
ac50: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
ac60: 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72  AGMA] file contr
ac70: 6f 6c 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  ol is an array o
ac80: 66 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f  f.** pointers to
ac90: 20 73 74 72 69 6e 67 73 20 28 63 68 61 72 2a 2a   strings (char**
aca0: 29 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 73  ) in which the s
acb0: 65 63 6f 6e 64 20 65 6c 65 6d 65 6e 74 20 6f 66  econd element of
acc0: 20 74 68 65 20 61 72 72 61 79 0a 2a 2a 20 69 73   the array.** is
acd0: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
ace0: 20 70 72 61 67 6d 61 20 61 6e 64 20 74 68 65 20   pragma and the 
acf0: 74 68 69 72 64 20 65 6c 65 6d 65 6e 74 20 69 73  third element is
ad00: 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f   the argument to
ad10: 20 74 68 65 0a 2a 2a 20 70 72 61 67 6d 61 20 6f   the.** pragma o
ad20: 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 70 72  r NULL if the pr
ad30: 61 67 6d 61 20 68 61 73 20 6e 6f 20 61 72 67 75  agma has no argu
ad40: 6d 65 6e 74 2e 20 20 5e 54 68 65 20 68 61 6e 64  ment.  ^The hand
ad50: 6c 65 72 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53  ler for an.** [S
ad60: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
ad70: 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  MA] file control
ad80: 20 63 61 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79 20   can optionally 
ad90: 6d 61 6b 65 20 74 68 65 20 66 69 72 73 74 20 65  make the first e
ada0: 6c 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 65  lement.** of the
adb0: 20 63 68 61 72 2a 2a 20 61 72 67 75 6d 65 6e 74   char** argument
adc0: 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69   point to a stri
add0: 6e 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ng obtained from
ade0: 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74   [sqlite3_mprint
adf0: 66 28 29 5d 0a 2a 2a 20 6f 72 20 74 68 65 20 65  f()].** or the e
ae00: 71 75 69 76 61 6c 65 6e 74 20 61 6e 64 20 74 68  quivalent and th
ae10: 61 74 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62  at string will b
ae20: 65 63 6f 6d 65 20 74 68 65 20 72 65 73 75 6c 74  ecome the result
ae30: 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 6f   of the pragma o
ae40: 72 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 6d  r.** the error m
ae50: 65 73 73 61 67 65 20 69 66 20 74 68 65 20 70 72  essage if the pr
ae60: 61 67 6d 61 20 66 61 69 6c 73 2e 20 5e 49 66 20  agma fails. ^If 
ae70: 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46  the.** [SQLITE_F
ae80: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c  CNTL_PRAGMA] fil
ae90: 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e  e control return
aea0: 73 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  s [SQLITE_NOTFOU
aeb0: 4e 44 5d 2c 20 74 68 65 6e 20 6e 6f 72 6d 61 6c  ND], then normal
aec0: 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d 20 70 72   .** [PRAGMA] pr
aed0: 6f 63 65 73 73 69 6e 67 20 63 6f 6e 74 69 6e 75  ocessing continu
aee0: 65 73 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51  es.  ^If the [SQ
aef0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
af00: 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72  A].** file contr
af10: 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ol returns [SQLI
af20: 54 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20 74 68 65  TE_OK], then the
af30: 20 70 61 72 73 65 72 20 61 73 73 75 6d 65 73 20   parser assumes 
af40: 74 68 61 74 20 74 68 65 0a 2a 2a 20 56 46 53 20  that the.** VFS 
af50: 68 61 73 20 68 61 6e 64 6c 65 64 20 74 68 65 20  has handled the 
af60: 50 52 41 47 4d 41 20 69 74 73 65 6c 66 20 61 6e  PRAGMA itself an
af70: 64 20 74 68 65 20 70 61 72 73 65 72 20 67 65 6e  d the parser gen
af80: 65 72 61 74 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a  erates a no-op.*
af90: 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  * prepared state
afa0: 6d 65 6e 74 20 69 66 20 72 65 73 75 6c 74 20 73  ment if result s
afb0: 74 72 69 6e 67 20 69 73 20 4e 55 4c 4c 2c 20 6f  tring is NULL, o
afc0: 72 20 74 68 61 74 20 72 65 74 75 72 6e 73 20 61  r that returns a
afd0: 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20   copy.** of the 
afe0: 72 65 73 75 6c 74 20 73 74 72 69 6e 67 20 69 66  result string if
aff0: 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 20 6e   the string is n
b000: 6f 6e 2d 4e 55 4c 4c 2e 0a 2a 2a 20 5e 49 66 20  on-NULL..** ^If 
b010: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  the [SQLITE_FCNT
b020: 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63  L_PRAGMA] file c
b030: 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 0a 2a  ontrol returns.*
b040: 2a 20 61 6e 79 20 72 65 73 75 6c 74 20 63 6f 64  * any result cod
b050: 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  e other than [SQ
b060: 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c  LITE_OK] or [SQL
b070: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74  ITE_NOTFOUND], t
b080: 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61  hat means.** tha
b090: 74 20 74 68 65 20 56 46 53 20 65 6e 63 6f 75 6e  t the VFS encoun
b0a0: 74 65 72 65 64 20 61 6e 20 65 72 72 6f 72 20 77  tered an error w
b0b0: 68 69 6c 65 20 68 61 6e 64 6c 69 6e 67 20 74 68  hile handling th
b0c0: 65 20 5b 50 52 41 47 4d 41 5d 20 61 6e 64 20 74  e [PRAGMA] and t
b0d0: 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74 69 6f  he.** compilatio
b0e0: 6e 20 6f 66 20 74 68 65 20 50 52 41 47 4d 41 20  n of the PRAGMA 
b0f0: 66 61 69 6c 73 20 77 69 74 68 20 61 6e 20 65 72  fails with an er
b100: 72 6f 72 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49  ror.  ^The [SQLI
b110: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
b120: 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  .** file control
b130: 20 6f 63 63 75 72 73 20 61 74 20 74 68 65 20 62   occurs at the b
b140: 65 67 69 6e 6e 69 6e 67 20 6f 66 20 70 72 61 67  eginning of prag
b150: 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 61  ma statement ana
b160: 6c 79 73 69 73 20 61 6e 64 20 73 6f 0a 2a 2a 20  lysis and so.** 
b170: 69 74 20 69 73 20 61 62 6c 65 20 74 6f 20 6f 76  it is able to ov
b180: 65 72 72 69 64 65 20 62 75 69 6c 74 2d 69 6e 20  erride built-in 
b190: 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65  [PRAGMA] stateme
b1a0: 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  nts..**.** <li>[
b1b0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55  [SQLITE_FCNTL_BU
b1c0: 53 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e  SYHANDLER]].** ^
b1d0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
b1e0: 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 0a 2a  L_BUSYHANDLER].*
b1f0: 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d  * file-control m
b200: 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 62 79  ay be invoked by
b210: 20 53 51 4c 69 74 65 20 6f 6e 20 74 68 65 20 64   SQLite on the d
b220: 61 74 61 62 61 73 65 20 66 69 6c 65 20 68 61 6e  atabase file han
b230: 64 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c 79 20 61  dle.** shortly a
b240: 66 74 65 72 20 69 74 20 69 73 20 6f 70 65 6e 65  fter it is opene
b250: 64 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72  d in order to pr
b260: 6f 76 69 64 65 20 61 20 63 75 73 74 6f 6d 20 56  ovide a custom V
b270: 46 53 20 77 69 74 68 20 61 63 63 65 73 73 0a 2a  FS with access.*
b280: 2a 20 74 6f 20 74 68 65 20 63 6f 6e 6e 65 63 74  * to the connect
b290: 69 6f 6e 73 20 62 75 73 79 2d 68 61 6e 64 6c 65  ions busy-handle
b2a0: 72 20 63 61 6c 6c 62 61 63 6b 2e 20 54 68 65 20  r callback. The 
b2b0: 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 66 20 74  argument is of t
b2c0: 79 70 65 20 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a  ype (void **).**
b2d0: 20 2d 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74   - an array of t
b2e0: 77 6f 20 28 76 6f 69 64 20 2a 29 20 76 61 6c 75  wo (void *) valu
b2f0: 65 73 2e 20 54 68 65 20 66 69 72 73 74 20 28 76  es. The first (v
b300: 6f 69 64 20 2a 29 20 61 63 74 75 61 6c 6c 79 20  oid *) actually 
b310: 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 61 20 66  points.** to a f
b320: 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20  unction of type 
b330: 28 69 6e 74 20 28 2a 29 28 76 6f 69 64 20 2a 29  (int (*)(void *)
b340: 29 2e 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 69  ). In order to i
b350: 6e 76 6f 6b 65 20 74 68 65 20 63 6f 6e 6e 65 63  nvoke the connec
b360: 74 69 6f 6e 73 0a 2a 2a 20 62 75 73 79 2d 68 61  tions.** busy-ha
b370: 6e 64 6c 65 72 2c 20 74 68 69 73 20 66 75 6e 63  ndler, this func
b380: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 69  tion should be i
b390: 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 68 65 20  nvoked with the 
b3a0: 73 65 63 6f 6e 64 20 28 76 6f 69 64 20 2a 29 20  second (void *) 
b3b0: 69 6e 0a 2a 2a 20 74 68 65 20 61 72 72 61 79 20  in.** the array 
b3c0: 61 73 20 74 68 65 20 6f 6e 6c 79 20 61 72 67 75  as the only argu
b3d0: 6d 65 6e 74 2e 20 49 66 20 69 74 20 72 65 74 75  ment. If it retu
b3e0: 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
b3f0: 65 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  en the operation
b400: 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65  .** should be re
b410: 74 72 69 65 64 2e 20 49 66 20 69 74 20 72 65 74  tried. If it ret
b420: 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20 63  urns zero, the c
b430: 75 73 74 6f 6d 20 56 46 53 20 73 68 6f 75 6c 64  ustom VFS should
b440: 20 61 62 61 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20   abandon the.** 
b450: 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f  current operatio
b460: 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  n..**.** <li>[[S
b470: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50  QLITE_FCNTL_TEMP
b480: 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41  FILENAME]].** ^A
b490: 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 69  pplication can i
b4a0: 6e 76 6f 6b 65 20 74 68 65 20 5b 53 51 4c 49 54  nvoke the [SQLIT
b4b0: 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45  E_FCNTL_TEMPFILE
b4c0: 4e 41 4d 45 5d 20 66 69 6c 65 2d 63 6f 6e 74 72  NAME] file-contr
b4d0: 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76 65 20 53 51  ol.** to have SQ
b4e0: 4c 69 74 65 20 67 65 6e 65 72 61 74 65 20 61 0a  Lite generate a.
b4f0: 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  ** temporary fil
b500: 65 6e 61 6d 65 20 75 73 69 6e 67 20 74 68 65 20  ename using the 
b510: 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 74  same algorithm t
b520: 68 61 74 20 69 73 20 66 6f 6c 6c 6f 77 65 64 20  hat is followed 
b530: 74 6f 20 67 65 6e 65 72 61 74 65 0a 2a 2a 20 74  to generate.** t
b540: 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d  emporary filenam
b550: 65 73 20 66 6f 72 20 54 45 4d 50 20 74 61 62 6c  es for TEMP tabl
b560: 65 73 20 61 6e 64 20 6f 74 68 65 72 20 69 6e 74  es and other int
b570: 65 72 6e 61 6c 20 75 73 65 73 2e 20 20 54 68 65  ernal uses.  The
b580: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  .** argument sho
b590: 75 6c 64 20 62 65 20 61 20 63 68 61 72 2a 2a 20  uld be a char** 
b5a0: 77 68 69 63 68 20 77 69 6c 6c 20 62 65 20 66 69  which will be fi
b5b0: 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 66 69  lled with the fi
b5c0: 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72 69 74 74 65  lename.** writte
b5d0: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
b5e0: 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
b5f0: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20  ite3_malloc()]. 
b600: 20 54 68 65 20 63 61 6c 6c 65 72 20 73 68 6f 75   The caller shou
b610: 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20 5b 73 71  ld.** invoke [sq
b620: 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e  lite3_free()] on
b630: 20 74 68 65 20 72 65 73 75 6c 74 20 74 6f 20 61   the result to a
b640: 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65  void a memory le
b650: 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ak..**.** <li>[[
b660: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41  SQLITE_FCNTL_MMA
b670: 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20  P_SIZE]].** The 
b680: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d  [SQLITE_FCNTL_MM
b690: 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f  AP_SIZE] file co
b6a0: 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20 74 6f  ntrol is used to
b6b0: 20 71 75 65 72 79 20 6f 72 20 73 65 74 20 74 68   query or set th
b6c0: 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  e.** maximum num
b6d0: 62 65 72 20 6f 66 20 62 79 74 65 73 20 74 68 61  ber of bytes tha
b6e0: 74 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 66  t will be used f
b6f0: 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61 70 70 65 64  or memory-mapped
b700: 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20 61 72 67   I/O..** The arg
b710: 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
b720: 65 72 20 74 6f 20 61 20 76 61 6c 75 65 20 6f 66  er to a value of
b730: 20 74 79 70 65 20 73 71 6c 69 74 65 33 5f 69 6e   type sqlite3_in
b740: 74 36 34 20 74 68 61 74 0a 2a 2a 20 69 73 20 61  t64 that.** is a
b750: 6e 20 61 64 76 69 73 6f 72 79 20 6d 61 78 69 6d  n advisory maxim
b760: 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  um number of byt
b770: 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 20 74  es in the file t
b780: 6f 20 6d 65 6d 6f 72 79 20 6d 61 70 2e 20 20 54  o memory map.  T
b790: 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 73  he.** pointer is
b7a0: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74   overwritten wit
b7b0: 68 20 74 68 65 20 6f 6c 64 20 76 61 6c 75 65 2e  h the old value.
b7c0: 20 20 54 68 65 20 6c 69 6d 69 74 20 69 73 20 6e    The limit is n
b7d0: 6f 74 20 63 68 61 6e 67 65 64 20 69 66 0a 2a 2a  ot changed if.**
b7e0: 20 74 68 65 20 76 61 6c 75 65 20 6f 72 69 67 69   the value origi
b7f0: 6e 61 6c 6c 79 20 70 6f 69 6e 74 65 64 20 74 6f  nally pointed to
b800: 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 61 6e   is negative, an
b810: 64 20 73 6f 20 74 68 65 20 63 75 72 72 65 6e 74  d so the current
b820: 20 6c 69 6d 69 74 20 0a 2a 2a 20 63 61 6e 20 62   limit .** can b
b830: 65 20 71 75 65 72 69 65 64 20 62 79 20 70 61 73  e queried by pas
b840: 73 69 6e 67 20 69 6e 20 61 20 70 6f 69 6e 74 65  sing in a pointe
b850: 72 20 74 6f 20 61 20 6e 65 67 61 74 69 76 65 20  r to a negative 
b860: 6e 75 6d 62 65 72 2e 20 20 54 68 69 73 0a 2a 2a  number.  This.**
b870: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73   file-control is
b880: 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79   used internally
b890: 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 50   to implement [P
b8a0: 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d  RAGMA mmap_size]
b8b0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
b8c0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45  LITE_FCNTL_TRACE
b8d0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
b8e0: 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 66  E_FCNTL_TRACE] f
b8f0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 70 72 6f 76  ile control prov
b900: 69 64 65 73 20 61 64 76 69 73 6f 72 79 20 69 6e  ides advisory in
b910: 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20  formation.** to 
b920: 74 68 65 20 56 46 53 20 61 62 6f 75 74 20 77 68  the VFS about wh
b930: 61 74 20 74 68 65 20 68 69 67 68 65 72 20 6c 61  at the higher la
b940: 79 65 72 73 20 6f 66 20 74 68 65 20 53 51 4c 69  yers of the SQLi
b950: 74 65 20 73 74 61 63 6b 20 61 72 65 20 64 6f 69  te stack are doi
b960: 6e 67 2e 0a 2a 2a 20 54 68 69 73 20 66 69 6c 65  ng..** This file
b970: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64   control is used
b980: 20 62 79 20 73 6f 6d 65 20 56 46 53 20 61 63 74   by some VFS act
b990: 69 76 69 74 79 20 74 72 61 63 69 6e 67 20 5b 73  ivity tracing [s
b9a0: 68 69 6d 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 72  hims]..** The ar
b9b0: 67 75 6d 65 6e 74 20 69 73 20 61 20 7a 65 72 6f  gument is a zero
b9c0: 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
b9d0: 6e 67 2e 20 20 48 69 67 68 65 72 20 6c 61 79 65  ng.  Higher laye
b9e0: 72 73 20 69 6e 20 74 68 65 0a 2a 2a 20 53 51 4c  rs in the.** SQL
b9f0: 69 74 65 20 73 74 61 63 6b 20 6d 61 79 20 67 65  ite stack may ge
ba00: 6e 65 72 61 74 65 20 69 6e 73 74 61 6e 63 65 73  nerate instances
ba10: 20 6f 66 20 74 68 69 73 20 66 69 6c 65 20 63 6f   of this file co
ba20: 6e 74 72 6f 6c 20 69 66 0a 2a 2a 20 74 68 65 20  ntrol if.** the 
ba30: 5b 53 51 4c 49 54 45 5f 55 53 45 5f 46 43 4e 54  [SQLITE_USE_FCNT
ba40: 4c 5f 54 52 41 43 45 5d 20 63 6f 6d 70 69 6c 65  L_TRACE] compile
ba50: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20  -time option is 
ba60: 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  enabled..**.** <
ba70: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
ba80: 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 5d 0a 2a 2a  L_HAS_MOVED]].**
ba90: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
baa0: 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 20 66 69  TL_HAS_MOVED] fi
bab0: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 6e 74 65 72  le control inter
bac0: 70 72 65 74 73 20 69 74 73 20 61 72 67 75 6d 65  prets its argume
bad0: 6e 74 20 61 73 20 61 0a 2a 2a 20 70 6f 69 6e 74  nt as a.** point
bae0: 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
baf0: 20 61 6e 64 20 69 74 20 77 72 69 74 65 73 20 61   and it writes a
bb00: 20 62 6f 6f 6c 65 61 6e 20 69 6e 74 6f 20 74 68   boolean into th
bb10: 61 74 20 69 6e 74 65 67 65 72 20 64 65 70 65 6e  at integer depen
bb20: 64 69 6e 67 0a 2a 2a 20 6f 6e 20 77 68 65 74 68  ding.** on wheth
bb30: 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 66 69  er or not the fi
bb40: 6c 65 20 68 61 73 20 62 65 65 6e 20 72 65 6e 61  le has been rena
bb50: 6d 65 64 2c 20 6d 6f 76 65 64 2c 20 6f 72 20 64  med, moved, or d
bb60: 65 6c 65 74 65 64 20 73 69 6e 63 65 20 69 74 0a  eleted since it.
bb70: 2a 2a 20 77 61 73 20 66 69 72 73 74 20 6f 70 65  ** was first ope
bb80: 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ned..**.** <li>[
bb90: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49  [SQLITE_FCNTL_WI
bba0: 4e 33 32 5f 47 45 54 5f 48 41 4e 44 4c 45 5d 5d  N32_GET_HANDLE]]
bbb0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
bbc0: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f  FCNTL_WIN32_GET_
bbd0: 48 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 65 20 63  HANDLE] opcode c
bbe0: 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62  an be used to ob
bbf0: 74 61 69 6e 20 74 68 65 0a 2a 2a 20 75 6e 64 65  tain the.** unde
bc00: 72 6c 79 69 6e 67 20 6e 61 74 69 76 65 20 66 69  rlying native fi
bc10: 6c 65 20 68 61 6e 64 6c 65 20 61 73 73 6f 63 69  le handle associ
bc20: 61 74 65 64 20 77 69 74 68 20 61 20 66 69 6c 65  ated with a file
bc30: 20 68 61 6e 64 6c 65 2e 20 20 54 68 69 73 20 66   handle.  This f
bc40: 69 6c 65 0a 2a 2a 20 63 6f 6e 74 72 6f 6c 20 69  ile.** control i
bc50: 6e 74 65 72 70 72 65 74 73 20 69 74 73 20 61 72  nterprets its ar
bc60: 67 75 6d 65 6e 74 20 61 73 20 61 20 70 6f 69 6e  gument as a poin
bc70: 74 65 72 20 74 6f 20 61 20 6e 61 74 69 76 65 20  ter to a native 
bc80: 66 69 6c 65 20 68 61 6e 64 6c 65 20 61 6e 64 0a  file handle and.
bc90: 2a 2a 20 77 72 69 74 65 73 20 74 68 65 20 72 65  ** writes the re
bca0: 73 75 6c 74 69 6e 67 20 76 61 6c 75 65 20 74 68  sulting value th
bcb0: 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ere..**.** <li>[
bcc0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49  [SQLITE_FCNTL_WI
bcd0: 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 5d  N32_SET_HANDLE]]
bce0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
bcf0: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f  FCNTL_WIN32_SET_
bd00: 48 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 65 20 69  HANDLE] opcode i
bd10: 73 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67  s used for debug
bd20: 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f  ging.  This.** o
bd30: 70 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65  pcode causes the
bd40: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
bd50: 74 68 6f 64 20 74 6f 20 73 77 61 70 20 74 68 65  thod to swap the
bd60: 20 66 69 6c 65 20 68 61 6e 64 6c 65 20 77 69 74   file handle wit
bd70: 68 20 74 68 65 20 6f 6e 65 0a 2a 2a 20 70 6f 69  h the one.** poi
bd80: 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 70  nted to by the p
bd90: 41 72 67 20 61 72 67 75 6d 65 6e 74 2e 20 20 54  Arg argument.  T
bda0: 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 20 69  his capability i
bdb0: 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65  s used during te
bdc0: 73 74 69 6e 67 0a 2a 2a 20 61 6e 64 20 6f 6e 6c  sting.** and onl
bdd0: 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75  y needs to be su
bde0: 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c  pported when SQL
bdf0: 49 54 45 5f 54 45 53 54 20 69 73 20 64 65 66 69  ITE_TEST is defi
be00: 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ned..**.** <li>[
be10: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41  [SQLITE_FCNTL_WA
be20: 4c 5f 42 4c 4f 43 4b 5d 5d 0a 2a 2a 20 54 68 65  L_BLOCK]].** The
be30: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57   [SQLITE_FCNTL_W
be40: 41 4c 5f 42 4c 4f 43 4b 5d 20 69 73 20 61 20 73  AL_BLOCK] is a s
be50: 69 67 6e 61 6c 20 74 6f 20 74 68 65 20 56 46 53  ignal to the VFS
be60: 20 6c 61 79 65 72 20 74 68 61 74 20 69 74 20 6d   layer that it m
be70: 69 67 68 74 0a 2a 2a 20 62 65 20 61 64 76 61 6e  ight.** be advan
be80: 74 61 67 65 6f 75 73 20 74 6f 20 62 6c 6f 63 6b  tageous to block
be90: 20 6f 6e 20 74 68 65 20 6e 65 78 74 20 57 41 4c   on the next WAL
bea0: 20 6c 6f 63 6b 20 69 66 20 74 68 65 20 6c 6f 63   lock if the loc
beb0: 6b 20 69 73 20 6e 6f 74 20 69 6d 6d 65 64 69 61  k is not immedia
bec0: 74 65 6c 79 0a 2a 2a 20 61 76 61 69 6c 61 62 6c  tely.** availabl
bed0: 65 2e 20 20 54 68 65 20 57 41 4c 20 73 75 62 73  e.  The WAL subs
bee0: 79 73 74 65 6d 20 69 73 73 75 65 73 20 74 68 69  ystem issues thi
bef0: 73 20 73 69 67 6e 61 6c 20 64 75 72 69 6e 67 20  s signal during 
bf00: 72 61 72 65 0a 2a 2a 20 63 69 72 63 75 6d 73 74  rare.** circumst
bf10: 61 6e 63 65 73 20 69 6e 20 6f 72 64 65 72 20 74  ances in order t
bf20: 6f 20 66 69 78 20 61 20 70 72 6f 62 6c 65 6d 20  o fix a problem 
bf30: 77 69 74 68 20 70 72 69 6f 72 69 74 79 20 69 6e  with priority in
bf40: 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 41 70 70 6c  version..** Appl
bf50: 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
bf60: 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20 75 73 65  <em>not</em> use
bf70: 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72   this file-contr
bf80: 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ol..**.** <li>[[
bf90: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50  SQLITE_FCNTL_ZIP
bfa0: 56 46 53 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  VFS]].** The [SQ
bfb0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46  LITE_FCNTL_ZIPVF
bfc0: 53 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6d 70  S] opcode is imp
bfd0: 6c 65 6d 65 6e 74 65 64 20 62 79 20 7a 69 70 76  lemented by zipv
bfe0: 66 73 20 6f 6e 6c 79 2e 20 41 6c 6c 20 6f 74 68  fs only. All oth
bff0: 65 72 0a 2a 2a 20 56 46 53 20 73 68 6f 75 6c 64  er.** VFS should
c000: 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e   return SQLITE_N
c010: 4f 54 46 4f 55 4e 44 20 66 6f 72 20 74 68 69 73  OTFOUND for this
c020: 20 6f 70 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 3c   opcode..**.** <
c030: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
c040: 4c 5f 52 42 55 5d 5d 0a 2a 2a 20 54 68 65 20 5b  L_RBU]].** The [
c050: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55  SQLITE_FCNTL_RBU
c060: 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6d 70 6c  ] opcode is impl
c070: 65 6d 65 6e 74 65 64 20 62 79 20 74 68 65 20 73  emented by the s
c080: 70 65 63 69 61 6c 20 56 46 53 20 75 73 65 64 20  pecial VFS used 
c090: 62 79 0a 2a 2a 20 74 68 65 20 52 42 55 20 65 78  by.** the RBU ex
c0a0: 74 65 6e 73 69 6f 6e 20 6f 6e 6c 79 2e 20 20 41  tension only.  A
c0b0: 6c 6c 20 6f 74 68 65 72 20 56 46 53 20 73 68 6f  ll other VFS sho
c0c0: 75 6c 64 20 72 65 74 75 72 6e 20 53 51 4c 49 54  uld return SQLIT
c0d0: 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f 72 0a 2a  E_NOTFOUND for.*
c0e0: 2a 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 20  * this opcode.  
c0f0: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65  .** </ul>.*/.#de
c100: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c110: 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20  L_LOCKSTATE     
c120: 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66            1.#def
c130: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c140: 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _GET_LOCKPROXYFI
c150: 4c 45 20 20 20 20 20 20 20 32 0a 23 64 65 66 69  LE       2.#defi
c160: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c170: 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  SET_LOCKPROXYFIL
c180: 45 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e  E       3.#defin
c190: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c  e SQLITE_FCNTL_L
c1a0: 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20  AST_ERRNO       
c1b0: 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65         4.#define
c1c0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49   SQLITE_FCNTL_SI
c1d0: 5a 45 5f 48 49 4e 54 20 20 20 20 20 20 20 20 20  ZE_HINT         
c1e0: 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20        5.#define 
c1f0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55  SQLITE_FCNTL_CHU
c200: 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20  NK_SIZE         
c210: 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53       6.#define S
c220: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45  QLITE_FCNTL_FILE
c230: 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20  _POINTER        
c240: 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51      7.#define SQ
c250: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f  LITE_FCNTL_SYNC_
c260: 4f 4d 49 54 54 45 44 20 20 20 20 20 20 20 20 20  OMITTED         
c270: 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c     8.#define SQL
c280: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
c290: 41 56 5f 52 45 54 52 59 20 20 20 20 20 20 20 20  AV_RETRY        
c2a0: 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    9.#define SQLI
c2b0: 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54  TE_FCNTL_PERSIST
c2c0: 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20  _WAL            
c2d0: 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  10.#define SQLIT
c2e0: 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54  E_FCNTL_OVERWRIT
c2f0: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31  E              1
c300: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
c310: 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 20  _FCNTL_VFSNAME  
c320: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 32                12
c330: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c340: 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f  FCNTL_POWERSAFE_
c350: 4f 56 45 52 57 52 49 54 45 20 20 20 20 31 33 0a  OVERWRITE    13.
c360: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c370: 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20 20 20  CNTL_PRAGMA     
c380: 20 20 20 20 20 20 20 20 20 20 20 20 31 34 0a 23              14.#
c390: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
c3a0: 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 20  NTL_BUSYHANDLER 
c3b0: 20 20 20 20 20 20 20 20 20 20 20 31 35 0a 23 64             15.#d
c3c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
c3d0: 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 20  TL_TEMPFILENAME 
c3e0: 20 20 20 20 20 20 20 20 20 20 31 36 0a 23 64 65            16.#de
c3f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c400: 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 20  L_MMAP_SIZE     
c410: 20 20 20 20 20 20 20 20 20 31 38 0a 23 64 65 66           18.#def
c420: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c430: 5f 54 52 41 43 45 20 20 20 20 20 20 20 20 20 20  _TRACE          
c440: 20 20 20 20 20 20 20 20 31 39 0a 23 64 65 66 69          19.#defi
c450: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c460: 48 41 53 5f 4d 4f 56 45 44 20 20 20 20 20 20 20  HAS_MOVED       
c470: 20 20 20 20 20 20 20 32 30 0a 23 64 65 66 69 6e         20.#defin
c480: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  e SQLITE_FCNTL_S
c490: 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20  YNC             
c4a0: 20 20 20 20 20 20 32 31 0a 23 64 65 66 69 6e 65        21.#define
c4b0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f   SQLITE_FCNTL_CO
c4c0: 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 20 20 20  MMIT_PHASETWO   
c4d0: 20 20 20 20 20 32 32 0a 23 64 65 66 69 6e 65 20       22.#define 
c4e0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
c4f0: 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 20 20 20  32_SET_HANDLE   
c500: 20 20 20 20 32 33 0a 23 64 65 66 69 6e 65 20 53      23.#define S
c510: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f  QLITE_FCNTL_WAL_
c520: 42 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  BLOCK           
c530: 20 20 20 32 34 0a 23 64 65 66 69 6e 65 20 53 51     24.#define SQ
c540: 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46  LITE_FCNTL_ZIPVF
c550: 53 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  S               
c560: 20 20 32 35 0a 23 64 65 66 69 6e 65 20 53 51 4c    25.#define SQL
c570: 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 20 20 20  ITE_FCNTL_RBU   
c580: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
c590: 20 32 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   26.#define SQLI
c5a0: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49  TE_FCNTL_VFS_POI
c5b0: 4e 54 45 52 20 20 20 20 20 20 20 20 20 20 20 20  NTER            
c5c0: 32 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  27.#define SQLIT
c5d0: 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f  E_FCNTL_JOURNAL_
c5e0: 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 32  POINTER        2
c5f0: 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
c600: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54  _FCNTL_WIN32_GET
c610: 5f 48 41 4e 44 4c 45 20 20 20 20 20 20 20 32 39  _HANDLE       29
c620: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c630: 46 43 4e 54 4c 5f 50 44 42 20 20 20 20 20 20 20  FCNTL_PDB       
c640: 20 20 20 20 20 20 20 20 20 20 20 20 20 33 30 0a               30.
c650: 0a 2f 2a 20 64 65 70 72 65 63 61 74 65 64 20 6e  ./* deprecated n
c660: 61 6d 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ames */.#define 
c670: 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50  SQLITE_GET_LOCKP
c680: 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 53 51  ROXYFILE      SQ
c690: 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c  LITE_FCNTL_GET_L
c6a0: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65  OCKPROXYFILE.#de
c6b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f  fine SQLITE_SET_
c6c0: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20  LOCKPROXYFILE   
c6d0: 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f     SQLITE_FCNTL_
c6e0: 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  SET_LOCKPROXYFIL
c6f0: 45 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  E.#define SQLITE
c700: 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20  _LAST_ERRNO     
c710: 20 20 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46          SQLITE_F
c720: 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 0a  CNTL_LAST_ERRNO.
c730: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
c740: 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a  : Mutex Handle.*
c750: 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d  *.** The mutex m
c760: 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c  odule within SQL
c770: 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c  ite defines [sql
c780: 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62  ite3_mutex] to b
c790: 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74  e an.** abstract
c7a0: 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65   type for a mute
c7b0: 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53  x object.  The S
c7c0: 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72  QLite core never
c7d0: 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65   looks.** at the
c7e0: 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73   internal repres
c7f0: 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b  entation of an [
c800: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20  sqlite3_mutex]. 
c810: 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c   It only.** deal
c820: 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20  s with pointers 
c830: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
c840: 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a  mutex] object..*
c850: 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65  *.** Mutexes are
c860: 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b   created using [
c870: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c  sqlite3_mutex_al
c880: 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64  loc()]..*/.typed
c890: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
c8a0: 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f  3_mutex sqlite3_
c8b0: 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  mutex;../*.** CA
c8c0: 50 49 33 52 45 46 3a 20 4c 6f 61 64 61 62 6c 65  PI3REF: Loadable
c8d0: 20 45 78 74 65 6e 73 69 6f 6e 20 54 68 75 6e 6b   Extension Thunk
c8e0: 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72  .**.** A pointer
c8f0: 20 74 6f 20 74 68 65 20 6f 70 61 71 75 65 20 73   to the opaque s
c900: 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74 69  qlite3_api_routi
c910: 6e 65 73 20 73 74 72 75 63 74 75 72 65 20 69 73  nes structure is
c920: 20 70 61 73 73 65 64 20 61 73 0a 2a 2a 20 74 68   passed as.** th
c930: 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
c940: 72 20 74 6f 20 65 6e 74 72 79 20 70 6f 69 6e 74  r to entry point
c950: 73 20 6f 66 20 5b 6c 6f 61 64 61 62 6c 65 20 65  s of [loadable e
c960: 78 74 65 6e 73 69 6f 6e 73 5d 2e 20 20 54 68 69  xtensions].  Thi
c970: 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 6d  s.** structure m
c980: 75 73 74 20 62 65 20 74 79 70 65 64 65 66 65 64  ust be typedefed
c990: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 77 6f 72   in order to wor
c9a0: 6b 20 61 72 6f 75 6e 64 20 63 6f 6d 70 69 6c 65  k around compile
c9b0: 72 20 77 61 72 6e 69 6e 67 73 0a 2a 2a 20 6f 6e  r warnings.** on
c9c0: 20 73 6f 6d 65 20 70 6c 61 74 66 6f 72 6d 73 2e   some platforms.
c9d0: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
c9e0: 63 74 20 73 71 6c 69 74 65 33 5f 61 70 69 5f 72  ct sqlite3_api_r
c9f0: 6f 75 74 69 6e 65 73 20 73 71 6c 69 74 65 33 5f  outines sqlite3_
ca00: 61 70 69 5f 72 6f 75 74 69 6e 65 73 3b 0a 0a 2f  api_routines;../
ca10: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
ca20: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65  S Interface Obje
ca30: 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  ct.**.** An inst
ca40: 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69  ance of the sqli
ca50: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64  te3_vfs object d
ca60: 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72  efines the inter
ca70: 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20  face between.** 
ca80: 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  the SQLite core 
ca90: 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69  and the underlyi
caa0: 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  ng operating sys
cab0: 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a  tem.  The "vfs".
cac0: 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f  ** in the name o
cad0: 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61  f the object sta
cae0: 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c  nds for "virtual
caf0: 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 20 20   file system".  
cb00: 53 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20  See.** the [VFS 
cb10: 7c 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 61 74  | VFS documentat
cb20: 69 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 65 72  ion] for further
cb30: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
cb40: 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66  .** The value of
cb50: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69   the iVersion fi
cb60: 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79  eld is initially
cb70: 20 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61   1 but may be la
cb80: 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72  rger in.** futur
cb90: 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
cba0: 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61  Lite.  Additiona
cbb0: 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20  l fields may be 
cbc0: 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73  appended to this
cbd0: 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20  .** object when 
cbe0: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c  the iVersion val
cbf0: 75 65 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e  ue is increased.
cc00: 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20    Note that the 
cc10: 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20  structure.** of 
cc20: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20  the sqlite3_vfs 
cc30: 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69  object changes i
cc40: 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  n the transactio
cc50: 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c  n between.** SQL
cc60: 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
cc70: 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20  9 and 3.6.0 and 
cc80: 79 65 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e  yet the iVersion
cc90: 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a   field was not.*
cca0: 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a  * modified..**.*
ccb0: 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66  * The szOsFile f
ccc0: 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65  ield is the size
ccd0: 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 73   of the subclass
cce0: 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ed [sqlite3_file
ccf0: 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75  ].** structure u
cd00: 73 65 64 20 62 79 20 74 68 69 73 20 56 46 53 2e  sed by this VFS.
cd10: 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20    mxPathname is 
cd20: 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  the maximum leng
cd30: 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e  th of.** a pathn
cd40: 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e  ame in this VFS.
cd50: 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65  .**.** Registere
cd60: 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62  d sqlite3_vfs ob
cd70: 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f  jects are kept o
cd80: 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20  n a linked list 
cd90: 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65  formed by.** the
cda0: 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20   pNext pointer. 
cdb0: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   The [sqlite3_vf
cdc0: 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a  s_register()].**
cdd0: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66   and [sqlite3_vf
cde0: 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20  s_unregister()] 
cdf0: 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67  interfaces manag
ce00: 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69  e this list.** i
ce10: 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 20  n a thread-safe 
ce20: 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  way.  The [sqlit
ce30: 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69  e3_vfs_find()] i
ce40: 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72  nterface.** sear
ce50: 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20  ches the list.  
ce60: 4e 65 69 74 68 65 72 20 74 68 65 20 61 70 70 6c  Neither the appl
ce70: 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72  ication code nor
ce80: 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c   the VFS.** impl
ce90: 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c  ementation shoul
cea0: 64 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 20  d use the pNext 
ceb0: 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  pointer..**.** T
cec0: 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69  he pNext field i
ced0: 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64  s the only field
cee0: 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f   in the sqlite3_
cef0: 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  vfs.** structure
cf00: 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
cf10: 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20  l ever modify.  
cf20: 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79  SQLite will only
cf30: 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f   access.** or mo
cf40: 64 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 20  dify this field 
cf50: 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20  while holding a 
cf60: 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 69  particular stati
cf70: 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20  c mutex..** The 
cf80: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
cf90: 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20  ld never modify 
cfa0: 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20  anything within 
cfb0: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a  the sqlite3_vfs.
cfc0: 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74  ** object once t
cfd0: 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65  he object has be
cfe0: 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a  en registered..*
cff0: 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66  *.** The zName f
d000: 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e  ield holds the n
d010: 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d  ame of the VFS m
d020: 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65  odule.  The name
d030: 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71   must.** be uniq
d040: 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46  ue across all VF
d050: 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a  S modules..**.**
d060: 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78   [[sqlite3_vfs.x
d070: 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74  Open]].** ^SQLit
d080: 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  e guarantees tha
d090: 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20  t the zFilename 
d0a0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70  parameter to xOp
d0b0: 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20  en.** is either 
d0c0: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f  a NULL pointer o
d0d0: 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65  r string obtaine
d0e0: 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50  d.** from xFullP
d0f0: 61 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20 61  athname() with a
d100: 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66 69  n optional suffi
d110: 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20  x added..** ^If 
d120: 61 20 73 75 66 66 69 78 20 69 73 20 61 64 64 65  a suffix is adde
d130: 64 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61  d to the zFilena
d140: 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69 74  me parameter, it
d150: 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74   will.** consist
d160: 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d 22   of a single "-"
d170: 20 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f   character follo
d180: 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74  wed by no more t
d190: 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e  han.** 11 alphan
d1a0: 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d  umeric and/or "-
d1b0: 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  " characters..**
d1c0: 20 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65 72   ^SQLite further
d1d0: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
d1e0: 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77  .** the string w
d1f0: 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64  ill be valid and
d200: 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c   unchanged until
d210: 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20   xClose() is.** 
d220: 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20  called. Because 
d230: 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  of the previous 
d240: 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65  sentence,.** the
d250: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
d260: 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65  can safely store
d270: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
d280: 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66  e.** filename if
d290: 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d   it needs to rem
d2a0: 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61  ember the filena
d2b0: 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73  me for some reas
d2c0: 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46  on..** If the zF
d2d0: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
d2e0: 72 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 20  r to xOpen is a 
d2f0: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
d300: 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20  n xOpen.** must 
d310: 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74  invent its own t
d320: 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f  emporary name fo
d330: 72 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57 68  r the file.  ^Wh
d340: 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78  enever the .** x
d350: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
d360: 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69  er is NULL it wi
d370: 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63  ll also be the c
d380: 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ase that the.** 
d390: 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20  flags parameter 
d3a0: 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51  will include [SQ
d3b0: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
d3c0: 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20  ONCLOSE]..**.** 
d3d0: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
d3e0: 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e  nt to xOpen() in
d3f0: 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20  cludes all bits 
d400: 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c  set in.** the fl
d410: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
d420: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
d430: 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c  ()].  Or if [sql
d440: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20  ite3_open()].** 
d450: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  or [sqlite3_open
d460: 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74  16()] is used, t
d470: 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64  hen flags includ
d480: 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b  es at least.** [
d490: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
d4a0: 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45  WRITE] | [SQLITE
d4b0: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a  _OPEN_CREATE]. .
d4c0: 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70  ** If xOpen() op
d4d0: 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d  ens a file read-
d4e0: 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74  only then it set
d4f0: 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a  s *pOutFlags to.
d500: 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49  ** include [SQLI
d510: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
d520: 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20 69  ].  Other bits i
d530: 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79  n *pOutFlags may
d540: 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e   be set..**.** ^
d550: 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73  (SQLite will als
d560: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65  o add one of the
d570: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73   following flags
d580: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a   to the xOpen().
d590: 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69  ** call, dependi
d5a0: 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74  ng on the object
d5b0: 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a   being opened:.*
d5c0: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
d5d0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
d5e0: 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e  MAIN_DB].** <li>
d5f0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
d600: 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  AIN_JOURNAL].** 
d610: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
d620: 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c  EN_TEMP_DB].** <
d630: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
d640: 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a  N_TEMP_JOURNAL].
d650: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
d660: 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f  _OPEN_TRANSIENT_
d670: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  DB].** <li>  [SQ
d680: 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55  LITE_OPEN_SUBJOU
d690: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
d6a0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54  SQLITE_OPEN_MAST
d6b0: 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  ER_JOURNAL].** <
d6c0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
d6d0: 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29  N_WAL].** </ul>)
d6e0: 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65  ^.**.** The file
d6f0: 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74   I/O implementat
d700: 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20  ion can use the 
d710: 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67  object type flag
d720: 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74  s to.** change t
d730: 68 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20  he way it deals 
d740: 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72  with files.  For
d750: 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70   example, an app
d760: 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74  lication.** that
d770: 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61   does not care a
d780: 62 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76  bout crash recov
d790: 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20  ery or rollback 
d7a0: 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68  might make.** th
d7b0: 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72  e open of a jour
d7c0: 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70  nal file a no-op
d7d0: 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 69  .  Writes to thi
d7e0: 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a  s journal would.
d7f0: 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70  ** also be no-op
d800: 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d  s, and any attem
d810: 70 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a  pt to read the j
d820: 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74  ournal would ret
d830: 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f  urn.** SQLITE_IO
d840: 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70  ERR.  Or the imp
d850: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68  lementation migh
d860: 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74  t recognize that
d870: 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66   a database.** f
d880: 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e  ile will be doin
d890: 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73  g page-aligned s
d8a0: 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20  ector reads and 
d8b0: 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64  writes in a rand
d8c0: 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20  om.** order and 
d8d0: 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73  set up its I/O s
d8e0: 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69  ubsystem accordi
d8f0: 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  ngly..**.** SQLi
d900: 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64  te might also ad
d910: 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  d one of the fol
d920: 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20  lowing flags to 
d930: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  the xOpen method
d940: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
d950: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45  <li> [SQLITE_OPE
d960: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
d970: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
d980: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d  _OPEN_EXCLUSIVE]
d990: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
d9a0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
d9b0: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20  _DELETEONCLOSE] 
d9c0: 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66  flag means the f
d9d0: 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a  ile should be.**
d9e0: 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74   deleted when it
d9f0: 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68   is closed.  ^Th
da00: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  e [SQLITE_OPEN_D
da10: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a  ELETEONCLOSE].**
da20: 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72   will be set for
da30: 20 54 45 4d 50 20 64 61 74 61 62 61 73 65 73 20   TEMP databases 
da40: 61 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e 61  and their journa
da50: 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a  ls, transient.**
da60: 20 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64 20   databases, and 
da70: 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a  subjournals..**.
da80: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
da90: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20  OPEN_EXCLUSIVE] 
daa0: 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20 75  flag is always u
dab0: 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69  sed in conjuncti
dac0: 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  on.** with the [
dad0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
dae0: 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20  TE] flag, which 
daf0: 61 72 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c  are both directl
db00: 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74  y.** analogous t
db10: 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64  o the O_EXCL and
db20: 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f   O_CREAT flags o
db30: 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e  f the POSIX open
db40: 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20  ().** API.  The 
db50: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
db60: 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e  USIVE flag, when
db70: 20 70 61 69 72 65 64 20 77 69 74 68 20 74 68 65   paired with the
db80: 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e   .** SQLITE_OPEN
db90: 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73 65 64  _CREATE, is used
dba0: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61   to indicate tha
dbb0: 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c  t file should al
dbc0: 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74  ways.** be creat
dbd0: 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20  ed, and that it 
dbe0: 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69  is an error if i
dbf0: 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 73  t already exists
dc00: 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f  ..** It is <i>no
dc10: 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e  t</i> used to in
dc20: 64 69 63 61 74 65 20 74 68 65 20 66 69 6c 65 20  dicate the file 
dc30: 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64  should be opened
dc40: 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69   .** for exclusi
dc50: 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a  ve access..**.**
dc60: 20 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46   ^At least szOsF
dc70: 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d  ile bytes of mem
dc80: 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65  ory are allocate
dc90: 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74  d by SQLite.** t
dca0: 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c  o hold the  [sql
dcb0: 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63  ite3_file] struc
dcc0: 74 75 72 65 20 70 61 73 73 65 64 20 61 73 20 74  ture passed as t
dcd0: 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75  he third.** argu
dce0: 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20  ment to xOpen.  
dcf0: 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  The xOpen method
dd00: 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74   does not have t
dd10: 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68  o.** allocate th
dd20: 65 20 73 74 72 75 63 74 75 72 65 3b 20 69 74 20  e structure; it 
dd30: 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c  should just fill
dd40: 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68   it in.  Note th
dd50: 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20  at.** the xOpen 
dd60: 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20  method must set 
dd70: 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  the sqlite3_file
dd80: 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74  .pMethods to eit
dd90: 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b  her.** a valid [
dda0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
ddb0: 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f  ds] object or to
ddc0: 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75   NULL.  xOpen mu
ddd0: 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76  st do.** this ev
dde0: 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66  en if the open f
ddf0: 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78  ails.  SQLite ex
de00: 70 65 63 74 73 20 74 68 61 74 20 74 68 65 20 73  pects that the s
de10: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74  qlite3_file.pMet
de20: 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20  hods.** element 
de30: 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66  will be valid af
de40: 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e  ter xOpen return
de50: 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  s regardless of 
de60: 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f  the success.** o
de70: 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65  r failure of the
de80: 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a   xOpen call..**.
de90: 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73  ** [[sqlite3_vfs
dea0: 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54  .xAccess]].** ^T
deb0: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
dec0: 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d  t to xAccess() m
ded0: 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43  ay be [SQLITE_AC
dee0: 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20  CESS_EXISTS].** 
def0: 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 20  to test for the 
df00: 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66  existence of a f
df10: 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ile, or [SQLITE_
df20: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
df30: 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65  ] to.** test whe
df40: 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 72  ther a file is r
df50: 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74  eadable and writ
df60: 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45  able, or [SQLITE
df70: 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a  _ACCESS_READ].**
df80: 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65 72   to test whether
df90: 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65   a file is at le
dfa0: 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20  ast readable.   
dfb0: 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20  The file can be 
dfc0: 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a  a.** directory..
dfd0: 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  **.** ^SQLite wi
dfe0: 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61  ll always alloca
dff0: 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61  te at least mxPa
e000: 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66  thname+1 bytes f
e010: 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74  or the.** output
e020: 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74   buffer xFullPat
e030: 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63  hname.  The exac
e040: 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75  t size of the ou
e050: 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69  tput buffer.** i
e060: 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73  s also passed as
e070: 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   a parameter to 
e080: 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49  both  methods. I
e090: 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66  f the output buf
e0a0: 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61  fer.** is not la
e0b0: 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c  rge enough, [SQL
e0c0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68  ITE_CANTOPEN] sh
e0d0: 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64  ould be returned
e0e0: 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a  . Since this is.
e0f0: 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20  ** handled as a 
e100: 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53  fatal error by S
e110: 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65  QLite, vfs imple
e120: 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c  mentations shoul
e130: 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f  d endeavor.** to
e140: 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79   prevent this by
e150: 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e   setting mxPathn
e160: 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 69  ame to a suffici
e170: 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75  ently large valu
e180: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61  e..**.** The xRa
e190: 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65  ndomness(), xSle
e1a0: 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69  ep(), xCurrentTi
e1b0: 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65  me(), and xCurre
e1c0: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a  ntTimeInt64().**
e1d0: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
e1e0: 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20 70  not strictly a p
e1f0: 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73  art of the files
e200: 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20  ystem, but they 
e210: 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20  are.** included 
e220: 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 75 63  in the VFS struc
e230: 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74  ture for complet
e240: 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52  eness..** The xR
e250: 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63  andomness() func
e260: 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f  tion attempts to
e270: 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62   return nBytes b
e280: 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d  ytes.** of good-
e290: 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65  quality randomne
e2a0: 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54  ss into zOut.  T
e2b0: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
e2c0: 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c  is.** the actual
e2d0: 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
e2e0: 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f   of randomness o
e2f0: 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20  btained..** The 
e300: 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20  xSleep() method 
e310: 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69  causes the calli
e320: 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65  ng thread to sle
e330: 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61  ep for at.** lea
e340: 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  st the number of
e350: 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69   microseconds gi
e360: 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72  ven.  ^The xCurr
e370: 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74  entTime().** met
e380: 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75  hod returns a Ju
e390: 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20  lian Day Number 
e3a0: 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20  for the current 
e3b0: 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73  date and time as
e3c0: 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70  .** a floating p
e3d0: 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e  oint value..** ^
e3e0: 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  The xCurrentTime
e3f0: 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72  Int64() method r
e400: 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e  eturns, as an in
e410: 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61  teger, the Julia
e420: 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20  n.** Day Number 
e430: 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38 36  multiplied by 86
e440: 34 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62  400000 (the numb
e450: 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  er of millisecon
e460: 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68  ds in .** a 24-h
e470: 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e  our day).  .** ^
e480: 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
e490: 74 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  the xCurrentTime
e4a0: 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74  Int64() method t
e4b0: 6f 20 67 65 74 20 74 68 65 20 63 75 72 72 65 6e  o get the curren
e4c0: 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69  t.** date and ti
e4d0: 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f  me if that metho
e4e0: 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28  d is available (
e4f0: 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32  if iVersion is 2
e500: 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20   or .** greater 
e510: 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  and the function
e520: 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
e530: 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66  NULL) and will f
e540: 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78  all back.** to x
e550: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66  CurrentTime() if
e560: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74   xCurrentTimeInt
e570: 36 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61  64() is unavaila
e580: 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ble..**.** ^The 
e590: 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29  xSetSystemCall()
e5a0: 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c  , xGetSystemCall
e5b0: 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73  (), and xNestSys
e5c0: 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66  temCall() interf
e5d0: 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20  aces.** are not 
e5e0: 75 73 65 64 20 62 79 20 74 68 65 20 53 51 4c 69  used by the SQLi
e5f0: 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20  te core.  These 
e600: 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61  optional interfa
e610: 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64  ces are provided
e620: 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65  .** by some VFSe
e630: 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20  s to facilitate 
e640: 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56  testing of the V
e650: 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72  FS code. By over
e660: 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65  riding .** syste
e670: 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e  m calls with fun
e680: 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73  ctions under its
e690: 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74   control, a test
e6a0: 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20   program can.** 
e6b0: 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20  simulate faults 
e6c0: 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74  and error condit
e6d0: 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20  ions that would 
e6e0: 6f 74 68 65 72 77 69 73 65 20 62 65 20 64 69 66  otherwise be dif
e6f0: 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70  ficult.** or imp
e700: 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63  ossible to induc
e710: 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20 73  e.  The set of s
e720: 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74  ystem calls that
e730: 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64   can be overridd
e740: 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f  en.** varies fro
e750: 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f  m one VFS to ano
e760: 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f  ther, and from o
e770: 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68  ne version of th
e780: 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68  e same VFS to th
e790: 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c  e.** next.  Appl
e7a0: 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73  ications that us
e7b0: 65 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  e these interfac
e7c0: 65 73 20 6d 75 73 74 20 62 65 20 70 72 65 70 61  es must be prepa
e7d0: 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f  red for any.** o
e7e0: 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69  r all of these i
e7f0: 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62 65 20  nterfaces to be 
e800: 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69  NULL or for thei
e810: 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68  r behavior to ch
e820: 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65  ange.** from one
e830: 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20   release to the 
e840: 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69  next.  Applicati
e850: 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74  ons must not att
e860: 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a  empt to access.*
e870: 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d  * any of these m
e880: 65 74 68 6f 64 73 20 69 66 20 74 68 65 20 69 56  ethods if the iV
e890: 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46  ersion of the VF
e8a0: 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33  S is less than 3
e8b0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
e8c0: 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20  uct sqlite3_vfs 
e8d0: 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70  sqlite3_vfs;.typ
e8e0: 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69  edef void (*sqli
e8f0: 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29  te3_syscall_ptr)
e900: 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73  (void);.struct s
e910: 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69  qlite3_vfs {.  i
e920: 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20  nt iVersion;    
e930: 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63          /* Struc
e940: 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d  ture version num
e950: 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33  ber (currently 3
e960: 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46  ) */.  int szOsF
e970: 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20  ile;            
e980: 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c  /* Size of subcl
e990: 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69  assed sqlite3_fi
e9a0: 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61  le */.  int mxPa
e9b0: 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20  thname;         
e9c0: 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65   /* Maximum file
e9d0: 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68   pathname length
e9e0: 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66   */.  sqlite3_vf
e9f0: 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f  s *pNext;      /
ea00: 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65  * Next registere
ea10: 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74  d VFS */.  const
ea20: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20   char *zName;   
ea30: 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74      /* Name of t
ea40: 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65  his virtual file
ea50: 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69   system */.  voi
ea60: 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20  d *pAppData;    
ea70: 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72        /* Pointer
ea80: 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   to application-
ea90: 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f  specific data */
eaa0: 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28  .  int (*xOpen)(
eab0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
eac0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
ead0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a   sqlite3_file*,.
eae0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69                 i
eaf0: 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70  nt flags, int *p
eb00: 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74  OutFlags);.  int
eb10: 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69   (*xDelete)(sqli
eb20: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
eb30: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
eb40: 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74   syncDir);.  int
eb50: 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69   (*xAccess)(sqli
eb60: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
eb70: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
eb80: 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65   flags, int *pRe
eb90: 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sOut);.  int (*x
eba0: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71  FullPathname)(sq
ebb0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
ebc0: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
ebd0: 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a  nt nOut, char *z
ebe0: 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a  Out);.  void *(*
ebf0: 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33  xDlOpen)(sqlite3
ec00: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
ec10: 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20  r *zFilename);. 
ec20: 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72   void (*xDlError
ec30: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
ec40: 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20  int nByte, char 
ec50: 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69  *zErrMsg);.  voi
ec60: 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71  d (*(*xDlSym)(sq
ec70: 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a  lite3_vfs*,void*
ec80: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53  , const char *zS
ec90: 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20  ymbol))(void);. 
eca0: 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65   void (*xDlClose
ecb0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
ecc0: 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  void*);.  int (*
ecd0: 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c  xRandomness)(sql
ece0: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e  ite3_vfs*, int n
ecf0: 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74  Byte, char *zOut
ed00: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65  );.  int (*xSlee
ed10: 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  p)(sqlite3_vfs*,
ed20: 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64   int microsecond
ed30: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72  s);.  int (*xCur
ed40: 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65  rentTime)(sqlite
ed50: 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29  3_vfs*, double*)
ed60: 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61  ;.  int (*xGetLa
ed70: 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33  stError)(sqlite3
ed80: 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72  _vfs*, int, char
ed90: 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54   *);.  /*.  ** T
eda0: 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  he methods above
edb0: 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20   are in version 
edc0: 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f  1 of the sqlite_
edd0: 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20  vfs object.  ** 
ede0: 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f  definition.  Tho
edf0: 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61  se that follow a
ee00: 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 72 73  re added in vers
ee10: 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20  ion 2 or later. 
ee20: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72   */.  int (*xCur
ee30: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73  rentTimeInt64)(s
ee40: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c  qlite3_vfs*, sql
ee50: 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20  ite3_int64*);.  
ee60: 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68  /*.  ** The meth
ee70: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
ee80: 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20   versions 1 and 
ee90: 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f  2 of the sqlite_
eea0: 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a  vfs object..  **
eeb0: 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65   Those below are
eec0: 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61   for version 3 a
eed0: 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f  nd greater..  */
eee0: 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73  .  int (*xSetSys
eef0: 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33  temCall)(sqlite3
ef00: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
ef10: 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65  r *zName, sqlite
ef20: 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a  3_syscall_ptr);.
ef30: 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c    sqlite3_syscal
ef40: 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73 74  l_ptr (*xGetSyst
ef50: 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f  emCall)(sqlite3_
ef60: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
ef70: 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73   *zName);.  cons
ef80: 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53  t char *(*xNextS
ef90: 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74  ystemCall)(sqlit
efa0: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
efb0: 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f  har *zName);.  /
efc0: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
efd0: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
efe0: 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75  versions 1 throu
eff0: 67 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69  gh 3 of the sqli
f000: 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20  te_vfs object.. 
f010: 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d   ** New fields m
f020: 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69  ay be appended i
f030: 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e  n future version
f040: 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e  s.  The iVersion
f050: 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c  .  ** value will
f060: 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65   increment whene
f070: 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73  ver this happens
f080: 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  . .  */.};../*.*
f090: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67  * CAPI3REF: Flag
f0a0: 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73  s for the xAcces
f0b0: 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a  s VFS method.**.
f0c0: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72  ** These integer
f0d0: 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62   constants can b
f0e0: 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68  e used as the th
f0f0: 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
f100: 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20  .** the xAccess 
f110: 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71  method of an [sq
f120: 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
f130: 74 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d 69  t.  They determi
f140: 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20  ne.** what kind 
f150: 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74  of permissions t
f160: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
f170: 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72  d is looking for
f180: 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45  ..** With SQLITE
f190: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20  _ACCESS_EXISTS, 
f1a0: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
f1b0: 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65  od.** simply che
f1c0: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
f1d0: 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20  file exists..** 
f1e0: 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45  With SQLITE_ACCE
f1f0: 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68  SS_READWRITE, th
f200: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
f210: 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68  .** checks wheth
f220: 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72  er the named dir
f230: 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72  ectory is both r
f240: 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74  eadable and writ
f250: 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65  able.** (in othe
f260: 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65  r words, if file
f270: 73 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20  s can be added, 
f280: 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e  removed, and ren
f290: 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74  amed within.** t
f2a0: 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a  he directory)..*
f2b0: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43  * The SQLITE_ACC
f2c0: 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f  ESS_READWRITE co
f2d0: 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e  nstant is curren
f2e0: 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79  tly used only by
f2f0: 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74   the.** [temp_st
f300: 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
f310: 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68  agma], though th
f320: 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20  is could change 
f330: 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72  in a future.** r
f340: 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
f350: 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45  ..** With SQLITE
f360: 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68  _ACCESS_READ, th
f370: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
f380: 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68  .** checks wheth
f390: 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72  er the file is r
f3a0: 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51  eadable.  The SQ
f3b0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
f3c0: 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20   constant is.** 
f3d0: 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64  currently unused
f3e0: 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68  , though it migh
f3f0: 74 20 62 65 20 75 73 65 64 20 69 6e 20 61 20 66  t be used in a f
f400: 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66  uture release of
f410: 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23  .** SQLite..*/.#
f420: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
f430: 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 30  CESS_EXISTS    0
f440: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
f450: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
f460: 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20   1   /* Used by 
f470: 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72  PRAGMA temp_stor
f480: 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23  e_directory */.#
f490: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
f4a0: 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32  CESS_READ      2
f4b0: 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a     /* Unused */.
f4c0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
f4d0: 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78   Flags for the x
f4e0: 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68  ShmLock VFS meth
f4f0: 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69  od.**.** These i
f500: 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
f510: 20 64 65 66 69 6e 65 20 74 68 65 20 76 61 72 69   define the vari
f520: 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72  ous locking oper
f530: 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65  ations.** allowe
f540: 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63  d by the xShmLoc
f550: 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c  k method of [sql
f560: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
f570: 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77  .  The.** follow
f580: 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79  ing are the only
f590: 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69   legal combinati
f5a0: 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20  ons of flags to 
f5b0: 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20  the.** xShmLock 
f5c0: 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  method:.**.** <u
f5d0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  l>.** <li>  SQLI
f5e0: 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51  TE_SHM_LOCK | SQ
f5f0: 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a  LITE_SHM_SHARED.
f600: 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
f610: 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  SHM_LOCK | SQLIT
f620: 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a  E_SHM_EXCLUSIVE.
f630: 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
f640: 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c  SHM_UNLOCK | SQL
f650: 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a  ITE_SHM_SHARED.*
f660: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
f670: 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49  HM_UNLOCK | SQLI
f680: 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
f690: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
f6a0: 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20  When unlocking, 
f6b0: 74 68 65 20 73 61 6d 65 20 53 48 41 52 45 44 20  the same SHARED 
f6c0: 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61  or EXCLUSIVE fla
f6d0: 67 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69  g must be suppli
f6e0: 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76  ed as.** was giv
f6f0: 65 6e 20 6f 6e 20 74 68 65 20 63 6f 72 72 65 73  en on the corres
f700: 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a  ponding lock.  .
f710: 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f  **.** The xShmLo
f720: 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72  ck method can tr
f730: 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e  ansition between
f740: 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48   unlocked and SH
f750: 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65  ARED or.** betwe
f760: 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20  en unlocked and 
f770: 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63  EXCLUSIVE.  It c
f780: 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e  annot transition
f790: 20 62 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a   between SHARED.
f7a0: 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45  ** and EXCLUSIVE
f7b0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
f7c0: 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20  ITE_SHM_UNLOCK  
f7d0: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
f7e0: 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20  QLITE_SHM_LOCK  
f7f0: 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
f800: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52   SQLITE_SHM_SHAR
f810: 45 44 20 20 20 20 20 20 20 34 0a 23 64 65 66 69  ED       4.#defi
f820: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58  ne SQLITE_SHM_EX
f830: 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a  CLUSIVE    8../*
f840: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61  .** CAPI3REF: Ma
f850: 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69  ximum xShmLock i
f860: 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ndex.**.** The x
f870: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f  ShmLock method o
f880: 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  n [sqlite3_io_me
f890: 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76  thods] may use v
f8a0: 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e  alues.** between
f8b0: 20 30 20 61 6e 64 20 74 68 69 73 20 75 70 70 65   0 and this uppe
f8c0: 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22  r bound as its "
f8d0: 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74  offset" argument
f8e0: 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20  ..** The SQLite 
f8f0: 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  core will never 
f900: 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69  attempt to acqui
f910: 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a  re or release a.
f920: 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20  ** lock outside 
f930: 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f  of this range.*/
f940: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
f950: 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20  SHM_NLOCK       
f960: 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   8.../*.** CAPI3
f970: 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20  REF: Initialize 
f980: 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61  The SQLite Libra
f990: 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ry.**.** ^The sq
f9a0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f9b0: 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69  () routine initi
f9c0: 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51  alizes the.** SQ
f9d0: 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e  Lite library.  ^
f9e0: 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74  The sqlite3_shut
f9f0: 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a  down() routine.*
fa00: 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e  * deallocates an
fa10: 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 74  y resources that
fa20: 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20   were allocated 
fa30: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  by sqlite3_initi
fa40: 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73  alize()..** Thes
fa50: 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64  e routines are d
fa60: 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69  esigned to aid i
fa70: 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61  n process initia
fa80: 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20  lization and.** 
fa90: 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65  shutdown on embe
faa0: 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57  dded systems.  W
fab0: 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69  orkstation appli
fac0: 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a  cations using.**
fad0: 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79   SQLite normally
fae0: 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20   do not need to 
faf0: 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66  invoke either of
fb00: 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
fb10: 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f  .**.** A call to
fb20: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
fb30: 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66  ize() is an "eff
fb40: 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20  ective" call if 
fb50: 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72  it is.** the fir
fb60: 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f  st time sqlite3_
fb70: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
fb80: 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74  invoked during t
fb90: 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a  he lifetime of.*
fba0: 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f  * the process, o
fbb0: 72 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66  r if it is the f
fbc0: 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65  irst time sqlite
fbd0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
fbe0: 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c  s invoked.** fol
fbf0: 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f  lowing a call to
fc00: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
fc10: 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20  n().  ^(Only an 
fc20: 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a  effective call.*
fc30: 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69  * of sqlite3_ini
fc40: 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61  tialize() does a
fc50: 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ny initializatio
fc60: 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61  n.  All other ca
fc70: 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c  lls.** are harml
fc80: 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a  ess no-ops.)^.**
fc90: 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71  .** A call to sq
fca0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
fcb0: 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76   is an "effectiv
fcc0: 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73  e" call if it is
fcd0: 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61   the first.** ca
fce0: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
fcf0: 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74  utdown() since t
fd00: 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f  he last sqlite3_
fd10: 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e  initialize().  ^
fd20: 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65  (Only.** an effe
fd30: 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71  ctive call to sq
fd40: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
fd50: 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74   does any deinit
fd60: 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41  ialization..** A
fd70: 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63  ll other valid c
fd80: 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
fd90: 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68  shutdown() are h
fda0: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29  armless no-ops.)
fdb0: 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ^.**.** The sqli
fdc0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
fdd0: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68   interface is th
fde0: 72 65 61 64 73 61 66 65 2c 20 62 75 74 20 73 71  readsafe, but sq
fdf0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
fe00: 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65  .** is not.  The
fe10: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
fe20: 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75  n() interface mu
fe30: 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65  st only be calle
fe40: 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67  d from a.** sing
fe50: 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20  le thread.  All 
fe60: 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63  open [database c
fe70: 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74  onnections] must
fe80: 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61   be closed and a
fe90: 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69  ll.** other SQLi
fea0: 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73  te resources mus
feb0: 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  t be deallocated
fec0: 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69   prior to invoki
fed0: 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68  ng.** sqlite3_sh
fee0: 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20  utdown()..**.** 
fef0: 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e  Among other thin
ff00: 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69  gs, ^sqlite3_ini
ff10: 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69  tialize() will i
ff20: 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33  nvoke.** sqlite3
ff30: 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d  _os_init().  Sim
ff40: 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33  ilarly, ^sqlite3
ff50: 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77  _shutdown().** w
ff60: 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  ill invoke sqlit
ff70: 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a  e3_os_end()..**.
ff80: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
ff90: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
ffa0: 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51  tine returns [SQ
ffb0: 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
ffc0: 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20  ess..** ^If for 
ffd0: 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c  some reason, sql
ffe0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
fff0: 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69  ) is unable to i
10000 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65  nitialize.** the
10010 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 70   library (perhap
10020 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74  s it is unable t
10030 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65  o allocate a nee
10040 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 63  ded resource suc
10050 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29  h.** as a mutex)
10060 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b   it returns an [
10070 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65  error code] othe
10080 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f  r than [SQLITE_O
10090 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  K]..**.** ^The s
100a0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
100b0 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63  e() routine is c
100c0 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  alled internally
100d0 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a   by many other.*
100e0 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  * SQLite interfa
100f0 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61  ces so that an a
10100 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c  pplication usual
10110 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  ly does not need
10120 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71   to.** invoke sq
10130 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
10140 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f  () directly.  Fo
10150 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69  r example, [sqli
10160 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63  te3_open()].** c
10170 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69  alls sqlite3_ini
10180 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65  tialize() so the
10190 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20   SQLite library 
101a0 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69  will be automati
101b0 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c  cally.** initial
101c0 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74  ized when [sqlit
101d0 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61  e3_open()] is ca
101e0 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 6e  lled if it has n
101f0 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65  ot be initialize
10200 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e  d.** already.  ^
10210 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69  However, if SQLi
10220 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
10230 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ith the [SQLITE_
10240 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a  OMIT_AUTOINIT].*
10250 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  * compile-time o
10260 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20  ption, then the 
10270 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20  automatic calls 
10280 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  to sqlite3_initi
10290 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f  alize().** are o
102a0 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 61  mitted and the a
102b0 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
102c0 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69  call sqlite3_ini
102d0 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74  tialize() direct
102e0 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75  ly.** prior to u
102f0 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53  sing any other S
10300 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
10310 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f    For maximum po
10320 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74  rtability,.** it
10330 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
10340 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  that application
10350 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20  s always invoke 
10360 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
10370 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79  ze().** directly
10380 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20   prior to using 
10390 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65  any other SQLite
103a0 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74   interface.  Fut
103b0 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20  ure releases.** 
103c0 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65  of SQLite may re
103d0 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20  quire this.  In 
103e0 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65  other words, the
103f0 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 69   behavior exhibi
10400 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69  ted.** when SQLi
10410 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
10420 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  ith [SQLITE_OMIT
10430 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74  _AUTOINIT] might
10440 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64   become the.** d
10450 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20  efault behavior 
10460 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72  in some future r
10470 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
10480 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
10490 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f  te3_os_init() ro
104a0 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61  utine does opera
104b0 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63  ting-system spec
104c0 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69  ific.** initiali
104d0 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51  zation of the SQ
104e0 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54  Lite library.  T
104f0 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  he sqlite3_os_en
10500 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75  d().** routine u
10510 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74  ndoes the effect
10520 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69   of sqlite3_os_i
10530 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20  nit().  Typical 
10540 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d  tasks.** perform
10550 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 74  ed by these rout
10560 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c  ines include all
10570 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c  ocation or deall
10580 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74  ocation.** of st
10590 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20  atic resources, 
105a0 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f  initialization o
105b0 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c  f global variabl
105c0 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75  es,.** setting u
105d0 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  p a default [sql
105e0 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65  ite3_vfs] module
105f0 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a  , or setting up.
10600 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e  ** a default con
10610 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67  figuration using
10620 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
10630 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  ()]..**.** The a
10640 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
10650 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65  d never invoke e
10660 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73  ither sqlite3_os
10670 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71  _init().** or sq
10680 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64  lite3_os_end() d
10690 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70  irectly.  The ap
106a0 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
106b0 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20   only invoke.** 
106c0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
106d0 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  ze() and sqlite3
106e0 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68  _shutdown().  Th
106f0 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  e sqlite3_os_ini
10700 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  t().** interface
10710 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d   is called autom
10720 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69  atically by sqli
10730 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
10740 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   and.** sqlite3_
10750 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c  os_end() is call
10760 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68  ed by sqlite3_sh
10770 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f  utdown().  Appro
10780 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d  priate.** implem
10790 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71  entations for sq
107a0 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
107b0 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  and sqlite3_os_e
107c0 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c  nd().** are buil
107d0 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68  t into SQLite wh
107e0 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65  en it is compile
107f0 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64  d for Unix, Wind
10800 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a  ows, or OS/2..**
10810 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75   When [custom bu
10820 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72  ilds | built for
10830 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73   other platforms
10840 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20  ].** (using the 
10850 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52  [SQLITE_OS_OTHER
10860 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =1] compile-time
10870 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20  .** option) the 
10880 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
10890 20 73 75 70 70 6c 79 20 61 20 73 75 69 74 61 62   supply a suitab
108a0 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
108b0 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  n for.** sqlite3
108c0 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73  _os_init() and s
108d0 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e  qlite3_os_end().
108e0 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e    An application
108f0 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70  -supplied.** imp
10900 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73  lementation of s
10910 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
10920 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65   or sqlite3_os_e
10930 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74  nd().** must ret
10940 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
10950 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 73  on success and s
10960 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72  ome other [error
10970 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66   code] upon.** f
10980 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73  ailure..*/.int s
10990 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
109a0 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  e(void);.int sql
109b0 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f  ite3_shutdown(vo
109c0 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  id);.int sqlite3
109d0 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a  _os_init(void);.
109e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  int sqlite3_os_e
109f0 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a  nd(void);../*.**
10a00 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
10a10 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74  guring The SQLit
10a20 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20  e Library.**.** 
10a30 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  The sqlite3_conf
10a40 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ig() interface i
10a50 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67  s used to make g
10a60 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74  lobal configurat
10a70 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74  ion.** changes t
10a80 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65  o SQLite in orde
10a90 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65  r to tune SQLite
10aa0 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63   to the specific
10ab0 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65   needs of.** the
10ac0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54   application.  T
10ad0 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69  he default confi
10ae0 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f  guration is reco
10af0 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74  mmended for most
10b00 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  .** applications
10b10 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75   and so this rou
10b20 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20  tine is usually 
10b30 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20  not necessary.  
10b40 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65  It is.** provide
10b50 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72  d to support rar
10b60 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77  e applications w
10b70 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64  ith unusual need
10b80 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 54 68 65 20  s..**.** <b>The 
10b90 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
10ba0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f   interface is no
10bb0 74 20 74 68 72 65 61 64 73 61 66 65 2e 20 54 68  t threadsafe. Th
10bc0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a  e application.**
10bd0 20 6d 75 73 74 20 65 6e 73 75 72 65 20 74 68 61   must ensure tha
10be0 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74  t no other SQLit
10bf0 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  e interfaces are
10c00 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65   invoked by othe
10c10 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69  r.** threads whi
10c20 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  le sqlite3_confi
10c30 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 3c  g() is running.<
10c40 2f 62 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  /b>.**.** The sq
10c50 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
10c60 6e 74 65 72 66 61 63 65 0a 2a 2a 20 6d 61 79 20  nterface.** may 
10c70 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20  only be invoked 
10c80 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79  prior to library
10c90 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
10ca0 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
10cb0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20  3_initialize()] 
10cc0 6f 72 20 61 66 74 65 72 20 73 68 75 74 64 6f 77  or after shutdow
10cd0 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68  n by [sqlite3_sh
10ce0 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49  utdown()]..** ^I
10cf0 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  f sqlite3_config
10d00 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74  () is called aft
10d10 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74  er [sqlite3_init
10d20 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65  ialize()] and be
10d30 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  fore.** [sqlite3
10d40 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65  _shutdown()] the
10d50 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e  n it will return
10d60 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a   SQLITE_MISUSE..
10d70 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72  ** Note, however
10d80 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f  , that ^sqlite3_
10d90 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20  config() can be 
10da0 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f  called as part o
10db0 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  f the.** impleme
10dc0 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70  ntation of an ap
10dd0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
10de0 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  d [sqlite3_os_in
10df0 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  it()]..**.** The
10e00 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
10e10 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  to sqlite3_confi
10e20 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65  g() is an intege
10e30 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74  r.** [configurat
10e40 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74  ion option] that
10e50 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77   determines.** w
10e60 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20  hat property of 
10e70 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20  SQLite is to be 
10e80 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62  configured.  Sub
10e90 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74  sequent argument
10ea0 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64  s.** vary depend
10eb0 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66  ing on the [conf
10ec0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
10ed0 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73  ].** in the firs
10ee0 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  t argument..**.*
10ef0 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67  * ^When a config
10f00 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69  uration option i
10f10 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63  s set, sqlite3_c
10f20 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73 20  onfig() returns 
10f30 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20  [SQLITE_OK]..** 
10f40 5e 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69  ^If the option i
10f50 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c  s unknown or SQL
10f60 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ite is unable to
10f70 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a   set the option.
10f80 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75  ** then this rou
10f90 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e  tine returns a n
10fa0 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
10fb0 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ode]..*/.int sql
10fc0 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c  ite3_config(int,
10fd0 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   ...);../*.** CA
10fe0 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
10ff0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
11000 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44  ctions.** METHOD
11010 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
11020 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63  The sqlite3_db_c
11030 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
11040 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b  e is used to mak
11050 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a  e configuration.
11060 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20  ** changes to a 
11070 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
11080 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65  tion].  The inte
11090 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72  rface is similar
110a0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
110b0 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74  config()] except
110c0 20 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65   that the change
110d0 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e  s apply to a sin
110e0 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  gle.** [database
110f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70   connection] (sp
11100 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66  ecified in the f
11110 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a  irst argument)..
11120 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
11130 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
11140 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44  ite3_db_config(D
11150 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a  ,V,...)  is the.
11160 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ** [SQLITE_DBCON
11170 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20  FIG_LOOKASIDE | 
11180 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65  configuration ve
11190 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72  rb] - an integer
111a0 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69   code .** that i
111b0 6e 64 69 63 61 74 65 73 20 77 68 61 74 20 61 73  ndicates what as
111c0 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74  pect of the [dat
111d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
111e0 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69  ] is being confi
111f0 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71  gured..** Subseq
11200 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76  uent arguments v
11210 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ary depending on
11220 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
11230 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e  on verb..**.** ^
11240 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  Calls to sqlite3
11250 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74  _db_config() ret
11260 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66  urn SQLITE_OK if
11270 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
11280 74 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73  the call is cons
11290 69 64 65 72 65 64 20 73 75 63 63 65 73 73 66 75  idered successfu
112a0 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l..*/.int sqlite
112b0 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69  3_db_config(sqli
112c0 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e  te3*, int op, ..
112d0 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
112e0 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f  REF: Memory Allo
112f0 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a  cation Routines.
11300 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
11310 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
11320 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74   defines the int
11330 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53  erface between S
11340 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77  QLite.** and low
11350 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c  -level memory al
11360 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
11370 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62  s..**.** This ob
11380 6a 65 63 74 20 69 73 20 75 73 65 64 20 69 6e 20  ject is used in 
11390 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69  only one place i
113a0 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74  n the SQLite int
113b0 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69  erface..** A poi
113c0 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
113d0 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
113e0 63 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65  ct is the argume
113f0 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  nt to.** [sqlite
11400 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e  3_config()] when
11410 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
11420 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20  on option is.** 
11430 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
11440 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54  ALLOC] or [SQLIT
11450 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
11460 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65  OC].  .** By cre
11470 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63  ating an instanc
11480 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
11490 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20  .** and passing 
114a0 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  it to [sqlite3_c
114b0 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43  onfig]([SQLITE_C
114c0 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a  ONFIG_MALLOC]).*
114d0 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75  * during configu
114e0 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69  ration, an appli
114f0 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69  cation can speci
11500 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76  fy an alternativ
11510 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  e.** memory allo
11520 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d  cation subsystem
11530 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75   for SQLite to u
11540 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  se for all of it
11550 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d  s.** dynamic mem
11560 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a  ory needs..**.**
11570 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74   Note that SQLit
11580 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76  e comes with sev
11590 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d  eral [built-in m
115a0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73  emory allocators
115b0 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65  ].** that are pe
115c0 72 66 65 63 74 6c 79 20 61 64 65 71 75 61 74 65  rfectly adequate
115d0 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65   for the overwhe
115e0 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f  lming majority o
115f0 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  f applications.*
11600 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20  * and that this 
11610 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75  object is only u
11620 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20  seful to a tiny 
11630 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c  minority of appl
11640 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68  ications.** with
11650 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d   specialized mem
11660 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
11670 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68  equirements.  Th
11680 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20  is object is.** 
11690 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67  also used during
116a0 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69   testing of SQLi
116b0 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73  te in order to s
116c0 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e  pecify an altern
116d0 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ative.** memory 
116e0 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73  allocator that s
116f0 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20  imulates memory 
11700 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f  out-of-memory co
11710 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f  nditions in.** o
11720 72 64 65 72 20 74 6f 20 76 65 72 69 66 79 20 74  rder to verify t
11730 68 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76  hat SQLite recov
11740 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66  ers gracefully f
11750 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64  rom such.** cond
11760 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  itions..**.** Th
11770 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c  e xMalloc, xReal
11780 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65 65 20 6d  loc, and xFree m
11790 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b  ethods must work
117a0 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c   like the.** mal
117b0 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29  loc(), realloc()
117c0 20 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63   and free() func
117d0 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73  tions from the s
117e0 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
117f0 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75  y..** ^SQLite gu
11800 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
11810 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
11820 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63  t to.** xRealloc
11830 20 69 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c   is always a val
11840 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 61  ue returned by a
11850 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78   prior call to x
11860 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78  Roundup..**.** x
11870 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75  Size should retu
11880 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64  rn the allocated
11890 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72   size of a memor
118a0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
118b0 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69  previously obtai
118c0 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63  ned from xMalloc
118d0 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54   or xRealloc.  T
118e0 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
118f0 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61  e.** is always a
11900 74 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61  t least as big a
11910 73 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20  s the requested 
11920 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20  size but may be 
11930 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  larger..**.** Th
11940 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f  e xRoundup metho
11950 64 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 77  d returns what w
11960 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f  ould be the allo
11970 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a  cated size of.**
11980 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
11990 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72  tion given a par
119a0 74 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 65  ticular requeste
119b0 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65  d size.  Most me
119c0 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f  mory.** allocato
119d0 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f  rs round up memo
119e0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61  ry allocations a
119f0 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e  t least to the n
11a00 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20  ext multiple.** 
11a10 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f  of 8.  Some allo
11a20 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
11a30 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74  to a larger mult
11a40 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77  iple or to a pow
11a50 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72  er of 2..** Ever
11a60 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  y memory allocat
11a70 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69  ion request comi
11a80 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73  ng in through [s
11a90 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
11aa0 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
11ab0 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74  realloc()] first
11ac0 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e   calls xRoundup.
11ad0 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65    If xRoundup re
11ae0 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61  turns 0, .** tha
11af0 74 20 63 61 75 73 65 73 20 74 68 65 20 63 6f 72  t causes the cor
11b00 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72  responding memor
11b10 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20  y allocation to 
11b20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fail..**.** The 
11b30 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69  xInit method ini
11b40 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d  tializes the mem
11b50 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20  ory allocator.  
11b60 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20  For example,.** 
11b70 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74  it might allocat
11b80 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75  e any require mu
11b90 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c  texes or initial
11ba0 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  ize internal dat
11bb0 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e  a.** structures.
11bc0 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20    The xShutdown 
11bd0 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65  method is invoke
11be0 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62  d (indirectly) b
11bf0 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68  y.** [sqlite3_sh
11c00 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68  utdown()] and sh
11c10 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20  ould deallocate 
11c20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61 63  any resources ac
11c30 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e  quired.** by xIn
11c40 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 61 74  it.  The pAppDat
11c50 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65  a pointer is use
11c60 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61  d as the only pa
11c70 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49  rameter to.** xI
11c80 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77  nit and xShutdow
11c90 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  n..**.** SQLite 
11ca0 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54  holds the [SQLIT
11cb0 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d  E_MUTEX_STATIC_M
11cc0 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68 65  ASTER] mutex whe
11cd0 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20  n it invokes.** 
11ce0 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64  the xInit method
11cf0 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20 6d  , so the xInit m
11d00 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62  ethod need not b
11d10 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54  e threadsafe.  T
11d20 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20  he.** xShutdown 
11d30 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63  method is only c
11d40 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  alled from [sqli
11d50 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20  te3_shutdown()] 
11d60 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f  so it does.** no
11d70 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68 72  t need to be thr
11d80 65 61 64 73 61 66 65 20 65 69 74 68 65 72 2e 20  eadsafe either. 
11d90 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d   For all other m
11da0 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a  ethods, SQLite.*
11db0 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c  * holds the [SQL
11dc0 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
11dd0 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c  _MEM] mutex as l
11de0 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53  ong as the.** [S
11df0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
11e00 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 72  STATUS] configur
11e10 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20  ation option is 
11e20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 68  turned on (which
11e30 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65 66  .** it is by def
11e40 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 65  ault) and so the
11e50 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75 74   methods are aut
11e60 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69 61  omatically seria
11e70 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65  lized..** Howeve
11e80 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f  r, if [SQLITE_CO
11e90 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20  NFIG_MEMSTATUS] 
11ea0 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65  is disabled, the
11eb0 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d  n the other.** m
11ec0 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20 74  ethods must be t
11ed0 68 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c 73  hreadsafe or els
11ee0 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 6e  e make their own
11ef0 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f   arrangements fo
11f00 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 69  r.** serializati
11f10 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  on..**.** SQLite
11f20 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f   will never invo
11f30 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 20  ke xInit() more 
11f40 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75  than once withou
11f50 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67  t an intervening
11f60 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 75  .** call to xShu
11f70 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65  tdown()..*/.type
11f80 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
11f90 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73  e3_mem_methods s
11fa0 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
11fb0 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  ds;.struct sqlit
11fc0 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b  e3_mem_methods {
11fd0 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c  .  void *(*xMall
11fe0 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20  oc)(int);       
11ff0 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f    /* Memory allo
12000 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20  cation function 
12010 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65  */.  void (*xFre
12020 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  e)(void*);      
12030 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72      /* Free a pr
12040 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a  ior allocation *
12050 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61  /.  void *(*xRea
12060 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29  lloc)(void*,int)
12070 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20  ;  /* Resize an 
12080 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20  allocation */.  
12090 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69  int (*xSize)(voi
120a0 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f  d*);           /
120b0 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a  * Return the siz
120c0 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69  e of an allocati
120d0 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52  on */.  int (*xR
120e0 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20  oundup)(int);   
120f0 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20         /* Round 
12100 75 70 20 72 65 71 75 65 73 74 20 73 69 7a 65 20  up request size 
12110 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  to allocation si
12120 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49  ze */.  int (*xI
12130 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  nit)(void*);    
12140 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61         /* Initia
12150 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  lize the memory 
12160 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76  allocator */.  v
12170 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29  oid (*xShutdown)
12180 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a  (void*);      /*
12190 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68   Deinitialize th
121a0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
121b0 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41  or */.  void *pA
121c0 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20  ppData;         
121d0 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65         /* Argume
121e0 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e  nt to xInit() an
121f0 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f  d xShutdown() */
12200 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
12210 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69  REF: Configurati
12220 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45  on Options.** KE
12230 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75  YWORDS: {configu
12240 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a  ration option}.*
12250 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
12260 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61  ants are the ava
12270 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63  ilable integer c
12280 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
12290 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e  ions that.** can
122a0 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
122b0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
122c0 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
122d0 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
122e0 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  face..**.** New 
122f0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
12300 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64  tions may be add
12310 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
12320 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
12330 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e  .** Existing con
12340 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
12350 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63  ns might be disc
12360 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69  ontinued.  Appli
12370 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
12380 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  d check the retu
12390 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71  rn code from [sq
123a0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
123b0 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  to make sure tha
123c0 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f  t.** the call wo
123d0 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69  rked.  The [sqli
123e0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  te3_config()] in
123f0 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74  terface will ret
12400 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72  urn a.** non-zer
12410 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  o [error code] i
12420 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64  f a discontinued
12430 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20   or unsupported 
12440 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
12450 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b  tion.** is invok
12460 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  ed..**.** <dl>.*
12470 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
12480 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d  G_SINGLETHREAD]]
12490 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
124a0 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c  IG_SINGLETHREAD<
124b0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
124c0 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
124d0 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
124e0 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  n.  ^This option
124f0 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68   sets the.** [th
12500 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f  reading mode] to
12510 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20   Single-thread. 
12520 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
12530 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20   it disables.** 
12540 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64  all mutexing and
12550 20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74   puts SQLite int
12560 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69  o a mode where i
12570 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73  t can only be us
12580 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c  ed.** by a singl
12590 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20  e thread.   ^If 
125a0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
125b0 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
125c0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
125d0 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
125e0 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
125f0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
12600 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70  n.** it is not p
12610 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67  ossible to chang
12620 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67  e the [threading
12630 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20   mode] from its 
12640 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65  default.** value
12650 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61   of Single-threa
12660 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65  d and so [sqlite
12670 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c  3_config()] will
12680 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c   return .** [SQL
12690 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61  ITE_ERROR] if ca
126a0 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51  lled with the SQ
126b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
126c0 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66  LETHREAD.** conf
126d0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
126e0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
126f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
12700 54 49 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53  TITHREAD]] <dt>S
12710 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
12720 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a  TITHREAD</dt>.**
12730 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
12740 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
12750 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
12760 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
12770 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
12780 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d   mode] to Multi-
12790 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65  thread.  In othe
127a0 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61  r words, it disa
127b0 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67  bles.** mutexing
127c0 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
127d0 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70  nnection] and [p
127e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
127f0 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54  t] objects..** T
12800 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  he application i
12810 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
12820 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63  r serializing ac
12830 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61  cess to.** [data
12840 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
12850 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
12860 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75  statements].  Bu
12870 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a  t other mutexes.
12880 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73  ** are enabled s
12890 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  o that SQLite wi
128a0 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 73  ll be safe to us
128b0 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72  e in a multi-thr
128c0 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e  eaded.** environ
128d0 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20  ment as long as 
128e0 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 61  no two threads a
128f0 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68  ttempt to use th
12900 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62  e same.** [datab
12910 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
12920 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
12930 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73  .  ^If SQLite is
12940 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
12950 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
12960 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
12970 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
12980 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
12990 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69  ion then.** it i
129a0 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74  s not possible t
129b0 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d  o set the Multi-
129c0 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e  thread [threadin
129d0 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b  g mode] and.** [
129e0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
129f0 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  ] will return [S
12a00 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
12a10 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a  called with the.
12a20 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ** SQLITE_CONFIG
12a30 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e  _MULTITHREAD con
12a40 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
12a50 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  n.</dd>.**.** [[
12a60 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
12a70 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53  RIALIZED]] <dt>S
12a80 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
12a90 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20  IALIZED</dt>.** 
12aa0 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f  <dd>There are no
12ab0 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
12ac0 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69  is option.  ^Thi
12ad0 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68  s option sets th
12ae0 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20  e.** [threading 
12af0 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69  mode] to Seriali
12b00 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f  zed. In other wo
12b10 72 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e  rds, this option
12b20 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20   enables.** all 
12b30 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e  mutexes includin
12b40 67 20 74 68 65 20 72 65 63 75 72 73 69 76 65 0a  g the recursive.
12b50 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64  ** mutexes on [d
12b60 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
12b70 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  on] and [prepare
12b80 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a  d statement] obj
12b90 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73  ects..** In this
12ba0 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73 20   mode (which is 
12bb0 74 68 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e  the default when
12bc0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
12bd0 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c  led with.** [SQL
12be0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31  ITE_THREADSAFE=1
12bf0 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  ]) the SQLite li
12c00 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c  brary will itsel
12c10 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65  f serialize acce
12c20 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61  ss.** to [databa
12c30 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
12c40 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
12c50 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61  atements] so tha
12c60 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61  t the.** applica
12c70 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20  tion is free to 
12c80 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61  use the same [da
12c90 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
12ca0 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d  n] or the.** sam
12cb0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
12cc0 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72  ement] in differ
12cd0 65 6e 74 20 74 68 72 65 61 64 73 20 61 74 20 74  ent threads at t
12ce0 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a  he same time..**
12cf0 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
12d00 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
12d10 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
12d20 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
12d30 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
12d40 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
12d50 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20  n then.** it is 
12d60 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
12d70 73 65 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a  set the Serializ
12d80 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ed [threading mo
12d90 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  de] and.** [sqli
12da0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
12db0 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
12dc0 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c  E_ERROR] if call
12dd0 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53  ed with the.** S
12de0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
12df0 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72  IALIZED configur
12e00 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64  ation option.</d
12e10 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
12e20 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
12e30 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
12e40 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a  FIG_MALLOC</dt>.
12e50 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51  ** <dd> ^(The SQ
12e60 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
12e70 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  OC option takes 
12e80 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
12e90 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 61  t which is .** a
12ea0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
12eb0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
12ec0 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
12ed0 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a  ods] structure..
12ee0 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  ** The argument 
12ef0 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74  specifies.** alt
12f00 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76  ernative low-lev
12f10 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  el memory alloca
12f20 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f  tion routines to
12f30 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63   be used in plac
12f40 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f  e of.** the memo
12f50 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
12f60 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74  utines built int
12f70 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c  o SQLite.)^ ^SQL
12f80 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73  ite makes.** its
12f90 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70   own private cop
12fa0 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74  y of the content
12fb0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
12fc0 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
12fd0 72 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72  ructure.** befor
12fe0 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  e the [sqlite3_c
12ff0 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65  onfig()] call re
13000 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  turns.</dd>.**.*
13010 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
13020 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64  G_GETMALLOC]] <d
13030 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
13040 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a  GETMALLOC</dt>.*
13050 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c  * <dd> ^(The SQL
13060 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
13070 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65  LLOC option take
13080 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
13090 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ent which.** is 
130a0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
130b0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
130c0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
130d0 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
130e0 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
130f0 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  _mem_methods].**
13100 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69   structure is fi
13110 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75  lled with the cu
13120 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20  rrently defined 
13130 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
13140 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a  n routines.)^.**
13150 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e   This option can
13160 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72   be used to over
13170 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74  load the default
13180 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
13190 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77  on.** routines w
131a0 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74 68  ith a wrapper th
131b0 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d  at simulations m
131c0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
131d0 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74   failure or.** t
131e0 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61  racks memory usa
131f0 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e  ge, for example.
13200 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
13210 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
13220 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c  STATUS]] <dt>SQL
13230 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
13240 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATUS</dt>.** <dd
13250 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  > ^The SQLITE_CO
13260 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 6f  NFIG_MEMSTATUS o
13270 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67  ption takes sing
13280 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74  le argument of t
13290 79 70 65 20 69 6e 74 2c 0a 2a 2a 20 69 6e 74 65  ype int,.** inte
132a0 72 70 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f  rpreted as a boo
132b0 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62  lean, which enab
132c0 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
132d0 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f  the collection o
132e0 66 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  f.** memory allo
132f0 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
13300 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79  s. ^(When memory
13310 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74   allocation stat
13320 69 73 74 69 63 73 20 61 72 65 0a 2a 2a 20 64 69  istics are.** di
13330 73 61 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c 6c  sabled, the foll
13340 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74  owing SQLite int
13350 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e  erfaces become n
13360 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a  on-operational:.
13370 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c  **   <ul>.**   <
13380 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  li> [sqlite3_mem
13390 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20  ory_used()].**  
133a0 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d   <li> [sqlite3_m
133b0 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
133c0 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  )].**   <li> [sq
133d0 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f  lite3_soft_heap_
133e0 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20  limit64()].**   
133f0 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74  <li> [sqlite3_st
13400 61 74 75 73 36 34 28 29 5d 0a 2a 2a 20 20 20 3c  atus64()].**   <
13410 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72  /ul>)^.** ^Memor
13420 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  y allocation sta
13430 74 69 73 74 69 63 73 20 61 72 65 20 65 6e 61 62  tistics are enab
13440 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 75  led by default u
13450 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a  nless SQLite is.
13460 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  ** compiled with
13470 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54   [SQLITE_DEFAULT
13480 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e  _MEMSTATUS]=0 in
13490 20 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f   which case memo
134a0 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  ry.** allocation
134b0 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20   statistics are 
134c0 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
134d0 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ult..** </dd>.**
134e0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
134f0 46 49 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64  FIG_SCRATCH]] <d
13500 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
13510 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20  SCRATCH</dt>.** 
13520 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45  <dd> ^The SQLITE
13530 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20  _CONFIG_SCRATCH 
13540 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73  option specifies
13550 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79   a static memory
13560 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20   buffer.** that 
13570 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66  SQLite can use f
13580 6f 72 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72  or scratch memor
13590 79 2e 20 20 5e 28 54 68 65 72 65 20 61 72 65 20  y.  ^(There are 
135a0 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 0a  three arguments.
135b0 2a 2a 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e  ** to SQLITE_CON
135c0 46 49 47 5f 53 43 52 41 54 43 48 3a 20 20 41 20  FIG_SCRATCH:  A 
135d0 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79 74  pointer an 8-byt
135e0 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d  e.** aligned mem
135f0 6f 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d 20  ory buffer from 
13600 77 68 69 63 68 20 74 68 65 20 73 63 72 61 74 63  which the scratc
13610 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69  h allocations wi
13620 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20  ll be.** drawn, 
13630 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68  the size of each
13640 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
13650 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64  ion (sz),.** and
13660 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   the maximum num
13670 62 65 72 20 6f 66 20 73 63 72 61 74 63 68 20 61  ber of scratch a
13680 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e 29  llocations (N).)
13690 5e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ^.** The first a
136a0 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20  rgument must be 
136b0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
136c0 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62  8-byte aligned b
136d0 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c  uffer.** of at l
136e0 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20  east sz*N bytes 
136f0 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53  of memory..** ^S
13700 51 4c 69 74 65 20 77 69 6c 6c 20 6e 6f 74 20 75  QLite will not u
13710 73 65 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65  se more than one
13720 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 73   scratch buffers
13730 20 70 65 72 20 74 68 72 65 61 64 2e 0a 2a 2a 20   per thread..** 
13740 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76  ^SQLite will nev
13750 65 72 20 72 65 71 75 65 73 74 20 61 20 73 63 72  er request a scr
13760 61 74 63 68 20 62 75 66 66 65 72 20 74 68 61 74  atch buffer that
13770 20 69 73 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a   is more than 6.
13780 2a 2a 20 74 69 6d 65 73 20 74 68 65 20 64 61 74  ** times the dat
13790 61 62 61 73 65 20 70 61 67 65 20 73 69 7a 65 2e  abase page size.
137a0 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 6e  .** ^If SQLite n
137b0 65 65 64 73 20 6e 65 65 64 73 20 61 64 64 69 74  eeds needs addit
137c0 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68  ional.** scratch
137d0 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77   memory beyond w
137e0 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20  hat is provided 
137f0 62 79 20 74 68 69 73 20 63 6f 6e 66 69 67 75 72  by this configur
13800 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68  ation option, th
13810 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  en .** [sqlite3_
13820 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62  malloc()] will b
13830 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  e used to obtain
13840 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64   the memory need
13850 65 64 2e 3c 70 3e 0a 2a 2a 20 5e 57 68 65 6e 20  ed.<p>.** ^When 
13860 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
13870 70 72 6f 76 69 64 65 73 20 61 6e 79 20 61 6d 6f  provides any amo
13880 75 6e 74 20 6f 66 20 73 63 72 61 74 63 68 20 6d  unt of scratch m
13890 65 6d 6f 72 79 20 75 73 69 6e 67 0a 2a 2a 20 53  emory using.** S
138a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
138b0 41 54 43 48 2c 20 53 51 4c 69 74 65 20 61 76 6f  ATCH, SQLite avo
138c0 69 64 73 20 75 6e 6e 65 63 65 73 73 61 72 79 20  ids unnecessary 
138d0 6c 61 72 67 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  large.** [sqlite
138e0 33 5f 6d 61 6c 6c 6f 63 7c 68 65 61 70 20 61 6c  3_malloc|heap al
138f0 6c 6f 63 61 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54  locations]..** T
13900 68 69 73 20 63 61 6e 20 68 65 6c 70 20 5b 52 6f  his can help [Ro
13910 62 73 6f 6e 20 70 72 6f 6f 66 7c 70 72 65 76 65  bson proof|preve
13920 6e 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  nt memory alloca
13930 74 69 6f 6e 20 66 61 69 6c 75 72 65 73 5d 20 64  tion failures] d
13940 75 65 20 74 6f 20 68 65 61 70 0a 2a 2a 20 66 72  ue to heap.** fr
13950 61 67 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 20 6c  agmentation in l
13960 6f 77 2d 6d 65 6d 6f 72 79 20 65 6d 62 65 64 64  ow-memory embedd
13970 65 64 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 20 3c  ed systems..** <
13980 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
13990 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
139a0 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  ACHE]] <dt>SQLIT
139b0 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
139c0 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  HE</dt>.** <dd> 
139d0 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
139e0 49 47 5f 50 41 47 45 43 41 43 48 45 20 6f 70 74  IG_PAGECACHE opt
139f0 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20  ion specifies a 
13a00 6d 65 6d 6f 72 79 20 70 6f 6f 6c 0a 2a 2a 20 74  memory pool.** t
13a10 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75  hat SQLite can u
13a20 73 65 20 66 6f 72 20 74 68 65 20 64 61 74 61 62  se for the datab
13a30 61 73 65 20 70 61 67 65 20 63 61 63 68 65 20 77  ase page cache w
13a40 69 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 20  ith the default 
13a50 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d  page.** cache im
13a60 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a  plementation.  .
13a70 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72  ** This configur
13a80 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20  ation option is 
13a90 61 20 6e 6f 2d 6f 70 20 69 66 20 61 6e 20 61 70  a no-op if an ap
13aa0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
13ab0 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69   page.** cache i
13ac0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73  mplementation is
13ad0 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68   loaded using th
13ae0 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  e [SQLITE_CONFIG
13af0 5f 50 43 41 43 48 45 32 5d 2e 0a 2a 2a 20 5e 54  _PCACHE2]..** ^T
13b00 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
13b10 72 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49  rguments to SQLI
13b20 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
13b30 43 48 45 3a 20 41 20 70 6f 69 6e 74 65 72 20 74  CHE: A pointer t
13b40 6f 0a 2a 2a 20 38 2d 62 79 74 65 20 61 6c 69 67  o.** 8-byte alig
13b50 6e 65 64 20 6d 65 6d 6f 72 79 20 28 70 4d 65 6d  ned memory (pMem
13b60 29 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65  ), the size of e
13b70 61 63 68 20 70 61 67 65 20 63 61 63 68 65 20 6c  ach page cache l
13b80 69 6e 65 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64  ine (sz),.** and
13b90 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
13ba0 61 63 68 65 20 6c 69 6e 65 73 20 28 4e 29 2e 0a  ache lines (N)..
13bb0 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65  ** The sz argume
13bc0 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65  nt should be the
13bd0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72   size of the lar
13be0 67 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61  gest database pa
13bf0 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f  ge.** (a power o
13c00 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31  f two between 51
13c10 32 20 61 6e 64 20 36 35 35 33 36 29 20 70 6c 75  2 and 65536) plu
13c20 73 20 73 6f 6d 65 20 65 78 74 72 61 20 62 79 74  s some extra byt
13c30 65 73 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70  es for each.** p
13c40 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68  age header.  ^Th
13c50 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72  e number of extr
13c60 61 20 62 79 74 65 73 20 6e 65 65 64 65 64 20 62  a bytes needed b
13c70 79 20 74 68 65 20 70 61 67 65 20 68 65 61 64 65  y the page heade
13c80 72 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65  r.** can be dete
13c90 72 6d 69 6e 65 64 20 75 73 69 6e 67 20 5b 53 51  rmined using [SQ
13ca0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
13cb0 48 45 5f 48 44 52 53 5a 5d 2e 0a 2a 2a 20 5e 49  HE_HDRSZ]..** ^I
13cc0 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61  t is harmless, a
13cd0 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61  part from the wa
13ce0 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20  sted memory,.** 
13cf0 66 6f 72 20 74 68 65 20 73 7a 20 70 61 72 61 6d  for the sz param
13d00 65 74 65 72 20 74 6f 20 62 65 20 6c 61 72 67 65  eter to be large
13d10 72 20 74 68 61 6e 20 6e 65 63 65 73 73 61 72 79  r than necessary
13d20 2e 20 20 54 68 65 20 70 4d 65 6d 0a 2a 2a 20 61  .  The pMem.** a
13d30 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20  rgument must be 
13d40 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f  either a NULL po
13d50 69 6e 74 65 72 20 6f 72 20 61 20 70 6f 69 6e 74  inter or a point
13d60 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a  er to an 8-byte.
13d70 2a 2a 20 61 6c 69 67 6e 65 64 20 62 6c 6f 63 6b  ** aligned block
13d80 20 6f 66 20 6d 65 6d 6f 72 79 20 6f 66 20 61 74   of memory of at
13d90 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65   least sz*N byte
13da0 73 2c 20 6f 74 68 65 72 77 69 73 65 0a 2a 2a 20  s, otherwise.** 
13db0 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76  subsequent behav
13dc0 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
13dd0 2e 0a 2a 2a 20 5e 57 68 65 6e 20 70 4d 65 6d 20  ..** ^When pMem 
13de0 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c  is not NULL, SQL
13df0 69 74 65 20 77 69 6c 6c 20 73 74 72 69 76 65 20  ite will strive 
13e00 74 6f 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72  to use the memor
13e10 79 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 74 6f  y provided.** to
13e20 20 73 61 74 69 73 66 79 20 70 61 67 65 20 63 61   satisfy page ca
13e30 63 68 65 20 6e 65 65 64 73 2c 20 66 61 6c 6c 69  che needs, falli
13e40 6e 67 20 62 61 63 6b 20 74 6f 20 5b 73 71 6c 69  ng back to [sqli
13e50 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 66  te3_malloc()] if
13e60 0a 2a 2a 20 61 20 70 61 67 65 20 63 61 63 68 65  .** a page cache
13e70 20 6c 69 6e 65 20 69 73 20 6c 61 72 67 65 72 20   line is larger 
13e80 74 68 61 6e 20 73 7a 20 62 79 74 65 73 20 6f 72  than sz bytes or
13e90 20 69 66 20 61 6c 6c 20 6f 66 20 74 68 65 20 70   if all of the p
13ea0 4d 65 6d 20 62 75 66 66 65 72 0a 2a 2a 20 69 73  Mem buffer.** is
13eb0 20 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 5e   exhausted..** ^
13ec0 49 66 20 70 4d 65 6d 20 69 73 20 4e 55 4c 4c 20  If pMem is NULL 
13ed0 61 6e 64 20 4e 20 69 73 20 6e 6f 6e 2d 7a 65 72  and N is non-zer
13ee0 6f 2c 20 74 68 65 6e 20 65 61 63 68 20 64 61 74  o, then each dat
13ef0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
13f00 0a 2a 2a 20 64 6f 65 73 20 61 6e 20 69 6e 69 74  .** does an init
13f10 69 61 6c 20 62 75 6c 6b 20 61 6c 6c 6f 63 61 74  ial bulk allocat
13f20 69 6f 6e 20 66 6f 72 20 70 61 67 65 20 63 61 63  ion for page cac
13f30 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 66 72 6f  he memory.** fro
13f40 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
13f50 63 28 29 5d 20 73 75 66 66 69 63 69 65 6e 74 20  c()] sufficient 
13f60 66 6f 72 20 4e 20 63 61 63 68 65 20 6c 69 6e 65  for N cache line
13f70 73 20 69 66 20 4e 20 69 73 20 70 6f 73 69 74 69  s if N is positi
13f80 76 65 20 6f 72 0a 2a 2a 20 6f 66 20 2d 31 30 32  ve or.** of -102
13f90 34 2a 4e 20 62 79 74 65 73 20 69 66 20 4e 20 69  4*N bytes if N i
13fa0 73 20 6e 65 67 61 74 69 76 65 2c 20 2e 20 5e 49  s negative, . ^I
13fb0 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  f additional.** 
13fc0 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72  page cache memor
13fd0 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f  y is needed beyo
13fe0 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69  nd what is provi
13ff0 64 65 64 20 62 79 20 74 68 65 20 69 6e 69 74 69  ded by the initi
14000 61 6c 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  al.** allocation
14010 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 67 6f  , then SQLite go
14020 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d  es to [sqlite3_m
14030 61 6c 6c 6f 63 28 29 5d 20 73 65 70 61 72 61 74  alloc()] separat
14040 65 6c 79 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20  ely for each.** 
14050 61 64 64 69 74 69 6f 6e 61 6c 20 63 61 63 68 65  additional cache
14060 20 6c 69 6e 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a   line. </dd>.**.
14070 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
14080 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51  IG_HEAP]] <dt>SQ
14090 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
140a0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
140b0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
140c0 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20 73 70 65  _HEAP option spe
140d0 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
140e0 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 0a 2a  memory buffer .*
140f0 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  * that SQLite wi
14100 6c 6c 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f  ll use for all o
14110 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65  f its dynamic me
14120 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
14130 6e 65 65 64 73 0a 2a 2a 20 62 65 79 6f 6e 64 20  needs.** beyond 
14140 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64 20 66  those provided f
14150 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f  or by [SQLITE_CO
14160 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e  NFIG_SCRATCH] an
14170 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  d.** [SQLITE_CON
14180 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a  FIG_PAGECACHE]..
14190 2a 2a 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  ** ^The SQLITE_C
141a0 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 69 6f  ONFIG_HEAP optio
141b0 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61  n is only availa
141c0 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 73  ble if SQLite is
141d0 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74   compiled.** wit
141e0 68 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  h either [SQLITE
141f0 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d  _ENABLE_MEMSYS3]
14200 20 6f 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42   or [SQLITE_ENAB
14210 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 6e 64 20  LE_MEMSYS5] and 
14220 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49  returns.** [SQLI
14230 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 69 6e 76  TE_ERROR] if inv
14240 6f 6b 65 64 20 6f 74 68 65 72 77 69 73 65 2e 0a  oked otherwise..
14250 2a 2a 20 5e 54 68 65 72 65 20 61 72 65 20 74 68  ** ^There are th
14260 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  ree arguments to
14270 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48   SQLITE_CONFIG_H
14280 45 41 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79 74  EAP:.** An 8-byt
14290 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65  e aligned pointe
142a0 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c  r to the memory,
142b0 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
142c0 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d  f bytes in the m
142d0 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e  emory buffer, an
142e0 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c  d the minimum al
142f0 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a  location size..*
14300 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73 74 20  * ^If the first 
14310 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d  pointer (the mem
14320 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20  ory pointer) is 
14330 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74  NULL, then SQLit
14340 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20  e reverts.** to 
14350 75 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c  using its defaul
14360 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  t memory allocat
14370 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d  or (the system m
14380 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e  alloc() implemen
14390 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f  tation),.** undo
143a0 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e  ing any prior in
143b0 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c  vocation of [SQL
143c0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
143d0 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  C].  ^If the.** 
143e0 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69  memory pointer i
143f0 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20  s not NULL then 
14400 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20  the alternative 
14410 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
14420 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20 74  tor is engaged t
14430 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20  o handle all of 
14440 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61  SQLites memory a
14450 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e  llocation needs.
14460 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f  .** The first po
14470 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72  inter (the memor
14480 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20  y pointer) must 
14490 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  be aligned to an
144a0 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64   8-byte.** bound
144b0 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e  ary or subsequen
144c0 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51  t behavior of SQ
144d0 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64  Lite will be und
144e0 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d  efined..** The m
144f0 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f  inimum allocatio
14500 6e 20 73 69 7a 65 20 69 73 20 63 61 70 70 65 64  n size is capped
14510 20 61 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f   at 2**12. Reaso
14520 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20  nable values.** 
14530 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20  for the minimum 
14540 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20  allocation size 
14550 61 72 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 68  are 2**5 through
14560 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a   2**8.</dd>.**.*
14570 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
14580 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51  G_MUTEX]] <dt>SQ
14590 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
145a0 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  X</dt>.** <dd> ^
145b0 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
145c0 49 47 5f 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20  IG_MUTEX option 
145d0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
145e0 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
145f0 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f   a.** pointer to
14600 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
14610 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
14620 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  ex_methods] stru
14630 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72  cture..** The ar
14640 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73  gument specifies
14650 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77   alternative low
14660 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75  -level mutex rou
14670 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64  tines to be used
14680 0a 2a 2a 20 69 6e 20 70 6c 61 63 65 20 74 68 65  .** in place the
14690 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20   mutex routines 
146a0 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
146b0 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61  e.)^  ^SQLite ma
146c0 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a  kes a copy of.**
146d0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
146e0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
146f0 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  ex_methods] stru
14700 63 74 75 72 65 20 62 65 66 6f 72 65 20 74 68 65  cture before the
14710 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
14720 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72  ite3_config()] r
14730 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69  eturns. ^If SQLi
14740 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
14750 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
14760 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
14770 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
14780 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
14790 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
147a0 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65   the entire mute
147b0 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69  xing subsystem i
147c0 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74  s omitted from t
147d0 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e  he build and hen
147e0 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b  ce calls to.** [
147f0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
14800 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54  ] with the SQLIT
14810 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63  E_CONFIG_MUTEX c
14820 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
14830 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75  ion will.** retu
14840 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
14850 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ].</dd>.**.** [[
14860 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
14870 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c  TMUTEX]] <dt>SQL
14880 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
14890 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TEX</dt>.** <dd>
148a0 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
148b0 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 6f 70  NFIG_GETMUTEX op
148c0 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
148d0 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
148e0 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74  ch.** is a point
148f0 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
14900 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
14910 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
14920 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65   structure.  The
14930 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  .** [sqlite3_mut
14940 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73  ex_methods].** s
14950 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c  tructure is fill
14960 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72  ed with the curr
14970 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75  ently defined mu
14980 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a  tex routines.)^.
14990 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63  ** This option c
149a0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76  an be used to ov
149b0 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75  erload the defau
149c0 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74  lt mutex allocat
149d0 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ion.** routines 
149e0 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20 75  with a wrapper u
149f0 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74  sed to track mut
14a00 65 78 20 75 73 61 67 65 20 66 6f 72 20 70 65 72  ex usage for per
14a10 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66  formance.** prof
14a20 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67  iling or testing
14a30 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20  , for example.  
14a40 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
14a50 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
14a60 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
14a70 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
14a80 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
14a90 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
14aa0 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e  n then.** the en
14ab0 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75  tire mutexing su
14ac0 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74  bsystem is omitt
14ad0 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c  ed from the buil
14ae0 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c  d and hence call
14af0 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s to.** [sqlite3
14b00 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20  _config()] with 
14b10 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  the SQLITE_CONFI
14b20 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69  G_GETMUTEX confi
14b30 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
14b40 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  will.** return [
14b50 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f  SQLITE_ERROR].</
14b60 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
14b70 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
14b80 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  IDE]] <dt>SQLITE
14b90 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
14ba0 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
14bb0 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
14bc0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f 70 74  IG_LOOKASIDE opt
14bd0 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72  ion takes two ar
14be0 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74  guments that det
14bf0 65 72 6d 69 6e 65 0a 2a 2a 20 74 68 65 20 64 65  ermine.** the de
14c00 66 61 75 6c 74 20 73 69 7a 65 20 6f 66 20 6c 6f  fault size of lo
14c10 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 6f  okaside memory o
14c20 6e 20 65 61 63 68 20 5b 64 61 74 61 62 61 73 65  n each [database
14c30 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a   connection]..**
14c40 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
14c50 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69  ent is the.** si
14c60 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61  ze of each looka
14c70 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74  side buffer slot
14c80 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
14c90 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
14ca0 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61  .** slots alloca
14cb0 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 74 61  ted to each data
14cc0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  base connection.
14cd0 29 5e 20 20 5e 28 53 51 4c 49 54 45 5f 43 4f 4e  )^  ^(SQLITE_CON
14ce0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a 2a  FIG_LOOKASIDE.**
14cf0 20 73 65 74 73 20 74 68 65 20 3c 69 3e 64 65 66   sets the <i>def
14d00 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69  ault</i> lookasi
14d10 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51  de size. The [SQ
14d20 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
14d30 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 6f 70 74 69  OKASIDE].** opti
14d40 6f 6e 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64  on to [sqlite3_d
14d50 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20  b_config()] can 
14d60 62 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67  be used to chang
14d70 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a  e the lookaside.
14d80 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
14d90 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63   on individual c
14da0 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f  onnections.)^ </
14db0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
14dc0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
14dd0 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  2]] <dt>SQLITE_C
14de0 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 3c 2f 64  ONFIG_PCACHE2</d
14df0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
14e00 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
14e10 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61  CACHE2 option ta
14e20 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
14e30 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a  ument which is .
14e40 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** a pointer to 
14e50 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63  an [sqlite3_pcac
14e60 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a  he_methods2] obj
14e70 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63  ect.  This objec
14e80 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74  t specifies.** t
14e90 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20  he interface to 
14ea0 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61  a custom page ca
14eb0 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
14ec0 6f 6e 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74 65  on.)^.** ^SQLite
14ed0 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
14ee0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 63   the [sqlite3_pc
14ef0 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f  ache_methods2] o
14f00 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  bject.</dd>.**.*
14f10 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
14f20 47 5f 47 45 54 50 43 41 43 48 45 32 5d 5d 20 3c  G_GETPCACHE2]] <
14f30 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
14f40 5f 47 45 54 50 43 41 43 48 45 32 3c 2f 64 74 3e  _GETPCACHE2</dt>
14f50 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
14f60 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
14f70 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74  PCACHE2 option t
14f80 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
14f90 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20  gument which.** 
14fa0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
14fb0 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63  an [sqlite3_pcac
14fc0 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a  he_methods2] obj
14fd0 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70  ect.  SQLite cop
14fe0 69 65 73 20 6f 66 0a 2a 2a 20 74 68 65 20 63 75  ies of.** the cu
14ff0 72 72 65 6e 74 20 70 61 67 65 20 63 61 63 68 65  rrent page cache
15000 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
15010 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74  into that object
15020 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .)^ </dd>.**.** 
15030 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
15040 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  LOG]] <dt>SQLITE
15050 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e  _CONFIG_LOG</dt>
15060 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 4c  .** <dd> The SQL
15070 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f  ITE_CONFIG_LOG o
15080 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f  ption is used to
15090 20 63 6f 6e 66 69 67 75 72 65 20 74 68 65 20 53   configure the S
150a0 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20  QLite.** global 
150b0 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20  [error log]..** 
150c0 28 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  (^The SQLITE_CON
150d0 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74  FIG_LOG option t
150e0 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e  akes two argumen
150f0 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  ts: a pointer to
15100 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77   a.** function w
15110 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61  ith a call signa
15120 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28  ture of void(*)(
15130 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
15140 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20  char*), .** and 
15150 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69  a pointer to voi
15160 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74  d. ^If the funct
15170 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e  ion pointer is n
15180 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a  ot NULL, it is.*
15190 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71  * invoked by [sq
151a0 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20  lite3_log()] to 
151b0 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67  process each log
151c0 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66  ging event.  ^If
151d0 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   the.** function
151e0 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c   pointer is NULL
151f0 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  , the [sqlite3_l
15200 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  og()] interface 
15210 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e  becomes a no-op.
15220 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f  .** ^The void po
15230 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 74 68  inter that is th
15240 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
15250 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46  t to SQLITE_CONF
15260 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73  IG_LOG is.** pas
15270 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74  sed through as t
15280 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
15290 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63  er to the applic
152a0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f  ation-defined lo
152b0 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  gger.** function
152c0 20 77 68 65 6e 65 76 65 72 20 74 68 61 74 20 66   whenever that f
152d0 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b  unction is invok
152e0 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64  ed.  ^The second
152f0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
15300 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63   the logger func
15310 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f  tion is a copy o
15320 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  f the first para
15330 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72  meter to the cor
15340 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73  responding.** [s
15350 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61  qlite3_log()] ca
15360 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64  ll and is intend
15370 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75  ed to be a [resu
15380 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a  lt code] or an.*
15390 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
153a0 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20  lt code].  ^The 
153b0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
153c0 70 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f  passed to the lo
153d0 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d  gger is.** log m
153e0 65 73 73 61 67 65 20 61 66 74 65 72 20 66 6f 72  essage after for
153f0 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c  matting via [sql
15400 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
15410 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20  ..** The SQLite 
15420 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63  logging interfac
15430 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61  e is not reentra
15440 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66  nt; the logger f
15450 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c  unction.** suppl
15460 69 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69  ied by the appli
15470 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  cation must not 
15480 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74  invoke any SQLit
15490 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20  e interface..** 
154a0 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61  In a multi-threa
154b0 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c  ded application,
154c0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
154d0 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a  -defined logger.
154e0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ** function must
154f0 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20   be threadsafe. 
15500 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
15510 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d  LITE_CONFIG_URI]
15520 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
15530 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e  FIG_URI.** <dd>^
15540 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
15550 49 47 5f 55 52 49 20 6f 70 74 69 6f 6e 20 74 61  IG_URI option ta
15560 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
15570 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e  ument of type in
15580 74 2e 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65 72  t..** If non-zer
15590 6f 2c 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64  o, then URI hand
155a0 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79  ling is globally
155b0 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 65   enabled. If the
155c0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 7a 65   parameter is ze
155d0 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 55 52 49 20  ro,.** then URI 
155e0 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62  handling is glob
155f0 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e 29 5e  ally disabled.)^
15600 20 5e 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e   ^If URI handlin
15610 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a  g is globally.**
15620 20 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69   enabled, all fi
15630 6c 65 6e 61 6d 65 73 20 70 61 73 73 65 64 20 74  lenames passed t
15640 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  o [sqlite3_open(
15650 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
15660 6e 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  n_v2()],.** [sql
15670 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f  ite3_open16()] o
15680 72 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20 61  r.** specified a
15690 73 20 70 61 72 74 20 6f 66 20 5b 41 54 54 41 43  s part of [ATTAC
156a0 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20  H] commands are 
156b0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55  interpreted as U
156c0 52 49 73 2c 20 72 65 67 61 72 64 6c 65 73 73 0a  RIs, regardless.
156d0 2a 2a 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ** of whether or
156e0 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45   not the [SQLITE
156f0 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20  _OPEN_URI] flag 
15700 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20  is set when the 
15710 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
15720 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64  ection is opened
15730 2e 20 5e 49 66 20 69 74 20 69 73 20 67 6c 6f 62  . ^If it is glob
15740 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 66  ally disabled, f
15750 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20  ilenames are.** 
15760 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65 74 65 64  only interpreted
15770 20 61 73 20 55 52 49 73 20 69 66 20 74 68 65 20   as URIs if the 
15780 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20  SQLITE_OPEN_URI 
15790 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e  flag is set when
157a0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
157b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
157c0 70 65 6e 65 64 2e 20 5e 28 42 79 20 64 65 66 61  pened. ^(By defa
157d0 75 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e  ult, URI handlin
157e0 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a  g is globally.**
157f0 20 64 69 73 61 62 6c 65 64 2e 20 54 68 65 20 64   disabled. The d
15800 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6d 61 79  efault value may
15810 20 62 65 20 63 68 61 6e 67 65 64 20 62 79 20 63   be changed by c
15820 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 74 68  ompiling with th
15830 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45  e.** [SQLITE_USE
15840 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66  _URI] symbol def
15850 69 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  ined.)^.**.** [[
15860 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f  SQLITE_CONFIG_CO
15870 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
15880 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  N]] <dt>SQLITE_C
15890 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49  ONFIG_COVERING_I
158a0 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64  NDEX_SCAN.** <dd
158b0 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  >^The SQLITE_CON
158c0 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  FIG_COVERING_IND
158d0 45 58 5f 53 43 41 4e 20 6f 70 74 69 6f 6e 20 74  EX_SCAN option t
158e0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 69 6e  akes a single in
158f0 74 65 67 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e  teger.** argumen
15900 74 20 77 68 69 63 68 20 69 73 20 69 6e 74 65 72  t which is inter
15910 70 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c  preted as a bool
15920 65 61 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ean in order to 
15930 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c  enable or disabl
15940 65 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20  e.** the use of 
15950 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73  covering indices
15960 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20   for full table 
15970 73 63 61 6e 73 20 69 6e 20 74 68 65 20 71 75 65  scans in the que
15980 72 79 20 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a 2a  ry optimizer..**
15990 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73 65   ^The default se
159a0 74 74 69 6e 67 20 69 73 20 64 65 74 65 72 6d 69  tting is determi
159b0 6e 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53  ned.** by the [S
159c0 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45  QLITE_ALLOW_COVE
159d0 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d  RING_INDEX_SCAN]
159e0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
159f0 74 69 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22  tion, or is "on"
15a00 0a 2a 2a 20 69 66 20 74 68 61 74 20 63 6f 6d 70  .** if that comp
15a10 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
15a20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54  is omitted..** T
15a30 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 64 69  he ability to di
15a40 73 61 62 6c 65 20 74 68 65 20 75 73 65 20 6f 66  sable the use of
15a50 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65   covering indice
15a60 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65  s for full table
15a70 20 73 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63   scans.** is bec
15a80 61 75 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72  ause some incorr
15a90 65 63 74 6c 79 20 63 6f 64 65 64 20 6c 65 67 61  ectly coded lega
15aa0 63 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  cy applications 
15ab0 6d 69 67 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f  might malfunctio
15ac0 6e 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 6f 70  n.** when the op
15ad0 74 69 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e  timization is en
15ae0 61 62 6c 65 64 2e 20 20 50 72 6f 76 69 64 69 6e  abled.  Providin
15af0 67 20 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f  g the ability to
15b00 0a 2a 2a 20 64 69 73 61 62 6c 65 20 74 68 65 20  .** disable the 
15b10 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c  optimization all
15b20 6f 77 73 20 74 68 65 20 6f 6c 64 65 72 2c 20 62  ows the older, b
15b30 75 67 67 79 20 61 70 70 6c 69 63 61 74 69 6f 6e  uggy application
15b40 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a   code to work.**
15b50 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 65 20   without change 
15b60 65 76 65 6e 20 77 69 74 68 20 6e 65 77 65 72 20  even with newer 
15b70 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
15b80 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  te..**.** [[SQLI
15b90 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
15ba0 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ]] [[SQLITE_CONF
15bb0 49 47 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a  IG_GETPCACHE]].*
15bc0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
15bd0 46 49 47 5f 50 43 41 43 48 45 20 61 6e 64 20 53  FIG_PCACHE and S
15be0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
15bf0 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54  PCACHE.** <dd> T
15c00 68 65 73 65 20 6f 70 74 69 6f 6e 73 20 61 72 65  hese options are
15c10 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20 73 68   obsolete and sh
15c20 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64  ould not be used
15c30 20 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a   by new code..**
15c40 20 54 68 65 79 20 61 72 65 20 72 65 74 61 69 6e   They are retain
15c50 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ed for backwards
15c60 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 62   compatibility b
15c70 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70  ut are now no-op
15c80 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  s..** </dd>.**.*
15c90 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
15ca0 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64  G_SQLLOG]].** <d
15cb0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
15cc0 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68  SQLLOG.** <dd>Th
15cd0 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c  is option is onl
15ce0 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 73  y available if s
15cf0 71 6c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  qlite is compile
15d00 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53  d with the.** [S
15d10 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c  QLITE_ENABLE_SQL
15d20 4c 4f 47 5d 20 70 72 65 2d 70 72 6f 63 65 73 73  LOG] pre-process
15d30 6f 72 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64  or macro defined
15d40 2e 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  . The first argu
15d50 6d 65 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62  ment should.** b
15d60 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  e a pointer to a
15d70 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70   function of typ
15d80 65 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c  e void(*)(void*,
15d90 73 71 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63  sqlite3*,const c
15da0 68 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54  har*, int)..** T
15db0 68 65 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64  he second should
15dc0 20 62 65 20 6f 66 20 74 79 70 65 20 28 76 6f 69   be of type (voi
15dd0 64 2a 29 2e 20 54 68 65 20 63 61 6c 6c 62 61 63  d*). The callbac
15de0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20  k is invoked by 
15df0 74 68 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69  the library.** i
15e00 6e 20 74 68 72 65 65 20 73 65 70 61 72 61 74 65  n three separate
15e10 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20   circumstances, 
15e20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68  identified by th
15e30 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61  e value passed a
15e40 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20  s the.** fourth 
15e50 70 61 72 61 6d 65 74 65 72 2e 20 49 66 20 74 68  parameter. If th
15e60 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
15e70 65 72 20 69 73 20 30 2c 20 74 68 65 6e 20 74 68  er is 0, then th
15e80 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
15e90 63 74 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20  ction.** passed 
15ea0 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  as the second ar
15eb0 67 75 6d 65 6e 74 20 68 61 73 20 6a 75 73 74 20  gument has just 
15ec0 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65  been opened. The
15ed0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a   third argument.
15ee0 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 62  ** points to a b
15ef0 75 66 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67  uffer containing
15f00 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
15f10 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66   main database f
15f20 69 6c 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66  ile. If the.** f
15f30 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
15f40 69 73 20 31 2c 20 74 68 65 6e 20 74 68 65 20 53  is 1, then the S
15f50 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  QL statement tha
15f60 74 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  t the third para
15f70 6d 65 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20  meter.** points 
15f80 74 6f 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e  to has just been
15f90 20 65 78 65 63 75 74 65 64 2e 20 4f 72 2c 20 69   executed. Or, i
15fa0 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
15fb0 61 6d 65 74 65 72 20 69 73 20 32 2c 20 74 68 65  ameter is 2, the
15fc0 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74  n.** the connect
15fd0 69 6f 6e 20 62 65 69 6e 67 20 70 61 73 73 65 64  ion being passed
15fe0 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
15ff0 61 72 61 6d 65 74 65 72 20 69 73 20 62 65 69 6e  arameter is bein
16000 67 20 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a  g closed. The.**
16010 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
16020 20 69 73 20 70 61 73 73 65 64 20 4e 55 4c 4c 20   is passed NULL 
16030 49 6e 20 74 68 69 73 20 63 61 73 65 2e 20 20 41  In this case.  A
16040 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 75 73 69  n example of usi
16050 6e 67 20 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69  ng this.** confi
16060 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
16070 63 61 6e 20 62 65 20 73 65 65 6e 20 69 6e 20 74  can be seen in t
16080 68 65 20 22 74 65 73 74 5f 73 71 6c 6c 6f 67 2e  he "test_sqllog.
16090 63 22 20 73 6f 75 72 63 65 20 66 69 6c 65 20 69  c" source file i
160a0 6e 0a 2a 2a 20 74 68 65 20 63 61 6e 6f 6e 69 63  n.** the canonic
160b0 61 6c 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65  al SQLite source
160c0 20 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a   tree.</dd>.**.*
160d0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
160e0 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a  G_MMAP_SIZE]].**
160f0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
16100 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20  IG_MMAP_SIZE.** 
16110 3c 64 64 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e 46  <dd>^SQLITE_CONF
16120 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 74 61 6b  IG_MMAP_SIZE tak
16130 65 73 20 74 77 6f 20 36 34 2d 62 69 74 20 69 6e  es two 64-bit in
16140 74 65 67 65 72 20 28 73 71 6c 69 74 65 33 5f 69  teger (sqlite3_i
16150 6e 74 36 34 29 20 76 61 6c 75 65 73 0a 2a 2a 20  nt64) values.** 
16160 74 68 61 74 20 61 72 65 20 74 68 65 20 64 65 66  that are the def
16170 61 75 6c 74 20 6d 6d 61 70 20 73 69 7a 65 20 6c  ault mmap size l
16180 69 6d 69 74 20 28 74 68 65 20 64 65 66 61 75 6c  imit (the defaul
16190 74 20 73 65 74 74 69 6e 67 20 66 6f 72 0a 2a 2a  t setting for.**
161a0 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69   [PRAGMA mmap_si
161b0 7a 65 5d 29 20 61 6e 64 20 74 68 65 20 6d 61 78  ze]) and the max
161c0 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61  imum allowed mma
161d0 70 20 73 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a  p size limit..**
161e0 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73 65   ^The default se
161f0 74 74 69 6e 67 20 63 61 6e 20 62 65 20 6f 76 65  tting can be ove
16200 72 72 69 64 64 65 6e 20 62 79 20 65 61 63 68 20  rridden by each 
16210 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
16220 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 65 69 74  ion using.** eit
16230 68 65 72 20 74 68 65 20 5b 50 52 41 47 4d 41 20  her the [PRAGMA 
16240 6d 6d 61 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61  mmap_size] comma
16250 6e 64 2c 20 6f 72 20 62 79 20 75 73 69 6e 67 20  nd, or by using 
16260 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46  the.** [SQLITE_F
16270 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20  CNTL_MMAP_SIZE] 
16280 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e  file control.  ^
16290 28 54 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c  (The maximum all
162a0 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a  owed mmap size.*
162b0 2a 20 77 69 6c 6c 20 62 65 20 73 69 6c 65 6e 74  * will be silent
162c0 6c 79 20 74 72 75 6e 63 61 74 65 64 20 69 66 20  ly truncated if 
162d0 6e 65 63 65 73 73 61 72 79 20 73 6f 20 74 68 61  necessary so tha
162e0 74 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 65 78  t it does not ex
162f0 63 65 65 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70  ceed the.** comp
16300 69 6c 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d  ile-time maximum
16310 20 6d 6d 61 70 20 73 69 7a 65 20 73 65 74 20 62   mmap size set b
16320 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  y the.** [SQLITE
16330 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20  _MAX_MMAP_SIZE] 
16340 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
16350 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69  ion.)^.** ^If ei
16360 74 68 65 72 20 61 72 67 75 6d 65 6e 74 20 74 6f  ther argument to
16370 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20   this option is 
16380 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74  negative, then t
16390 68 61 74 20 61 72 67 75 6d 65 6e 74 20 69 73 0a  hat argument is.
163a0 2a 2a 20 63 68 61 6e 67 65 64 20 74 6f 20 69 74  ** changed to it
163b0 73 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64  s compile-time d
163c0 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  efault..**.** [[
163d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49  SQLITE_CONFIG_WI
163e0 4e 33 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a  N32_HEAPSIZE]].*
163f0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
16400 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49  FIG_WIN32_HEAPSI
16410 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53  ZE.** <dd>^The S
16420 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e  QLITE_CONFIG_WIN
16430 33 32 5f 48 45 41 50 53 49 5a 45 20 6f 70 74 69  32_HEAPSIZE opti
16440 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c  on is only avail
16450 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69  able if SQLite i
16460 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 66 6f  s.** compiled fo
16470 72 20 57 69 6e 64 6f 77 73 20 77 69 74 68 20 74  r Windows with t
16480 68 65 20 5b 53 51 4c 49 54 45 5f 57 49 4e 33 32  he [SQLITE_WIN32
16490 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d 70 72 6f  _MALLOC] pre-pro
164a0 63 65 73 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a 20  cessor macro.** 
164b0 64 65 66 69 6e 65 64 2e 20 5e 53 51 4c 49 54 45  defined. ^SQLITE
164c0 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45  _CONFIG_WIN32_HE
164d0 41 50 53 49 5a 45 20 74 61 6b 65 73 20 61 20 33  APSIZE takes a 3
164e0 32 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69  2-bit unsigned i
164f0 6e 74 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a 20  nteger value.** 
16500 74 68 61 74 20 73 70 65 63 69 66 69 65 73 20 74  that specifies t
16510 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20  he maximum size 
16520 6f 66 20 74 68 65 20 63 72 65 61 74 65 64 20 68  of the created h
16530 65 61 70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  eap..**.** [[SQL
16540 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
16550 45 5f 48 44 52 53 5a 5d 5d 0a 2a 2a 20 3c 64 74  E_HDRSZ]].** <dt
16560 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
16570 43 41 43 48 45 5f 48 44 52 53 5a 0a 2a 2a 20 3c  CACHE_HDRSZ.** <
16580 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  dd>^The SQLITE_C
16590 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52  ONFIG_PCACHE_HDR
165a0 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  SZ option takes 
165b0 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74  a single paramet
165c0 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61  er which.** is a
165d0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
165e0 6e 74 65 67 65 72 20 61 6e 64 20 77 72 69 74 65  nteger and write
165f0 73 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65  s into that inte
16600 67 65 72 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ger the number o
16610 66 20 65 78 74 72 61 0a 2a 2a 20 62 79 74 65 73  f extra.** bytes
16620 20 70 65 72 20 70 61 67 65 20 72 65 71 75 69 72   per page requir
16630 65 64 20 66 6f 72 20 65 61 63 68 20 70 61 67 65  ed for each page
16640 20 69 6e 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   in [SQLITE_CONF
16650 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a  IG_PAGECACHE]..*
16660 2a 20 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20  * The amount of 
16670 65 78 74 72 61 20 73 70 61 63 65 20 72 65 71 75  extra space requ
16680 69 72 65 64 20 63 61 6e 20 63 68 61 6e 67 65 20  ired can change 
16690 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
166a0 20 63 6f 6d 70 69 6c 65 72 2c 0a 2a 2a 20 74 61   compiler,.** ta
166b0 72 67 65 74 20 70 6c 61 74 66 6f 72 6d 2c 20 61  rget platform, a
166c0 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  nd SQLite versio
166d0 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  n..**.** [[SQLIT
166e0 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 5d 5d  E_CONFIG_PMASZ]]
166f0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
16700 4f 4e 46 49 47 5f 50 4d 41 53 5a 0a 2a 2a 20 3c  ONFIG_PMASZ.** <
16710 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  dd>^The SQLITE_C
16720 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 6f 70 74 69  ONFIG_PMASZ opti
16730 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
16740 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63  e parameter whic
16750 68 0a 2a 2a 20 69 73 20 61 6e 20 75 6e 73 69 67  h.** is an unsig
16760 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20  ned integer and 
16770 73 65 74 73 20 74 68 65 20 22 4d 69 6e 69 6d 75  sets the "Minimu
16780 6d 20 50 4d 41 20 53 69 7a 65 22 20 66 6f 72 20  m PMA Size" for 
16790 74 68 65 20 6d 75 6c 74 69 74 68 72 65 61 64 65  the multithreade
167a0 64 0a 2a 2a 20 73 6f 72 74 65 72 20 74 6f 20 74  d.** sorter to t
167b0 68 61 74 20 69 6e 74 65 67 65 72 2e 20 20 54 68  hat integer.  Th
167c0 65 20 64 65 66 61 75 6c 74 20 6d 69 6e 69 6d 75  e default minimu
167d0 6d 20 50 4d 41 20 53 69 7a 65 20 69 73 20 73 65  m PMA Size is se
167e0 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  t by the.** [SQL
167f0 49 54 45 5f 53 4f 52 54 45 52 5f 50 4d 41 53 5a  ITE_SORTER_PMASZ
16800 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
16810 70 74 69 6f 6e 2e 20 20 4e 65 77 20 74 68 72 65  ption.  New thre
16820 61 64 73 20 61 72 65 20 6c 61 75 6e 63 68 65 64  ads are launched
16830 0a 2a 2a 20 74 6f 20 68 65 6c 70 20 77 69 74 68  .** to help with
16840 20 73 6f 72 74 20 6f 70 65 72 61 74 69 6f 6e 73   sort operations
16850 20 77 68 65 6e 20 6d 75 6c 74 69 74 68 72 65 61   when multithrea
16860 64 65 64 20 73 6f 72 74 69 6e 67 0a 2a 2a 20 69  ded sorting.** i
16870 73 20 65 6e 61 62 6c 65 64 20 28 75 73 69 6e 67  s enabled (using
16880 20 74 68 65 20 5b 50 52 41 47 4d 41 20 74 68 72   the [PRAGMA thr
16890 65 61 64 73 5d 20 63 6f 6d 6d 61 6e 64 29 20 61  eads] command) a
168a0 6e 64 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66  nd the amount of
168b0 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 74 6f 20 62   content.** to b
168c0 65 20 73 6f 72 74 65 64 20 65 78 63 65 65 64 73  e sorted exceeds
168d0 20 74 68 65 20 70 61 67 65 20 73 69 7a 65 20 74   the page size t
168e0 69 6d 65 73 20 74 68 65 20 6d 69 6e 69 6d 75 6d  imes the minimum
168f0 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 50 52 41 47   of the.** [PRAG
16900 4d 41 20 63 61 63 68 65 5f 73 69 7a 65 5d 20 73  MA cache_size] s
16910 65 74 74 69 6e 67 20 61 6e 64 20 74 68 69 73 20  etting and this 
16920 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  value..**.** [[S
16930 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d  QLITE_CONFIG_STM
16940 54 4a 52 4e 4c 5f 53 50 49 4c 4c 5d 5d 0a 2a 2a  TJRNL_SPILL]].**
16950 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
16960 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c  IG_STMTJRNL_SPIL
16970 4c 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51  L.** <dd>^The SQ
16980 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54  LITE_CONFIG_STMT
16990 4a 52 4e 4c 5f 53 50 49 4c 4c 20 6f 70 74 69 6f  JRNL_SPILL optio
169a0 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
169b0 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68   parameter which
169c0 0a 2a 2a 20 62 65 63 6f 6d 65 73 20 74 68 65 20  .** becomes the 
169d0 5b 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e  [statement journ
169e0 61 6c 5d 20 73 70 69 6c 6c 2d 74 6f 2d 64 69 73  al] spill-to-dis
169f0 6b 20 74 68 72 65 73 68 6f 6c 64 2e 20 20 0a 2a  k threshold.  .*
16a00 2a 20 5b 53 74 61 74 65 6d 65 6e 74 20 6a 6f 75  * [Statement jou
16a10 72 6e 61 6c 73 5d 20 61 72 65 20 68 65 6c 64 20  rnals] are held 
16a20 69 6e 20 6d 65 6d 6f 72 79 20 75 6e 74 69 6c 20  in memory until 
16a30 74 68 65 69 72 20 73 69 7a 65 20 28 69 6e 20 62  their size (in b
16a40 79 74 65 73 29 0a 2a 2a 20 65 78 63 65 65 64 73  ytes).** exceeds
16a50 20 74 68 69 73 20 74 68 72 65 73 68 6f 6c 64 2c   this threshold,
16a60 20 61 74 20 77 68 69 63 68 20 70 6f 69 6e 74 20   at which point 
16a70 74 68 65 79 20 61 72 65 20 77 72 69 74 74 65 6e  they are written
16a80 20 74 6f 20 64 69 73 6b 2e 0a 2a 2a 20 4f 72 20   to disk..** Or 
16a90 69 66 20 74 68 65 20 74 68 72 65 73 68 6f 6c 64  if the threshold
16aa0 20 69 73 20 2d 31 2c 20 73 74 61 74 65 6d 65 6e   is -1, statemen
16ab0 74 20 6a 6f 75 72 6e 61 6c 73 20 61 72 65 20 61  t journals are a
16ac0 6c 77 61 79 73 20 68 65 6c 64 0a 2a 2a 20 65 78  lways held.** ex
16ad0 63 6c 75 73 69 76 65 6c 79 20 69 6e 20 6d 65 6d  clusively in mem
16ae0 6f 72 79 2e 0a 2a 2a 20 53 69 6e 63 65 20 6d 61  ory..** Since ma
16af0 6e 79 20 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75  ny statement jou
16b00 72 6e 61 6c 73 20 6e 65 76 65 72 20 62 65 63 6f  rnals never beco
16b10 6d 65 20 6c 61 72 67 65 2c 20 73 65 74 74 69 6e  me large, settin
16b20 67 20 74 68 65 20 73 70 69 6c 6c 0a 2a 2a 20 74  g the spill.** t
16b30 68 72 65 73 68 6f 6c 64 20 74 6f 20 61 20 76 61  hreshold to a va
16b40 6c 75 65 20 73 75 63 68 20 61 73 20 36 34 4b 69  lue such as 64Ki
16b50 42 20 63 61 6e 20 67 72 65 61 74 6c 79 20 72 65  B can greatly re
16b60 64 75 63 65 20 74 68 65 20 61 6d 6f 75 6e 74 20  duce the amount 
16b70 6f 66 0a 2a 2a 20 49 2f 4f 20 72 65 71 75 69 72  of.** I/O requir
16b80 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 73 74  ed to support st
16b90 61 74 65 6d 65 6e 74 20 72 6f 6c 6c 62 61 63 6b  atement rollback
16ba0 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74  ..** The default
16bb0 20 76 61 6c 75 65 20 66 6f 72 20 74 68 69 73 20   value for this 
16bc0 73 65 74 74 69 6e 67 20 69 73 20 63 6f 6e 74 72  setting is contr
16bd0 6f 6c 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  olled by the.** 
16be0 5b 53 51 4c 49 54 45 5f 53 54 4d 54 4a 52 4e 4c  [SQLITE_STMTJRNL
16bf0 5f 53 50 49 4c 4c 5d 20 63 6f 6d 70 69 6c 65 2d  _SPILL] compile-
16c00 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20  time option..** 
16c10 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
16c20 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
16c30 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 20  INGLETHREAD  1  
16c40 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
16c50 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16c60 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 20  MULTITHREAD   2 
16c70 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
16c80 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
16c90 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33  _SERIALIZED    3
16ca0 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66    /* nil */.#def
16cb0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
16cc0 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20  G_MALLOC        
16cd0 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65  4  /* sqlite3_me
16ce0 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  m_methods* */.#d
16cf0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
16d00 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20  FIG_GETMALLOC   
16d10 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f    5  /* sqlite3_
16d20 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  mem_methods* */.
16d30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16d40 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 20  ONFIG_SCRATCH   
16d50 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c      6  /* void*,
16d60 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a   int sz, int N *
16d70 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16d80 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
16d90 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64  E     7  /* void
16da0 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e  *, int sz, int N
16db0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16dc0 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20  TE_CONFIG_HEAP  
16dd0 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f          8  /* vo
16de0 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20  id*, int nByte, 
16df0 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69  int min */.#defi
16e00 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
16e10 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 39  _MEMSTATUS     9
16e20 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a    /* boolean */.
16e30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16e40 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20  ONFIG_MUTEX     
16e50 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65     10  /* sqlite
16e60 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a  3_mutex_methods*
16e70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16e80 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
16e90 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71  EX     11  /* sq
16ea0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
16eb0 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69  ods* */./* previ
16ec0 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e  ously SQLITE_CON
16ed0 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31  FIG_CHUNKALLOC 1
16ee0 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75  2 which is now u
16ef0 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69  nused. */ .#defi
16f00 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
16f10 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33  _LOOKASIDE    13
16f20 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a    /* int int */.
16f30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16f40 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20 20  ONFIG_PCACHE    
16f50 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20     14  /* no-op 
16f60 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16f70 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
16f80 48 45 20 20 20 20 31 35 20 20 2f 2a 20 6e 6f 2d  HE    15  /* no-
16f90 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  op */.#define SQ
16fa0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
16fb0 20 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a 20           16  /* 
16fc0 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a  xFunc, void* */.
16fd0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16fe0 4f 4e 46 49 47 5f 55 52 49 20 20 20 20 20 20 20  ONFIG_URI       
16ff0 20 20 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a 2f     17  /* int */
17000 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17010 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 20  CONFIG_PCACHE2  
17020 20 20 20 20 31 38 20 20 2f 2a 20 73 71 6c 69 74      18  /* sqlit
17030 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
17040 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  s2* */.#define S
17050 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
17060 50 43 41 43 48 45 32 20 20 20 31 39 20 20 2f 2a  PCACHE2   19  /*
17070 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f   sqlite3_pcache_
17080 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65  methods2* */.#de
17090 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
170a0 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45  IG_COVERING_INDE
170b0 58 5f 53 43 41 4e 20 32 30 20 20 2f 2a 20 69 6e  X_SCAN 20  /* in
170c0 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
170d0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f  ITE_CONFIG_SQLLO
170e0 47 20 20 20 20 20 20 20 32 31 20 20 2f 2a 20 78  G       21  /* x
170f0 53 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20 2a 2f  Sqllog, void* */
17100 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17110 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45  CONFIG_MMAP_SIZE
17120 20 20 20 20 32 32 20 20 2f 2a 20 73 71 6c 69 74      22  /* sqlit
17130 65 33 5f 69 6e 74 36 34 2c 20 73 71 6c 69 74 65  e3_int64, sqlite
17140 33 5f 69 6e 74 36 34 20 2a 2f 0a 23 64 65 66 69  3_int64 */.#defi
17150 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
17160 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20  _WIN32_HEAPSIZE 
17170 20 20 20 20 20 32 33 20 20 2f 2a 20 69 6e 74 20       23  /* int 
17180 6e 42 79 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65  nByte */.#define
17190 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
171a0 43 41 43 48 45 5f 48 44 52 53 5a 20 20 20 20 20  CACHE_HDRSZ     
171b0 20 20 20 32 34 20 20 2f 2a 20 69 6e 74 20 2a 70     24  /* int *p
171c0 73 7a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  sz */.#define SQ
171d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53  LITE_CONFIG_PMAS
171e0 5a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  Z               
171f0 32 35 20 20 2f 2a 20 75 6e 73 69 67 6e 65 64 20  25  /* unsigned 
17200 69 6e 74 20 73 7a 50 6d 61 20 2a 2f 0a 23 64 65  int szPma */.#de
17210 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
17220 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c  IG_STMTJRNL_SPIL
17230 4c 20 20 20 20 20 20 32 36 20 20 2f 2a 20 69 6e  L      26  /* in
17240 74 20 6e 42 79 74 65 20 2a 2f 0a 0a 2f 2a 0a 2a  t nByte */../*.*
17250 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61  * CAPI3REF: Data
17260 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20  base Connection 
17270 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70  Configuration Op
17280 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
17290 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
172a0 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  the available in
172b0 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74  teger configurat
172c0 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  ion options that
172d0 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65  .** can be passe
172e0 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
172f0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
17300 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
17310 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ig()] interface.
17320 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69  .**.** New confi
17330 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
17340 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
17350 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
17360 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45   of SQLite..** E
17370 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72  xisting configur
17380 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69  ation options mi
17390 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e  ght be discontin
173a0 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ued.  Applicatio
173b0 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65  ns.** should che
173c0 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f  ck the return co
173d0 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  de from [sqlite3
173e0 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f  _db_config()] to
173f0 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a   make sure that.
17400 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b  ** the call work
17410 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74  ed.  ^The [sqlit
17420 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
17430 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72  interface will r
17440 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a  eturn a.** non-z
17450 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
17460 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75   if a discontinu
17470 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65  ed or unsupporte
17480 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  d configuration 
17490 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76  option.** is inv
174a0 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  oked..**.** <dl>
174b0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
174c0 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
174d0 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
174e0 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
174f0 73 20 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e  s three addition
17500 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  al arguments tha
17510 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  t determine the 
17520 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d  .** [lookaside m
17530 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d  emory allocator]
17540 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66   configuration f
17550 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  or the [database
17560 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a   connection]..**
17570 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
17580 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72 64 20  ment (the third 
17590 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
175a0 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
175b0 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74  )] is a.** point
175c0 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62  er to a memory b
175d0 75 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72  uffer to use for
175e0 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
175f0 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  y..** ^The first
17600 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20   argument after 
17610 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  the SQLITE_DBCON
17620 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65  FIG_LOOKASIDE ve
17630 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c  rb.** may be NUL
17640 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  L in which case 
17650 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f  SQLite will allo
17660 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b  cate the.** look
17670 61 73 69 64 65 20 62 75 66 66 65 72 20 69 74 73  aside buffer its
17680 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  elf using [sqlit
17690 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54  e3_malloc()]. ^T
176a0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
176b0 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a  nt is the.** siz
176c0 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73  e of each lookas
176d0 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e  ide buffer slot.
176e0 20 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67    ^The third arg
176f0 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d  ument is the num
17700 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e  ber of.** slots.
17710 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68    The size of th
17720 65 20 62 75 66 66 65 72 20 69 6e 20 74 68 65 20  e buffer in the 
17730 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d  first argument m
17740 75 73 74 20 62 65 20 67 72 65 61 74 65 72 20 74  ust be greater t
17750 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20  han.** or equal 
17760 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f  to the product o
17770 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64  f the second and
17780 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73   third arguments
17790 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a  .  The buffer.**
177a0 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64   must be aligned
177b0 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f   to an 8-byte bo
177c0 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65  undary.  ^If the
177d0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
177e0 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42   to.** SQLITE_DB
177f0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
17800 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70   is not a multip
17810 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69  le of 8, it is i
17820 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75  nternally.** rou
17830 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65  nded down to the
17840 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75   next smaller mu
17850 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28  ltiple of 8.  ^(
17860 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  The lookaside me
17870 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  mory.** configur
17880 61 74 69 6f 6e 20 66 6f 72 20 61 20 64 61 74 61  ation for a data
17890 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
178a0 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e  can only be chan
178b0 67 65 64 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a  ged when that.**
178c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e   connection is n
178d0 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69  ot currently usi
178e0 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  ng lookaside mem
178f0 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72  ory, or in other
17900 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74   words.** when t
17910 68 65 20 22 63 75 72 72 65 6e 74 20 76 61 6c 75  he "current valu
17920 65 22 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  e" returned by.*
17930 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74  * [sqlite3_db_st
17940 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f  atus](D,[SQLITE_
17950 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
17960 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a  ],...) is zero..
17970 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74  ** Any attempt t
17980 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f  o change the loo
17990 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f  kaside memory co
179a0 6e 66 69 67 75 72 61 74 69 6f 6e 20 77 68 65 6e  nfiguration when
179b0 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65   lookaside.** me
179c0 6d 6f 72 79 20 69 73 20 69 6e 20 75 73 65 20 6c  mory is in use l
179d0 65 61 76 65 73 20 74 68 65 20 63 6f 6e 66 69 67  eaves the config
179e0 75 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65  uration unchange
179f0 64 20 61 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a  d and returns .*
17a00 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e  * [SQLITE_BUSY].
17a10 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  )^</dd>.**.** <d
17a20 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
17a30 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64  G_ENABLE_FKEY</d
17a40 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
17a50 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
17a60 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73  to enable or dis
17a70 61 62 6c 65 20 74 68 65 20 65 6e 66 6f 72 63 65  able the enforce
17a80 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65  ment of.** [fore
17a90 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69  ign key constrai
17aa0 6e 74 73 5d 2e 20 20 54 68 65 72 65 20 73 68 6f  nts].  There sho
17ab0 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74  uld be two addit
17ac0 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e  ional arguments.
17ad0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
17ae0 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74  gument is an int
17af0 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20  eger which is 0 
17b00 74 6f 20 64 69 73 61 62 6c 65 20 46 4b 20 65 6e  to disable FK en
17b10 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f  forcement,.** po
17b20 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65  sitive to enable
17b30 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20   FK enforcement 
17b40 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c  or negative to l
17b50 65 61 76 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d  eave FK enforcem
17b60 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64  ent.** unchanged
17b70 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  .  The second pa
17b80 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
17b90 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
17ba0 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a  er into which.**
17bb0 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72   is written 0 or
17bc0 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77   1 to indicate w
17bd0 68 65 74 68 65 72 20 46 4b 20 65 6e 66 6f 72 63  hether FK enforc
17be0 65 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f 72 20  ement is off or 
17bf0 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  on.** following 
17c00 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20  this call.  The 
17c10 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
17c20 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70   may be a NULL p
17c30 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68  ointer, in.** wh
17c40 69 63 68 20 63 61 73 65 20 74 68 65 20 46 4b 20  ich case the FK 
17c50 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65 74 74  enforcement sett
17c60 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72  ing is not repor
17c70 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a  ted back. </dd>.
17c80 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
17c90 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
17ca0 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a  _TRIGGER</dt>.**
17cb0 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
17cc0 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e  on is used to en
17cd0 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20  able or disable 
17ce0 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20  [CREATE TRIGGER 
17cf0 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20  | triggers]..** 
17d00 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20  There should be 
17d10 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61  two additional a
17d20 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65  rguments..** The
17d30 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
17d40 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  is an integer wh
17d50 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61  ich is 0 to disa
17d60 62 6c 65 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a  ble triggers,.**
17d70 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61   positive to ena
17d80 62 6c 65 20 74 72 69 67 67 65 72 73 20 6f 72 20  ble triggers or 
17d90 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76  negative to leav
17da0 65 20 74 68 65 20 73 65 74 74 69 6e 67 20 75 6e  e the setting un
17db0 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20  changed..** The 
17dc0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
17dd0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
17de0 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f   an integer into
17df0 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69   which.** is wri
17e00 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69  tten 0 or 1 to i
17e10 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20  ndicate whether 
17e20 74 72 69 67 67 65 72 73 20 61 72 65 20 64 69 73  triggers are dis
17e30 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64  abled or enabled
17e40 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  .** following th
17e50 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65  is call.  The se
17e60 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d  cond parameter m
17e70 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69  ay be a NULL poi
17e80 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63  nter, in.** whic
17e90 68 20 63 61 73 65 20 74 68 65 20 74 72 69 67 67  h case the trigg
17ea0 65 72 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f  er setting is no
17eb0 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e  t reported back.
17ec0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74   </dd>.**.** <dt
17ed0 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
17ee0 5f 45 4e 41 42 4c 45 5f 46 54 53 33 5f 54 4f 4b  _ENABLE_FTS3_TOK
17ef0 45 4e 49 5a 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c  ENIZER</dt>.** <
17f00 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
17f10 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62   is used to enab
17f20 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68  le or disable th
17f30 65 20 74 77 6f 2d 61 72 67 75 6d 65 6e 74 0a 2a  e two-argument.*
17f40 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65  * version of the
17f50 20 5b 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72   [fts3_tokenizer
17f60 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 77 68 69  ()] function whi
17f70 63 68 20 69 73 20 70 61 72 74 20 6f 66 20 74 68  ch is part of th
17f80 65 0a 2a 2a 20 5b 46 54 53 33 5d 20 66 75 6c 6c  e.** [FTS3] full
17f90 2d 74 65 78 74 20 73 65 61 72 63 68 20 65 6e 67  -text search eng
17fa0 69 6e 65 20 65 78 74 65 6e 73 69 6f 6e 2e 0a 2a  ine extension..*
17fb0 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62  * There should b
17fc0 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c  e two additional
17fd0 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54   arguments..** T
17fe0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
17ff0 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  t is an integer 
18000 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69  which is 0 to di
18010 73 61 62 6c 65 20 66 74 73 33 5f 74 6f 6b 65 6e  sable fts3_token
18020 69 7a 65 72 28 29 20 6f 72 0a 2a 2a 20 70 6f 73  izer() or.** pos
18030 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20  itive to enable 
18040 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28 29  fts3_tokenizer()
18050 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20   or negative to 
18060 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e  leave the settin
18070 67 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 0a  g.** unchanged..
18080 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  ** The second pa
18090 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
180a0 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
180b0 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a  er into which.**
180c0 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72   is written 0 or
180d0 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77   1 to indicate w
180e0 68 65 74 68 65 72 20 66 74 73 33 5f 74 6f 6b 65  hether fts3_toke
180f0 6e 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65  nizer is disable
18100 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20  d or enabled.** 
18110 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63  following this c
18120 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  all.  The second
18130 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
18140 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  e a NULL pointer
18150 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61  , in.** which ca
18160 73 65 20 74 68 65 20 6e 65 77 20 73 65 74 74 69  se the new setti
18170 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74  ng is not report
18180 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a  ed back. </dd>.*
18190 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
181a0 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
181b0 4c 4f 41 44 5f 45 58 54 45 4e 53 49 4f 4e 3c 2f  LOAD_EXTENSION</
181c0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
181d0 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  s option is used
181e0 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69   to enable or di
181f0 73 61 62 6c 65 20 74 68 65 20 5b 73 71 6c 69 74  sable the [sqlit
18200 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  e3_load_extensio
18210 6e 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  n()].** interfac
18220 65 20 69 6e 64 65 70 65 6e 64 65 6e 74 6c 79 20  e independently 
18230 6f 66 20 74 68 65 20 5b 6c 6f 61 64 5f 65 78 74  of the [load_ext
18240 65 6e 73 69 6f 6e 28 29 5d 20 53 51 4c 20 66 75  ension()] SQL fu
18250 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20 5b  nction..** The [
18260 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c  sqlite3_enable_l
18270 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d  oad_extension()]
18280 20 41 50 49 20 65 6e 61 62 6c 65 73 20 6f 72 20   API enables or 
18290 64 69 73 61 62 6c 65 73 20 62 6f 74 68 20 74 68  disables both th
182a0 65 0a 2a 2a 20 43 2d 41 50 49 20 5b 73 71 6c 69  e.** C-API [sqli
182b0 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  te3_load_extensi
182c0 6f 6e 28 29 5d 20 61 6e 64 20 74 68 65 20 53 51  on()] and the SQ
182d0 4c 20 66 75 6e 63 74 69 6f 6e 20 5b 6c 6f 61 64  L function [load
182e0 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 2e 0a 2a  _extension()]..*
182f0 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62  * There should b
18300 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c  e two additional
18310 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 57   arguments..** W
18320 68 65 6e 20 74 68 65 20 66 69 72 73 74 20 61 72  hen the first ar
18330 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 69  gument to this i
18340 6e 74 65 72 66 61 63 65 20 69 73 20 31 2c 20 74  nterface is 1, t
18350 68 65 6e 20 6f 6e 6c 79 20 74 68 65 20 43 2d 41  hen only the C-A
18360 50 49 20 69 73 0a 2a 2a 20 65 6e 61 62 6c 65 64  PI is.** enabled
18370 20 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75 6e   and the SQL fun
18380 63 74 69 6f 6e 20 72 65 6d 61 69 6e 73 20 64 69  ction remains di
18390 73 61 62 6c 65 64 2e 20 20 49 66 20 74 68 65 20  sabled.  If the 
183a0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
183b0 6f 0a 2a 2a 20 74 68 69 73 20 69 6e 74 65 72 66  o.** this interf
183c0 61 63 65 20 69 73 20 30 2c 20 74 68 65 6e 20 62  ace is 0, then b
183d0 6f 74 68 20 74 68 65 20 43 2d 41 50 49 20 61 6e  oth the C-API an
183e0 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  d the SQL functi
183f0 6f 6e 20 61 72 65 20 64 69 73 61 62 6c 65 64 2e  on are disabled.
18400 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 72 73 74  .** If the first
18410 20 61 72 67 75 6d 65 6e 74 20 69 73 20 2d 31 2c   argument is -1,
18420 20 74 68 65 6e 20 6e 6f 20 63 68 61 6e 67 65 73   then no changes
18430 20 61 72 65 20 6d 61 64 65 20 74 6f 20 73 74 61   are made to sta
18440 74 65 20 6f 66 20 65 69 74 68 65 72 20 74 68 65  te of either the
18450 0a 2a 2a 20 43 2d 41 50 49 20 6f 72 20 74 68 65  .** C-API or the
18460 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a   SQL function..*
18470 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * The second par
18480 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
18490 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
184a0 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20  r into which.** 
184b0 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20  is written 0 or 
184c0 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  1 to indicate wh
184d0 65 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 6c  ether [sqlite3_l
184e0 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d  oad_extension()]
184f0 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 73   interface.** is
18500 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61   disabled or ena
18510 62 6c 65 64 20 66 6f 6c 6c 6f 77 69 6e 67 20 74  bled following t
18520 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73  his call.  The s
18530 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
18540 6d 61 79 0a 2a 2a 20 62 65 20 61 20 4e 55 4c 4c  may.** be a NULL
18550 20 70 6f 69 6e 74 65 72 2c 20 69 6e 20 77 68 69   pointer, in whi
18560 63 68 20 63 61 73 65 20 74 68 65 20 6e 65 77 20  ch case the new 
18570 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72  setting is not r
18580 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 0a 2a 2a  eported back..**
18590 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74   </dd>.**.** <dt
185a0 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
185b0 5f 4d 41 49 4e 44 42 4e 41 4d 45 3c 2f 64 74 3e  _MAINDBNAME</dt>
185c0 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
185d0 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f  ption is used to
185e0 20 63 68 61 6e 67 65 20 74 68 65 20 6e 61 6d 65   change the name
185f0 20 6f 66 20 74 68 65 20 22 6d 61 69 6e 22 20 64   of the "main" d
18600 61 74 61 62 61 73 65 0a 2a 2a 20 73 63 68 65 6d  atabase.** schem
18610 61 2e 20 20 5e 54 68 65 20 73 6f 6c 65 20 61 72  a.  ^The sole ar
18620 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
18630 74 65 72 20 74 6f 20 61 20 63 6f 6e 73 74 61 6e  ter to a constan
18640 74 20 55 54 46 38 20 73 74 72 69 6e 67 0a 2a 2a  t UTF8 string.**
18650 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65 63 6f   which will beco
18660 6d 65 20 74 68 65 20 6e 65 77 20 73 63 68 65 6d  me the new schem
18670 61 20 6e 61 6d 65 20 69 6e 20 70 6c 61 63 65 20  a name in place 
18680 6f 66 20 22 6d 61 69 6e 22 2e 20 20 5e 53 51 4c  of "main".  ^SQL
18690 69 74 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  ite.** does not 
186a0 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f 66 20 74  make a copy of t
186b0 68 65 20 6e 65 77 20 6d 61 69 6e 20 73 63 68 65  he new main sche
186c0 6d 61 20 6e 61 6d 65 20 73 74 72 69 6e 67 2c 20  ma name string, 
186d0 73 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  so the applicati
186e0 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e 73 75 72  on.** must ensur
186f0 65 20 74 68 61 74 20 74 68 65 20 61 72 67 75 6d  e that the argum
18700 65 6e 74 20 70 61 73 73 65 64 20 69 6e 74 6f 20  ent passed into 
18710 74 68 69 73 20 44 42 43 4f 4e 46 49 47 20 6f 70  this DBCONFIG op
18720 74 69 6f 6e 20 69 73 20 75 6e 63 68 61 6e 67 65  tion is unchange
18730 64 0a 2a 2a 20 75 6e 74 69 6c 20 61 66 74 65 72  d.** until after
18740 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
18750 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e  nnection closes.
18760 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .** </dd>.**.** 
18770 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
18780 46 49 47 5f 4e 4f 5f 43 4b 50 54 5f 4f 4e 5f 43  FIG_NO_CKPT_ON_C
18790 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LOSE</dt>.** <dd
187a0 3e 20 55 73 75 61 6c 6c 79 2c 20 77 68 65 6e 20  > Usually, when 
187b0 61 20 64 61 74 61 62 61 73 65 20 69 6e 20 77 61  a database in wa
187c0 6c 20 6d 6f 64 65 20 69 73 20 63 6c 6f 73 65 64  l mode is closed
187d0 20 6f 72 20 64 65 74 61 63 68 65 64 20 66 72 6f   or detached fro
187e0 6d 20 61 20 0a 2a 2a 20 64 61 74 61 62 61 73 65  m a .** database
187f0 20 68 61 6e 64 6c 65 2c 20 53 51 4c 69 74 65 20   handle, SQLite 
18800 63 68 65 63 6b 73 20 69 66 20 74 68 69 73 20 77  checks if this w
18810 69 6c 6c 20 6d 65 61 6e 20 74 68 61 74 20 74 68  ill mean that th
18820 65 72 65 20 61 72 65 20 6e 6f 77 20 6e 6f 20 0a  ere are now no .
18830 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 61  ** connections a
18840 74 20 61 6c 6c 20 74 6f 20 74 68 65 20 64 61 74  t all to the dat
18850 61 62 61 73 65 2e 20 49 66 20 73 6f 2c 20 69 74  abase. If so, it
18860 20 70 65 72 66 6f 72 6d 73 20 61 20 63 68 65 63   performs a chec
18870 6b 70 6f 69 6e 74 20 0a 2a 2a 20 6f 70 65 72 61  kpoint .** opera
18880 74 69 6f 6e 20 62 65 66 6f 72 65 20 63 6c 6f 73  tion before clos
18890 69 6e 67 20 74 68 65 20 63 6f 6e 6e 65 63 74 69  ing the connecti
188a0 6f 6e 2e 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  on. This option 
188b0 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f 0a 2a  may be used to.*
188c0 2a 20 6f 76 65 72 72 69 64 65 20 74 68 69 73 20  * override this 
188d0 62 65 68 61 76 69 6f 75 72 2e 20 54 68 65 20 66  behaviour. The f
188e0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 70  irst parameter p
188f0 61 73 73 65 64 20 74 6f 20 74 68 69 73 20 6f 70  assed to this op
18900 65 72 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 61 6e  eration.** is an
18910 20 69 6e 74 65 67 65 72 20 2d 20 6e 6f 6e 2d 7a   integer - non-z
18920 65 72 6f 20 74 6f 20 64 69 73 61 62 6c 65 20 63  ero to disable c
18930 68 65 63 6b 70 6f 69 6e 74 73 2d 6f 6e 2d 63 6c  heckpoints-on-cl
18940 6f 73 65 2c 20 6f 72 20 7a 65 72 6f 20 28 74 68  ose, or zero (th
18950 65 0a 2a 2a 20 64 65 66 61 75 6c 74 29 20 74 6f  e.** default) to
18960 20 65 6e 61 62 6c 65 20 74 68 65 6d 2e 20 54 68   enable them. Th
18970 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
18980 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  er is a pointer 
18990 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  to an integer.**
189a0 20 69 6e 74 6f 20 77 68 69 63 68 20 69 73 20 77   into which is w
189b0 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f  ritten 0 or 1 to
189c0 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65   indicate whethe
189d0 72 20 63 68 65 63 6b 70 6f 69 6e 74 73 2d 6f 6e  r checkpoints-on
189e0 2d 63 6c 6f 73 65 0a 2a 2a 20 68 61 76 65 20 62  -close.** have b
189f0 65 65 6e 20 64 69 73 61 62 6c 65 64 20 2d 20 30  een disabled - 0
18a00 20 69 66 20 74 68 65 79 20 61 72 65 20 6e 6f 74   if they are not
18a10 20 64 69 73 61 62 6c 65 64 2c 20 31 20 69 66 20   disabled, 1 if 
18a20 74 68 65 79 20 61 72 65 2e 0a 2a 2a 20 3c 2f 64  they are..** </d
18a30 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
18a40 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 46 55 4c  ITE_DBCONFIG_FUL
18a50 4c 5f 45 51 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  L_EQP</dt>.** <d
18a60 64 3e 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74  d> By default, t
18a70 68 65 20 6f 75 74 70 75 74 20 6f 66 20 45 58 50  he output of EXP
18a80 4c 41 49 4e 20 51 55 45 52 59 20 50 4c 41 4e 20  LAIN QUERY PLAN 
18a90 63 6f 6d 6d 61 6e 64 73 20 64 6f 65 73 20 6e 6f  commands does no
18aa0 74 20 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 6f 75  t .** include ou
18ab0 74 70 75 74 20 66 6f 72 20 61 6e 79 20 6f 70 65  tput for any ope
18ac0 72 61 74 69 6f 6e 73 20 70 65 72 66 6f 72 6d 65  rations performe
18ad0 64 20 62 79 20 74 72 69 67 67 65 72 20 70 72 6f  d by trigger pro
18ae0 67 72 61 6d 73 2e 20 54 68 69 73 0a 2a 2a 20 6f  grams. This.** o
18af0 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f  ption is used to
18b00 20 73 65 74 20 6f 72 20 63 6c 65 61 72 20 28 74   set or clear (t
18b10 68 65 20 64 65 66 61 75 6c 74 29 20 61 20 66 6c  he default) a fl
18b20 61 67 20 74 68 61 74 20 67 6f 76 65 72 6e 73 20  ag that governs 
18b30 74 68 69 73 0a 2a 2a 20 62 65 68 61 76 69 6f 72  this.** behavior
18b40 2e 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61  . The first para
18b50 6d 65 74 65 72 20 70 61 73 73 65 64 20 74 6f 20  meter passed to 
18b60 74 68 69 73 20 6f 70 65 72 61 74 69 6f 6e 20 69  this operation i
18b70 73 20 61 6e 20 69 6e 74 65 67 65 72 20 2d 0a 2a  s an integer -.*
18b80 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 74 6f 20 65 6e  * non-zero to en
18b90 61 62 6c 65 20 6f 75 74 70 75 74 20 66 6f 72 20  able output for 
18ba0 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 73  trigger programs
18bb0 2c 20 6f 72 20 7a 65 72 6f 20 74 6f 20 64 69 73  , or zero to dis
18bc0 61 62 6c 65 20 69 74 2e 0a 2a 2a 20 54 68 65 20  able it..** The 
18bd0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
18be0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
18bf0 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f   an integer into
18c00 20 77 68 69 63 68 20 69 73 20 77 72 69 74 74 65   which is writte
18c10 6e 20 0a 2a 2a 20 30 20 6f 72 20 31 20 74 6f 20  n .** 0 or 1 to 
18c20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72  indicate whether
18c30 20 6f 75 74 70 75 74 2d 66 6f 72 2d 74 72 69 67   output-for-trig
18c40 67 65 72 73 20 68 61 73 20 62 65 65 6e 20 64 69  gers has been di
18c50 73 61 62 6c 65 64 20 2d 20 30 20 69 66 20 0a 2a  sabled - 0 if .*
18c60 2a 20 69 74 20 69 73 20 6e 6f 74 20 64 69 73 61  * it is not disa
18c70 62 6c 65 64 2c 20 31 20 69 66 20 69 74 20 69 73  bled, 1 if it is
18c80 2e 20 20 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 20  .  .** </dd>.** 
18c90 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
18ca0 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
18cb0 5f 4d 41 49 4e 44 42 4e 41 4d 45 20 20 20 20 20  _MAINDBNAME     
18cc0 20 20 20 20 20 20 20 31 30 30 30 20 2f 2a 20 63         1000 /* c
18cd0 6f 6e 73 74 20 63 68 61 72 2a 20 2a 2f 0a 23 64  onst char* */.#d
18ce0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
18cf0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
18d00 20 20 20 20 20 20 20 20 20 20 20 20 31 30 30 31              1001
18d10 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e   /* void* int in
18d20 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
18d30 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
18d40 42 4c 45 5f 46 4b 45 59 20 20 20 20 20 20 20 20  BLE_FKEY        
18d50 20 20 20 31 30 30 32 20 2f 2a 20 69 6e 74 20 69     1002 /* int i
18d60 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nt* */.#define S
18d70 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
18d80 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 20 20 20  NABLE_TRIGGER   
18d90 20 20 20 20 20 31 30 30 33 20 2f 2a 20 69 6e 74       1003 /* int
18da0 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65   int* */.#define
18db0 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
18dc0 5f 45 4e 41 42 4c 45 5f 46 54 53 33 5f 54 4f 4b  _ENABLE_FTS3_TOK
18dd0 45 4e 49 5a 45 52 20 31 30 30 34 20 2f 2a 20 69  ENIZER 1004 /* i
18de0 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69  nt int* */.#defi
18df0 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
18e00 49 47 5f 45 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45  IG_ENABLE_LOAD_E
18e10 58 54 45 4e 53 49 4f 4e 20 31 30 30 35 20 2f 2a  XTENSION 1005 /*
18e20 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65   int int* */.#de
18e30 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
18e40 4e 46 49 47 5f 4e 4f 5f 43 4b 50 54 5f 4f 4e 5f  NFIG_NO_CKPT_ON_
18e50 43 4c 4f 53 45 20 20 20 20 20 20 31 30 30 36 20  CLOSE      1006 
18e60 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23  /* int int* */.#
18e70 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
18e80 43 4f 4e 46 49 47 5f 46 55 4c 4c 5f 45 51 50 20  CONFIG_FULL_EQP 
18e90 20 20 20 20 20 20 20 20 20 20 20 20 20 31 30 30               100
18ea0 37 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f  7 /* int int* */
18eb0 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
18ec0 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73  F: Enable Or Dis
18ed0 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65  able Extended Re
18ee0 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4d 45  sult Codes.** ME
18ef0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
18f00 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
18f10 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
18f20 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65  _codes() routine
18f30 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61   enables or disa
18f40 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74  bles the.** [ext
18f50 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
18f60 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53  es] feature of S
18f70 51 4c 69 74 65 2e 20 5e 54 68 65 20 65 78 74 65  QLite. ^The exte
18f80 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63  nded result.** c
18f90 6f 64 65 73 20 61 72 65 20 64 69 73 61 62 6c 65  odes are disable
18fa0 64 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72  d by default for
18fb0 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70   historical comp
18fc0 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 69 6e  atibility..*/.in
18fd0 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  t sqlite3_extend
18fe0 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28  ed_result_codes(
18ff0 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e  sqlite3*, int on
19000 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  off);../*.** CAP
19010 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65  I3REF: Last Inse
19020 72 74 20 52 6f 77 69 64 0a 2a 2a 20 4d 45 54 48  rt Rowid.** METH
19030 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
19040 2a 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e  * ^Each entry in
19050 20 6d 6f 73 74 20 53 51 4c 69 74 65 20 74 61 62   most SQLite tab
19060 6c 65 73 20 28 65 78 63 65 70 74 20 66 6f 72 20  les (except for 
19070 5b 57 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20  [WITHOUT ROWID] 
19080 74 61 62 6c 65 73 29 0a 2a 2a 20 68 61 73 20 61  tables).** has a
19090 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73   unique 64-bit s
190a0 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72  igned.** integer
190b0 20 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20   key called the 
190c0 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22  [ROWID | "rowid"
190d0 5d 2e 20 5e 54 68 65 20 72 6f 77 69 64 20 69 73  ]. ^The rowid is
190e0 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c   always availabl
190f0 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63  e.** as an undec
19100 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d  lared column nam
19110 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f  ed ROWID, OID, o
19120 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e  r _ROWID_ as lon
19130 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61  g as those.** na
19140 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f  mes are not also
19150 20 75 73 65 64 20 62 79 20 65 78 70 6c 69 63 69   used by explici
19160 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c  tly declared col
19170 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65  umns. ^If.** the
19180 20 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c   table has a col
19190 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54  umn of type [INT
191a0 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59  EGER PRIMARY KEY
191b0 5d 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75  ] then that colu
191c0 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72  mn.** is another
191d0 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72   alias for the r
191e0 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  owid..**.** ^The
191f0 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e   sqlite3_last_in
19200 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20 69 6e  sert_rowid(D) in
19210 74 65 72 66 61 63 65 20 75 73 75 61 6c 6c 79 20  terface usually 
19220 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77  returns the [row
19230 69 64 5d 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 6f  id] of.** the mo
19240 73 74 20 72 65 63 65 6e 74 20 73 75 63 63 65 73  st recent succes
19250 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e  sful [INSERT] in
19260 74 6f 20 61 20 72 6f 77 69 64 20 74 61 62 6c 65  to a rowid table
19270 20 6f 72 20 5b 76 69 72 74 75 61 6c 20 74 61 62   or [virtual tab
19280 6c 65 5d 0a 2a 2a 20 6f 6e 20 64 61 74 61 62 61  le].** on databa
19290 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e  se connection D.
192a0 20 5e 49 6e 73 65 72 74 73 20 69 6e 74 6f 20 5b   ^Inserts into [
192b0 57 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74  WITHOUT ROWID] t
192c0 61 62 6c 65 73 20 61 72 65 20 6e 6f 74 0a 2a 2a  ables are not.**
192d0 20 72 65 63 6f 72 64 65 64 2e 20 5e 49 66 20 6e   recorded. ^If n
192e0 6f 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e  o successful [IN
192f0 53 45 52 54 5d 73 20 69 6e 74 6f 20 72 6f 77 69  SERT]s into rowi
19300 64 20 74 61 62 6c 65 73 20 68 61 76 65 20 65 76  d tables have ev
19310 65 72 20 6f 63 63 75 72 72 65 64 20 0a 2a 2a 20  er occurred .** 
19320 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  on the database 
19330 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2c 20 74 68  connection D, th
19340 65 6e 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  en sqlite3_last_
19350 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20  insert_rowid(D) 
19360 72 65 74 75 72 6e 73 20 0a 2a 2a 20 7a 65 72 6f  returns .** zero
19370 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 77 65 6c 6c 20  ..**.** As well 
19380 61 73 20 62 65 69 6e 67 20 73 65 74 20 61 75 74  as being set aut
19390 6f 6d 61 74 69 63 61 6c 6c 79 20 61 73 20 72 6f  omatically as ro
193a0 77 73 20 61 72 65 20 69 6e 73 65 72 74 65 64 20  ws are inserted 
193b0 69 6e 74 6f 20 64 61 74 61 62 61 73 65 0a 2a 2a  into database.**
193c0 20 74 61 62 6c 65 73 2c 20 74 68 65 20 76 61 6c   tables, the val
193d0 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  ue returned by t
193e0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79  his function may
193f0 20 62 65 20 73 65 74 20 65 78 70 6c 69 63 69 74   be set explicit
19400 6c 79 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ly by.** [sqlite
19410 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72  3_set_last_inser
19420 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 0a 2a 2a  t_rowid()].**.**
19430 20 53 6f 6d 65 20 76 69 72 74 75 61 6c 20 74 61   Some virtual ta
19440 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ble implementati
19450 6f 6e 73 20 6d 61 79 20 49 4e 53 45 52 54 20 72  ons may INSERT r
19460 6f 77 73 20 69 6e 74 6f 20 72 6f 77 69 64 20 74  ows into rowid t
19470 61 62 6c 65 73 20 61 73 0a 2a 2a 20 70 61 72 74  ables as.** part
19480 20 6f 66 20 63 6f 6d 6d 69 74 74 69 6e 67 20 61   of committing a
19490 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 28 65 2e   transaction (e.
194a0 67 2e 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61  g. to flush data
194b0 20 61 63 63 75 6d 75 6c 61 74 65 64 20 69 6e 20   accumulated in 
194c0 6d 65 6d 6f 72 79 0a 2a 2a 20 74 6f 20 64 69 73  memory.** to dis
194d0 6b 29 2e 20 49 6e 20 74 68 69 73 20 63 61 73 65  k). In this case
194e0 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
194f0 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69  s to this functi
19500 6f 6e 20 72 65 74 75 72 6e 20 74 68 65 20 72 6f  on return the ro
19510 77 69 64 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  wid.** associate
19520 64 20 77 69 74 68 20 74 68 65 73 65 20 69 6e 74  d with these int
19530 65 72 6e 61 6c 20 49 4e 53 45 52 54 20 6f 70 65  ernal INSERT ope
19540 72 61 74 69 6f 6e 73 2c 20 77 68 69 63 68 20 6c  rations, which l
19550 65 61 64 73 20 74 6f 20 0a 2a 2a 20 75 6e 69 6e  eads to .** unin
19560 74 75 69 74 69 76 65 20 72 65 73 75 6c 74 73 2e  tuitive results.
19570 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69   Virtual table i
19580 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74  mplementations t
19590 68 61 74 20 64 6f 20 77 72 69 74 65 20 74 6f 20  hat do write to 
195a0 72 6f 77 69 64 0a 2a 2a 20 74 61 62 6c 65 73 20  rowid.** tables 
195b0 69 6e 20 74 68 69 73 20 77 61 79 20 63 61 6e 20  in this way can 
195c0 61 76 6f 69 64 20 74 68 69 73 20 70 72 6f 62 6c  avoid this probl
195d0 65 6d 20 62 79 20 72 65 73 74 6f 72 69 6e 67 20  em by restoring 
195e0 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 0a 2a 2a  the original .**
195f0 20 72 6f 77 69 64 20 76 61 6c 75 65 20 75 73 69   rowid value usi
19600 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  ng [sqlite3_set_
19610 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
19620 64 28 29 5d 20 62 65 66 6f 72 65 20 72 65 74 75  d()] before retu
19630 72 6e 69 6e 67 20 0a 2a 2a 20 63 6f 6e 74 72 6f  rning .** contro
19640 6c 20 74 6f 20 74 68 65 20 75 73 65 72 2e 0a 2a  l to the user..*
19650 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e  *.** ^(If an [IN
19660 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69 74  SERT] occurs wit
19670 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 74 68  hin a trigger th
19680 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  en this routine 
19690 77 69 6c 6c 20 0a 2a 2a 20 72 65 74 75 72 6e 20  will .** return 
196a0 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74  the [rowid] of t
196b0 68 65 20 69 6e 73 65 72 74 65 64 20 72 6f 77 20  he inserted row 
196c0 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74  as long as the t
196d0 72 69 67 67 65 72 20 69 73 20 0a 2a 2a 20 72 75  rigger is .** ru
196e0 6e 6e 69 6e 67 2e 20 4f 6e 63 65 20 74 68 65 20  nning. Once the 
196f0 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20  trigger program 
19700 65 6e 64 73 2c 20 74 68 65 20 76 61 6c 75 65 20  ends, the value 
19710 72 65 74 75 72 6e 65 64 20 0a 2a 2a 20 62 79 20  returned .** by 
19720 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 76  this routine rev
19730 65 72 74 73 20 74 6f 20 77 68 61 74 20 69 74 20  erts to what it 
19740 77 61 73 20 62 65 66 6f 72 65 20 74 68 65 20 74  was before the t
19750 72 69 67 67 65 72 20 77 61 73 20 66 69 72 65 64  rigger was fired
19760 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49  .)^.**.** ^An [I
19770 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c  NSERT] that fail
19780 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74  s due to a const
19790 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20  raint violation 
197a0 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63  is not a.** succ
197b0 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20  essful [INSERT] 
197c0 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61  and does not cha
197d0 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 65  nge the value re
197e0 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a  turned by this.*
197f0 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75  * routine.  ^Thu
19800 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c  s INSERT OR FAIL
19810 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f  , INSERT OR IGNO
19820 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f  RE, INSERT OR RO
19830 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49  LLBACK,.** and I
19840 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d  NSERT OR ABORT m
19850 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74  ake no changes t
19860 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  o the return val
19870 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f  ue of this.** ro
19880 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72  utine when their
19890 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73   insertion fails
198a0 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54  .  ^(When INSERT
198b0 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65   OR REPLACE.** e
198c0 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73  ncounters a cons
198d0 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
198e0 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61  , it does not fa
198f0 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45  il.  The.** INSE
19900 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20  RT continues to 
19910 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72  completion after
19920 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74   deleting rows t
19930 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68  hat caused.** th
19940 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f  e constraint pro
19950 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f  blem so INSERT O
19960 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61  R REPLACE will a
19970 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20  lways change.** 
19980 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
19990 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61   of this interfa
199a0 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72  ce.)^.**.** ^For
199b0 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66   the purposes of
199c0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61   this routine, a
199d0 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f  n [INSERT] is co
199e0 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62  nsidered to.** b
199f0 65 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 65  e successful eve
19a00 6e 20 69 66 20 69 74 20 69 73 20 73 75 62 73 65  n if it is subse
19a10 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62  quently rolled b
19a20 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ack..**.** This 
19a30 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65  function is acce
19a40 73 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74  ssible to SQL st
19a50 61 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65  atements via the
19a60 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74  .** [last_insert
19a70 5f 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e  _rowid() SQL fun
19a80 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  ction]..**.** If
19a90 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
19aa0 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65  ad performs a ne
19ab0 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68  w [INSERT] on th
19ac0 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61  e same.** databa
19ad0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68  se connection wh
19ae0 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ile the [sqlite3
19af0 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
19b00 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f  id()].** functio
19b10 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64  n is running and
19b20 20 74 68 75 73 20 63 68 61 6e 67 65 73 20 74 68   thus changes th
19b30 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72  e last insert [r
19b40 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74  owid],.** then t
19b50 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
19b60 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61  d by [sqlite3_la
19b70 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
19b80 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69  )] is.** unpredi
19b90 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74  ctable and might
19ba0 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65   not equal eithe
19bb0 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65  r the old or the
19bc0 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73   new.** last ins
19bd0 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a  ert [rowid]..*/.
19be0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
19bf0 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
19c00 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a  t_rowid(sqlite3*
19c10 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
19c20 45 46 3a 20 53 65 74 20 74 68 65 20 4c 61 73 74  EF: Set the Last
19c30 20 49 6e 73 65 72 74 20 52 6f 77 69 64 20 76 61   Insert Rowid va
19c40 6c 75 65 2e 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  lue..** METHOD: 
19c50 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68  sqlite3.**.** Th
19c60 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61  e sqlite3_set_la
19c70 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
19c80 44 2c 20 52 29 20 6d 65 74 68 6f 64 20 61 6c 6c  D, R) method all
19c90 6f 77 73 20 74 68 65 20 61 70 70 6c 69 63 61 74  ows the applicat
19ca0 69 6f 6e 20 74 6f 0a 2a 2a 20 73 65 74 20 74 68  ion to.** set th
19cb0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
19cc0 20 62 79 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69   by calling sqli
19cd0 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
19ce0 72 6f 77 69 64 28 44 29 20 74 6f 20 52 20 0a 2a  rowid(D) to R .*
19cf0 2a 20 77 69 74 68 6f 75 74 20 69 6e 73 65 72 74  * without insert
19d00 69 6e 67 20 61 20 72 6f 77 20 69 6e 74 6f 20 74  ing a row into t
19d10 68 65 20 64 61 74 61 62 61 73 65 2e 0a 2a 2f 0a  he database..*/.
19d20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74  void sqlite3_set
19d30 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
19d40 69 64 28 73 71 6c 69 74 65 33 2a 2c 73 71 6c 69  id(sqlite3*,sqli
19d50 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a  te3_int64);../*.
19d60 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75  ** CAPI3REF: Cou
19d70 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66  nt The Number Of
19d80 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a   Rows Modified.*
19d90 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
19da0 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75  3.**.** ^This fu
19db0 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
19dc0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  he number of row
19dd0 73 20 6d 6f 64 69 66 69 65 64 2c 20 69 6e 73 65  s modified, inse
19de0 72 74 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74  rted or.** delet
19df0 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72  ed by the most r
19e00 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65  ecently complete
19e10 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  d INSERT, UPDATE
19e20 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74   or DELETE.** st
19e30 61 74 65 6d 65 6e 74 20 6f 6e 20 74 68 65 20 64  atement on the d
19e40 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
19e50 6f 6e 20 73 70 65 63 69 66 69 65 64 20 62 79 20  on specified by 
19e60 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74  the only paramet
19e70 65 72 2e 0a 2a 2a 20 5e 45 78 65 63 75 74 69 6e  er..** ^Executin
19e80 67 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65  g any other type
19e90 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   of SQL statemen
19ea0 74 20 64 6f 65 73 20 6e 6f 74 20 6d 6f 64 69 66  t does not modif
19eb0 79 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72  y the value.** r
19ec0 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20  eturned by this 
19ed0 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
19ee0 5e 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61  ^Only changes ma
19ef0 64 65 20 64 69 72 65 63 74 6c 79 20 62 79 20 74  de directly by t
19f00 68 65 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  he INSERT, UPDAT
19f10 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74  E or DELETE stat
19f20 65 6d 65 6e 74 20 61 72 65 0a 2a 2a 20 63 6f 6e  ement are.** con
19f30 73 69 64 65 72 65 64 20 2d 20 61 75 78 69 6c 69  sidered - auxili
19f40 61 72 79 20 63 68 61 6e 67 65 73 20 63 61 75 73  ary changes caus
19f50 65 64 20 62 79 20 5b 43 52 45 41 54 45 20 54 52  ed by [CREATE TR
19f60 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 73  IGGER | triggers
19f70 5d 2c 20 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20  ], .** [foreign 
19f80 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 6f 72 20  key actions] or 
19f90 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72  [REPLACE] constr
19fa0 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20  aint resolution 
19fb0 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e  are not counted.
19fc0 0a 2a 2a 20 0a 2a 2a 20 43 68 61 6e 67 65 73 20  .** .** Changes 
19fd0 74 6f 20 61 20 76 69 65 77 20 74 68 61 74 20 61  to a view that a
19fe0 72 65 20 69 6e 74 65 72 63 65 70 74 65 64 20 62  re intercepted b
19ff0 79 20 0a 2a 2a 20 5b 49 4e 53 54 45 41 44 20 4f  y .** [INSTEAD O
1a000 46 20 74 72 69 67 67 65 72 20 7c 20 49 4e 53 54  F trigger | INST
1a010 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 73 5d  EAD OF triggers]
1a020 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64   are not counted
1a030 2e 20 5e 54 68 65 20 76 61 6c 75 65 20 0a 2a 2a  . ^The value .**
1a040 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
1a050 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69  ite3_changes() i
1a060 6d 6d 65 64 69 61 74 65 6c 79 20 61 66 74 65 72  mmediately after
1a070 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41   an INSERT, UPDA
1a080 54 45 20 6f 72 20 0a 2a 2a 20 44 45 4c 45 54 45  TE or .** DELETE
1a090 20 73 74 61 74 65 6d 65 6e 74 20 72 75 6e 20 6f   statement run o
1a0a0 6e 20 61 20 76 69 65 77 20 69 73 20 61 6c 77 61  n a view is alwa
1a0b0 79 73 20 7a 65 72 6f 2e 20 4f 6e 6c 79 20 63 68  ys zero. Only ch
1a0c0 61 6e 67 65 73 20 6d 61 64 65 20 74 6f 20 72 65  anges made to re
1a0d0 61 6c 20 0a 2a 2a 20 74 61 62 6c 65 73 20 61 72  al .** tables ar
1a0e0 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a  e counted..**.**
1a0f0 20 54 68 69 6e 67 73 20 61 72 65 20 6d 6f 72 65   Things are more
1a100 20 63 6f 6d 70 6c 69 63 61 74 65 64 20 69 66 20   complicated if 
1a110 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  the sqlite3_chan
1a120 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  ges() function i
1a130 73 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 77 68  s.** executed wh
1a140 69 6c 65 20 61 20 74 72 69 67 67 65 72 20 70 72  ile a trigger pr
1a150 6f 67 72 61 6d 20 69 73 20 72 75 6e 6e 69 6e 67  ogram is running
1a160 2e 20 54 68 69 73 20 6d 61 79 20 68 61 70 70 65  . This may happe
1a170 6e 20 69 66 20 74 68 65 0a 2a 2a 20 70 72 6f 67  n if the.** prog
1a180 72 61 6d 20 75 73 65 73 20 74 68 65 20 5b 63 68  ram uses the [ch
1a190 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63  anges() SQL func
1a1a0 74 69 6f 6e 5d 2c 20 6f 72 20 69 66 20 73 6f 6d  tion], or if som
1a1b0 65 20 6f 74 68 65 72 20 63 61 6c 6c 62 61 63 6b  e other callback
1a1c0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 6e 76  .** function inv
1a1d0 6f 6b 65 73 20 73 71 6c 69 74 65 33 5f 63 68 61  okes sqlite3_cha
1a1e0 6e 67 65 73 28 29 20 64 69 72 65 63 74 6c 79 2e  nges() directly.
1a1f0 20 45 73 73 65 6e 74 69 61 6c 6c 79 3a 0a 2a 2a   Essentially:.**
1a200 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c   .** <ul>.**   <
1a210 6c 69 3e 20 5e 28 42 65 66 6f 72 65 20 65 6e 74  li> ^(Before ent
1a220 65 72 69 6e 67 20 61 20 74 72 69 67 67 65 72 20  ering a trigger 
1a230 70 72 6f 67 72 61 6d 20 74 68 65 20 76 61 6c 75  program the valu
1a240 65 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  e returned by.**
1a250 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f          sqlite3_
1a260 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69  changes() functi
1a270 6f 6e 20 69 73 20 73 61 76 65 64 2e 20 41 66 74  on is saved. Aft
1a280 65 72 20 74 68 65 20 74 72 69 67 67 65 72 20 70  er the trigger p
1a290 72 6f 67 72 61 6d 20 0a 2a 2a 20 20 20 20 20 20  rogram .**      
1a2a0 20 20 68 61 73 20 66 69 6e 69 73 68 65 64 2c 20    has finished, 
1a2b0 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 76 61 6c  the original val
1a2c0 75 65 20 69 73 20 72 65 73 74 6f 72 65 64 2e 29  ue is restored.)
1a2d0 5e 0a 2a 2a 20 0a 2a 2a 20 20 20 3c 6c 69 3e 20  ^.** .**   <li> 
1a2e0 5e 28 57 69 74 68 69 6e 20 61 20 74 72 69 67 67  ^(Within a trigg
1a2f0 65 72 20 70 72 6f 67 72 61 6d 20 65 61 63 68 20  er program each 
1a300 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 61  INSERT, UPDATE a
1a310 6e 64 20 44 45 4c 45 54 45 20 0a 2a 2a 20 20 20  nd DELETE .**   
1a320 20 20 20 20 20 73 74 61 74 65 6d 65 6e 74 20 73       statement s
1a330 65 74 73 20 74 68 65 20 76 61 6c 75 65 20 72 65  ets the value re
1a340 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
1a350 33 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20  3_changes() .** 
1a360 20 20 20 20 20 20 20 75 70 6f 6e 20 63 6f 6d 70         upon comp
1a370 6c 65 74 69 6f 6e 20 61 73 20 6e 6f 72 6d 61 6c  letion as normal
1a380 2e 20 4f 66 20 63 6f 75 72 73 65 2c 20 74 68 69  . Of course, thi
1a390 73 20 76 61 6c 75 65 20 77 69 6c 6c 20 6e 6f 74  s value will not
1a3a0 20 69 6e 63 6c 75 64 65 20 0a 2a 2a 20 20 20 20   include .**    
1a3b0 20 20 20 20 61 6e 79 20 63 68 61 6e 67 65 73 20      any changes 
1a3c0 70 65 72 66 6f 72 6d 65 64 20 62 79 20 73 75 62  performed by sub
1a3d0 2d 74 72 69 67 67 65 72 73 2c 20 61 73 20 74 68  -triggers, as th
1a3e0 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  e sqlite3_change
1a3f0 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 76  s() .**        v
1a400 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 73 61 76  alue will be sav
1a410 65 64 20 61 6e 64 20 72 65 73 74 6f 72 65 64 20  ed and restored 
1a420 61 66 74 65 72 20 65 61 63 68 20 73 75 62 2d 74  after each sub-t
1a430 72 69 67 67 65 72 20 68 61 73 20 72 75 6e 2e 29  rigger has run.)
1a440 5e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a  ^.** </ul>.** .*
1a450 2a 20 5e 54 68 69 73 20 6d 65 61 6e 73 20 74 68  * ^This means th
1a460 61 74 20 69 66 20 74 68 65 20 63 68 61 6e 67 65  at if the change
1a470 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  s() SQL function
1a480 20 28 6f 72 20 73 69 6d 69 6c 61 72 29 20 69 73   (or similar) is
1a490 20 75 73 65 64 0a 2a 2a 20 62 79 20 74 68 65 20   used.** by the 
1a4a0 66 69 72 73 74 20 49 4e 53 45 52 54 2c 20 55 50  first INSERT, UP
1a4b0 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73  DATE or DELETE s
1a4c0 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
1a4d0 61 20 74 72 69 67 67 65 72 2c 20 69 74 20 0a 2a  a trigger, it .*
1a4e0 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 61  * returns the va
1a4f0 6c 75 65 20 61 73 20 73 65 74 20 77 68 65 6e 20  lue as set when 
1a500 74 68 65 20 63 61 6c 6c 69 6e 67 20 73 74 61 74  the calling stat
1a510 65 6d 65 6e 74 20 62 65 67 61 6e 20 65 78 65 63  ement began exec
1a520 75 74 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 69 74  uting..** ^If it
1a530 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20   is used by the 
1a540 73 65 63 6f 6e 64 20 6f 72 20 73 75 62 73 65 71  second or subseq
1a550 75 65 6e 74 20 73 75 63 68 20 73 74 61 74 65 6d  uent such statem
1a560 65 6e 74 20 77 69 74 68 69 6e 20 61 20 74 72 69  ent within a tri
1a570 67 67 65 72 20 0a 2a 2a 20 70 72 6f 67 72 61 6d  gger .** program
1a580 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  , the value retu
1a590 72 6e 65 64 20 72 65 66 6c 65 63 74 73 20 74 68  rned reflects th
1a5a0 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  e number of rows
1a5b0 20 6d 6f 64 69 66 69 65 64 20 62 79 20 74 68 65   modified by the
1a5c0 20 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 49 4e   .** previous IN
1a5d0 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20  SERT, UPDATE or 
1a5e0 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74  DELETE statement
1a5f0 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65   within the same
1a600 20 74 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20   trigger..**.** 
1a610 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71  See also the [sq
1a620 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
1a630 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ges()] interface
1a640 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f  , the.** [count_
1a650 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c  changes pragma],
1a660 20 61 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 65   and the [change
1a670 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  s() SQL function
1a680 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65  ]..**.** If a se
1a690 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61  parate thread ma
1a6a0 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74  kes changes on t
1a6b0 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
1a6c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77   connection.** w
1a6d0 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68  hile [sqlite3_ch
1a6e0 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e  anges()] is runn
1a6f0 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c  ing then the val
1a700 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69  ue returned.** i
1a710 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  s unpredictable 
1a720 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66  and not meaningf
1a730 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ul..*/.int sqlit
1a740 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74  e3_changes(sqlit
1a750 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
1a760 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d  I3REF: Total Num
1a770 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69  ber Of Rows Modi
1a780 66 69 65 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  fied.** METHOD: 
1a790 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
1a7a0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
1a7b0 75 72 6e 73 20 74 68 65 20 74 6f 74 61 6c 20 6e  urns the total n
1a7c0 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 69 6e  umber of rows in
1a7d0 73 65 72 74 65 64 2c 20 6d 6f 64 69 66 69 65 64  serted, modified
1a7e0 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62   or.** deleted b
1a7f0 79 20 61 6c 6c 20 5b 49 4e 53 45 52 54 5d 2c 20  y all [INSERT], 
1a800 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c  [UPDATE] or [DEL
1a810 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 20  ETE] statements 
1a820 63 6f 6d 70 6c 65 74 65 64 0a 2a 2a 20 73 69 6e  completed.** sin
1a830 63 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ce the database 
1a840 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 61 73 20 6f  connection was o
1a850 70 65 6e 65 64 2c 20 69 6e 63 6c 75 64 69 6e 67  pened, including
1a860 20 74 68 6f 73 65 20 65 78 65 63 75 74 65 64 20   those executed 
1a870 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 72  as.** part of tr
1a880 69 67 67 65 72 20 70 72 6f 67 72 61 6d 73 2e 20  igger programs. 
1a890 5e 45 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f  ^Executing any o
1a8a0 74 68 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c  ther type of SQL
1a8b0 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 64 6f   statement.** do
1a8c0 65 73 20 6e 6f 74 20 61 66 66 65 63 74 20 74 68  es not affect th
1a8d0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
1a8e0 20 62 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61   by sqlite3_tota
1a8f0 6c 5f 63 68 61 6e 67 65 73 28 29 2e 0a 2a 2a 20  l_changes()..** 
1a900 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20 6d 61 64  .** ^Changes mad
1a910 65 20 61 73 20 70 61 72 74 20 6f 66 20 5b 66 6f  e as part of [fo
1a920 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e  reign key action
1a930 73 5d 20 61 72 65 20 69 6e 63 6c 75 64 65 64 20  s] are included 
1a940 69 6e 20 74 68 65 0a 2a 2a 20 63 6f 75 6e 74 2c  in the.** count,
1a950 20 62 75 74 20 74 68 6f 73 65 20 6d 61 64 65 20   but those made 
1a960 61 73 20 70 61 72 74 20 6f 66 20 52 45 50 4c 41  as part of REPLA
1a970 43 45 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65  CE constraint re
1a980 73 6f 6c 75 74 69 6f 6e 20 61 72 65 0a 2a 2a 20  solution are.** 
1a990 6e 6f 74 2e 20 5e 43 68 61 6e 67 65 73 20 74 6f  not. ^Changes to
1a9a0 20 61 20 76 69 65 77 20 74 68 61 74 20 61 72 65   a view that are
1a9b0 20 69 6e 74 65 72 63 65 70 74 65 64 20 62 79 20   intercepted by 
1a9c0 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67  INSTEAD OF trigg
1a9d0 65 72 73 20 0a 2a 2a 20 61 72 65 20 6e 6f 74 20  ers .** are not 
1a9e0 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20  counted..** .** 
1a9f0 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71  See also the [sq
1aa00 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d  lite3_changes()]
1aa10 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a   interface, the.
1aa20 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65  ** [count_change
1aa30 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74  s pragma], and t
1aa40 68 65 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65  he [total_change
1aa50 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  s() SQL function
1aa60 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65  ]..**.** If a se
1aa70 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61  parate thread ma
1aa80 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74  kes changes on t
1aa90 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
1aaa0 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77   connection.** w
1aab0 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f  hile [sqlite3_to
1aac0 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  tal_changes()] i
1aad0 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74  s running then t
1aae0 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75  he value.** retu
1aaf0 72 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69 63  rned is unpredic
1ab00 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65  table and not me
1ab10 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74  aningful..*/.int
1ab20 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63   sqlite3_total_c
1ab30 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29  hanges(sqlite3*)
1ab40 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1ab50 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c  F: Interrupt A L
1ab60 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72  ong-Running Quer
1ab70 79 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  y.** METHOD: sql
1ab80 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ite3.**.** ^This
1ab90 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73   function causes
1aba0 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74   any pending dat
1abb0 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20  abase operation 
1abc0 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20  to abort and.** 
1abd0 72 65 74 75 72 6e 20 61 74 20 69 74 73 20 65 61  return at its ea
1abe0 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69  rliest opportuni
1abf0 74 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65  ty. This routine
1ac00 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a   is typically.**
1ac10 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f   called in respo
1ac20 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20 61 63  nse to a user ac
1ac30 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65  tion such as pre
1ac40 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a  ssing "Cancel".*
1ac50 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72  * or Ctrl-C wher
1ac60 65 20 74 68 65 20 75 73 65 72 20 77 61 6e 74 73  e the user wants
1ac70 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70   a long query op
1ac80 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a  eration to halt.
1ac90 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a  ** immediately..
1aca0 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66  **.** ^It is saf
1acb0 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72  e to call this r
1acc0 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68  outine from a th
1acd0 72 65 61 64 20 64 69 66 66 65 72 65 6e 74 20 66  read different f
1ace0 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61  rom the.** threa
1acf0 64 20 74 68 61 74 20 69 73 20 63 75 72 72 65 6e  d that is curren
1ad00 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20  tly running the 
1ad10 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69  database operati
1ad20 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69  on.  But it.** i
1ad30 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61  s not safe to ca
1ad40 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ll this routine 
1ad50 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65  with a [database
1ad60 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61   connection] tha
1ad70 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f  t.** is closed o
1ad80 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65  r might close be
1ad90 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  fore sqlite3_int
1ada0 65 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73  errupt() returns
1adb0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53  ..**.** ^If an S
1adc0 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  QL operation is 
1add0 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69  very nearly fini
1ade0 73 68 65 64 20 61 74 20 74 68 65 20 74 69 6d 65  shed at the time
1adf0 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   when.** sqlite3
1ae00 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69 73 20  _interrupt() is 
1ae10 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20  called, then it 
1ae20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61  might not have a
1ae30 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a  n opportunity.**
1ae40 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74   to be interrupt
1ae50 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e  ed and might con
1ae60 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74  tinue to complet
1ae70 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53  ion..**.** ^An S
1ae80 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61  QL operation tha
1ae90 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64  t is interrupted
1aea0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
1aeb0 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e  LITE_INTERRUPT].
1aec0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65  .** ^If the inte
1aed0 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72  rrupted SQL oper
1aee0 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45  ation is an INSE
1aef0 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
1af00 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73  ELETE.** that is
1af10 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69   inside an expli
1af20 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c  cit transaction,
1af30 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65   then the entire
1af40 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20   transaction.** 
1af50 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62  will be rolled b
1af60 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ack automaticall
1af70 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  y..**.** ^The sq
1af80 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1af90 44 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66  D) call is in ef
1afa0 66 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63  fect until all c
1afb0 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67  urrently running
1afc0 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
1afd0 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20  ts on [database 
1afe0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f  connection] D co
1aff0 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65  mplete.  ^Any ne
1b000 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  w SQL statements
1b010 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61  .** that are sta
1b020 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73  rted after the s
1b030 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1b040 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f  () call and befo
1b050 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69  re the .** runni
1b060 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65  ng statements re
1b070 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69  aches zero are i
1b080 6e 74 65 72 72 75 70 74 65 64 20 61 73 20 69 66  nterrupted as if
1b090 20 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a   they had been.*
1b0a0 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20  * running prior 
1b0b0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  to the sqlite3_i
1b0c0 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e  nterrupt() call.
1b0d0 20 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65    ^New SQL state
1b0e0 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
1b0f0 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
1b100 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74  the running stat
1b110 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63  ement count reac
1b120 68 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20  hes zero are.** 
1b130 6e 6f 74 20 65 66 66 65 63 74 65 64 20 62 79 20  not effected by 
1b140 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
1b150 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63  rrupt()..** ^A c
1b160 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  all to sqlite3_i
1b170 6e 74 65 72 72 75 70 74 28 44 29 20 74 68 61 74  nterrupt(D) that
1b180 20 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68 65   occurs when the
1b190 72 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e  re are no runnin
1b1a0 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  g.** SQL stateme
1b1b0 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61  nts is a no-op a
1b1c0 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74  nd has no effect
1b1d0 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   on SQL statemen
1b1e0 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73  ts.** that are s
1b1f0 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65  tarted after the
1b200 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
1b210 70 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e  pt() call return
1b220 73 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  s..*/.void sqlit
1b230 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c  e3_interrupt(sql
1b240 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
1b250 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69  API3REF: Determi
1b260 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61  ne If An SQL Sta
1b270 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65  tement Is Comple
1b280 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  te.**.** These r
1b290 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66  outines are usef
1b2a0 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e  ul during comman
1b2b0 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20  d-line input to 
1b2c0 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65  determine if the
1b2d0 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e  .** currently en
1b2e0 74 65 72 65 64 20 74 65 78 74 20 73 65 65 6d 73  tered text seems
1b2f0 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c   to form a compl
1b300 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ete SQL statemen
1b310 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74  t or.** if addit
1b320 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e  ional input is n
1b330 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e  eeded before sen
1b340 64 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e  ding the text in
1b350 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72  to.** SQLite for
1b360 20 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73   parsing.  ^Thes
1b370 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
1b380 6e 20 31 20 69 66 20 74 68 65 20 69 6e 70 75 74  n 1 if the input
1b390 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61   string.** appea
1b3a0 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c  rs to be a compl
1b3b0 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ete SQL statemen
1b3c0 74 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74  t.  ^A statement
1b3d0 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65   is judged to be
1b3e0 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20  .** complete if 
1b3f0 69 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 73  it ends with a s
1b400 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61  emicolon token a
1b410 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66  nd is not a pref
1b420 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d  ix of a.** well-
1b430 66 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54 52  formed CREATE TR
1b440 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e  IGGER statement.
1b450 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68    ^Semicolons th
1b460 61 74 20 61 72 65 20 65 6d 62 65 64 64 65 64 20  at are embedded 
1b470 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67  within.** string
1b480 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f   literals or quo
1b490 74 65 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e  ted identifier n
1b4a0 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73  ames or comments
1b4b0 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65   are not.** inde
1b4c0 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28  pendent tokens (
1b4d0 74 68 65 79 20 61 72 65 20 70 61 72 74 20 6f 66  they are part of
1b4e0 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68   the token in wh
1b4f0 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20  ich they are.** 
1b500 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74 68  embedded) and th
1b510 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20  us do not count 
1b520 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74  as a statement t
1b530 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69  erminator.  ^Whi
1b540 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63  tespace.** and c
1b550 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c  omments that fol
1b560 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65  low the final se
1b570 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f  micolon are igno
1b580 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  red..**.** ^Thes
1b590 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
1b5a0 6e 20 30 20 69 66 20 74 68 65 20 73 74 61 74 65  n 0 if the state
1b5b0 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65  ment is incomple
1b5c0 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65  te.  ^If a.** me
1b5d0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1b5e0 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49  fails, then SQLI
1b5f0 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75  TE_NOMEM is retu
1b600 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rned..**.** ^The
1b610 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e  se routines do n
1b620 6f 74 20 70 61 72 73 65 20 74 68 65 20 53 51 4c  ot parse the SQL
1b630 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73   statements thus
1b640 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74  .** will not det
1b650 65 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c  ect syntacticall
1b660 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e  y incorrect SQL.
1b670 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69  .**.** ^(If SQLi
1b680 74 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20  te has not been 
1b690 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e  initialized usin
1b6a0 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  g [sqlite3_initi
1b6b0 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a  alize()] prior .
1b6c0 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73  ** to invoking s
1b6d0 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
1b6e0 36 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33  6() then sqlite3
1b6f0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
1b700 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f   invoked.** auto
1b710 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c  matically by sql
1b720 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
1b730 29 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69 74  ).  If that init
1b740 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73  ialization fails
1b750 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65  ,.** then the re
1b760 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20  turn value from 
1b770 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
1b780 31 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e  16() will be non
1b790 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c  -zero.** regardl
1b7a0 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
1b7b0 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20  r not the input 
1b7c0 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e  SQL is complete.
1b7d0 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70  )^.**.** The inp
1b7e0 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ut to [sqlite3_c
1b7f0 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20  omplete()] must 
1b800 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  be a zero-termin
1b810 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74  ated.** UTF-8 st
1b820 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ring..**.** The 
1b830 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
1b840 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20  3_complete16()] 
1b850 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74  must be a zero-t
1b860 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46  erminated.** UTF
1b870 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61  -16 string in na
1b880 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
1b890 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1b8a0 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63  complete(const c
1b8b0 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73  har *sql);.int s
1b8c0 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
1b8d0 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  6(const void *sq
1b8e0 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
1b8f0 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20  REF: Register A 
1b900 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64  Callback To Hand
1b910 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45  le SQLITE_BUSY E
1b920 72 72 6f 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  rrors.** KEYWORD
1b930 53 3a 20 7b 62 75 73 79 2d 68 61 6e 64 6c 65 72  S: {busy-handler
1b940 20 63 61 6c 6c 62 61 63 6b 7d 20 7b 62 75 73 79   callback} {busy
1b950 20 68 61 6e 64 6c 65 72 7d 0a 2a 2a 20 4d 45 54   handler}.** MET
1b960 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
1b970 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1b980 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 44 2c 58  busy_handler(D,X
1b990 2c 50 29 20 72 6f 75 74 69 6e 65 20 73 65 74 73  ,P) routine sets
1b9a0 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
1b9b0 74 69 6f 6e 20 58 0a 2a 2a 20 74 68 61 74 20 6d  tion X.** that m
1b9c0 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20  ight be invoked 
1b9d0 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20  with argument P 
1b9e0 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61  whenever.** an a
1b9f0 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74  ttempt is made t
1ba00 6f 20 61 63 63 65 73 73 20 61 20 64 61 74 61 62  o access a datab
1ba10 61 73 65 20 74 61 62 6c 65 20 61 73 73 6f 63 69  ase table associ
1ba20 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 5b 64 61  ated with.** [da
1ba30 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1ba40 6e 5d 20 44 20 77 68 65 6e 20 61 6e 6f 74 68 65  n] D when anothe
1ba50 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70  r thread.** or p
1ba60 72 6f 63 65 73 73 20 68 61 73 20 74 68 65 20 74  rocess has the t
1ba70 61 62 6c 65 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20  able locked..** 
1ba80 54 68 65 20 73 71 6c 69 74 65 33 5f 62 75 73 79  The sqlite3_busy
1ba90 5f 68 61 6e 64 6c 65 72 28 29 20 69 6e 74 65 72  _handler() inter
1baa0 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20  face is used to 
1bab0 69 6d 70 6c 65 6d 65 6e 74 0a 2a 2a 20 5b 73 71  implement.** [sq
1bac0 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
1bad0 75 74 28 29 5d 20 61 6e 64 20 5b 50 52 41 47 4d  ut()] and [PRAGM
1bae0 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 2e  A busy_timeout].
1baf0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62  .**.** ^If the b
1bb00 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  usy callback is 
1bb10 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49  NULL, then [SQLI
1bb20 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 69 73 20 72  TE_BUSY].** is r
1bb30 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74  eturned immediat
1bb40 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74  ely upon encount
1bb50 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20  ering the lock. 
1bb60 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61   ^If the busy ca
1bb70 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74  llback.** is not
1bb80 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20   NULL, then the 
1bb90 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62  callback might b
1bba0 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74  e invoked with t
1bbb0 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  wo arguments..**
1bbc0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
1bbd0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62  rgument to the b
1bbe0 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61  usy handler is a
1bbf0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69   copy of the voi
1bc00 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68  d* pointer which
1bc10 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72 64  .** is the third
1bc20 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
1bc30 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
1bc40 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e  r().  ^The secon
1bc50 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
1bc60 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
1bc70 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68  r callback is th
1bc80 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65  e number of time
1bc90 73 20 74 68 61 74 20 74 68 65 20 62 75 73 79 20  s that the busy 
1bca0 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62  handler has.** b
1bcb0 65 65 6e 20 69 6e 76 6f 6b 65 64 20 70 72 65 76  een invoked prev
1bcc0 69 6f 75 73 6c 79 20 66 6f 72 20 74 68 65 20 73  iously for the s
1bcd0 61 6d 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e  ame locking even
1bce0 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62  t.  ^If the.** b
1bcf0 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  usy callback ret
1bd00 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20  urns 0, then no 
1bd10 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d  additional attem
1bd20 70 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a  pts are made to.
1bd30 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20 64 61  ** access the da
1bd40 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49  tabase and [SQLI
1bd50 54 45 5f 42 55 53 59 5d 20 69 73 20 72 65 74 75  TE_BUSY] is retu
1bd60 72 6e 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 61  rned.** to the a
1bd70 70 70 6c 69 63 61 74 69 6f 6e 2e 0a 2a 2a 20 5e  pplication..** ^
1bd80 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
1bd90 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
1bda0 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61  , then another a
1bdb0 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64  ttempt.** is mad
1bdc0 65 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  e to access the 
1bdd0 64 61 74 61 62 61 73 65 20 61 6e 64 20 74 68 65  database and the
1bde0 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a   cycle repeats..
1bdf0 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e  **.** The presen
1be00 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e  ce of a busy han
1be10 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75  dler does not gu
1be20 61 72 61 6e 74 65 65 20 74 68 61 74 20 69 74 20  arantee that it 
1be30 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a  will be invoked.
1be40 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69 73  ** when there is
1be50 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e   lock contention
1be60 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74  . ^If SQLite det
1be70 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76  ermines that inv
1be80 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a  oking the busy.*
1be90 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20  * handler could 
1bea0 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64  result in a dead
1beb0 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f  lock, it will go
1bec0 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 75 72   ahead and retur
1bed0 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a  n [SQLITE_BUSY].
1bee0 2a 2a 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63  ** to the applic
1bef0 61 74 69 6f 6e 20 69 6e 73 74 65 61 64 20 6f 66  ation instead of
1bf00 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 0a 2a   invoking the .*
1bf10 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  * busy handler..
1bf20 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63  ** Consider a sc
1bf30 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65  enario where one
1bf40 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64   process is hold
1bf50 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20  ing a read lock 
1bf60 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72  that.** it is tr
1bf70 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20  ying to promote 
1bf80 74 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f  to a reserved lo
1bf90 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f  ck and.** a seco
1bfa0 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f  nd process is ho
1bfb0 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76 65 64  lding a reserved
1bfc0 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73   lock that it is
1bfd0 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72   trying.** to pr
1bfe0 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c  omote to an excl
1bff0 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65  usive lock.  The
1c000 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 63   first process c
1c010 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a  annot proceed.**
1c020 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62   because it is b
1c030 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73 65  locked by the se
1c040 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63  cond and the sec
1c050 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e  ond process cann
1c060 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65  ot.** proceed be
1c070 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63  cause it is bloc
1c080 6b 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ked by the first
1c090 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65  .  If both proce
1c0a0 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74  sses.** invoke t
1c0b0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73  he busy handlers
1c0c0 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d  , neither will m
1c0d0 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73  ake any progress
1c0e0 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a  .  Therefore,.**
1c0f0 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20   SQLite returns 
1c100 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f  [SQLITE_BUSY] fo
1c110 72 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63  r the first proc
1c120 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74  ess, hoping that
1c130 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e   this.** will in
1c140 64 75 63 65 20 74 68 65 20 66 69 72 73 74 20 70  duce the first p
1c150 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73  rocess to releas
1c160 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20  e its read lock 
1c170 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65  and allow.** the
1c180 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
1c190 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a  to proceed..**.*
1c1a0 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62  * ^The default b
1c1b0 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  usy callback is 
1c1c0 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  NULL..**.** ^(Th
1c1d0 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ere can only be 
1c1e0 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61  a single busy ha
1c1f0 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f  ndler defined fo
1c200 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62  r each.** [datab
1c210 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
1c220 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20    Setting a new 
1c230 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65  busy handler cle
1c240 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69  ars any.** previ
1c250 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65  ously set handle
1c260 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74  r.)^  ^Note that
1c270 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
1c280 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29  3_busy_timeout()
1c290 5d 0a 2a 2a 20 6f 72 20 65 76 61 6c 75 61 74 69  ].** or evaluati
1c2a0 6e 67 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f  ng [PRAGMA busy_
1c2b0 74 69 6d 65 6f 75 74 3d 4e 5d 20 77 69 6c 6c 20  timeout=N] will 
1c2c0 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 62 75  change the.** bu
1c2d0 73 79 20 68 61 6e 64 6c 65 72 20 61 6e 64 20 74  sy handler and t
1c2e0 68 75 73 20 63 6c 65 61 72 20 61 6e 79 20 70 72  hus clear any pr
1c2f0 65 76 69 6f 75 73 6c 79 20 73 65 74 20 62 75 73  eviously set bus
1c300 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a  y handler..**.**
1c310 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   The busy callba
1c320 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61  ck should not ta
1c330 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77  ke any actions w
1c340 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a  hich modify the.
1c350 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
1c360 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
1c370 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e  ked the busy han
1c380 64 6c 65 72 2e 20 20 49 6e 20 6f 74 68 65 72 20  dler.  In other 
1c390 77 6f 72 64 73 2c 0a 2a 2a 20 74 68 65 20 62 75  words,.** the bu
1c3a0 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 6e 6f  sy handler is no
1c3b0 74 20 72 65 65 6e 74 72 61 6e 74 2e 20 20 41 6e  t reentrant.  An
1c3c0 79 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a  y such actions.*
1c3d0 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65  * result in unde
1c3e0 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a  fined behavior..
1c3f0 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61  ** .** A busy ha
1c400 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63  ndler must not c
1c410 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73  lose the databas
1c420 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
1c430 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  or [prepared sta
1c440 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76  tement] that inv
1c450 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61  oked the busy ha
1c460 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ndler..*/.int sq
1c470 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
1c480 65 72 28 73 71 6c 69 74 65 33 2a 2c 69 6e 74 28  er(sqlite3*,int(
1c490 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 76 6f  *)(void*,int),vo
1c4a0 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
1c4b0 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 75 73  I3REF: Set A Bus
1c4c0 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 20 4d 45 54  y Timeout.** MET
1c4d0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
1c4e0 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
1c4f0 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33   sets a [sqlite3
1c500 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20  _busy_handler | 
1c510 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68  busy handler] th
1c520 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72  at sleeps.** for
1c530 20 61 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f   a specified amo
1c540 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e  unt of time when
1c550 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b   a table is lock
1c560 65 64 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65  ed.  ^The handle
1c570 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20  r.** will sleep 
1c580 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75  multiple times u
1c590 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d  ntil at least "m
1c5a0 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  s" milliseconds 
1c5b0 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68  of sleeping.** h
1c5c0 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e  ave accumulated.
1c5d0 20 20 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73    ^After at leas
1c5e0 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f  t "ms" milliseco
1c5f0 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c  nds of sleeping,
1c600 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20  .** the handler 
1c610 72 65 74 75 72 6e 73 20 30 20 77 68 69 63 68 20  returns 0 which 
1c620 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f  causes [sqlite3_
1c630 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72  step()] to retur
1c640 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53  n.** [SQLITE_BUS
1c650 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69  Y]..**.** ^Calli
1c660 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ng this routine 
1c670 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74  with an argument
1c680 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71   less than or eq
1c690 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74  ual to zero.** t
1c6a0 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73  urns off all bus
1c6b0 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a  y handlers..**.*
1c6c0 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e  * ^(There can on
1c6d0 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62  ly be a single b
1c6e0 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20  usy handler for 
1c6f0 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20  a particular.** 
1c700 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1c710 74 69 6f 6e 5d 20 61 74 20 61 6e 79 20 67 69 76  tion] at any giv
1c720 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61  en moment.  If a
1c730 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64  nother busy hand
1c740 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e  ler.** was defin
1c750 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69  ed  (using [sqli
1c760 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
1c770 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61  ()]) prior to ca
1c780 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f  lling.** this ro
1c790 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65  utine, that othe
1c7a0 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69  r busy handler i
1c7b0 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2a 0a  s cleared.)^.**.
1c7c0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 50  ** See also:  [P
1c7d0 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f  RAGMA busy_timeo
1c7e0 75 74 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ut].*/.int sqlit
1c7f0 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
1c800 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73  sqlite3*, int ms
1c810 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1c820 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20  EF: Convenience 
1c830 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e  Routines For Run
1c840 6e 69 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 20  ning Queries.** 
1c850 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
1c860 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20  **.** This is a 
1c870 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
1c880 20 74 68 61 74 20 69 73 20 70 72 65 73 65 72 76   that is preserv
1c890 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ed for backwards
1c8a0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
1c8b0 2a 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20 69  ** Use of this i
1c8c0 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20  nterface is not 
1c8d0 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a  recommended..**.
1c8e0 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41  ** Definition: A
1c8f0 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65   <b>result table
1c900 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64  </b> is memory d
1c910 61 74 61 20 73 74 72 75 63 74 75 72 65 20 63 72  ata structure cr
1c920 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  eated by the.** 
1c930 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
1c940 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  le()] interface.
1c950 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65    A result table
1c960 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20   records the.** 
1c970 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72  complete query r
1c980 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20  esults from one 
1c990 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e  or more queries.
1c9a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65  .**.** The table
1c9b0 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61   conceptually ha
1c9c0 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  s a number of ro
1c9d0 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20  ws and columns. 
1c9e0 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75   But.** these nu
1c9f0 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61  mbers are not pa
1ca00 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  rt of the result
1ca10 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20   table itself.  
1ca20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73  These.** numbers
1ca30 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65   are obtained se
1ca40 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e  parately.  Let N
1ca50 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   be the number o
1ca60 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20  f rows.** and M 
1ca70 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  be the number of
1ca80 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20   columns..**.** 
1ca90 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  A result table i
1caa0 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
1cab0 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74  inters to zero-t
1cac0 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
1cad0 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72  strings..** Ther
1cae0 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c  e are (N+1)*M el
1caf0 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72  ements in the ar
1cb00 72 61 79 2e 20 20 54 68 65 20 66 69 72 73 74 20  ray.  The first 
1cb10 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74  M pointers point
1cb20 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d  .** to zero-term
1cb30 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74  inated strings t
1cb40 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65  hat  contain the
1cb50 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f   names of the co
1cb60 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65  lumns..** The re
1cb70 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20  maining entries 
1cb80 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65  all point to que
1cb90 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c  ry results.  NUL
1cba0 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a  L values result.
1cbb0 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74  ** in NULL point
1cbc0 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20  ers.  All other 
1cbd0 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68  values are in th
1cbe0 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74  eir UTF-8 zero-t
1cbf0 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72  erminated.** str
1cc00 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 69  ing representati
1cc10 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 62  on as returned b
1cc20 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  y [sqlite3_colum
1cc30 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  n_text()]..**.**
1cc40 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
1cc50 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66  might consist of
1cc60 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d   one or more mem
1cc70 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e  ory allocations.
1cc80 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61  .** It is not sa
1cc90 66 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 73  fe to pass a res
1cca0 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 74  ult table direct
1ccb0 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  ly to [sqlite3_f
1ccc0 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73  ree()]..** A res
1ccd0 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64  ult table should
1cce0 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
1ccf0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
1cd00 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a  ree_table()]..**
1cd10 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 6d  .** ^(As an exam
1cd20 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c  ple of the resul
1cd30 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20  t table format, 
1cd40 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 79 20  suppose a query 
1cd50 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20  result.** is as 
1cd60 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
1cd70 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1cd80 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20  .**        Name 
1cd90 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20         | Age.** 
1cda0 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d         ---------
1cdb0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a  --------------.*
1cdc0 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 20  *        Alice  
1cdd0 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20       | 43.**    
1cde0 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 20      Bob         
1cdf0 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43  | 28.**        C
1ce00 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a  indy       | 21.
1ce10 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1ce20 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  quote>.**.** The
1ce30 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d  re are two colum
1ce40 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72  n (M==2) and thr
1ce50 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20  ee rows (N==3). 
1ce60 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73   Thus the.** res
1ce70 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38 20  ult table has 8 
1ce80 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73  entries.  Suppos
1ce90 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  e the result tab
1cea0 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20  le is stored.** 
1ceb0 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65  in an array name
1cec0 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65  s azResult.  The
1ced0 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73  n azResult holds
1cee0 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a   this content:.*
1cef0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1cf00 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20  ><pre>.**       
1cf10 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d   azResult&#91;0]
1cf20 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20   = "Name";.**   
1cf30 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1cf40 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a  1;1] = "Age";.**
1cf50 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1cf60 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65  &#91;2] = "Alice
1cf70 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1cf80 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22  esult&#91;3] = "
1cf90 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  43";.**        a
1cfa0 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d  zResult&#91;4] =
1cfb0 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20   "Bob";.**      
1cfc0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35    azResult&#91;5
1cfd0 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20  ] = "28";.**    
1cfe0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1cff0 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a  ;6] = "Cindy";.*
1d000 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1d010 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b  t&#91;7] = "21";
1d020 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1d030 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20  kquote>)^.**.** 
1d040 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74  ^The sqlite3_get
1d050 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f  _table() functio
1d060 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20  n evaluates one 
1d070 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63  or more.** semic
1d080 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53  olon-separated S
1d090 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e  QL statements in
1d0a0 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   the zero-termin
1d0b0 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74  ated UTF-8.** st
1d0c0 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20  ring of its 2nd 
1d0d0 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65  parameter and re
1d0e0 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74  turns a result t
1d0f0 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70  able to the.** p
1d100 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20  ointer given in 
1d110 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65  its 3rd paramete
1d120 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74  r..**.** After t
1d130 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68  he application h
1d140 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
1d150 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d   the result from
1d160 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1d170 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74  le(),.** it must
1d180 20 70 61 73 73 20 74 68 65 20 72 65 73 75 6c 74   pass the result
1d190 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74   table pointer t
1d1a0 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74  o sqlite3_free_t
1d1b0 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20  able() in order 
1d1c0 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68  to.** release th
1d1d0 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61  e memory that wa
1d1e0 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63  s malloced.  Bec
1d1f0 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 20  ause of the way 
1d200 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
1d210 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e  malloc()] happen
1d220 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33  s within sqlite3
1d230 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68  _get_table(), th
1d240 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e  e calling.** fun
1d250 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74  ction must not t
1d260 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69  ry to call [sqli
1d270 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65  te3_free()] dire
1d280 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b  ctly.  Only.** [
1d290 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
1d2a0 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f  le()] is able to
1d2b0 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d   release the mem
1d2c0 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64  ory properly and
1d2d0 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54   safely..**.** T
1d2e0 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
1d2f0 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  able() interface
1d300 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20   is implemented 
1d310 61 73 20 61 20 77 72 61 70 70 65 72 20 61 72 6f  as a wrapper aro
1d320 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  und.** [sqlite3_
1d330 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71  exec()].  The sq
1d340 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1d350 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e  ) routine does n
1d360 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a  ot have access.*
1d370 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61  * to any interna
1d380 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  l data structure
1d390 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74  s of SQLite.  It
1d3a0 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70   uses only the p
1d3b0 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61  ublic.** interfa
1d3c0 63 65 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e  ce defined here.
1d3d0 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e    As a consequen
1d3e0 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20  ce, errors that 
1d3f0 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20  occur in the.** 
1d400 77 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75  wrapper layer ou
1d410 74 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74  tside of the int
1d420 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65  ernal [sqlite3_e
1d430 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20  xec()] call are 
1d440 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64  not.** reflected
1d450 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63   in subsequent c
1d460 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
1d470 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a  _errcode()] or.*
1d480 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  * [sqlite3_errms
1d490 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  g()]..*/.int sql
1d4a0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a  ite3_get_table(.
1d4b0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
1d4c0 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70          /* An op
1d4d0 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20  en database */. 
1d4e0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
1d4f0 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f  l,     /* SQL to
1d500 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
1d510 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65  .  char ***pazRe
1d520 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75  sult,    /* Resu
1d530 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 79  lts of the query
1d540 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77   */.  int *pnRow
1d550 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e  ,           /* N
1d560 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20  umber of result 
1d570 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72  rows written her
1d580 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f  e */.  int *pnCo
1d590 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20  lumn,        /* 
1d5a0 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74  Number of result
1d5b0 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e   columns written
1d5c0 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20   here */.  char 
1d5d0 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20  **pzErrmsg      
1d5e0 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72   /* Error msg wr
1d5f0 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b  itten here */.);
1d600 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72  .void sqlite3_fr
1d610 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a  ee_table(char **
1d620 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  result);../*.** 
1d630 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74  CAPI3REF: Format
1d640 74 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74  ted String Print
1d650 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ing Functions.**
1d660 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
1d670 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b  es are work-alik
1d680 65 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74  es of the "print
1d690 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66  f()" family of f
1d6a0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d  unctions.** from
1d6b0 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
1d6c0 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 54 68 65 73  library..** Thes
1d6d0 65 20 72 6f 75 74 69 6e 65 73 20 75 6e 64 65 72  e routines under
1d6e0 73 74 61 6e 64 20 6d 6f 73 74 20 6f 66 20 74 68  stand most of th
1d6f0 65 20 63 6f 6d 6d 6f 6e 20 4b 26 52 20 66 6f 72  e common K&R for
1d700 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 2c  matting options,
1d710 0a 2a 2a 20 70 6c 75 73 20 73 6f 6d 65 20 61 64  .** plus some ad
1d720 64 69 74 69 6f 6e 61 6c 20 6e 6f 6e 2d 73 74 61  ditional non-sta
1d730 6e 64 61 72 64 20 66 6f 72 6d 61 74 73 2c 20 64  ndard formats, d
1d740 65 74 61 69 6c 65 64 20 62 65 6c 6f 77 2e 0a 2a  etailed below..*
1d750 2a 20 4e 6f 74 65 20 74 68 61 74 20 73 6f 6d 65  * Note that some
1d760 20 6f 66 20 74 68 65 20 6d 6f 72 65 20 6f 62 73   of the more obs
1d770 63 75 72 65 20 66 6f 72 6d 61 74 74 69 6e 67 20  cure formatting 
1d780 6f 70 74 69 6f 6e 73 20 66 72 6f 6d 20 72 65 63  options from rec
1d790 65 6e 74 0a 2a 2a 20 43 2d 6c 69 62 72 61 72 79  ent.** C-library
1d7a0 20 73 74 61 6e 64 61 72 64 73 20 61 72 65 20 6f   standards are o
1d7b0 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 69 73  mitted from this
1d7c0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
1d7d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1d7e0 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e  te3_mprintf() an
1d7f0 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e  d sqlite3_vmprin
1d800 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72  tf() routines wr
1d810 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73  ite their.** res
1d820 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  ults into memory
1d830 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
1d840 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1d850 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67  ]..** The string
1d860 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
1d870 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73  ese two routines
1d880 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65   should be.** re
1d890 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74  leased by [sqlit
1d8a0 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f  e3_free()].  ^Bo
1d8b0 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  th routines retu
1d8c0 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69  rn a.** NULL poi
1d8d0 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33  nter if [sqlite3
1d8e0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e  _malloc()] is un
1d8f0 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
1d900 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72   enough.** memor
1d910 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65  y to hold the re
1d920 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a  sulting string..
1d930 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69  **.** ^(The sqli
1d940 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72  te3_snprintf() r
1d950 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61  outine is simila
1d960 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29  r to "snprintf()
1d970 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74  " from.** the st
1d980 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
1d990 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 73  .  The result is
1d9a0 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68   written into th
1d9b0 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70  e.** buffer supp
1d9c0 6c 69 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  lied as the seco
1d9d0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f  nd parameter who
1d9e0 73 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e  se size is given
1d9f0 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74   by.** the first
1da00 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65   parameter. Note
1da10 20 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 20   that the order 
1da20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20  of the.** first 
1da30 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69  two parameters i
1da40 73 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20  s reversed from 
1da50 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54  snprintf().)^  T
1da60 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73  his is an.** his
1da70 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74  torical accident
1da80 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20   that cannot be 
1da90 66 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72  fixed without br
1daa0 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61  eaking.** backwa
1dab0 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
1dac0 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20  y.  ^(Note also 
1dad0 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70  that sqlite3_snp
1dae0 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72  rintf().** retur
1daf0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
1db00 69 74 73 20 62 75 66 66 65 72 20 69 6e 73 74 65  its buffer inste
1db10 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72  ad of the number
1db20 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72   of.** character
1db30 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74  s actually writt
1db40 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66  en into the buff
1db50 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20  er.)^  We admit 
1db60 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  that.** the numb
1db70 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
1db80 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62   written would b
1db90 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20  e a more useful 
1dba0 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20  return.** value 
1dbb0 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68  but we cannot ch
1dbc0 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65  ange the impleme
1dbd0 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74  ntation of sqlit
1dbe0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
1dbf0 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65   now without bre
1dc00 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c  aking compatibil
1dc10 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c  ity..**.** ^As l
1dc20 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 65  ong as the buffe
1dc30 72 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 65  r size is greate
1dc40 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c  r than zero, sql
1dc50 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
1dc60 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  ** guarantees th
1dc70 61 74 20 74 68 65 20 62 75 66 66 65 72 20 69 73  at the buffer is
1dc80 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72   always zero-ter
1dc90 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66  minated.  ^The f
1dca0 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65  irst.** paramete
1dcb0 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74  r "n" is the tot
1dcc0 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62  al size of the b
1dcd0 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67  uffer, including
1dce0 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68   space for.** th
1dcf0 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  e zero terminato
1dd00 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65  r.  So the longe
1dd10 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 63  st string that c
1dd20 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79  an be completely
1dd30 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c  .** written will
1dd40 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65   be n-1 characte
1dd50 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  rs..**.** ^The s
1dd60 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66  qlite3_vsnprintf
1dd70 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20  () routine is a 
1dd80 76 61 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20  varargs version 
1dd90 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  of sqlite3_snpri
1dda0 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ntf()..**.** The
1ddb0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20  se routines all 
1ddc0 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61  implement some a
1ddd0 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74  dditional format
1dde0 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20  ting.** options 
1ddf0 74 68 61 74 20 61 72 65 20 75 73 65 66 75 6c 20  that are useful 
1de00 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67  for constructing
1de10 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e   SQL statements.
1de20 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75  .** All of the u
1de30 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f  sual printf() fo
1de40 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73  rmatting options
1de50 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69   apply.  In addi
1de60 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69  tion, there.** i
1de70 73 20 61 72 65 20 22 25 71 22 2c 20 22 25 51 22  s are "%q", "%Q"
1de80 2c 20 22 25 77 22 20 61 6e 64 20 22 25 7a 22 20  , "%w" and "%z" 
1de90 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  options..**.** ^
1dea0 28 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77  (The %q option w
1deb0 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20  orks like %s in 
1dec0 74 68 61 74 20 69 74 20 73 75 62 73 74 69 74 75  that it substitu
1ded0 74 65 73 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e  tes a nul-termin
1dee0 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66  ated.** string f
1def0 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74  rom the argument
1df00 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20 61   list.  But %q a
1df10 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72  lso doubles ever
1df20 79 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72  y '\'' character
1df30 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67  ..** %q is desig
1df40 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69  ned for use insi
1df50 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65  de a string lite
1df60 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c  ral.)^  By doubl
1df70 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a  ing each '\''.**
1df80 20 63 68 61 72 61 63 74 65 72 20 69 74 20 65 73   character it es
1df90 63 61 70 65 73 20 74 68 61 74 20 63 68 61 72 61  capes that chara
1dfa0 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20  cter and allows 
1dfb0 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65  it to be inserte
1dfc0 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74  d into.** the st
1dfd0 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20  ring..**.** For 
1dfe0 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20  example, assume 
1dff0 74 68 65 20 73 74 72 69 6e 67 20 76 61 72 69 61  the string varia
1e000 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69  ble zText contai
1e010 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f  ns text as follo
1e020 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
1e030 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1e040 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49  char *zText = "I
1e050 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21  t's a happy day!
1e060 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  ";.** </pre></bl
1e070 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
1e080 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69 73  One can use this
1e090 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20   text in an SQL 
1e0a0 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c  statement as fol
1e0b0 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
1e0c0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1e0d0 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73    char *zSQL = s
1e0e0 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22  qlite3_mprintf("
1e0f0 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
1e100 65 20 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c  e VALUES('%q')",
1e110 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c   zText);.**  sql
1e120 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53  ite3_exec(db, zS
1e130 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a  QL, 0, 0, 0);.**
1e140 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a    sqlite3_free(z
1e150 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  SQL);.** </pre><
1e160 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1e170 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 20 25  ** Because the %
1e180 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20  q format string 
1e190 69 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27  is used, the '\'
1e1a0 27 20 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a  ' character in z
1e1b0 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70  Text.** is escap
1e1c0 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67  ed and the SQL g
1e1d0 65 6e 65 72 61 74 65 64 20 69 73 20 61 73 20 66  enerated is as f
1e1e0 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
1e1f0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1e200 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20  **  INSERT INTO 
1e210 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49  table1 VALUES('I
1e220 74 27 27 73 20 61 20 68 61 70 70 79 20 64 61 79  t''s a happy day
1e230 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  !').** </pre></b
1e240 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1e250 20 54 68 69 73 20 69 73 20 63 6f 72 72 65 63 74   This is correct
1e260 2e 20 20 48 61 64 20 77 65 20 75 73 65 64 20 25  .  Had we used %
1e270 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c  s instead of %q,
1e280 20 74 68 65 20 67 65 6e 65 72 61 74 65 64 20 53   the generated S
1e290 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65  QL.** would have
1e2a0 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69   looked like thi
1e2b0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
1e2c0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49  uote><pre>.**  I
1e2d0 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
1e2e0 31 20 56 41 4c 55 45 53 28 27 49 74 27 73 20 61  1 VALUES('It's a
1e2f0 20 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a   happy day!');.*
1e300 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1e310 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  uote>.**.** This
1e320 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20   second example 
1e330 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78  is an SQL syntax
1e340 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65   error.  As a ge
1e350 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73  neral rule you s
1e360 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20  hould.** always 
1e370 75 73 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f  use %q instead o
1e380 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74  f %s when insert
1e390 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20  ing text into a 
1e3a0 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a  string literal..
1e3b0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f  **.** ^(The %Q o
1e3c0 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
1e3d0 20 25 71 20 65 78 63 65 70 74 20 69 74 20 61 6c   %q except it al
1e3e0 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71  so adds single q
1e3f0 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20  uotes around.** 
1e400 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74  the outside of t
1e410 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e  he total string.
1e420 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20    Additionally, 
1e430 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
1e440 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d   in the.** argum
1e450 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55  ent list is a NU
1e460 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73  LL pointer, %Q s
1e470 75 62 73 74 69 74 75 74 65 73 20 74 68 65 20 74  ubstitutes the t
1e480 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68  ext "NULL" (with
1e490 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75  out.** single qu
1e4a0 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f  otes).)^  So, fo
1e4b0 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63  r example, one c
1e4c0 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20  ould say:.**.** 
1e4d0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1e4e0 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c  >.**  char *zSQL
1e4f0 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e   = sqlite3_mprin
1e500 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20  tf("INSERT INTO 
1e510 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29  table VALUES(%Q)
1e520 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73  ", zText);.**  s
1e530 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20  qlite3_exec(db, 
1e540 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a  zSQL, 0, 0, 0);.
1e550 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65  **  sqlite3_free
1e560 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65  (zSQL);.** </pre
1e570 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1e580 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62  *.** The code ab
1e590 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20  ove will render 
1e5a0 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74  a correct SQL st
1e5b0 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a  atement in the z
1e5c0 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20  SQL.** variable 
1e5d0 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78  even if the zTex
1e5e0 74 20 76 61 72 69 61 62 6c 65 20 69 73 20 61 20  t variable is a 
1e5f0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
1e600 0a 2a 2a 20 5e 28 54 68 65 20 22 25 77 22 20 66  .** ^(The "%w" f
1e610 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e  ormatting option
1e620 20 69 73 20 6c 69 6b 65 20 22 25 71 22 20 65 78   is like "%q" ex
1e630 63 65 70 74 20 74 68 61 74 20 69 74 20 65 78 70  cept that it exp
1e640 65 63 74 73 20 74 6f 0a 2a 2a 20 62 65 20 63 6f  ects to.** be co
1e650 6e 74 61 69 6e 65 64 20 77 69 74 68 69 6e 20 64  ntained within d
1e660 6f 75 62 6c 65 2d 71 75 6f 74 65 73 20 69 6e 73  ouble-quotes ins
1e670 74 65 61 64 20 6f 66 20 73 69 6e 67 6c 65 20 71  tead of single q
1e680 75 6f 74 65 73 2c 20 61 6e 64 20 69 74 0a 2a 2a  uotes, and it.**
1e690 20 65 73 63 61 70 65 73 20 74 68 65 20 64 6f 75   escapes the dou
1e6a0 62 6c 65 2d 71 75 6f 74 65 20 63 68 61 72 61 63  ble-quote charac
1e6b0 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74  ter instead of t
1e6c0 68 65 20 73 69 6e 67 6c 65 2d 71 75 6f 74 65 0a  he single-quote.
1e6d0 2a 2a 20 63 68 61 72 61 63 74 65 72 2e 29 5e 20  ** character.)^ 
1e6e0 20 54 68 65 20 22 25 77 22 20 66 6f 72 6d 61 74   The "%w" format
1e6f0 74 69 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20 69  ting option is i
1e700 6e 74 65 6e 64 65 64 20 66 6f 72 20 73 61 66 65  ntended for safe
1e710 6c 79 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20  ly inserting.** 
1e720 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e  table and column
1e730 20 6e 61 6d 65 73 20 69 6e 74 6f 20 61 20 63 6f   names into a co
1e740 6e 73 74 72 75 63 74 65 64 20 53 51 4c 20 73 74  nstructed SQL st
1e750 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  atement..**.** ^
1e760 28 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74  (The "%z" format
1e770 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b  ting option work
1e780 73 20 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20  s like "%s" but 
1e790 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69  with the.** addi
1e7a0 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20  tion that after 
1e7b0 74 68 65 20 73 74 72 69 6e 67 20 68 61 73 20 62  the string has b
1e7c0 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70  een read and cop
1e7d0 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20  ied into.** the 
1e7e0 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33  result, [sqlite3
1e7f0 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c  _free()] is call
1e800 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20  ed on the input 
1e810 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61  string.)^.*/.cha
1e820 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  r *sqlite3_mprin
1e830 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e  tf(const char*,.
1e840 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74  ..);.char *sqlit
1e850 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73  e3_vmprintf(cons
1e860 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74  t char*, va_list
1e870 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
1e880 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68  _snprintf(int,ch
1e890 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
1e8a0 20 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c   ...);.char *sql
1e8b0 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69  ite3_vsnprintf(i
1e8c0 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  nt,char*,const c
1e8d0 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a  har*, va_list);.
1e8e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1e8f0 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69   Memory Allocati
1e900 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a  on Subsystem.**.
1e910 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  ** The SQLite co
1e920 72 65 20 75 73 65 73 20 74 68 65 73 65 20 74 68  re uses these th
1e930 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72  ree routines for
1e940 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a   all of its own.
1e950 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f  ** internal memo
1e960 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
1e970 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74  eds. "Core" in t
1e980 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74  he previous sent
1e990 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74  ence.** does not
1e9a0 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69   include operati
1e9b0 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66  ng-system specif
1e9c0 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  ic VFS implement
1e9d0 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57  ation.  The.** W
1e9e0 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 20  indows VFS uses 
1e9f0 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20  native malloc() 
1ea00 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 73  and free() for s
1ea10 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a  ome operations..
1ea20 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1ea30 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74  e3_malloc() rout
1ea40 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ine returns a po
1ea50 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b  inter to a block
1ea60 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74  .** of memory at
1ea70 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69   least N bytes i
1ea80 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20  n length, where 
1ea90 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 74  N is the paramet
1eaa0 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  er..** ^If sqlit
1eab0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75  e3_malloc() is u
1eac0 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20  nable to obtain 
1ead0 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a  sufficient free.
1eae0 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65  ** memory, it re
1eaf0 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
1eb00 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70  nter.  ^If the p
1eb10 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a  arameter N to.**
1eb20 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1eb30 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67  ) is zero or neg
1eb40 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74  ative then sqlit
1eb50 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75  e3_malloc() retu
1eb60 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f  rns.** a NULL po
1eb70 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  inter..**.** ^Th
1eb80 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  e sqlite3_malloc
1eb90 36 34 28 4e 29 20 72 6f 75 74 69 6e 65 20 77 6f  64(N) routine wo
1eba0 72 6b 73 20 6a 75 73 74 20 6c 69 6b 65 0a 2a 2a  rks just like.**
1ebb0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1ebc0 4e 29 20 65 78 63 65 70 74 20 74 68 61 74 20 4e  N) except that N
1ebd0 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20   is an unsigned 
1ebe0 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 69  64-bit integer i
1ebf0 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 73  nstead.** of a s
1ec00 69 67 6e 65 64 20 33 32 2d 62 69 74 20 69 6e 74  igned 32-bit int
1ec10 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  eger..**.** ^Cal
1ec20 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65  ling sqlite3_fre
1ec30 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  e() with a point
1ec40 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  er previously re
1ec50 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c  turned.** by sql
1ec60 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72  ite3_malloc() or
1ec70 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1ec80 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74  () releases that
1ec90 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68   memory so.** th
1eca0 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72  at it might be r
1ecb0 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c  eused.  ^The sql
1ecc0 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74  ite3_free() rout
1ecd0 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f  ine is.** a no-o
1ece0 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77  p if is called w
1ecf0 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ith a NULL point
1ed00 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e  er.  Passing a N
1ed10 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  ULL pointer.** t
1ed20 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  o sqlite3_free()
1ed30 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41   is harmless.  A
1ed40 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64  fter being freed
1ed50 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75  , memory.** shou
1ed60 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65  ld neither be re
1ed70 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20  ad nor written. 
1ed80 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72   Even reading pr
1ed90 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a  eviously freed.*
1eda0 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72  * memory might r
1edb0 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65  esult in a segme
1edc0 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72  ntation fault or
1edd0 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72   other severe er
1ede0 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63  ror..** Memory c
1edf0 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67  orruption, a seg
1ee00 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c  mentation fault,
1ee10 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65   or other severe
1ee20 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20   error.** might 
1ee30 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65  result if sqlite
1ee40 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c  3_free() is call
1ee50 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55  ed with a non-NU
1ee60 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a  LL pointer that.
1ee70 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69  ** was not obtai
1ee80 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ned from sqlite3
1ee90 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c  _malloc() or sql
1eea0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a  ite3_realloc()..
1eeb0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1eec0 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20  e3_realloc(X,N) 
1eed0 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70  interface attemp
1eee0 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a  ts to resize a.*
1eef0 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61  * prior memory a
1ef00 6c 6c 6f 63 61 74 69 6f 6e 20 58 20 74 6f 20 62  llocation X to b
1ef10 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  e at least N byt
1ef20 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 58  es..** ^If the X
1ef30 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
1ef40 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
1ef50 4e 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20  N).** is a NULL 
1ef60 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73  pointer then its
1ef70 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 65   behavior is ide
1ef80 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e  ntical to callin
1ef90 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c  g.** sqlite3_mal
1efa0 6c 6f 63 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20 74  loc(N)..** ^If t
1efb0 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 74  he N parameter t
1efc0 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
1efd0 63 28 58 2c 4e 29 20 69 73 20 7a 65 72 6f 20 6f  c(X,N) is zero o
1efe0 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68  r.** negative th
1eff0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
1f000 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73  is exactly the s
1f010 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a  ame as calling.*
1f020 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 58  * sqlite3_free(X
1f030 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72  )..** ^sqlite3_r
1f040 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75  ealloc(X,N) retu
1f050 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
1f060 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
1f070 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65  tion.** of at le
1f080 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73  ast N bytes in s
1f090 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 69  ize or NULL if i
1f0a0 6e 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f  nsufficient memo
1f0b0 72 79 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e  ry is available.
1f0c0 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65  .** ^If M is the
1f0d0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69   size of the pri
1f0e0 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74  or allocation, t
1f0f0 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74  hen min(N,M) byt
1f100 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69  es.** of the pri
1f110 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72  or allocation ar
1f120 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68  e copied into th
1f130 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62  e beginning of b
1f140 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a  uffer returned.*
1f150 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61  * by sqlite3_rea
1f160 6c 6c 6f 63 28 58 2c 4e 29 20 61 6e 64 20 74 68  lloc(X,N) and th
1f170 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
1f180 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20  on is freed..** 
1f190 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  ^If sqlite3_real
1f1a0 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73  loc(X,N) returns
1f1b0 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20 70   NULL and N is p
1f1c0 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20 74 68  ositive, then th
1f1d0 65 0a 2a 2a 20 70 72 69 6f 72 20 61 6c 6c 6f 63  e.** prior alloc
1f1e0 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 66 72 65  ation is not fre
1f1f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
1f200 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34  qlite3_realloc64
1f210 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 73  (X,N) interfaces
1f220 20 77 6f 72 6b 73 20 74 68 65 20 73 61 6d 65 20   works the same 
1f230 61 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  as.** sqlite3_re
1f240 61 6c 6c 6f 63 28 58 2c 4e 29 20 65 78 63 65 70  alloc(X,N) excep
1f250 74 20 74 68 61 74 20 4e 20 69 73 20 61 20 36 34  t that N is a 64
1f260 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e  -bit unsigned in
1f270 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a  teger instead.**
1f280 20 6f 66 20 61 20 33 32 2d 62 69 74 20 73 69 67   of a 32-bit sig
1f290 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a  ned integer..**.
1f2a0 2a 2a 20 5e 49 66 20 58 20 69 73 20 61 20 6d 65  ** ^If X is a me
1f2b0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1f2c0 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69  previously obtai
1f2d0 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ned from sqlite3
1f2e0 5f 6d 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71  _malloc(),.** sq
1f2f0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29  lite3_malloc64()
1f300 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  , sqlite3_reallo
1f310 63 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f  c(), or sqlite3_
1f320 72 65 61 6c 6c 6f 63 36 34 28 29 2c 20 74 68 65  realloc64(), the
1f330 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69  n.** sqlite3_msi
1f340 7a 65 28 58 29 20 72 65 74 75 72 6e 73 20 74 68  ze(X) returns th
1f350 65 20 73 69 7a 65 20 6f 66 20 74 68 61 74 20 6d  e size of that m
1f360 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1f370 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 54   in bytes..** ^T
1f380 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
1f390 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 73 69  d by sqlite3_msi
1f3a0 7a 65 28 58 29 20 6d 69 67 68 74 20 62 65 20 6c  ze(X) might be l
1f3b0 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 6e  arger than the n
1f3c0 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74 65  umber.** of byte
1f3d0 73 20 72 65 71 75 65 73 74 65 64 20 77 68 65 6e  s requested when
1f3e0 20 58 20 77 61 73 20 61 6c 6c 6f 63 61 74 65 64   X was allocated
1f3f0 2e 20 20 5e 49 66 20 58 20 69 73 20 61 20 4e 55  .  ^If X is a NU
1f400 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a  LL pointer then.
1f410 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65  ** sqlite3_msize
1f420 28 58 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  (X) returns zero
1f430 2e 20 20 49 66 20 58 20 70 6f 69 6e 74 73 20 74  .  If X points t
1f440 6f 20 73 6f 6d 65 74 68 69 6e 67 20 74 68 61 74  o something that
1f450 20 69 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 62   is not.** the b
1f460 65 67 69 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d 6f  eginning of memo
1f470 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 6f  ry allocation, o
1f480 72 20 69 66 20 69 74 20 70 6f 69 6e 74 73 20 74  r if it points t
1f490 6f 20 61 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a 20  o a formerly.** 
1f4a0 76 61 6c 69 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  valid memory all
1f4b0 6f 63 61 74 69 6f 6e 20 74 68 61 74 20 68 61 73  ocation that has
1f4c0 20 6e 6f 77 20 62 65 65 6e 20 66 72 65 65 64 2c   now been freed,
1f4d0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
1f4e0 6f 72 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  or.** of sqlite3
1f4f0 5f 6d 73 69 7a 65 28 58 29 20 69 73 20 75 6e 64  _msize(X) is und
1f500 65 66 69 6e 65 64 20 61 6e 64 20 70 6f 73 73 69  efined and possi
1f510 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a  bly harmful..**.
1f520 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72  ** ^The memory r
1f530 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
1f540 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c 20 73 71 6c  e3_malloc(), sql
1f550 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 0a  ite3_realloc(),.
1f560 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
1f570 63 36 34 28 29 2c 20 61 6e 64 20 73 71 6c 69 74  c64(), and sqlit
1f580 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29 0a 2a  e3_realloc64().*
1f590 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67  * is always alig
1f5a0 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20  ned to at least 
1f5b0 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61  an 8 byte bounda
1f5c0 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34  ry, or to a.** 4
1f5d0 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69   byte boundary i
1f5e0 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f  f the [SQLITE_4_
1f5f0 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c  BYTE_ALIGNED_MAL
1f600 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  LOC] compile-tim
1f610 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75  e.** option is u
1f620 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51  sed..**.** In SQ
1f630 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
1f640 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74  .0 and 3.5.1, it
1f650 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f   was possible to
1f660 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53   define.** the S
1f670 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52  QLITE_OMIT_MEMOR
1f680 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69  Y_ALLOCATION whi
1f690 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74  ch would cause t
1f6a0 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69  he built-in.** i
1f6b0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
1f6c0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
1f6d0 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20  to be omitted.  
1f6e0 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a  That capability.
1f6f0 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  ** is no longer 
1f700 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20  provided.  Only 
1f710 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
1f720 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62  allocators can b
1f730 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72  e used..**.** Pr
1f740 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65  ior to SQLite ve
1f750 72 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68  rsion 3.7.10, th
1f760 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74  e Windows OS int
1f770 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c  erface layer cal
1f780 6c 65 64 0a 2a 2a 20 74 68 65 20 73 79 73 74 65  led.** the syste
1f790 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66  m malloc() and f
1f7a0 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 77  ree() directly w
1f7b0 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a  hen converting.*
1f7c0 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77  * filenames betw
1f7d0 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e  een the UTF-8 en
1f7e0 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 53  coding used by S
1f7f0 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61  QLite.** and wha
1f800 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65  tever filename e
1f810 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20  ncoding is used 
1f820 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c 61  by the particula
1f830 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73  r Windows.** ins
1f840 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f  tallation.  Memo
1f850 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
1f860 72 6f 72 73 20 77 65 72 65 20 64 65 74 65 63 74  rors were detect
1f870 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20  ed, but.** they 
1f880 77 65 72 65 20 72 65 70 6f 72 74 65 64 20 62 61  were reported ba
1f890 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41  ck as [SQLITE_CA
1f8a0 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53  NTOPEN] or.** [S
1f8b0 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74  QLITE_IOERR] rat
1f8c0 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
1f8d0 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54  _NOMEM]..**.** T
1f8e0 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d  he pointer argum
1f8f0 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  ents to [sqlite3
1f900 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71  _free()] and [sq
1f910 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
1f920 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68  .** must be eith
1f930 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20  er NULL or else 
1f940 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65  pointers obtaine
1f950 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a  d from a prior.*
1f960 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  * invocation of 
1f970 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1f980 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
1f990 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68  ealloc()] that h
1f9a0 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62  ave.** not yet b
1f9b0 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a  een released..**
1f9c0 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
1f9d0 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61  ion must not rea
1f9e0 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70  d or write any p
1f9f0 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63  art of.** a bloc
1fa00 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65  k of memory afte
1fa10 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65  r it has been re
1fa20 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20  leased using.** 
1fa30 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1fa40 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
1fa50 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64  lloc()]..*/.void
1fa60 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   *sqlite3_malloc
1fa70 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c  (int);.void *sql
1fa80 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 73 71  ite3_malloc64(sq
1fa90 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 76  lite3_uint64);.v
1faa0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61  oid *sqlite3_rea
1fab0 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29  lloc(void*, int)
1fac0 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  ;.void *sqlite3_
1fad0 72 65 61 6c 6c 6f 63 36 34 28 76 6f 69 64 2a 2c  realloc64(void*,
1fae0 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29   sqlite3_uint64)
1faf0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66  ;.void sqlite3_f
1fb00 72 65 65 28 76 6f 69 64 2a 29 3b 0a 73 71 6c 69  ree(void*);.sqli
1fb10 74 65 33 5f 75 69 6e 74 36 34 20 73 71 6c 69 74  te3_uint64 sqlit
1fb20 65 33 5f 6d 73 69 7a 65 28 76 6f 69 64 2a 29 3b  e3_msize(void*);
1fb30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1fb40 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
1fb50 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a  or Statistics.**
1fb60 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69  .** SQLite provi
1fb70 64 65 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e  des these two in
1fb80 74 65 72 66 61 63 65 73 20 66 6f 72 20 72 65 70  terfaces for rep
1fb90 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74  orting on the st
1fba0 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  atus.** of the [
1fbb0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1fbc0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ], [sqlite3_free
1fbd0 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
1fbe0 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  3_realloc()].** 
1fbf0 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20  routines, which 
1fc00 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69  form the built-i
1fc10 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
1fc20 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a  ion subsystem..*
1fc30 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  *.** ^The [sqlit
1fc40 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
1fc50 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ] routine return
1fc60 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
1fc70 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f  bytes.** of memo
1fc80 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74  ry currently out
1fc90 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63  standing (malloc
1fca0 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64  ed but not freed
1fcb0 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  )..** ^The [sqli
1fcc0 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
1fcd0 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20  ater()] routine 
1fce0 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69  returns the maxi
1fcf0 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  mum.** value of 
1fd00 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1fd10 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68  used()] since th
1fd20 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72  e high-water mar
1fd30 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65  k.** was last re
1fd40 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65  set.  ^The value
1fd50 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
1fd60 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
1fd70 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71  ed()] and.** [sq
1fd80 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
1fd90 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64  hwater()] includ
1fda0 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a  e any overhead.*
1fdb0 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c 69 74  * added by SQLit
1fdc0 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65  e in its impleme
1fdd0 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69  ntation of [sqli
1fde0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a  te3_malloc()],.*
1fdf0 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65  * but not overhe
1fe00 61 64 20 61 64 64 65 64 20 62 79 20 74 68 65 20  ad added by the 
1fe10 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73  any underlying s
1fe20 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a  ystem library.**
1fe30 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b   routines that [
1fe40 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1fe50 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a  ] may call..**.*
1fe60 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69  * ^The memory hi
1fe70 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73  gh-water mark is
1fe80 20 72 65 73 65 74 20 74 6f 20 74 68 65 20 63 75   reset to the cu
1fe90 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a  rrent value of.*
1fea0 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  * [sqlite3_memor
1feb0 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64  y_used()] if and
1fec0 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72   only if the par
1fed0 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71  ameter to.** [sq
1fee0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
1fef0 68 77 61 74 65 72 28 29 5d 20 69 73 20 74 72 75  hwater()] is tru
1ff00 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72  e.  ^The value r
1ff10 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73  eturned.** by [s
1ff20 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
1ff30 67 68 77 61 74 65 72 28 31 29 5d 20 69 73 20 74  ghwater(1)] is t
1ff40 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61  he high-water ma
1ff50 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74  rk.** prior to t
1ff60 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c  he reset..*/.sql
1ff70 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
1ff80 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76  e3_memory_used(v
1ff90 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e  oid);.sqlite3_in
1ffa0 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  t64 sqlite3_memo
1ffb0 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74  ry_highwater(int
1ffc0 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a   resetFlag);../*
1ffd0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73  .** CAPI3REF: Ps
1ffe0 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62  eudo-Random Numb
1fff0 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a  er Generator.**.
20000 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69  ** SQLite contai
20010 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74  ns a high-qualit
20020 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20  y pseudo-random 
20030 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72  number generator
20040 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a   (PRNG) used to.
20050 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d  ** select random
20060 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73   [ROWID | ROWIDs
20070 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67  ] when inserting
20080 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74   new records int
20090 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a  o a table that.*
200a0 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 74  * already uses t
200b0 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69  he largest possi
200c0 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68  ble [ROWID].  Th
200d0 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75  e PRNG is also u
200e0 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62  sed for.** the b
200f0 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29  uild-in random()
20100 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28   and randomblob(
20110 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e  ) SQL functions.
20120 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65    This interface
20130 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69   allows.** appli
20140 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73  cations to acces
20150 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20  s the same PRNG 
20160 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73  for other purpos
20170 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c  es..**.** ^A cal
20180 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  l to this routin
20190 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73  e stores N bytes
201a0 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69   of randomness i
201b0 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a  nto buffer P..**
201c0 20 5e 54 68 65 20 50 20 70 61 72 61 6d 65 74 65   ^The P paramete
201d0 72 20 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c 20  r can be a NULL 
201e0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
201f0 49 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  If this routine 
20200 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 70 72 65  has not been pre
20210 76 69 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20 6f  viously called o
20220 72 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75  r if the previou
20230 73 0a 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e 20  s.** call had N 
20240 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 6f 72  less than one or
20250 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
20260 66 6f 72 20 50 2c 20 74 68 65 6e 20 74 68 65 20  for P, then the 
20270 50 52 4e 47 20 69 73 0a 2a 2a 20 73 65 65 64 65  PRNG is.** seede
20280 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65  d using randomne
20290 73 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ss obtained from
202a0 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73   the xRandomness
202b0 20 6d 65 74 68 6f 64 20 6f 66 0a 2a 2a 20 74 68   method of.** th
202c0 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
202d0 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a  e3_vfs] object..
202e0 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 65 76 69  ** ^If the previ
202f0 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73  ous call to this
20300 20 72 6f 75 74 69 6e 65 20 68 61 64 20 61 6e 20   routine had an 
20310 4e 20 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20 61  N of 1 or more a
20320 6e 64 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c  nd a.** non-NULL
20330 20 50 20 74 68 65 6e 20 74 68 65 20 70 73 65 75   P then the pseu
20340 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73  do-randomness is
20350 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e   generated.** in
20360 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74  ternally and wit
20370 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f  hout recourse to
20380 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
20390 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a  s] xRandomness.*
203a0 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69  * method..*/.voi
203b0 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d  d sqlite3_random
203c0 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64  ness(int N, void
203d0 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50   *P);../*.** CAP
203e0 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54  I3REF: Compile-T
203f0 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f  ime Authorizatio
20400 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d  n Callbacks.** M
20410 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
20420 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
20430 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 6e 20  ne registers an 
20440 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
20450 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74 69  ack with a parti
20460 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61  cular.** [databa
20470 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20  se connection], 
20480 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20  supplied in the 
20490 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a  first argument..
204a0 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a  ** ^The authoriz
204b0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
204c0 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74  nvoked as SQL st
204d0 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69  atements are bei
204e0 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62  ng compiled.** b
204f0 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  y [sqlite3_prepa
20500 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  re()] or its var
20510 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70  iants [sqlite3_p
20520 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a  repare_v2()],.**
20530 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
20540 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  e16()] and [sqli
20550 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
20560 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 75  ()].  ^At variou
20570 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69  s.** points duri
20580 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69  ng the compilati
20590 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c  on process, as l
205a0 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 63 72  ogic is being cr
205b0 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66  eated.** to perf
205c0 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69  orm various acti
205d0 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69  ons, the authori
205e0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
205f0 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65  invoked to.** se
20600 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f  e if those actio
20610 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20  ns are allowed. 
20620 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72   ^The authorizer
20630 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64   callback should
20640 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
20650 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20  TE_OK] to allow 
20660 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c  the action, [SQL
20670 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64  ITE_IGNORE] to d
20680 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73  isallow the.** s
20690 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62  pecific action b
206a0 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c  ut allow the SQL
206b0 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f   statement to co
206c0 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20  ntinue to be.** 
206d0 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51  compiled, or [SQ
206e0 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61  LITE_DENY] to ca
206f0 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20 53  use the entire S
20700 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  QL statement to 
20710 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77  be.** rejected w
20720 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e  ith an error.  ^
20730 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  If the authorize
20740 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  r callback retur
20750 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20  ns.** any value 
20760 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
20770 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c  TE_IGNORE], [SQL
20780 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c  ITE_OK], or [SQL
20790 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65  ITE_DENY].** the
207a0 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70  n the [sqlite3_p
207b0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
207c0 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20  equivalent call 
207d0 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a  that triggered.*
207e0 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * the authorizer
207f0 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20   will fail with 
20800 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
20810 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
20820 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
20830 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74  s [SQLITE_OK], t
20840 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70  hat means the op
20850 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65  eration.** reque
20860 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68  sted is ok.  ^Wh
20870 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
20880 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
20890 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73  DENY], the.** [s
208a0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
208b0 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65  2()] or equivale
208c0 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69  nt call that tri
208d0 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75  ggered the.** au
208e0 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61  thorizer will fa
208f0 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  il with an error
20900 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e   message explain
20910 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65  ing that.** acce
20920 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a  ss is denied. .*
20930 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
20940 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
20950 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
20960 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f  back is a copy o
20970 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70  f the third.** p
20980 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
20990 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
209a0 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61  orizer() interfa
209b0 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  ce. ^The second 
209c0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20  parameter.** to 
209d0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
209e0 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49  an integer [SQLI
209f0 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e  TE_COPY | action
20a00 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63   code] that spec
20a10 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72  ifies.** the par
20a20 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74  ticular action t
20a30 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e  o be authorized.
20a40 20 5e 54 68 65 20 74 68 69 72 64 20 74 68 72 6f   ^The third thro
20a50 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d 65  ugh sixth parame
20a60 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63  ters.** to the c
20a70 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f  allback are zero
20a80 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
20a90 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  ngs that contain
20aa0 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64   additional.** d
20ab0 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65  etails about the
20ac0 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75   action to be au
20ad0 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20  thorized..**.** 
20ae0 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63  ^If the action c
20af0 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52  ode is [SQLITE_R
20b00 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20  EAD].** and the 
20b10 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
20b20 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
20b30 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72   then the.** [pr
20b40 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
20b50 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63  ] statement is c
20b60 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73 75  onstructed to su
20b70 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55  bstitute.** a NU
20b80 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63  LL value in plac
20b90 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63  e of the table c
20ba0 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64  olumn that would
20bb0 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65   have.** been re
20bc0 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b  ad if [SQLITE_OK
20bd0 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75 72  ] had been retur
20be0 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ned.  The [SQLIT
20bf0 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74  E_IGNORE].** ret
20c00 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  urn can be used 
20c10 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75  to deny an untru
20c20 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73 73  sted user access
20c30 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a   to individual.*
20c40 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74  * columns of a t
20c50 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  able..** ^If the
20c60 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20   action code is 
20c70 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20  [SQLITE_DELETE] 
20c80 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  and the callback
20c90 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c   returns.** [SQL
20ca0 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e  ITE_IGNORE] then
20cb0 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70   the [DELETE] op
20cc0 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73  eration proceeds
20cd0 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75   but the.** [tru
20ce0 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69  ncate optimizati
20cf0 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20  on] is disabled 
20d00 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65  and all rows are
20d10 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64   deleted individ
20d20 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20  ually..**.** An 
20d30 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73  authorizer is us
20d40 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33  ed when [sqlite3
20d50 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61  _prepare | prepa
20d60 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61  ring].** SQL sta
20d70 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20  tements from an 
20d80 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65  untrusted source
20d90 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74  , to ensure that
20da0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
20db0 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72  nts.** do not tr
20dc0 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74 61  y to access data
20dd0 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c   they are not al
20de0 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72  lowed to see, or
20df0 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f   that they do no
20e00 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63  t.** try to exec
20e10 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74  ute malicious st
20e20 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61  atements that da
20e30 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61 73  mage the databas
20e40 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70  e.  For.** examp
20e50 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69  le, an applicati
20e60 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75  on may allow a u
20e70 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62  ser to enter arb
20e80 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75  itrary.** SQL qu
20e90 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61  eries for evalua
20ea0 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61  tion by a databa
20eb0 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70 70  se.  But the app
20ec0 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a  lication does.**
20ed0 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73   not want the us
20ee0 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f  er to be able to
20ef0 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79 20   make arbitrary 
20f00 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a  changes to the.*
20f10 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20  * database.  An 
20f20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64  authorizer could
20f30 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20   then be put in 
20f40 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a  place while the.
20f50 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20  ** user-entered 
20f60 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71  SQL is being [sq
20f70 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20  lite3_prepare | 
20f80 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a  prepared] that.*
20f90 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72  * disallows ever
20fa0 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53  ything except [S
20fb0 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
20fc0 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61  s..**.** Applica
20fd0 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20  tions that need 
20fe0 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66  to process SQL f
20ff0 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f  rom untrusted so
21000 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61  urces.** might a
21010 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77  lso consider low
21020 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c  ering resource l
21030 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c  imits using [sql
21040 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a  ite3_limit()].**
21050 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61   and limiting da
21060 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e  tabase size usin
21070 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f  g the [max_page_
21080 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a  count] [PRAGMA].
21090 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74  ** in addition t
210a0 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f  o using an autho
210b0 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f  rizer..**.** ^(O
210c0 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74  nly a single aut
210d0 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69  horizer can be i
210e0 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74  n place on a dat
210f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
21100 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20  .** at a time.  
21110 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c  Each call to sql
21120 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
21130 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74 68  zer overrides th
21140 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61  e.** previous ca
21150 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20  ll.)^  ^Disable 
21160 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62  the authorizer b
21170 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e  y installing a N
21180 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  ULL callback..**
21190 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   The authorizer 
211a0 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  is disabled by d
211b0 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  efault..**.** Th
211c0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
211d0 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64  lback must not d
211e0 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20  o anything that 
211f0 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74  will modify.** t
21200 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
21210 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
21220 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ked the authoriz
21230 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20  er callback..** 
21240 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74  Note that [sqlit
21250 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
21260 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
21270 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66  ep()] both modif
21280 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62  y their.** datab
21290 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
212a0 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20  for the meaning 
212b0 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74  of "modify" in t
212c0 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a  his paragraph..*
212d0 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69  *.** ^When [sqli
212e0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
212f0 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70 72 65  ] is used to pre
21300 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74  pare a statement
21310 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65  , the.** stateme
21320 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70  nt might be re-p
21330 72 65 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b  repared during [
21340 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
21350 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68  due to a .** sch
21360 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e  ema change.  Hen
21370 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74  ce, the applicat
21380 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72  ion should ensur
21390 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f  e that the.** co
213a0 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72  rrect authorizer
213b0 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e   callback remain
213c0 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e  s in place durin
213d0 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  g the [sqlite3_s
213e0 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e  tep()]..**.** ^N
213f0 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75 74  ote that the aut
21400 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
21410 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79   is invoked only
21420 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69   during.** [sqli
21430 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
21440 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20  r its variants. 
21450 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69   Authorization i
21460 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d  s not.** perform
21470 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d  ed during statem
21480 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69  ent evaluation i
21490 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  n [sqlite3_step(
214a0 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73  )], unless.** as
214b0 20 73 74 61 74 65 64 20 69 6e 20 74 68 65 20 70   stated in the p
214c0 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70  revious paragrap
214d0 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  h, sqlite3_step(
214e0 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c  ) invokes.** sql
214f0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
21500 29 20 74 6f 20 72 65 70 72 65 70 61 72 65 20 61  ) to reprepare a
21510 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72   statement after
21520 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65   a schema change
21530 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
21540 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
21550 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69  .  sqlite3*,.  i
21560 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64  nt (*xAuth)(void
21570 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72  *,int,const char
21580 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  *,const char*,co
21590 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
215a0 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a  char*),.  void *
215b0 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a  pUserData.);../*
215c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75  .** CAPI3REF: Au
215d0 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20  thorizer Return 
215e0 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Codes.**.** The 
215f0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
21600 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
21610 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75  izer callback fu
21620 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20  nction] must.** 
21630 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53  return either [S
21640 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65  QLITE_OK] or one
21650 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f   of these two co
21660 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72  nstants in order
21670 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51  .** to signal SQ
21680 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f 72 20  Lite whether or 
21690 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69  not the action i
216a0 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65  s permitted.  Se
216b0 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  e the.** [sqlite
216c0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
216d0 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f   | authorizer do
216e0 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72  cumentation] for
216f0 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
21700 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
21710 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 49  * Note that SQLI
21720 54 45 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c 73  TE_IGNORE is als
21730 6f 20 75 73 65 64 20 61 73 20 61 20 5b 63 6f 6e  o used as a [con
21740 66 6c 69 63 74 20 72 65 73 6f 6c 75 74 69 6f 6e  flict resolution
21750 20 6d 6f 64 65 5d 0a 2a 2a 20 72 65 74 75 72 6e   mode].** return
21760 65 64 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c  ed from the [sql
21770 69 74 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e  ite3_vtab_on_con
21780 66 6c 69 63 74 28 29 5d 20 69 6e 74 65 72 66 61  flict()] interfa
21790 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ce..*/.#define S
217a0 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20  QLITE_DENY   1  
217b0 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51   /* Abort the SQ
217c0 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  L statement with
217d0 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65   an error */.#de
217e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f  fine SQLITE_IGNO
217f0 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20  RE 2   /* Don't 
21800 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75  allow access, bu
21810 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65  t don't generate
21820 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a   an error */../*
21830 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75  .** CAPI3REF: Au
21840 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20  thorizer Action 
21850 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Codes.**.** The 
21860 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
21870 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72  horizer()] inter
21880 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61  face registers a
21890 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
218a0 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e  on.** that is in
218b0 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69  voked to authori
218c0 7a 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73  ze certain SQL s
218d0 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73  tatement actions
218e0 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64  .  The.** second
218f0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
21900 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  e callback is an
21910 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68   integer code th
21920 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  at specifies.** 
21930 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62  what action is b
21940 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e  eing authorized.
21950 20 20 54 68 65 73 65 20 61 72 65 20 74 68 65 20    These are the 
21960 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63  integer action c
21970 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65  odes that.** the
21980 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
21990 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73  back may be pass
219a0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ed..**.** These 
219b0 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75  action code valu
219c0 65 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 20  es signify what 
219d0 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f  kind of operatio
219e0 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75  n is to be.** au
219f0 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33  thorized.  The 3
21a00 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d  rd and 4th param
21a10 65 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 74  eters to the aut
21a20 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61  horization.** ca
21a30 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
21a40 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65  will be paramete
21a50 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e  rs or NULL depen
21a60 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66  ding on which of
21a70 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20   these.** codes 
21a80 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73  is used as the s
21a90 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  econd parameter.
21aa0 20 20 5e 28 54 68 65 20 35 74 68 20 70 61 72 61    ^(The 5th para
21ab0 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20  meter to the.** 
21ac0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
21ad0 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20  ack is the name 
21ae0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
21af0 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c  ("main", "temp",
21b00 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70  .** etc.) if app
21b10 6c 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65  licable.)^  ^The
21b20 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   6th parameter t
21b30 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  o the authorizer
21b40 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20   callback.** is 
21b50 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
21b60 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67  inner-most trigg
21b70 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20  er or view that 
21b80 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
21b90 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73  or.** the access
21ba0 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c   attempt or NULL
21bb0 20 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20   if this access 
21bc0 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63  attempt is direc
21bd0 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d  tly from.** top-
21be0 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a  level SQL code..
21bf0 2a 2f 0a 2f 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 2a 20  *************** 
21c20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  3rd ************
21c30 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   4th ***********
21c40 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
21c50 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20  _CREATE_INDEX   
21c60 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e         1   /* In
21c70 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
21c80 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
21c90 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
21ca0 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20  CREATE_TABLE    
21cb0 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62        2   /* Tab
21cc0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
21cd0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
21ce0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
21cf0 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58  REATE_TEMP_INDEX
21d00 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65       3   /* Inde
21d10 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
21d20 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
21d30 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
21d40 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20  EATE_TEMP_TABLE 
21d50 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65      4   /* Table
21d60 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
21d70 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
21d80 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
21d90 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52  ATE_TEMP_TRIGGER
21da0 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65     5   /* Trigge
21db0 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
21dc0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
21dd0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
21de0 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20  TE_TEMP_VIEW    
21df0 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61    6   /* View Na
21e00 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
21e10 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
21e20 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
21e30 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20  E_TRIGGER       
21e40 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20   7   /* Trigger 
21e50 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
21e60 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
21e70 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
21e80 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20  _VIEW           
21e90 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  8   /* View Name
21ea0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
21eb0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
21ec0 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20  e SQLITE_DELETE 
21ed0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 39                 9
21ee0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
21ef0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
21f00 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
21f10 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44   SQLITE_DROP_IND
21f20 45 58 20 20 20 20 20 20 20 20 20 20 20 31 30 20  EX           10 
21f30 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
21f40 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
21f50 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
21f60 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c  SQLITE_DROP_TABL
21f70 45 20 20 20 20 20 20 20 20 20 20 20 31 31 20 20  E           11  
21f80 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
21f90 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
21fa0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
21fb0 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
21fc0 49 4e 44 45 58 20 20 20 20 20 20 31 32 20 20 20  INDEX      12   
21fd0 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
21fe0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
21ff0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
22000 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54  LITE_DROP_TEMP_T
22010 41 42 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f  ABLE      13   /
22020 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
22030 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
22040 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22050 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52  ITE_DROP_TEMP_TR
22060 49 47 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a  IGGER    14   /*
22070 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
22080 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
22090 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
220a0 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45  TE_DROP_TEMP_VIE
220b0 57 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20  W       15   /* 
220c0 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
220d0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
220e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
220f0 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20  E_DROP_TRIGGER  
22100 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54         16   /* T
22110 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
22120 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
22130 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22140 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20  _DROP_VIEW      
22150 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69        17   /* Vi
22160 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
22170 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
22180 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22190 49 4e 53 45 52 54 20 20 20 20 20 20 20 20 20 20  INSERT          
221a0 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62       18   /* Tab
221b0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
221c0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
221d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50  #define SQLITE_P
221e0 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20  RAGMA           
221f0 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67      19   /* Prag
22200 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20  ma Name     1st 
22210 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23  arg or NULL */.#
22220 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
22230 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20  AD              
22240 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65     20   /* Table
22250 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d   Name      Colum
22260 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  n Name     */.#d
22270 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c  efine SQLITE_SEL
22280 45 43 54 20 20 20 20 20 20 20 20 20 20 20 20 20  ECT             
22290 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20    21   /* NULL  
222a0 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20            NULL  
222b0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
222c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e  fine SQLITE_TRAN
222d0 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20  SACTION         
222e0 20 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69   22   /* Operati
222f0 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  on       NULL   
22300 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
22310 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54  ine SQLITE_UPDAT
22320 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
22330 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  23   /* Table Na
22340 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e  me      Column N
22350 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
22360 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48  ne SQLITE_ATTACH
22370 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
22380 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20  4   /* Filename 
22390 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
223a0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
223b0 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20  e SQLITE_DETACH 
223c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35                25
223d0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e     /* Database N
223e0 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20  ame   NULL      
223f0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
22400 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41   SQLITE_ALTER_TA
22410 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 36 20  BLE          26 
22420 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61    /* Database Na
22430 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  me   Table Name 
22440 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
22450 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20  SQLITE_REINDEX  
22460 20 20 20 20 20 20 20 20 20 20 20 20 32 37 20 20              27  
22470 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
22480 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
22490 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
224a0 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20  QLITE_ANALYZE   
224b0 20 20 20 20 20 20 20 20 20 20 20 32 38 20 20 20             28   
224c0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
224d0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
224e0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
224f0 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42  LITE_CREATE_VTAB
22500 4c 45 20 20 20 20 20 20 20 20 32 39 20 20 20 2f  LE        29   /
22510 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
22520 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20    Module Name   
22530 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22540 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20  ITE_DROP_VTABLE 
22550 20 20 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a           30   /*
22560 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
22570 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20   Module Name    
22580 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
22590 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20  TE_FUNCTION     
225a0 20 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20          31   /* 
225b0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
225c0 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20  Function Name   
225d0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
225e0 45 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20  E_SAVEPOINT     
225f0 20 20 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f         32   /* O
22600 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53  peration       S
22610 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a  avepoint Name  *
22620 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22630 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20 20 20  _COPY           
22640 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f         0   /* No
22650 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a   longer used */.
22660 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
22670 45 43 55 52 53 49 56 45 20 20 20 20 20 20 20 20  ECURSIVE        
22680 20 20 20 20 33 33 20 20 20 2f 2a 20 4e 55 4c 4c      33   /* NULL
22690 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c              NULL
226a0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 0a              */..
226b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
226c0 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66  Tracing And Prof
226d0 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a  iling Functions.
226e0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
226f0 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  e3.**.** These r
22700 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65 70 72  outines are depr
22710 65 63 61 74 65 64 2e 20 55 73 65 20 74 68 65 20  ecated. Use the 
22720 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76  [sqlite3_trace_v
22730 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a  2()] interface.*
22740 2a 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65  * instead of the
22750 20 72 6f 75 74 69 6e 65 73 20 64 65 73 63 72 69   routines descri
22760 62 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20  bed here..**.** 
22770 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
22780 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b  egister callback
22790 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20   functions that 
227a0 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a  can be used for.
227b0 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70  ** tracing and p
227c0 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65  rofiling the exe
227d0 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74  cution of SQL st
227e0 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
227f0 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75  ^The callback fu
22800 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65  nction registere
22810 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61  d by sqlite3_tra
22820 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20  ce() is invoked 
22830 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69  at.** various ti
22840 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20  mes when an SQL 
22850 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69  statement is bei
22860 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74  ng run by [sqlit
22870 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e  e3_step()]..** ^
22880 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63  The sqlite3_trac
22890 65 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  e() callback is 
228a0 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55  invoked with a U
228b0 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f  TF-8 rendering o
228c0 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61  f the.** SQL sta
228d0 74 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74  tement text as t
228e0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72  he statement fir
228f0 73 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 74  st begins execut
22900 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69  ing..** ^(Additi
22910 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61  onal sqlite3_tra
22920 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d  ce() callbacks m
22930 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73  ight occur.** as
22940 20 65 61 63 68 20 74 72 69 67 67 65 72 65 64 20   each triggered 
22950 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e  subprogram is en
22960 74 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c  tered.  The call
22970 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65  backs for trigge
22980 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20  rs.** contain a 
22990 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e  UTF-8 SQL commen
229a0 74 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 65  t that identifie
229b0 73 20 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e  s the trigger.)^
229c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  .**.** The [SQLI
229d0 54 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49  TE_TRACE_SIZE_LI
229e0 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  MIT] compile-tim
229f0 65 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  e option can be 
22a00 75 73 65 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a  used to limit.**
22a10 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b   the length of [
22a20 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 5d  bound parameter]
22a30 20 65 78 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68   expansion in th
22a40 65 20 6f 75 74 70 75 74 20 6f 66 20 73 71 6c 69  e output of sqli
22a50 74 65 33 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a  te3_trace()..**.
22a60 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b  ** ^The callback
22a70 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74   function regist
22a80 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ered by sqlite3_
22a90 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76  profile() is inv
22aa0 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20  oked.** as each 
22ab0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69  SQL statement fi
22ac0 6e 69 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72  nishes.  ^The pr
22ad0 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63  ofile callback c
22ae0 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f  ontains.** the o
22af0 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e  riginal statemen
22b00 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73  t text and an es
22b10 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63  timate of wall-c
22b20 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20  lock time.** of 
22b30 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74  how long that st
22b40 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20  atement took to 
22b50 72 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 69  run.  ^The profi
22b60 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74  le callback.** t
22b70 69 6d 65 20 69 73 20 69 6e 20 75 6e 69 74 73 20  ime is in units 
22b80 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20  of nanoseconds, 
22b90 68 6f 77 65 76 65 72 20 74 68 65 20 63 75 72 72  however the curr
22ba0 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ent implementati
22bb0 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61  on.** is only ca
22bc0 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65  pable of millise
22bd0 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20  cond resolution 
22be0 73 6f 20 74 68 65 20 73 69 78 20 6c 65 61 73 74  so the six least
22bf0 20 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20   significant.** 
22c00 64 69 67 69 74 73 20 69 6e 20 74 68 65 20 74 69  digits in the ti
22c10 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65  me are meaningle
22c20 73 73 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  ss.  Future vers
22c30 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a  ions of SQLite.*
22c40 2a 20 6d 69 67 68 74 20 70 72 6f 76 69 64 65 20  * might provide 
22c50 67 72 65 61 74 65 72 20 72 65 73 6f 6c 75 74 69  greater resoluti
22c60 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c  on on the profil
22c70 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68  er callback.  Th
22c80 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f  e.** sqlite3_pro
22c90 66 69 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  file() function 
22ca0 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78  is considered ex
22cb0 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69  perimental and i
22cc0 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f 20  s.** subject to 
22cd0 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65  change in future
22ce0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
22cf0 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 44  ite..*/.SQLITE_D
22d00 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 2a  EPRECATED void *
22d10 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71  sqlite3_trace(sq
22d20 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28  lite3*,.   void(
22d30 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63  *xTrace)(void*,c
22d40 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69  onst char*), voi
22d50 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52  d*);.SQLITE_DEPR
22d60 45 43 41 54 45 44 20 76 6f 69 64 20 2a 73 71 6c  ECATED void *sql
22d70 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c  ite3_profile(sql
22d80 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a  ite3*,.   void(*
22d90 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c  xProfile)(void*,
22da0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69  const char*,sqli
22db0 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69  te3_uint64), voi
22dc0 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
22dd0 33 52 45 46 3a 20 53 51 4c 20 54 72 61 63 65 20  3REF: SQL Trace 
22de0 45 76 65 6e 74 20 43 6f 64 65 73 0a 2a 2a 20 4b  Event Codes.** K
22df0 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f  EYWORDS: SQLITE_
22e00 54 52 41 43 45 0a 2a 2a 0a 2a 2a 20 54 68 65 73  TRACE.**.** Thes
22e10 65 20 63 6f 6e 73 74 61 6e 74 73 20 69 64 65 6e  e constants iden
22e20 74 69 66 79 20 63 6c 61 73 73 65 73 20 6f 66 20  tify classes of 
22e30 65 76 65 6e 74 73 20 74 68 61 74 20 63 61 6e 20  events that can 
22e40 62 65 20 6d 6f 6e 69 74 6f 72 65 64 0a 2a 2a 20  be monitored.** 
22e50 75 73 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74  using the [sqlit
22e60 65 33 5f 74 72 61 63 65 5f 76 32 28 29 5d 20 74  e3_trace_v2()] t
22e70 72 61 63 69 6e 67 20 6c 6f 67 69 63 2e 20 20 54  racing logic.  T
22e80 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
22e90 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33  t.** to [sqlite3
22ea0 5f 74 72 61 63 65 5f 76 32 28 29 5d 20 69 73 20  _trace_v2()] is 
22eb0 61 6e 20 4f 52 2d 65 64 20 63 6f 6d 62 69 6e 61  an OR-ed combina
22ec0 74 69 6f 6e 20 6f 66 20 6f 6e 65 20 6f 72 20 6d  tion of one or m
22ed0 6f 72 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f  ore of.** the fo
22ee0 6c 6c 6f 77 69 6e 67 20 63 6f 6e 73 74 61 6e 74  llowing constant
22ef0 73 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 61  s.  ^The first a
22f00 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 74  rgument to the t
22f10 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  race callback.**
22f20 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 66   is one of the f
22f30 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e 73 74 61 6e  ollowing constan
22f40 74 73 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 74 72  ts..**.** New tr
22f50 61 63 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20  acing constants 
22f60 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
22f70 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e  future releases.
22f80 0a 2a 2a 0a 2a 2a 20 5e 41 20 74 72 61 63 65 20  .**.** ^A trace 
22f90 63 61 6c 6c 62 61 63 6b 20 68 61 73 20 66 6f 75  callback has fou
22fa0 72 20 61 72 67 75 6d 65 6e 74 73 3a 20 78 43 61  r arguments: xCa
22fb0 6c 6c 62 61 63 6b 28 54 2c 43 2c 50 2c 58 29 2e  llback(T,C,P,X).
22fc0 0a 2a 2a 20 5e 54 68 65 20 54 20 61 72 67 75 6d  .** ^The T argum
22fd0 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 74 68  ent is one of th
22fe0 65 20 69 6e 74 65 67 65 72 20 74 79 70 65 20 63  e integer type c
22ff0 6f 64 65 73 20 61 62 6f 76 65 2e 0a 2a 2a 20 5e  odes above..** ^
23000 54 68 65 20 43 20 61 72 67 75 6d 65 6e 74 20 69  The C argument i
23010 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
23020 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 20  context pointer 
23030 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 65  passed in as the
23040 0a 2a 2a 20 66 6f 75 72 74 68 20 61 72 67 75 6d  .** fourth argum
23050 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ent to [sqlite3_
23060 74 72 61 63 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20  trace_v2()]..** 
23070 54 68 65 20 50 20 61 6e 64 20 58 20 61 72 67 75  The P and X argu
23080 6d 65 6e 74 73 20 61 72 65 20 70 6f 69 6e 74 65  ments are pointe
23090 72 73 20 77 68 6f 73 65 20 6d 65 61 6e 69 6e 67  rs whose meaning
230a0 73 20 64 65 70 65 6e 64 20 6f 6e 20 54 2e 0a 2a  s depend on T..*
230b0 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53  *.** <dl>.** [[S
230c0 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54  QLITE_TRACE_STMT
230d0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52  ]] <dt>SQLITE_TR
230e0 41 43 45 5f 53 54 4d 54 3c 2f 64 74 3e 0a 2a 2a  ACE_STMT</dt>.**
230f0 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f   <dd>^An SQLITE_
23100 54 52 41 43 45 5f 53 54 4d 54 20 63 61 6c 6c 62  TRACE_STMT callb
23110 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  ack is invoked w
23120 68 65 6e 20 61 20 70 72 65 70 61 72 65 64 20 73  hen a prepared s
23130 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 66 69 72 73  tatement.** firs
23140 74 20 62 65 67 69 6e 73 20 72 75 6e 6e 69 6e 67  t begins running
23150 20 61 6e 64 20 70 6f 73 73 69 62 6c 79 20 61 74   and possibly at
23160 20 6f 74 68 65 72 20 74 69 6d 65 73 20 64 75 72   other times dur
23170 69 6e 67 20 74 68 65 0a 2a 2a 20 65 78 65 63 75  ing the.** execu
23180 74 69 6f 6e 20 6f 66 20 74 68 65 20 70 72 65 70  tion of the prep
23190 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 2c 20  ared statement, 
231a0 73 75 63 68 20 61 73 20 61 74 20 74 68 65 20 73  such as at the s
231b0 74 61 72 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20  tart of each.** 
231c0 74 72 69 67 67 65 72 20 73 75 62 70 72 6f 67 72  trigger subprogr
231d0 61 6d 2e 20 5e 54 68 65 20 50 20 61 72 67 75 6d  am. ^The P argum
231e0 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
231f0 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   to the.** [prep
23200 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
23210 20 5e 54 68 65 20 58 20 61 72 67 75 6d 65 6e 74   ^The X argument
23220 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
23230 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 0a   a string which.
23240 2a 2a 20 69 73 20 74 68 65 20 75 6e 65 78 70 61  ** is the unexpa
23250 6e 64 65 64 20 53 51 4c 20 74 65 78 74 20 6f 66  nded SQL text of
23260 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
23270 61 74 65 6d 65 6e 74 20 6f 72 20 61 6e 20 53 51  atement or an SQ
23280 4c 20 63 6f 6d 6d 65 6e 74 20 0a 2a 2a 20 74 68  L comment .** th
23290 61 74 20 69 6e 64 69 63 61 74 65 73 20 74 68 65  at indicates the
232a0 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 61   invocation of a
232b0 20 74 72 69 67 67 65 72 2e 20 20 5e 54 68 65 20   trigger.  ^The 
232c0 63 61 6c 6c 62 61 63 6b 20 63 61 6e 20 63 6f 6d  callback can com
232d0 70 75 74 65 0a 2a 2a 20 74 68 65 20 73 61 6d 65  pute.** the same
232e0 20 74 65 78 74 20 74 68 61 74 20 77 6f 75 6c 64   text that would
232f0 20 68 61 76 65 20 62 65 65 6e 20 72 65 74 75 72   have been retur
23300 6e 65 64 20 62 79 20 74 68 65 20 6c 65 67 61 63  ned by the legac
23310 79 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65  y [sqlite3_trace
23320 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
23330 20 62 79 20 75 73 69 6e 67 20 74 68 65 20 58 20   by using the X 
23340 61 72 67 75 6d 65 6e 74 20 77 68 65 6e 20 58 20  argument when X 
23350 62 65 67 69 6e 73 20 77 69 74 68 20 22 2d 2d 22  begins with "--"
23360 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a   and invoking.**
23370 20 5b 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64   [sqlite3_expand
23380 65 64 5f 73 71 6c 28 50 29 5d 20 6f 74 68 65 72  ed_sql(P)] other
23390 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  wise..**.** [[SQ
233a0 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49  LITE_TRACE_PROFI
233b0 4c 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  LE]] <dt>SQLITE_
233c0 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 3c 2f 64  TRACE_PROFILE</d
233d0 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51  t>.** <dd>^An SQ
233e0 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49  LITE_TRACE_PROFI
233f0 4c 45 20 63 61 6c 6c 62 61 63 6b 20 70 72 6f 76  LE callback prov
23400 69 64 65 73 20 61 70 70 72 6f 78 69 6d 61 74 65  ides approximate
23410 6c 79 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 69  ly the same.** i
23420 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 69 73  nformation as is
23430 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65   provided by the
23440 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c   [sqlite3_profil
23450 65 28 29 5d 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  e()] callback..*
23460 2a 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e  * ^The P argumen
23470 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
23480 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  o the [prepared 
23490 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 74  statement] and t
234a0 68 65 0a 2a 2a 20 58 20 61 72 67 75 6d 65 6e 74  he.** X argument
234b0 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 36 34 2d   points to a 64-
234c0 62 69 74 20 69 6e 74 65 67 65 72 20 77 68 69 63  bit integer whic
234d0 68 20 69 73 20 74 68 65 20 65 73 74 69 6d 61 74  h is the estimat
234e0 65 64 20 6f 66 0a 2a 2a 20 74 68 65 20 6e 75 6d  ed of.** the num
234f0 62 65 72 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e  ber of nanosecon
23500 64 20 74 68 61 74 20 74 68 65 20 70 72 65 70 61  d that the prepa
23510 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  red statement to
23520 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a 2a 20 5e 54  ok to run..** ^T
23530 68 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  he SQLITE_TRACE_
23540 50 52 4f 46 49 4c 45 20 63 61 6c 6c 62 61 63 6b  PROFILE callback
23550 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   is invoked when
23560 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66   the statement f
23570 69 6e 69 73 68 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b  inishes..**.** [
23580 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f  [SQLITE_TRACE_RO
23590 57 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54  W]] <dt>SQLITE_T
235a0 52 41 43 45 5f 52 4f 57 3c 2f 64 74 3e 0a 2a 2a  RACE_ROW</dt>.**
235b0 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f   <dd>^An SQLITE_
235c0 54 52 41 43 45 5f 52 4f 57 20 63 61 6c 6c 62 61  TRACE_ROW callba
235d0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68  ck is invoked wh
235e0 65 6e 65 76 65 72 20 61 20 70 72 65 70 61 72 65  enever a prepare
235f0 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 67  d.** statement g
23600 65 6e 65 72 61 74 65 73 20 61 20 73 69 6e 67 6c  enerates a singl
23610 65 20 72 6f 77 20 6f 66 20 72 65 73 75 6c 74 2e  e row of result.
23620 20 20 0a 2a 2a 20 5e 54 68 65 20 50 20 61 72 67    .** ^The P arg
23630 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
23640 65 72 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61  er to the [prepa
23650 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61  red statement] a
23660 6e 64 20 74 68 65 0a 2a 2a 20 58 20 61 72 67 75  nd the.** X argu
23670 6d 65 6e 74 20 69 73 20 75 6e 75 73 65 64 2e 0a  ment is unused..
23680 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54  **.** [[SQLITE_T
23690 52 41 43 45 5f 43 4c 4f 53 45 5d 5d 20 3c 64 74  RACE_CLOSE]] <dt
236a0 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c  >SQLITE_TRACE_CL
236b0 4f 53 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  OSE</dt>.** <dd>
236c0 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45  ^An SQLITE_TRACE
236d0 5f 43 4c 4f 53 45 20 63 61 6c 6c 62 61 63 6b 20  _CLOSE callback 
236e0 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  is invoked when 
236f0 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  a database.** co
23700 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e  nnection closes.
23710 0a 2a 2a 20 5e 54 68 65 20 50 20 61 72 67 75 6d  .** ^The P argum
23720 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
23730 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73   to the [databas
23740 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62  e connection] ob
23750 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 74 68 65 20  ject.** and the 
23760 58 20 61 72 67 75 6d 65 6e 74 20 69 73 20 75 6e  X argument is un
23770 75 73 65 64 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  used..** </dl>.*
23780 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
23790 5f 54 52 41 43 45 5f 53 54 4d 54 20 20 20 20 20  _TRACE_STMT     
237a0 20 20 30 78 30 31 0a 23 64 65 66 69 6e 65 20 53    0x01.#define S
237b0 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46  QLITE_TRACE_PROF
237c0 49 4c 45 20 20 20 20 30 78 30 32 0a 23 64 65 66  ILE    0x02.#def
237d0 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45  ine SQLITE_TRACE
237e0 5f 52 4f 57 20 20 20 20 20 20 20 20 30 78 30 34  _ROW        0x04
237f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
23800 54 52 41 43 45 5f 43 4c 4f 53 45 20 20 20 20 20  TRACE_CLOSE     
23810 20 30 78 30 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50   0x08../*.** CAP
23820 49 33 52 45 46 3a 20 53 51 4c 20 54 72 61 63 65  I3REF: SQL Trace
23830 20 48 6f 6f 6b 0a 2a 2a 20 4d 45 54 48 4f 44 3a   Hook.** METHOD:
23840 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
23850 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63  The sqlite3_trac
23860 65 5f 76 32 28 44 2c 4d 2c 58 2c 50 29 20 69 6e  e_v2(D,M,X,P) in
23870 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72  terface register
23880 73 20 61 20 74 72 61 63 65 20 63 61 6c 6c 62 61  s a trace callba
23890 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58  ck.** function X
238a0 20 61 67 61 69 6e 73 74 20 5b 64 61 74 61 62 61   against [databa
238b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
238c0 2c 20 75 73 69 6e 67 20 70 72 6f 70 65 72 74 79  , using property
238d0 20 6d 61 73 6b 20 4d 0a 2a 2a 20 61 6e 64 20 63   mask M.** and c
238e0 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 20 50  ontext pointer P
238f0 2e 20 20 5e 49 66 20 74 68 65 20 58 20 63 61 6c  .  ^If the X cal
23900 6c 62 61 63 6b 20 69 73 0a 2a 2a 20 4e 55 4c 4c  lback is.** NULL
23910 20 6f 72 20 69 66 20 74 68 65 20 4d 20 6d 61 73   or if the M mas
23920 6b 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20  k is zero, then 
23930 74 72 61 63 69 6e 67 20 69 73 20 64 69 73 61 62  tracing is disab
23940 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 4d 20 61  led.  The.** M a
23950 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62  rgument should b
23960 65 20 74 68 65 20 62 69 74 77 69 73 65 20 4f 52  e the bitwise OR
23970 2d 65 64 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20  -ed combination 
23980 6f 66 0a 2a 2a 20 7a 65 72 6f 20 6f 72 20 6d 6f  of.** zero or mo
23990 72 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45  re [SQLITE_TRACE
239a0 5d 20 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a  ] constants..**.
239b0 2a 2a 20 5e 45 61 63 68 20 63 61 6c 6c 20 74 6f  ** ^Each call to
239c0 20 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f   either sqlite3_
239d0 74 72 61 63 65 28 29 20 6f 72 20 73 71 6c 69 74  trace() or sqlit
239e0 65 33 5f 74 72 61 63 65 5f 76 32 28 29 20 6f 76  e3_trace_v2() ov
239f0 65 72 72 69 64 65 73 20 0a 2a 2a 20 28 63 61 6e  errides .** (can
23a00 63 65 6c 73 29 20 61 6e 79 20 70 72 69 6f 72 20  cels) any prior 
23a10 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
23a20 5f 74 72 61 63 65 28 29 20 6f 72 20 73 71 6c 69  _trace() or sqli
23a30 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 2e 0a  te3_trace_v2()..
23a40 2a 2a 0a 2a 2a 20 5e 54 68 65 20 58 20 63 61 6c  **.** ^The X cal
23a50 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
23a60 20 77 68 65 6e 65 76 65 72 20 61 6e 79 20 6f 66   whenever any of
23a70 20 74 68 65 20 65 76 65 6e 74 73 20 69 64 65 6e   the events iden
23a80 74 69 66 69 65 64 20 62 79 20 0a 2a 2a 20 6d 61  tified by .** ma
23a90 73 6b 20 4d 20 6f 63 63 75 72 2e 20 20 5e 54 68  sk M occur.  ^Th
23aa0 65 20 69 6e 74 65 67 65 72 20 72 65 74 75 72 6e  e integer return
23ab0 20 76 61 6c 75 65 20 66 72 6f 6d 20 74 68 65 20   value from the 
23ac0 63 61 6c 6c 62 61 63 6b 20 69 73 20 63 75 72 72  callback is curr
23ad0 65 6e 74 6c 79 0a 2a 2a 20 69 67 6e 6f 72 65 64  ently.** ignored
23ae0 2c 20 74 68 6f 75 67 68 20 74 68 69 73 20 6d 61  , though this ma
23af0 79 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75  y change in futu
23b00 72 65 20 72 65 6c 65 61 73 65 73 2e 20 20 43 61  re releases.  Ca
23b10 6c 6c 62 61 63 6b 0a 2a 2a 20 69 6d 70 6c 65 6d  llback.** implem
23b20 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  entations should
23b30 20 72 65 74 75 72 6e 20 7a 65 72 6f 20 74 6f 20   return zero to 
23b40 65 6e 73 75 72 65 20 66 75 74 75 72 65 20 63 6f  ensure future co
23b50 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a  mpatibility..**.
23b60 2a 2a 20 5e 41 20 74 72 61 63 65 20 63 61 6c 6c  ** ^A trace call
23b70 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
23b80 77 69 74 68 20 66 6f 75 72 20 61 72 67 75 6d 65  with four argume
23b90 6e 74 73 3a 20 63 61 6c 6c 62 61 63 6b 28 54 2c  nts: callback(T,
23ba0 43 2c 50 2c 58 29 2e 0a 2a 2a 20 5e 54 68 65 20  C,P,X)..** ^The 
23bb0 54 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e  T argument is on
23bc0 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45  e of the [SQLITE
23bd0 5f 54 52 41 43 45 5d 0a 2a 2a 20 63 6f 6e 73 74  _TRACE].** const
23be0 61 6e 74 73 20 74 6f 20 69 6e 64 69 63 61 74 65  ants to indicate
23bf0 20 77 68 79 20 74 68 65 20 63 61 6c 6c 62 61 63   why the callbac
23c00 6b 20 77 61 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a  k was invoked..*
23c10 2a 20 5e 54 68 65 20 43 20 61 72 67 75 6d 65 6e  * ^The C argumen
23c20 74 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  t is a copy of t
23c30 68 65 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74  he context point
23c40 65 72 2e 0a 2a 2a 20 54 68 65 20 50 20 61 6e 64  er..** The P and
23c50 20 58 20 61 72 67 75 6d 65 6e 74 73 20 61 72 65   X arguments are
23c60 20 70 6f 69 6e 74 65 72 73 20 77 68 6f 73 65 20   pointers whose 
23c70 6d 65 61 6e 69 6e 67 73 20 64 65 70 65 6e 64 20  meanings depend 
23c80 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  on T..**.** The 
23c90 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32  sqlite3_trace_v2
23ca0 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
23cb0 69 6e 74 65 6e 64 65 64 20 74 6f 20 72 65 70 6c  intended to repl
23cc0 61 63 65 20 74 68 65 20 6c 65 67 61 63 79 0a 2a  ace the legacy.*
23cd0 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71  * interfaces [sq
23ce0 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d 20 61  lite3_trace()] a
23cf0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66  nd [sqlite3_prof
23d00 69 6c 65 28 29 5d 2c 20 62 6f 74 68 20 6f 66 20  ile()], both of 
23d10 77 68 69 63 68 0a 2a 2a 20 61 72 65 20 64 65 70  which.** are dep
23d20 72 65 63 61 74 65 64 2e 0a 2a 2f 0a 69 6e 74 20  recated..*/.int 
23d30 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32  sqlite3_trace_v2
23d40 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20  (.  sqlite3*,.  
23d50 75 6e 73 69 67 6e 65 64 20 75 4d 61 73 6b 2c 0a  unsigned uMask,.
23d60 20 20 69 6e 74 28 2a 78 43 61 6c 6c 62 61 63 6b    int(*xCallback
23d70 29 28 75 6e 73 69 67 6e 65 64 2c 76 6f 69 64 2a  )(unsigned,void*
23d80 2c 76 6f 69 64 2a 2c 76 6f 69 64 2a 29 2c 0a 20  ,void*,void*),. 
23d90 20 76 6f 69 64 20 2a 70 43 74 78 0a 29 3b 0a 0a   void *pCtx.);..
23da0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
23db0 51 75 65 72 79 20 50 72 6f 67 72 65 73 73 20 43  Query Progress C
23dc0 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48  allbacks.** METH
23dd0 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
23de0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 70  * ^The sqlite3_p
23df0 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28  rogress_handler(
23e00 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66 61  D,N,X,P) interfa
23e10 63 65 20 63 61 75 73 65 73 20 74 68 65 20 63 61  ce causes the ca
23e20 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69  llback.** functi
23e30 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b  on X to be invok
23e40 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20  ed periodically 
23e50 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e  during long runn
23e60 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  ing calls to.** 
23e70 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
23e80 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
23e90 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
23ea0 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72  get_table()] for
23eb0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
23ec0 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65  nection D.  An e
23ed0 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74  xample use for t
23ee0 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  his.** interface
23ef0 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55   is to keep a GU
23f00 49 20 75 70 64 61 74 65 64 20 64 75 72 69 6e 67  I updated during
23f10 20 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a   a large query..
23f20 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d  **.** ^The param
23f30 65 74 65 72 20 50 20 69 73 20 70 61 73 73 65 64  eter P is passed
23f40 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20   through as the 
23f50 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74  only parameter t
23f60 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61  o the .** callba
23f70 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20  ck function X.  
23f80 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e  ^The parameter N
23f90 20 69 73 20 74 68 65 20 61 70 70 72 6f 78 69 6d   is the approxim
23fa0 61 74 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a  ate number of .*
23fb0 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61 63 68 69  * [virtual machi
23fc0 6e 65 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d  ne instructions]
23fd0 20 74 68 61 74 20 61 72 65 20 65 76 61 6c 75 61   that are evalua
23fe0 74 65 64 20 62 65 74 77 65 65 6e 20 73 75 63 63  ted between succ
23ff0 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61  essive.** invoca
24000 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 63 61 6c  tions of the cal
24010 6c 62 61 63 6b 20 58 2e 20 20 5e 49 66 20 4e 20  lback X.  ^If N 
24020 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65  is less than one
24030 20 74 68 65 6e 20 74 68 65 20 70 72 6f 67 72 65   then the progre
24040 73 73 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 69 73  ss.** handler is
24050 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a   disabled..**.**
24060 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20   ^Only a single 
24070 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
24080 20 6d 61 79 20 62 65 20 64 65 66 69 6e 65 64 20   may be defined 
24090 61 74 20 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a  at one time per.
240a0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
240b0 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e  nection]; settin
240c0 67 20 61 20 6e 65 77 20 70 72 6f 67 72 65 73 73  g a new progress
240d0 20 68 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73   handler cancels
240e0 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e   the.** old one.
240f0 20 20 5e 53 65 74 74 69 6e 67 20 70 61 72 61 6d    ^Setting param
24100 65 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64  eter X to NULL d
24110 69 73 61 62 6c 65 73 20 74 68 65 20 70 72 6f 67  isables the prog
24120 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  ress handler..**
24130 20 5e 54 68 65 20 70 72 6f 67 72 65 73 73 20 68   ^The progress h
24140 61 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f 20 64  andler is also d
24150 69 73 61 62 6c 65 64 20 62 79 20 73 65 74 74 69  isabled by setti
24160 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c 75 65 20  ng N to a value 
24170 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a  less.** than 1..
24180 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72  **.** ^If the pr
24190 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20  ogress callback 
241a0 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
241b0 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20  , the operation 
241c0 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65  is.** interrupte
241d0 64 2e 20 20 54 68 69 73 20 66 65 61 74 75 72 65  d.  This feature
241e0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
241f0 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22  implement a.** "
24200 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f  Cancel" button o
24210 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65 73 73  n a GUI progress
24220 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a   dialog box..**.
24230 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73 20  ** The progress 
24240 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b  handler callback
24250 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79   must not do any
24260 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20  thing that will 
24270 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61  modify.** the da
24280 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
24290 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
242a0 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
242b0 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ler..** Note tha
242c0 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  t [sqlite3_prepa
242d0 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
242e0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f  lite3_step()] bo
242f0 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a  th modify their.
24300 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
24310 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20  ections for the 
24320 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69  meaning of "modi
24330 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61  fy" in this para
24340 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69  graph..**.*/.voi
24350 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65  d sqlite3_progre
24360 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74  ss_handler(sqlit
24370 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29  e3*, int, int(*)
24380 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b  (void*), void*);
24390 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
243a0 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20  : Opening A New 
243b0 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
243c0 69 6f 6e 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54  ion.** CONSTRUCT
243d0 4f 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OR: sqlite3.**.*
243e0 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
243f0 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65  s open an SQLite
24400 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 61   database file a
24410 73 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  s specified by t
24420 68 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20  he .** filename 
24430 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66  argument. ^The f
24440 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
24450 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
24460 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20  as UTF-8 for.** 
24470 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
24480 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nd sqlite3_open_
24490 76 32 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d  v2() and as UTF-
244a0 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  16 in the native
244b0 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66   byte.** order f
244c0 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  or sqlite3_open1
244d0 36 28 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61  6(). ^(A [databa
244e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68  se connection] h
244f0 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79  andle is usually
24500 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20  .** returned in 
24510 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61  *ppDb, even if a
24520 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20  n error occurs. 
24530 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74   The only except
24540 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69  ion is that.** i
24550 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62  f SQLite is unab
24560 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  le to allocate m
24570 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
24580 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
24590 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69  ct,.** a NULL wi
245a0 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e  ll be written in
245b0 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64  to *ppDb instead
245c0 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   of a pointer to
245d0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a   the [sqlite3].*
245e0 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66  * object.)^ ^(If
245f0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
24600 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20   opened (and/or 
24610 63 72 65 61 74 65 64 29 20 73 75 63 63 65 73 73  created) success
24620 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b  fully, then.** [
24630 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65  SQLITE_OK] is re
24640 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69  turned.  Otherwi
24650 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  se an [error cod
24660 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29  e] is returned.)
24670 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ^ ^The.** [sqlit
24680 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20  e3_errmsg()] or 
24690 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  [sqlite3_errmsg1
246a0 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61  6()] routines ca
246b0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74  n be used to obt
246c0 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73  ain.** an Englis
246d0 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72  h language descr
246e0 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72  iption of the er
246f0 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  ror following a 
24700 66 61 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a  failure of any.*
24710 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  * of the sqlite3
24720 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73  _open() routines
24730 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66  ..**.** ^The def
24740 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 77 69  ault encoding wi
24750 6c 6c 20 62 65 20 55 54 46 2d 38 20 66 6f 72 20  ll be UTF-8 for 
24760 64 61 74 61 62 61 73 65 73 20 63 72 65 61 74 65  databases create
24770 64 20 75 73 69 6e 67 0a 2a 2a 20 73 71 6c 69 74  d using.** sqlit
24780 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c  e3_open() or sql
24790 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20  ite3_open_v2(). 
247a0 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e   ^The default en
247b0 63 6f 64 69 6e 67 20 66 6f 72 20 64 61 74 61 62  coding for datab
247c0 61 73 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20  ases.** created 
247d0 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70  using sqlite3_op
247e0 65 6e 31 36 28 29 20 77 69 6c 6c 20 62 65 20 55  en16() will be U
247f0 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74  TF-16 in the nat
24800 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
24810 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72  **.** Whether or
24820 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63   not an error oc
24830 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 20  curs when it is 
24840 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65  opened, resource
24850 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  s.** associated 
24860 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61  with the [databa
24870 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68  se connection] h
24880 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20  andle should be 
24890 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70  released by.** p
248a0 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71  assing it to [sq
248b0 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77  lite3_close()] w
248c0 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e  hen it is no lon
248d0 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a  ger required..**
248e0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
248f0 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66  open_v2() interf
24900 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73  ace works like s
24910 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a  qlite3_open().**
24920 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20   except that it 
24930 61 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 69  accepts two addi
24940 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72  tional parameter
24950 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  s for additional
24960 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72   control.** over
24970 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73   the new databas
24980 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e  e connection.  ^
24990 28 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d  (The flags param
249a0 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  eter to.** sqlit
249b0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e  e3_open_v2() can
249c0 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20   take one of.** 
249d0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  the following th
249e0 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69  ree values, opti
249f0 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20  onally combined 
24a00 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51  with the .** [SQ
24a10 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
24a20 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  X], [SQLITE_OPEN
24a30 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51  _FULLMUTEX], [SQ
24a40 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
24a50 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  CACHE],.** [SQLI
24a60 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
24a70 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53  ACHE], and/or [S
24a80 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20  QLITE_OPEN_URI] 
24a90 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c  flags:)^.**.** <
24aa0 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  dl>.** ^(<dt>[SQ
24ab0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
24ac0 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LY]</dt>.** <dd>
24ad0 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
24ae0 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f  opened in read-o
24af0 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68  nly mode.  If th
24b00 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20  e database does 
24b10 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65  not.** already e
24b20 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69  xist, an error i
24b30 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e  s returned.</dd>
24b40 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b  )^.**.** ^(<dt>[
24b50 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
24b60 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  WRITE]</dt>.** <
24b70 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
24b80 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
24b90 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e  ading and writin
24ba0 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f  g if possible, o
24bb0 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c  r reading.** onl
24bc0 79 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73  y if the file is
24bd0 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64   write protected
24be0 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e   by the operatin
24bf0 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69  g system.  In ei
24c00 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65  ther.** case the
24c10 20 64 61 74 61 62 61 73 65 20 6d 75 73 74 20 61   database must a
24c20 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74  lready exist, ot
24c30 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72  herwise an error
24c40 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64   is returned.</d
24c50 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74  d>)^.**.** ^(<dt
24c60 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  >[SQLITE_OPEN_RE
24c70 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49  ADWRITE] | [SQLI
24c80 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c  TE_OPEN_CREATE]<
24c90 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
24ca0 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
24cb0 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61  ed for reading a
24cc0 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20  nd writing, and 
24cd0 69 73 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a  is created if.**
24ce0 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72   it does not alr
24cf0 65 61 64 79 20 65 78 69 73 74 2e 20 54 68 69 73  eady exist. This
24d00 20 69 73 20 74 68 65 20 62 65 68 61 76 69 6f 72   is the behavior
24d10 20 74 68 61 74 20 69 73 20 61 6c 77 61 79 73 20   that is always 
24d20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69  used for.** sqli
24d30 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
24d40 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e  qlite3_open16().
24d50 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e  </dd>)^.** </dl>
24d60 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72  .**.** If the 3r
24d70 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
24d80 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
24d90 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74   is not one of t
24da0 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f  he.** combinatio
24db0 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f  ns shown above o
24dc0 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e  ptionally combin
24dd0 65 64 20 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a  ed with other.**
24de0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
24df0 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f  ADONLY | SQLITE_
24e00 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20  OPEN_* bits].** 
24e10 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
24e20 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
24e30 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53  **.** ^If the [S
24e40 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
24e50 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c  EX] flag is set,
24e60 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
24e70 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
24e80 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75   opens in the mu
24e90 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65  lti-thread [thre
24ea0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c  ading mode] as l
24eb0 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c  ong as the singl
24ec0 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65  e-thread.** mode
24ed0 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65   has not been se
24ee0 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  t at compile-tim
24ef0 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e  e or start-time.
24f00 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51    ^If the.** [SQ
24f10 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55  LITE_OPEN_FULLMU
24f20 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74  TEX] flag is set
24f30 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
24f40 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70  se connection op
24f50 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65  ens.** in the se
24f60 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64  rialized [thread
24f70 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73  ing mode] unless
24f80 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77   single-thread w
24f90 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  as.** previously
24fa0 20 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d   selected at com
24fb0 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61  pile-time or sta
24fc0 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65  rt-time..** ^The
24fd0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48   [SQLITE_OPEN_SH
24fe0 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20  AREDCACHE] flag 
24ff0 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62  causes the datab
25000 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
25010 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65  o be.** eligible
25020 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20   to use [shared 
25030 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67  cache mode], reg
25040 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
25050 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64  er or not shared
25060 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61  .** cache is ena
25070 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  bled using [sqli
25080 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65  te3_enable_share
25090 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68  d_cache()].  ^Th
250a0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  e.** [SQLITE_OPE
250b0 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 20  N_PRIVATECACHE] 
250c0 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20  flag causes the 
250d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
250e0 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61  ion to not.** pa
250f0 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68  rticipate in [sh
25100 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d  ared cache mode]
25110 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 65   even if it is e
25120 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  nabled..**.** ^T
25130 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
25140 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
25150 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20  pen_v2() is the 
25160 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  name of the.** [
25170 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
25180 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73  ect that defines
25190 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
251a0 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20  ystem interface 
251b0 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20  that.** the new 
251c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
251d0 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20  ion should use. 
251e0 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20   ^If the fourth 
251f0 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
25200 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
25210 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20  hen the default 
25220 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
25230 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a  ject is used..**
25240 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65  .** ^If the file
25250 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79  name is ":memory
25260 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61  :", then a priva
25270 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e  te, temporary in
25280 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
25290 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20 66  .** is created f
252a0 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  or the connectio
252b0 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d  n.  ^This in-mem
252c0 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 69 6c  ory database wil
252d0 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a  l vanish when.**
252e0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
252f0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73  nnection is clos
25300 65 64 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  ed.  Future vers
25310 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
25320 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65  ight.** make use
25330 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73   of additional s
25340 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73  pecial filenames
25350 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 68   that begin with
25360 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 74   the ":" charact
25370 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63  er..** It is rec
25380 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68  ommended that wh
25390 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69  en a database fi
253a0 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20  lename actually 
253b0 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a  does begin with.
253c0 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63 74  ** a ":" charact
253d0 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72  er you should pr
253e0 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d  efix the filenam
253f0 65 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d  e with a pathnam
25400 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f  e such as.** "./
25410 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67  " to avoid ambig
25420 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  uity..**.** ^If 
25430 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20  the filename is 
25440 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c  an empty string,
25450 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c   then a private,
25460 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e   temporary.** on
25470 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77  -disk database w
25480 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20  ill be created. 
25490 20 5e 54 68 69 73 20 70 72 69 76 61 74 65 20 64   ^This private d
254a0 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a  atabase will be.
254b0 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ** automatically
254c0 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e   deleted as soon
254d0 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73 65   as the database
254e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63   connection is c
254f0 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55  losed..**.** [[U
25500 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20  RI filenames in 
25510 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d  sqlite3_open()]]
25520 20 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d   <h3>URI Filenam
25530 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49  es</h3>.**.** ^I
25540 66 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d  f [URI filename]
25550 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20   interpretation 
25560 69 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20  is enabled, and 
25570 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  the filename arg
25580 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20  ument.** begins 
25590 77 69 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 68  with "file:", th
255a0 65 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  en the filename 
255b0 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
255c0 73 20 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a  s a URI. ^URI.**
255d0 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70   filename interp
255e0 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62  retation is enab
255f0 6c 65 64 20 69 66 20 74 68 65 20 5b 53 51 4c 49  led if the [SQLI
25600 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61  TE_OPEN_URI] fla
25610 67 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74  g is.** set in t
25620 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
25630 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  nt to sqlite3_op
25640 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66 20 69  en_v2(), or if i
25650 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e  t has.** been en
25660 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75  abled globally u
25670 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45  sing the [SQLITE
25680 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74  _CONFIG_URI] opt
25690 69 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  ion with the.** 
256a0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
256b0 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62 79 20  )] method or by 
256c0 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f  the [SQLITE_USE_
256d0 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  URI] compile-tim
256e0 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20  e option..** As 
256f0 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  of SQLite versio
25700 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c  n 3.7.7, URI fil
25710 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61  ename interpreta
25720 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f  tion is turned o
25730 66 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74  ff.** by default
25740 2c 20 62 75 74 20 66 75 74 75 72 65 20 72 65 6c  , but future rel
25750 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20  eases of SQLite 
25760 6d 69 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49  might enable URI
25770 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74   filename.** int
25780 65 72 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64  erpretation by d
25790 65 66 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55  efault.  See "[U
257a0 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66  RI filenames]" f
257b0 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  or additional.**
257c0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
257d0 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  .** URI filename
257e0 73 20 61 72 65 20 70 61 72 73 65 64 20 61 63 63  s are parsed acc
257f0 6f 72 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39  ording to RFC 39
25800 38 36 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20  86. ^If the URI 
25810 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61  contains an.** a
25820 75 74 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69  uthority, then i
25830 74 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72  t must be either
25840 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
25850 20 6f 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a   or the string .
25860 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20  ** "localhost". 
25870 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 74  ^If the authorit
25880 79 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74  y is not an empt
25890 79 20 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63  y string or "loc
258a0 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20  alhost", an .** 
258b0 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
258c0 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e  d to the caller.
258d0 20 5e 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63   ^The fragment c
258e0 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52  omponent of a UR
258f0 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e  I, if .** presen
25900 74 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a  t, is ignored..*
25910 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65  *.** ^SQLite use
25920 73 20 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f  s the path compo
25930 6e 65 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20  nent of the URI 
25940 61 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  as the name of t
25950 68 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20  he disk file.** 
25960 77 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74  which contains t
25970 68 65 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66  he database. ^If
25980 20 74 68 65 20 70 61 74 68 20 62 65 67 69 6e 73   the path begins
25990 20 77 69 74 68 20 61 20 27 2f 27 20 63 68 61 72   with a '/' char
259a0 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20  acter, .** then 
259b0 69 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  it is interprete
259c0 64 20 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65  d as an absolute
259d0 20 70 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70   path. ^If the p
259e0 61 74 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67  ath does not beg
259f0 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f  in .** with a '/
25a00 27 20 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20  ' (meaning that 
25a10 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 73 65  the authority se
25a20 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64  ction is omitted
25a30 20 66 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a   from the URI).*
25a40 2a 20 74 68 65 6e 20 74 68 65 20 70 61 74 68 20  * then the path 
25a50 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
25a60 73 20 61 20 72 65 6c 61 74 69 76 65 20 70 61 74  s a relative pat
25a70 68 2e 20 0a 2a 2a 20 5e 28 4f 6e 20 77 69 6e 64  h. .** ^(On wind
25a80 6f 77 73 2c 20 74 68 65 20 66 69 72 73 74 20 63  ows, the first c
25a90 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61  omponent of an a
25aa0 62 73 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a  bsolute path .**
25ab0 20 69 73 20 61 20 64 72 69 76 65 20 73 70 65 63   is a drive spec
25ac0 69 66 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20  ification (e.g. 
25ad0 22 43 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  "C:").)^.**.** [
25ae0 5b 63 6f 72 65 20 55 52 49 20 71 75 65 72 79 20  [core URI query 
25af0 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20  parameters]].** 
25b00 54 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e  The query compon
25b10 65 6e 74 20 6f 66 20 61 20 55 52 49 20 6d 61 79  ent of a URI may
25b20 20 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 74   contain paramet
25b30 65 72 73 20 74 68 61 74 20 61 72 65 20 69 6e 74  ers that are int
25b40 65 72 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 68  erpreted.** eith
25b50 65 72 20 62 79 20 53 51 4c 69 74 65 20 69 74 73  er by SQLite its
25b60 65 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 46  elf, or by a [VF
25b70 53 20 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 69  S | custom VFS i
25b80 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a  mplementation]..
25b90 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64 20 69 74  ** SQLite and it
25ba0 73 20 62 75 69 6c 74 2d 69 6e 20 5b 56 46 53 65  s built-in [VFSe
25bb0 73 5d 20 69 6e 74 65 72 70 72 65 74 20 74 68 65  s] interpret the
25bc0 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 71 75  .** following qu
25bd0 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 3a 0a  ery parameters:.
25be0 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20  **.** <ul>.**   
25bf0 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a  <li> <b>vfs</b>:
25c00 20 5e 54 68 65 20 22 76 66 73 22 20 70 61 72 61   ^The "vfs" para
25c10 6d 65 74 65 72 20 6d 61 79 20 62 65 20 75 73 65  meter may be use
25c20 64 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65  d to specify the
25c30 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20   name of.**     
25c40 61 20 56 46 53 20 6f 62 6a 65 63 74 20 74 68 61  a VFS object tha
25c50 74 20 70 72 6f 76 69 64 65 73 20 74 68 65 20 6f  t provides the o
25c60 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
25c70 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 73  interface that s
25c80 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20  hould.**     be 
25c90 75 73 65 64 20 74 6f 20 61 63 63 65 73 73 20 74  used to access t
25ca0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
25cb0 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74 68   on disk. ^If th
25cc0 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74  is option is set
25cd0 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d   to.**     an em
25ce0 70 74 79 20 73 74 72 69 6e 67 20 74 68 65 20 64  pty string the d
25cf0 65 66 61 75 6c 74 20 56 46 53 20 6f 62 6a 65 63  efault VFS objec
25d00 74 20 69 73 20 75 73 65 64 2e 20 5e 53 70 65 63  t is used. ^Spec
25d10 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77  ifying an unknow
25d20 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20 69 73 20  n.**     VFS is 
25d30 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20 73 71  an error. ^If sq
25d40 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
25d50 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20  is used and the 
25d60 76 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a  vfs option is.**
25d70 20 20 20 20 20 70 72 65 73 65 6e 74 2c 20 74 68       present, th
25d80 65 6e 20 74 68 65 20 56 46 53 20 73 70 65 63 69  en the VFS speci
25d90 66 69 65 64 20 62 79 20 74 68 65 20 6f 70 74 69  fied by the opti
25da0 6f 6e 20 74 61 6b 65 73 20 70 72 65 63 65 64 65  on takes precede
25db0 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20  nce over.**     
25dc0 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64  the value passed
25dd0 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 70   as the fourth p
25de0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
25df0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a  te3_open_v2()..*
25e00 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d  *.**   <li> <b>m
25e10 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d  ode</b>: ^(The m
25e20 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61  ode parameter ma
25e30 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68  y be set to eith
25e40 65 72 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a 2a  er "ro", "rw",.*
25e50 2a 20 20 20 20 20 22 72 77 63 22 2c 20 6f 72 20  *     "rwc", or 
25e60 22 6d 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d 70  "memory". Attemp
25e70 74 69 6e 67 20 74 6f 20 73 65 74 20 69 74 20 74  ting to set it t
25e80 6f 20 61 6e 79 20 6f 74 68 65 72 20 76 61 6c 75  o any other valu
25e90 65 20 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20 65  e is.**     an e
25ea0 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20  rror)^. .**     
25eb0 5e 49 66 20 22 72 6f 22 20 69 73 20 73 70 65 63  ^If "ro" is spec
25ec0 69 66 69 65 64 2c 20 74 68 65 6e 20 74 68 65 20  ified, then the 
25ed0 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
25ee0 65 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79  ed for read-only
25ef0 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c   .**     access,
25f00 20 6a 75 73 74 20 61 73 20 69 66 20 74 68 65 20   just as if the 
25f10 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
25f20 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64 20  DONLY] flag had 
25f30 62 65 65 6e 20 73 65 74 20 69 6e 20 74 68 65 20  been set in the 
25f40 0a 2a 2a 20 20 20 20 20 74 68 69 72 64 20 61 72  .**     third ar
25f50 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
25f60 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 49 66  3_open_v2(). ^If
25f70 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e   the mode option
25f80 20 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20   is set to .**  
25f90 20 20 20 22 72 77 22 2c 20 74 68 65 6e 20 74 68     "rw", then th
25fa0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
25fb0 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 77 72  ened for read-wr
25fc0 69 74 65 20 28 62 75 74 20 6e 6f 74 20 63 72 65  ite (but not cre
25fd0 61 74 65 29 20 0a 2a 2a 20 20 20 20 20 61 63 63  ate) .**     acc
25fe0 65 73 73 2c 20 61 73 20 69 66 20 53 51 4c 49 54  ess, as if SQLIT
25ff0 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
26000 20 28 62 75 74 20 6e 6f 74 20 53 51 4c 49 54 45   (but not SQLITE
26010 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29 20 68 61  _OPEN_CREATE) ha
26020 64 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20 73  d .**     been s
26030 65 74 2e 20 5e 56 61 6c 75 65 20 22 72 77 63 22  et. ^Value "rwc"
26040 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74   is equivalent t
26050 6f 20 73 65 74 74 69 6e 67 20 62 6f 74 68 20 0a  o setting both .
26060 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50  **     SQLITE_OP
26070 45 4e 5f 52 45 41 44 57 52 49 54 45 20 61 6e 64  EN_READWRITE and
26080 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
26090 41 54 45 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f  ATE.  ^If the mo
260a0 64 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20  de option is.** 
260b0 20 20 20 20 73 65 74 20 74 6f 20 22 6d 65 6d 6f      set to "memo
260c0 72 79 22 20 74 68 65 6e 20 61 20 70 75 72 65 20  ry" then a pure 
260d0 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62  [in-memory datab
260e0 61 73 65 5d 20 74 68 61 74 20 6e 65 76 65 72 20  ase] that never 
260f0 72 65 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72 20  reads.**     or 
26100 77 72 69 74 65 73 20 66 72 6f 6d 20 64 69 73 6b  writes from disk
26110 20 69 73 20 75 73 65 64 2e 20 5e 49 74 20 69 73   is used. ^It is
26120 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70 65   an error to spe
26130 63 69 66 79 20 61 20 76 61 6c 75 65 20 66 6f 72  cify a value for
26140 0a 2a 2a 20 20 20 20 20 74 68 65 20 6d 6f 64 65  .**     the mode
26150 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 20   parameter that 
26160 69 73 20 6c 65 73 73 20 72 65 73 74 72 69 63 74  is less restrict
26170 69 76 65 20 74 68 61 6e 20 74 68 61 74 20 73 70  ive than that sp
26180 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20  ecified by.**   
26190 20 20 74 68 65 20 66 6c 61 67 73 20 70 61 73 73    the flags pass
261a0 65 64 20 69 6e 20 74 68 65 20 74 68 69 72 64 20  ed in the third 
261b0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
261c0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a  ite3_open_v2()..
261d0 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e  **.**   <li> <b>
261e0 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20  cache</b>: ^The 
261f0 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20  cache parameter 
26200 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69  may be set to ei
26210 74 68 65 72 20 22 73 68 61 72 65 64 22 20 6f 72  ther "shared" or
26220 0a 2a 2a 20 20 20 20 20 22 70 72 69 76 61 74 65  .**     "private
26230 22 2e 20 5e 53 65 74 74 69 6e 67 20 69 74 20 74  ". ^Setting it t
26240 6f 20 22 73 68 61 72 65 64 22 20 69 73 20 65 71  o "shared" is eq
26250 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74  uivalent to sett
26260 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 53  ing the.**     S
26270 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
26280 44 43 41 43 48 45 20 62 69 74 20 69 6e 20 74 68  DCACHE bit in th
26290 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
262a0 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20   passed to.**   
262b0 20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76    sqlite3_open_v
262c0 32 28 29 2e 20 5e 53 65 74 74 69 6e 67 20 74 68  2(). ^Setting th
262d0 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65  e cache paramete
262e0 72 20 74 6f 20 22 70 72 69 76 61 74 65 22 20 69  r to "private" i
262f0 73 20 0a 2a 2a 20 20 20 20 20 65 71 75 69 76 61  s .**     equiva
26300 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20  lent to setting 
26310 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  the SQLITE_OPEN_
26320 50 52 49 56 41 54 45 43 41 43 48 45 20 62 69 74  PRIVATECACHE bit
26330 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73 71 6c  ..**     ^If sql
26340 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
26350 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 22  s used and the "
26360 63 61 63 68 65 22 20 70 61 72 61 6d 65 74 65 72  cache" parameter
26370 20 69 73 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a   is present in.*
26380 2a 20 20 20 20 20 61 20 55 52 49 20 66 69 6c 65  *     a URI file
26390 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c 75 65 20  name, its value 
263a0 6f 76 65 72 72 69 64 65 73 20 61 6e 79 20 62 65  overrides any be
263b0 68 61 76 69 6f 72 20 72 65 71 75 65 73 74 65 64  havior requested
263c0 20 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20   by setting.**  
263d0 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50     SQLITE_OPEN_P
263e0 52 49 56 41 54 45 43 41 43 48 45 20 6f 72 20 53  RIVATECACHE or S
263f0 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
26400 44 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 0a  DCACHE flag..**.
26410 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 70 73 6f 77  **  <li> <b>psow
26420 3c 2f 62 3e 3a 20 5e 54 68 65 20 70 73 6f 77 20  </b>: ^The psow 
26430 70 61 72 61 6d 65 74 65 72 20 69 6e 64 69 63 61  parameter indica
26440 74 65 73 20 77 68 65 74 68 65 72 20 6f 72 20 6e  tes whether or n
26450 6f 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 5b 70  ot the.**     [p
26460 6f 77 65 72 73 61 66 65 20 6f 76 65 72 77 72 69  owersafe overwri
26470 74 65 5d 20 70 72 6f 70 65 72 74 79 20 64 6f 65  te] property doe
26480 73 20 6f 72 20 64 6f 65 73 20 6e 6f 74 20 61 70  s or does not ap
26490 70 6c 79 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20  ply to the.**   
264a0 20 20 73 74 6f 72 61 67 65 20 6d 65 64 69 61 20    storage media 
264b0 6f 6e 20 77 68 69 63 68 20 74 68 65 20 64 61 74  on which the dat
264c0 61 62 61 73 65 20 66 69 6c 65 20 72 65 73 69 64  abase file resid
264d0 65 73 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20  es..**.**  <li> 
264e0 3c 62 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e  <b>nolock</b>: ^
264f0 54 68 65 20 6e 6f 6c 6f 63 6b 20 70 61 72 61 6d  The nolock param
26500 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 61  eter is a boolea
26510 6e 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  n query paramete
26520 72 0a 2a 2a 20 20 20 20 20 77 68 69 63 68 20 69  r.**     which i
26530 66 20 73 65 74 20 64 69 73 61 62 6c 65 73 20 66  f set disables f
26540 69 6c 65 20 6c 6f 63 6b 69 6e 67 20 69 6e 20 72  ile locking in r
26550 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 20  ollback journal 
26560 6d 6f 64 65 73 2e 20 20 54 68 69 73 0a 2a 2a 20  modes.  This.** 
26570 20 20 20 20 69 73 20 75 73 65 66 75 6c 20 66 6f      is useful fo
26580 72 20 61 63 63 65 73 73 69 6e 67 20 61 20 64 61  r accessing a da
26590 74 61 62 61 73 65 20 6f 6e 20 61 20 66 69 6c 65  tabase on a file
265a0 73 79 73 74 65 6d 20 74 68 61 74 20 64 6f 65 73  system that does
265b0 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 73 75 70 70   not.**     supp
265c0 6f 72 74 20 6c 6f 63 6b 69 6e 67 2e 20 20 43 61  ort locking.  Ca
265d0 75 74 69 6f 6e 3a 20 20 44 61 74 61 62 61 73 65  ution:  Database
265e0 20 63 6f 72 72 75 70 74 69 6f 6e 20 6d 69 67 68   corruption migh
265f0 74 20 72 65 73 75 6c 74 20 69 66 20 74 77 6f 0a  t result if two.
26600 2a 2a 20 20 20 20 20 6f 72 20 6d 6f 72 65 20 70  **     or more p
26610 72 6f 63 65 73 73 65 73 20 77 72 69 74 65 20 74  rocesses write t
26620 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  o the same datab
26630 61 73 65 20 61 6e 64 20 61 6e 79 20 6f 6e 65 20  ase and any one 
26640 6f 66 20 74 68 6f 73 65 0a 2a 2a 20 20 20 20 20  of those.**     
26650 70 72 6f 63 65 73 73 65 73 20 75 73 65 73 20 6e  processes uses n
26660 6f 6c 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20  olock=1..**.**  
26670 3c 6c 69 3e 20 3c 62 3e 69 6d 6d 75 74 61 62 6c  <li> <b>immutabl
26680 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 69 6d 6d 75  e</b>: ^The immu
26690 74 61 62 6c 65 20 70 61 72 61 6d 65 74 65 72 20  table parameter 
266a0 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65  is a boolean que
266b0 72 79 0a 2a 2a 20 20 20 20 20 70 61 72 61 6d 65  ry.**     parame
266c0 74 65 72 20 74 68 61 74 20 69 6e 64 69 63 61 74  ter that indicat
266d0 65 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61  es that the data
266e0 62 61 73 65 20 66 69 6c 65 20 69 73 20 73 74 6f  base file is sto
266f0 72 65 64 20 6f 6e 0a 2a 2a 20 20 20 20 20 72 65  red on.**     re
26700 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 2e 20 20  ad-only media.  
26710 5e 57 68 65 6e 20 69 6d 6d 75 74 61 62 6c 65 20  ^When immutable 
26720 69 73 20 73 65 74 2c 20 53 51 4c 69 74 65 20 61  is set, SQLite a
26730 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a  ssumes that the.
26740 2a 2a 20 20 20 20 20 64 61 74 61 62 61 73 65 20  **     database 
26750 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 63  file cannot be c
26760 68 61 6e 67 65 64 2c 20 65 76 65 6e 20 62 79 20  hanged, even by 
26770 61 20 70 72 6f 63 65 73 73 20 77 69 74 68 20 68  a process with h
26780 69 67 68 65 72 0a 2a 2a 20 20 20 20 20 70 72 69  igher.**     pri
26790 76 69 6c 65 67 65 2c 20 61 6e 64 20 73 6f 20 74  vilege, and so t
267a0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
267b0 70 65 6e 65 64 20 72 65 61 64 2d 6f 6e 6c 79 20  pened read-only 
267c0 61 6e 64 20 61 6c 6c 20 6c 6f 63 6b 69 6e 67 0a  and all locking.
267d0 2a 2a 20 20 20 20 20 61 6e 64 20 63 68 61 6e 67  **     and chang
267e0 65 20 64 65 74 65 63 74 69 6f 6e 20 69 73 20 64  e detection is d
267f0 69 73 61 62 6c 65 64 2e 20 20 43 61 75 74 69 6f  isabled.  Cautio
26800 6e 3a 20 53 65 74 74 69 6e 67 20 74 68 65 20 69  n: Setting the i
26810 6d 6d 75 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20  mmutable.**     
26820 70 72 6f 70 65 72 74 79 20 6f 6e 20 61 20 64 61  property on a da
26830 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 61 74  tabase file that
26840 20 64 6f 65 73 20 69 6e 20 66 61 63 74 20 63 68   does in fact ch
26850 61 6e 67 65 20 63 61 6e 20 72 65 73 75 6c 74 0a  ange can result.
26860 2a 2a 20 20 20 20 20 69 6e 20 69 6e 63 6f 72 72  **     in incorr
26870 65 63 74 20 71 75 65 72 79 20 72 65 73 75 6c 74  ect query result
26880 73 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45  s and/or [SQLITE
26890 5f 43 4f 52 52 55 50 54 5d 20 65 72 72 6f 72 73  _CORRUPT] errors
268a0 2e 0a 2a 2a 20 20 20 20 20 53 65 65 20 61 6c 73  ..**     See als
268b0 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  o: [SQLITE_IOCAP
268c0 5f 49 4d 4d 55 54 41 42 4c 45 5d 2e 0a 2a 2a 20  _IMMUTABLE]..** 
268d0 20 20 20 20 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a        .** </ul>.
268e0 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e  **.** ^Specifyin
268f0 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72  g an unknown par
26900 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20 71 75  ameter in the qu
26910 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  ery component of
26920 20 61 20 55 52 49 20 69 73 20 6e 6f 74 20 61 6e   a URI is not an
26930 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75 74 75  .** error.  Futu
26940 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
26950 51 4c 69 74 65 20 6d 69 67 68 74 20 75 6e 64 65  QLite might unde
26960 72 73 74 61 6e 64 20 61 64 64 69 74 69 6f 6e 61  rstand additiona
26970 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d  l query.** param
26980 65 74 65 72 73 2e 20 20 53 65 65 20 22 5b 71 75  eters.  See "[qu
26990 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 20 77  ery parameters w
269a0 69 74 68 20 73 70 65 63 69 61 6c 20 6d 65 61 6e  ith special mean
269b0 69 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d 22 20  ing to SQLite]" 
269c0 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61  for.** additiona
269d0 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
269e0 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e  *.** [[URI filen
269f0 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c  ame examples]] <
26a00 68 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65 20  h3>URI filename 
26a10 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a  examples</h3>.**
26a20 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65  .** <table borde
26a30 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74  r="1" align=cent
26a40 65 72 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35  er cellpadding=5
26a50 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52  >.** <tr><th> UR
26a60 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e  I filenames <th>
26a70 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e   Results.** <tr>
26a80 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64  <td> file:data.d
26a90 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  b <td> .**      
26aa0 20 20 20 20 4f 70 65 6e 20 74 68 65 20 66 69 6c      Open the fil
26ab0 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74  e "data.db" in t
26ac0 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63  he current direc
26ad0 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  tory..** <tr><td
26ae0 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65  > file:/home/fre
26af0 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a  d/data.db<br>.**
26b00 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f            file:/
26b10 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  //home/fred/data
26b20 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20  .db <br> .**    
26b30 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63        file://loc
26b40 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64  alhost/home/fred
26b50 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74  /data.db <br> <t
26b60 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
26b70 4f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  Open the databas
26b80 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72  e file "/home/fr
26b90 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20  ed/data.db"..** 
26ba0 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f  <tr><td> file://
26bb0 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72  darkstar/home/fr
26bc0 65 64 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e 20  ed/data.db <td> 
26bd0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20  .**          An 
26be0 65 72 72 6f 72 2e 20 22 64 61 72 6b 73 74 61 72  error. "darkstar
26bf0 22 20 69 73 20 6e 6f 74 20 61 20 72 65 63 6f 67  " is not a recog
26c00 6e 69 7a 65 64 20 61 75 74 68 6f 72 69 74 79 2e  nized authority.
26c10 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c  .** <tr><td styl
26c20 65 3d 22 77 68 69 74 65 2d 73 70 61 63 65 3a 6e  e="white-space:n
26c30 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20  owrap"> .**     
26c40 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f       file:///C:/
26c50 44 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e 64 25  Documents%20and%
26c60 32 30 53 65 74 74 69 6e 67 73 2f 66 72 65 64 2f  20Settings/fred/
26c70 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a  Desktop/data.db.
26c80 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57 69 6e 64  **     <td> Wind
26c90 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74  ows only: Open t
26ca0 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62  he file "data.db
26cb0 22 20 6f 6e 20 66 72 65 64 27 73 20 64 65 73 6b  " on fred's desk
26cc0 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20  top on drive.** 
26cd0 20 20 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74           C:. Not
26ce0 65 20 74 68 61 74 20 74 68 65 20 25 32 30 20 65  e that the %20 e
26cf0 73 63 61 70 69 6e 67 20 69 6e 20 74 68 69 73 20  scaping in this 
26d00 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73  example is not s
26d10 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20  trictly .**     
26d20 20 20 20 20 20 6e 65 63 65 73 73 61 72 79 20 2d       necessary -
26d30 20 73 70 61 63 65 20 63 68 61 72 61 63 74 65 72   space character
26d40 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 6c 69  s can be used li
26d50 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20  terally.**      
26d60 20 20 20 20 69 6e 20 55 52 49 20 66 69 6c 65 6e      in URI filen
26d70 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  ames..** <tr><td
26d80 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d  > file:data.db?m
26d90 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d 70 72 69  ode=ro&cache=pri
26da0 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  vate <td> .**   
26db0 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65         Open file
26dc0 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68   "data.db" in th
26dd0 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74  e current direct
26de0 6f 72 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c  ory for read-onl
26df0 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20  y access..**    
26e00 20 20 20 20 20 20 52 65 67 61 72 64 6c 65 73 73        Regardless
26e10 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
26e20 6f 74 20 73 68 61 72 65 64 2d 63 61 63 68 65 20  ot shared-cache 
26e30 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20  mode is enabled 
26e40 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64  by.**          d
26e50 65 66 61 75 6c 74 2c 20 75 73 65 20 61 20 70 72  efault, use a pr
26e60 69 76 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20  ivate cache..** 
26e70 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68  <tr><td> file:/h
26e80 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
26e90 3f 76 66 73 3d 75 6e 69 78 2d 64 6f 74 66 69 6c  ?vfs=unix-dotfil
26ea0 65 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20  e <td>.**       
26eb0 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68     Open file "/h
26ec0 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
26ed0 22 2e 20 55 73 65 20 74 68 65 20 73 70 65 63 69  ". Use the speci
26ee0 61 6c 20 56 46 53 20 22 75 6e 69 78 2d 64 6f 74  al VFS "unix-dot
26ef0 66 69 6c 65 22 0a 2a 2a 20 20 20 20 20 20 20 20  file".**        
26f00 20 20 74 68 61 74 20 75 73 65 73 20 64 6f 74 2d    that uses dot-
26f10 66 69 6c 65 73 20 69 6e 20 70 6c 61 63 65 20 6f  files in place o
26f20 66 20 70 6f 73 69 78 20 61 64 76 69 73 6f 72 79  f posix advisory
26f30 20 6c 6f 63 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 72   locking..** <tr
26f40 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e  ><td> file:data.
26f50 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79  db?mode=readonly
26f60 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
26f70 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 72 65     An error. "re
26f80 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61  adonly" is not a
26f90 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f   valid option fo
26fa0 72 20 74 68 65 20 22 6d 6f 64 65 22 20 70 61 72  r the "mode" par
26fb0 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62  ameter..** </tab
26fc0 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68  le>.**.** ^URI h
26fd0 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70  exadecimal escap
26fe0 65 20 73 65 71 75 65 6e 63 65 73 20 28 25 48 48  e sequences (%HH
26ff0 29 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20  ) are supported 
27000 77 69 74 68 69 6e 20 74 68 65 20 70 61 74 68 20  within the path 
27010 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d  and.** query com
27020 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55 52 49  ponents of a URI
27030 2e 20 41 20 68 65 78 61 64 65 63 69 6d 61 6c 20  . A hexadecimal 
27040 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 20  escape sequence 
27050 63 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a  consists of a.**
27060 20 70 65 72 63 65 6e 74 20 73 69 67 6e 20 2d 20   percent sign - 
27070 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62  "%" - followed b
27080 79 20 65 78 61 63 74 6c 79 20 74 77 6f 20 68 65  y exactly two he
27090 78 61 64 65 63 69 6d 61 6c 20 64 69 67 69 74 73  xadecimal digits
270a0 20 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e 67 20   .** specifying 
270b0 61 6e 20 6f 63 74 65 74 20 76 61 6c 75 65 2e 20  an octet value. 
270c0 5e 42 65 66 6f 72 65 20 74 68 65 20 70 61 74 68  ^Before the path
270d0 20 6f 72 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e   or query compon
270e0 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49  ents of a.** URI
270f0 20 66 69 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e   filename are in
27100 74 65 72 70 72 65 74 65 64 2c 20 74 68 65 79 20  terpreted, they 
27110 61 72 65 20 65 6e 63 6f 64 65 64 20 75 73 69 6e  are encoded usin
27120 67 20 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20  g UTF-8 and all 
27130 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d 61 6c 20  .** hexadecimal 
27140 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73  escape sequences
27150 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 73   replaced by a s
27160 69 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e 74 61  ingle byte conta
27170 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72  ining the.** cor
27180 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74  responding octet
27190 2e 20 49 66 20 74 68 69 73 20 70 72 6f 63 65 73  . If this proces
271a0 73 20 67 65 6e 65 72 61 74 65 73 20 61 6e 20 69  s generates an i
271b0 6e 76 61 6c 69 64 20 55 54 46 2d 38 20 65 6e 63  nvalid UTF-8 enc
271c0 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65  oding,.** the re
271d0 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
271e0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f  ned..**.** <b>No
271f0 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73  te to Windows us
27200 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e  ers:</b>  The en
27210 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20  coding used for 
27220 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  the filename arg
27230 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69  ument.** of sqli
27240 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
27250 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
27260 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20   must be UTF-8, 
27270 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20  not whatever.** 
27280 63 6f 64 65 70 61 67 65 20 69 73 20 63 75 72 72  codepage is curr
27290 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20  ently defined.  
272a0 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69  Filenames contai
272b0 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e  ning internation
272c0 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73  al.** characters
272d0 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
272e0 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f  ed to UTF-8 prio
272f0 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65  r to passing the
27300 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  m into.** sqlite
27310 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69  3_open() or sqli
27320 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a  te3_open_v2()..*
27330 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20  *.** <b>Note to 
27340 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 20  Windows Runtime 
27350 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20  users:</b>  The 
27360 74 65 6d 70 6f 72 61 72 79 20 64 69 72 65 63 74  temporary direct
27370 6f 72 79 20 6d 75 73 74 20 62 65 20 73 65 74 0a  ory must be set.
27380 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c  ** prior to call
27390 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ing sqlite3_open
273a0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  () or sqlite3_op
273b0 65 6e 5f 76 32 28 29 2e 20 20 4f 74 68 65 72 77  en_v2().  Otherw
273c0 69 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20  ise, various.** 
273d0 66 65 61 74 75 72 65 73 20 74 68 61 74 20 72 65  features that re
273e0 71 75 69 72 65 20 74 68 65 20 75 73 65 20 6f 66  quire the use of
273f0 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73   temporary files
27400 20 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a   may fail..**.**
27410 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
27420 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f  te3_temp_directo
27430 72 79 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ry].*/.int sqlit
27440 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74  e3_open(.  const
27450 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c   char *filename,
27460 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
27470 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20  ilename (UTF-8) 
27480 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
27490 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb          /* 
274a0 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
274b0 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20  andle */.);.int 
274c0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a  sqlite3_open16(.
274d0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69    const void *fi
274e0 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
274f0 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
27500 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c  UTF-16) */.  sql
27510 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20  ite3 **ppDb     
27520 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
27530 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
27540 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
27550 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74  open_v2(.  const
27560 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c   char *filename,
27570 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
27580 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20  ilename (UTF-8) 
27590 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
275a0 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb,         /* 
275b0 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
275c0 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66  andle */.  int f
275d0 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20 20  lags,           
275e0 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20     /* Flags */. 
275f0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66   const char *zVf
27600 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65  s        /* Name
27610 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74   of VFS module t
27620 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  o use */.);../*.
27630 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74  ** CAPI3REF: Obt
27640 61 69 6e 20 56 61 6c 75 65 73 20 46 6f 72 20 55  ain Values For U
27650 52 49 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a  RI Parameters.**
27660 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 75 74  .** These are ut
27670 69 6c 69 74 79 20 72 6f 75 74 69 6e 65 73 2c 20  ility routines, 
27680 75 73 65 66 75 6c 20 74 6f 20 56 46 53 20 69 6d  useful to VFS im
27690 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74  plementations, t
276a0 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f 20  hat check.** to 
276b0 73 65 65 20 69 66 20 61 20 64 61 74 61 62 61 73  see if a databas
276c0 65 20 66 69 6c 65 20 77 61 73 20 61 20 55 52 49  e file was a URI
276d0 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 65 64 20   that contained 
276e0 61 20 73 70 65 63 69 66 69 63 20 71 75 65 72 79  a specific query
276f0 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20   .** parameter, 
27700 61 6e 64 20 69 66 20 73 6f 20 6f 62 74 61 69 6e  and if so obtain
27710 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
27720 68 61 74 20 71 75 65 72 79 20 70 61 72 61 6d 65  hat query parame
27730 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20  ter..**.** If F 
27740 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  is the database 
27750 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72  filename pointer
27760 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65   passed into the
27770 20 78 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64 20   xOpen() method 
27780 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d 70  of .** a VFS imp
27790 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e  lementation when
277a0 20 74 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d   the flags param
277b0 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 28 29 20  eter to xOpen() 
277c0 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d  has one or .** m
277d0 6f 72 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  ore of the [SQLI
277e0 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 20  TE_OPEN_URI] or 
277f0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49  [SQLITE_OPEN_MAI
27800 4e 5f 44 42 5d 20 62 69 74 73 20 73 65 74 20 61  N_DB] bits set a
27810 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68 65 20 6e  nd.** P is the n
27820 61 6d 65 20 6f 66 20 74 68 65 20 71 75 65 72 79  ame of the query
27830 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e   parameter, then
27840 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  .** sqlite3_uri_
27850 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72  parameter(F,P) r
27860 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65  eturns the value
27870 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20 70 61 72   of the P.** par
27880 61 6d 65 74 65 72 20 69 66 20 69 74 20 65 78 69  ameter if it exi
27890 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f  sts or a NULL po
278a0 69 6e 74 65 72 20 69 66 20 50 20 64 6f 65 73 20  inter if P does 
278b0 6e 6f 74 20 61 70 70 65 61 72 20 61 73 20 61 20  not appear as a 
278c0 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65  .** query parame
278d0 74 65 72 20 6f 6e 20 46 2e 20 20 49 66 20 50 20  ter on F.  If P 
278e0 69 73 20 61 20 71 75 65 72 79 20 70 61 72 61 6d  is a query param
278f0 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61 73  eter of F.** has
27900 20 6e 6f 20 65 78 70 6c 69 63 69 74 20 76 61 6c   no explicit val
27910 75 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ue, then sqlite3
27920 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46  _uri_parameter(F
27930 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  ,P) returns.** a
27940 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 65   pointer to an e
27950 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  mpty string..**.
27960 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75  ** The sqlite3_u
27970 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
27980 29 20 72 6f 75 74 69 6e 65 20 61 73 73 75 6d 65  ) routine assume
27990 73 20 74 68 61 74 20 50 20 69 73 20 61 20 62 6f  s that P is a bo
279a0 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 74  olean.** paramet
279b0 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74  er and returns t
279c0 72 75 65 20 28 31 29 20 6f 72 20 66 61 6c 73 65  rue (1) or false
279d0 20 28 30 29 20 61 63 63 6f 72 64 69 6e 67 20 74   (0) according t
279e0 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 6f  o the value.** o
279f0 66 20 50 2e 20 20 54 68 65 20 73 71 6c 69 74 65  f P.  The sqlite
27a00 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c  3_uri_boolean(F,
27a10 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 72 65 74  P,B) routine ret
27a20 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 69 66  urns true (1) if
27a30 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66   the.** value of
27a40 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
27a50 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 79 65   P is one of "ye
27a60 73 22 2c 20 22 74 72 75 65 22 2c 20 6f 72 20 22  s", "true", or "
27a70 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 61  on" in any.** ca
27a80 73 65 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c  se or if the val
27a90 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 61  ue begins with a
27aa0 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 72   non-zero number
27ab0 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69 74  .  The .** sqlit
27ac0 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
27ad0 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 73 20 72  ,P,B) routines r
27ae0 65 74 75 72 6e 73 20 66 61 6c 73 65 20 28 30 29  eturns false (0)
27af0 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66   if the value of
27b00 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65  .** query parame
27b10 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20  ter P is one of 
27b20 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20 6f  "no", "false", o
27b30 72 20 22 6f 66 66 22 20 69 6e 20 61 6e 79 20 63  r "off" in any c
27b40 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68 65  ase or.** if the
27b50 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69   value begins wi
27b60 74 68 20 61 20 6e 75 6d 65 72 69 63 20 7a 65 72  th a numeric zer
27b70 6f 2e 20 20 49 66 20 50 20 69 73 20 6e 6f 74 20  o.  If P is not 
27b80 61 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d  a query.** param
27b90 65 74 65 72 20 6f 6e 20 46 20 6f 72 20 69 66 20  eter on F or if 
27ba0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69  the value of P i
27bb0 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68  s does not match
27bc0 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20 61   any of the.** a
27bd0 62 6f 76 65 2c 20 74 68 65 6e 20 73 71 6c 69 74  bove, then sqlit
27be0 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
27bf0 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 28 42  ,P,B) returns (B
27c00 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  !=0)..**.** The 
27c10 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36  sqlite3_uri_int6
27c20 34 28 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e 65  4(F,P,D) routine
27c30 20 63 6f 6e 76 65 72 74 73 20 74 68 65 20 76 61   converts the va
27c40 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f 20 61 0a  lue of P into a.
27c50 2a 2a 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  ** 64-bit signed
27c60 20 69 6e 74 65 67 65 72 20 61 6e 64 20 72 65 74   integer and ret
27c70 75 72 6e 73 20 74 68 61 74 20 69 6e 74 65 67 65  urns that intege
27c80 72 2c 20 6f 72 20 44 20 69 66 20 50 20 64 6f 65  r, or D if P doe
27c90 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e 20  s not.** exist. 
27ca0 20 49 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66   If the value of
27cb0 20 50 20 69 73 20 73 6f 6d 65 74 68 69 6e 67 20   P is something 
27cc0 6f 74 68 65 72 20 74 68 61 6e 20 61 6e 20 69 6e  other than an in
27cd0 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a  teger, then.** z
27ce0 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ero is returned.
27cf0 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73 20  .** .** If F is 
27d00 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
27d10 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69  then sqlite3_uri
27d20 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20  _parameter(F,P) 
27d30 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64  returns NULL and
27d40 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  .** sqlite3_uri_
27d50 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
27d60 65 74 75 72 6e 73 20 42 2e 20 20 49 66 20 46 20  eturns B.  If F 
27d70 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 6f  is not a NULL po
27d80 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73 20  inter and.** is 
27d90 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66  not a database f
27da0 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 70 6f 69  ile pathname poi
27db0 6e 74 65 72 20 74 68 61 74 20 53 51 4c 69 74 65  nter that SQLite
27dc0 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65   passed into the
27dd0 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d 65   xOpen.** VFS me
27de0 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 65 20 62  thod, then the b
27df0 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69 73 20  ehavior of this 
27e00 72 6f 75 74 69 6e 65 20 69 73 20 75 6e 64 65 66  routine is undef
27e10 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c  ined and probabl
27e20 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65  y.** undesirable
27e30 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
27e40 2a 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72  *sqlite3_uri_par
27e50 61 6d 65 74 65 72 28 63 6f 6e 73 74 20 63 68 61  ameter(const cha
27e60 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 6f  r *zFilename, co
27e70 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d  nst char *zParam
27e80 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 75  );.int sqlite3_u
27e90 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74  ri_boolean(const
27ea0 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63 6f   char *zFile, co
27eb0 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d  nst char *zParam
27ec0 2c 20 69 6e 74 20 62 44 65 66 61 75 6c 74 29 3b  , int bDefault);
27ed0 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
27ee0 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34  qlite3_uri_int64
27ef0 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63 6f  (const char*, co
27f00 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74  nst char*, sqlit
27f10 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a  e3_int64);.../*.
27f20 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72 72  ** CAPI3REF: Err
27f30 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73  or Codes And Mes
27f40 73 61 67 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  sages.** METHOD:
27f50 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
27f60 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
27f70 6e 74 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49  nt sqlite3_* API
27f80 20 63 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 64   call associated
27f90 20 77 69 74 68 20 0a 2a 2a 20 5b 64 61 74 61 62   with .** [datab
27fa0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
27fb0 44 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 20 74  D failed, then t
27fc0 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  he sqlite3_errco
27fd0 64 65 28 44 29 20 69 6e 74 65 72 66 61 63 65 0a  de(D) interface.
27fe0 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ** returns the n
27ff0 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63  umeric [result c
28000 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65  ode] or [extende
28010 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66  d result code] f
28020 6f 72 20 74 68 61 74 0a 2a 2a 20 41 50 49 20 63  or that.** API c
28030 61 6c 6c 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6d  all..** If the m
28040 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49 20 63  ost recent API c
28050 61 6c 6c 20 77 61 73 20 73 75 63 63 65 73 73 66  all was successf
28060 75 6c 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  ul,.** then the 
28070 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f  return value fro
28080 6d 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  m sqlite3_errcod
28090 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64  e() is undefined
280a0 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
280b0 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f  3_extended_errco
280c0 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  de().** interfac
280d0 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 65 78  e is the same ex
280e0 63 65 70 74 20 74 68 61 74 20 69 74 20 61 6c 77  cept that it alw
280f0 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 65 20  ays returns the 
28100 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
28110 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20  sult code] even 
28120 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65  when extended re
28130 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a  sult codes are.*
28140 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  * disabled..**.*
28150 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
28160 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69  rrmsg() and sqli
28170 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72  te3_errmsg16() r
28180 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61  eturn English-la
28190 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74  nguage.** text t
281a0 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68  hat describes th
281b0 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68  e error, as eith
281c0 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d  er UTF-8 or UTF-
281d0 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  16 respectively.
281e0 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20  .** ^(Memory to 
281f0 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d  hold the error m
28200 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73  essage string is
28210 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61   managed interna
28220 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  lly..** The appl
28230 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74  ication does not
28240 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61   need to worry a
28250 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68 65  bout freeing the
28260 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65   result..** Howe
28270 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73  ver, the error s
28280 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f  tring might be o
28290 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65  verwritten or de
282a0 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20  allocated by.** 
282b0 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
282c0 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65   to other SQLite
282d0 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74   interface funct
282e0 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  ions.)^.**.** ^T
282f0 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 73 74  he sqlite3_errst
28300 72 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  r() interface re
28310 74 75 72 6e 73 20 74 68 65 20 45 6e 67 6c 69 73  turns the Englis
28320 68 2d 6c 61 6e 67 75 61 67 65 20 74 65 78 74 0a  h-language text.
28330 2a 2a 20 74 68 61 74 20 64 65 73 63 72 69 62 65  ** that describe
28340 73 20 74 68 65 20 5b 72 65 73 75 6c 74 20 63 6f  s the [result co
28350 64 65 5d 2c 20 61 73 20 55 54 46 2d 38 2e 0a 2a  de], as UTF-8..*
28360 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f  * ^(Memory to ho
28370 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  ld the error mes
28380 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d  sage string is m
28390 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c  anaged internall
283a0 79 0a 2a 2a 20 61 6e 64 20 6d 75 73 74 20 6e 6f  y.** and must no
283b0 74 20 62 65 20 66 72 65 65 64 20 62 79 20 74 68  t be freed by th
283c0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 5e 2e  e application)^.
283d0 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
283e0 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65  serialized [thre
283f0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69  ading mode] is i
28400 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68 74 20  n use, it might 
28410 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 74  be the.** case t
28420 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65 72 72  hat a second err
28430 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 73  or occurs on a s
28440 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 69  eparate thread i
28450 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65  n between.** the
28460 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66 69 72   time of the fir
28470 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74 68 65  st error and the
28480 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 69   call to these i
28490 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68  nterfaces..** Wh
284a0 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e 73 2c  en that happens,
284b0 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72 72 6f   the second erro
284c0 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 74  r will be report
284d0 65 64 20 73 69 6e 63 65 20 74 68 65 73 65 0a 2a  ed since these.*
284e0 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 6c 77  * interfaces alw
284f0 61 79 73 20 72 65 70 6f 72 74 20 74 68 65 20 6d  ays report the m
28500 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73 75 6c  ost recent resul
28510 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20  t.  To avoid.** 
28520 74 68 69 73 2c 20 65 61 63 68 20 74 68 72 65 61  this, each threa
28530 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 63  d can obtain exc
28540 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20 74 68  lusive use of th
28550 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
28560 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20  ection] D.** by 
28570 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65  invoking [sqlite
28580 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b  3_mutex_enter]([
28590 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78  sqlite3_db_mutex
285a0 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62 65 67  ](D)) before beg
285b0 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65  inning.** to use
285c0 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20   D and invoking 
285d0 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c  [sqlite3_mutex_l
285e0 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64  eave]([sqlite3_d
285f0 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 66 74  b_mutex](D)) aft
28600 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20  er.** all calls 
28610 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  to the interface
28620 73 20 6c 69 73 74 65 64 20 68 65 72 65 20 61 72  s listed here ar
28630 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a  e completed..**.
28640 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61  ** If an interfa
28650 63 65 20 66 61 69 6c 73 20 77 69 74 68 20 53 51  ce fails with SQ
28660 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61  LITE_MISUSE, tha
28670 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65  t means the inte
28680 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76  rface.** was inv
28690 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79  oked incorrectly
286a0 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
286b0 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61  ion.  In that ca
286c0 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72  se, the.** error
286d0 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67   code and messag
286e0 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74  e may or may not
286f0 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20   be set..*/.int 
28700 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
28710 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 69 6e  sqlite3 *db);.in
28720 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  t sqlite3_extend
28730 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74  ed_errcode(sqlit
28740 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63  e3 *db);.const c
28750 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72  har *sqlite3_err
28760 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63  msg(sqlite3*);.c
28770 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
28780 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69  e3_errmsg16(sqli
28790 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 63 68 61  te3*);.const cha
287a0 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 73 74  r *sqlite3_errst
287b0 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  r(int);../*.** C
287c0 41 50 49 33 52 45 46 3a 20 50 72 65 70 61 72 65  API3REF: Prepare
287d0 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  d Statement Obje
287e0 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ct.** KEYWORDS: 
287f0 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  {prepared statem
28800 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73  ent} {prepared s
28810 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a  tatements}.**.**
28820 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
28830 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72  this object repr
28840 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20  esents a single 
28850 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68  SQL statement th
28860 61 74 0a 2a 2a 20 68 61 73 20 62 65 65 6e 20 63  at.** has been c
28870 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 62 69 6e  ompiled into bin
28880 61 72 79 20 66 6f 72 6d 20 61 6e 64 20 69 73 20  ary form and is 
28890 72 65 61 64 79 20 74 6f 20 62 65 20 65 76 61 6c  ready to be eval
288a0 75 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  uated..**.** Thi
288b0 6e 6b 20 6f 66 20 65 61 63 68 20 53 51 4c 20 73  nk of each SQL s
288c0 74 61 74 65 6d 65 6e 74 20 61 73 20 61 20 73 65  tatement as a se
288d0 70 61 72 61 74 65 20 63 6f 6d 70 75 74 65 72 20  parate computer 
288e0 70 72 6f 67 72 61 6d 2e 20 20 54 68 65 0a 2a 2a  program.  The.**
288f0 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65   original SQL te
28900 78 74 20 69 73 20 73 6f 75 72 63 65 20 63 6f 64  xt is source cod
28910 65 2e 20 20 41 20 70 72 65 70 61 72 65 64 20 73  e.  A prepared s
28920 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20  tatement object 
28930 0a 2a 2a 20 69 73 20 74 68 65 20 63 6f 6d 70 69  .** is the compi
28940 6c 65 64 20 6f 62 6a 65 63 74 20 63 6f 64 65 2e  led object code.
28950 20 20 41 6c 6c 20 53 51 4c 20 6d 75 73 74 20 62    All SQL must b
28960 65 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f  e converted into
28970 20 61 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73   a.** prepared s
28980 74 61 74 65 6d 65 6e 74 20 62 65 66 6f 72 65 20  tatement before 
28990 69 74 20 63 61 6e 20 62 65 20 72 75 6e 2e 0a 2a  it can be run..*
289a0 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 2d 63 79  *.** The life-cy
289b0 63 6c 65 20 6f 66 20 61 20 70 72 65 70 61 72 65  cle of a prepare
289c0 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65  d statement obje
289d0 63 74 20 75 73 75 61 6c 6c 79 20 67 6f 65 73 20  ct usually goes 
289e0 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a  like this:.**.**
289f0 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72   <ol>.** <li> Cr
28a00 65 61 74 65 20 74 68 65 20 70 72 65 70 61 72 65  eate the prepare
28a10 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65  d statement obje
28a20 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ct using [sqlite
28a30 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2e  3_prepare_v2()].
28a40 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61  .** <li> Bind va
28a50 6c 75 65 73 20 74 6f 20 5b 70 61 72 61 6d 65 74  lues to [paramet
28a60 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73  ers] using the s
28a70 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a  qlite3_bind_*().
28a80 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61 63  **      interfac
28a90 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20  es..** <li> Run 
28aa0 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69  the SQL by calli
28ab0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
28ac0 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  ()] one or more 
28ad0 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52  times..** <li> R
28ae0 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65  eset the prepare
28af0 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  d statement usin
28b00 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
28b10 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b  ()] then go back
28b20 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70  .**      to step
28b30 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72   2.  Do this zer
28b40 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e  o or more times.
28b50 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79  .** <li> Destroy
28b60 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e   the object usin
28b70 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
28b80 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e  ize()]..** </ol>
28b90 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
28ba0 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ct sqlite3_stmt 
28bb0 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f  sqlite3_stmt;../
28bc0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
28bd0 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a  un-time Limits.*
28be0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
28bf0 33 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69  3.**.** ^(This i
28c00 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 20  nterface allows 
28c10 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72 69  the size of vari
28c20 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20 74  ous constructs t
28c30 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20  o be limited.** 
28c40 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  on a connection 
28c50 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61  by connection ba
28c60 73 69 73 2e 20 20 54 68 65 20 66 69 72 73 74 20  sis.  The first 
28c70 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
28c80 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
28c90 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20  nnection] whose 
28ca0 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20 73  limit is to be s
28cb0 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20 20  et or queried.  
28cc0 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61  The.** second pa
28cd0 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6f  rameter is one o
28ce0 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 74  f the [limit cat
28cf0 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64 65  egories] that de
28d00 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20  fine a.** class 
28d10 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f  of constructs to
28d20 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 64   be size limited
28d30 2e 20 20 54 68 65 20 74 68 69 72 64 20 70 61 72  .  The third par
28d40 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
28d50 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 74   new limit for t
28d60 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e  hat construct.)^
28d70 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e  .**.** ^If the n
28d80 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65  ew limit is a ne
28d90 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74  gative number, t
28da0 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68  he limit is unch
28db0 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20  anged..** ^(For 
28dc0 65 61 63 68 20 6c 69 6d 69 74 20 63 61 74 65 67  each limit categ
28dd0 6f 72 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ory SQLITE_LIMIT
28de0 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65  _<i>NAME</i> the
28df0 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d  re is a .** [lim
28e00 69 74 73 20 7c 20 68 61 72 64 20 75 70 70 65 72  its | hard upper
28e10 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61   bound].** set a
28e20 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62  t compile-time b
28e30 79 20 61 20 43 20 70 72 65 70 72 6f 63 65 73 73  y a C preprocess
28e40 6f 72 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a  or macro called.
28e50 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c  ** [limits | SQL
28e60 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c  ITE_MAX_<i>NAME<
28e70 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f  /i>]..** (The "_
28e80 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 6e  LIMIT_" in the n
28e90 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20 74  ame is changed t
28ea0 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a  o "_MAX_".))^.**
28eb0 20 5e 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e   ^Attempts to in
28ec0 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61  crease a limit a
28ed0 62 6f 76 65 20 69 74 73 20 68 61 72 64 20 75 70  bove its hard up
28ee0 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a  per bound are.**
28ef0 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61   silently trunca
28f00 74 65 64 20 74 6f 20 74 68 65 20 68 61 72 64 20  ted to the hard 
28f10 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a  upper bound..**.
28f20 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20 6f  ** ^Regardless o
28f30 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
28f40 20 74 68 65 20 6c 69 6d 69 74 20 77 61 73 20 63   the limit was c
28f50 68 61 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20  hanged, the .** 
28f60 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
28f70 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
28f80 72 6e 73 20 74 68 65 20 70 72 69 6f 72 20 76 61  rns the prior va
28f90 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69 74  lue of the limit
28fa0 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20  ..** ^Hence, to 
28fb0 66 69 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74  find the current
28fc0 20 76 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69   value of a limi
28fd0 74 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 69  t without changi
28fe0 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79  ng it,.** simply
28ff0 20 69 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e 74   invoke this int
29000 65 72 66 61 63 65 20 77 69 74 68 20 74 68 65 20  erface with the 
29010 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
29020 73 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a  set to -1..**.**
29030 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73   Run-time limits
29040 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f   are intended fo
29050 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61  r use in applica
29060 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67  tions that manag
29070 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20  e.** both their 
29080 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  own internal dat
29090 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64  abase and also d
290a0 61 74 61 62 61 73 65 73 20 74 68 61 74 20 61 72  atabases that ar
290b0 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20  e controlled.** 
290c0 62 79 20 75 6e 74 72 75 73 74 65 64 20 65 78 74  by untrusted ext
290d0 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20  ernal sources.  
290e0 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69  An example appli
290f0 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20  cation might be 
29100 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65 72  a.** web browser
29110 20 74 68 61 74 20 68 61 73 20 69 74 73 20 6f 77   that has its ow
29120 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f 72 20  n databases for 
29130 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20  storing history 
29140 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20  and.** separate 
29150 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f  databases contro
29160 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72 69  lled by JavaScri
29170 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  pt applications 
29180 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66  downloaded.** of
29190 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20  f the Internet. 
291a0 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61   The internal da
291b0 74 61 62 61 73 65 73 20 63 61 6e 20 62 65 20 67  tabases can be g
291c0 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67  iven the.** larg
291d0 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74  e, default limit
291e0 73 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d 61  s.  Databases ma
291f0 6e 61 67 65 64 20 62 79 20 65 78 74 65 72 6e 61  naged by externa
29200 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a  l sources can.**
29210 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73   be given much s
29220 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65  maller limits de
29230 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e  signed to preven
29240 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65  t a denial of se
29250 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e  rvice.** attack.
29260 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67    Developers mig
29270 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20  ht also want to 
29280 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  use the [sqlite3
29290 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
292a0 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  )].** interface 
292b0 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72  to further contr
292c0 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c  ol untrusted SQL
292d0 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74  .  The size of t
292e0 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  he database.** c
292f0 72 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74  reated by an unt
29300 72 75 73 74 65 64 20 73 63 72 69 70 74 20 63 61  rusted script ca
29310 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75  n be contained u
29320 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78  sing the.** [max
29330 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52  _page_count] [PR
29340 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  AGMA]..**.** New
29350 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20   run-time limit 
29360 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62  categories may b
29370 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
29380 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69  e releases..*/.i
29390 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  nt sqlite3_limit
293a0 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69  (sqlite3*, int i
293b0 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a  d, int newVal);.
293c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
293d0 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20   Run-Time Limit 
293e0 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45  Categories.** KE
293f0 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63  YWORDS: {limit c
29400 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74  ategory} {*limit
29410 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a   categories}.**.
29420 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
29430 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75  ts define variou
29440 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69  s performance li
29450 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e  mits.** that can
29460 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72   be lowered at r
29470 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73  un-time using [s
29480 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e  qlite3_limit()].
29490 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73  .** The synopsis
294a0 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73   of the meanings
294b0 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73 20   of the various 
294c0 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20  limits is shown 
294d0 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69  below..** Additi
294e0 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
294f0 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74   is available at
29500 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74   [limits | Limit
29510 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a  s in SQLite]..**
29520 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51  .** <dl>.** [[SQ
29530 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
29540 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
29550 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64  _LIMIT_LENGTH</d
29560 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
29570 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e  ximum size of an
29580 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  y string or BLOB
29590 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c 20 69   or table row, i
295a0 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a  n bytes.<dd>)^.*
295b0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
295c0 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d  MIT_SQL_LENGTH]]
295d0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
295e0 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f  MIT_SQL_LENGTH</
295f0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
29600 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
29610 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
29620 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64  t, in bytes.</dd
29630 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
29640 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d  TE_LIMIT_COLUMN]
29650 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
29660 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e  IMIT_COLUMN</dt>
29670 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
29680 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  mum number of co
29690 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65  lumns in a table
296a0 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69   definition or i
296b0 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  n the.** result 
296c0 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54  set of a [SELECT
296d0 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d  ] or the maximum
296e0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
296f0 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a  ns in an index.*
29700 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52  * or in an ORDER
29710 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20   BY or GROUP BY 
29720 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a  clause.</dd>)^.*
29730 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
29740 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d  MIT_EXPR_DEPTH]]
29750 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
29760 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f  MIT_EXPR_DEPTH</
29770 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
29780 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20  aximum depth of 
29790 74 68 65 20 70 61 72 73 65 20 74 72 65 65 20 6f  the parse tree o
297a0 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e  n any expression
297b0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
297c0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  [SQLITE_LIMIT_CO
297d0 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20  MPOUND_SELECT]] 
297e0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
297f0 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
29800 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  CT</dt>.** <dd>T
29810 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
29820 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20  r of terms in a 
29830 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20  compound SELECT 
29840 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29  statement.</dd>)
29850 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
29860 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d  _LIMIT_VDBE_OP]]
29870 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
29880 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e  MIT_VDBE_OP</dt>
29890 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
298a0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e  mum number of in
298b0 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20  structions in a 
298c0 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
298d0 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20  program.** used 
298e0 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20  to implement an 
298f0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  SQL statement.  
29900 49 66 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  If [sqlite3_prep
29910 61 72 65 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20  are_v2()] or.** 
29920 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20 74  the equivalent t
29930 72 69 65 73 20 74 6f 20 61 6c 6c 6f 63 61 74 65  ries to allocate
29940 20 73 70 61 63 65 20 66 6f 72 20 6d 6f 72 65 20   space for more 
29950 74 68 61 6e 20 74 68 69 73 20 6d 61 6e 79 20 6f  than this many o
29960 70 63 6f 64 65 73 0a 2a 2a 20 69 6e 20 61 20 73  pcodes.** in a s
29970 69 6e 67 6c 65 20 70 72 65 70 61 72 65 64 20 73  ingle prepared s
29980 74 61 74 65 6d 65 6e 74 2c 20 61 6e 20 53 51 4c  tatement, an SQL
29990 49 54 45 5f 4e 4f 4d 45 4d 20 65 72 72 6f 72 20  ITE_NOMEM error 
299a0 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64  is returned.</dd
299b0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
299c0 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
299d0 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 51  N_ARG]] ^(<dt>SQ
299e0 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
299f0 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20  ION_ARG</dt>.** 
29a00 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
29a10 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
29a20 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f  nts on a functio
29a30 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  n.</dd>)^.**.** 
29a40 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  [[SQLITE_LIMIT_A
29a50 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74 3e  TTACHED]] ^(<dt>
29a60 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54  SQLITE_LIMIT_ATT
29a70 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ACHED</dt>.** <d
29a80 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
29a90 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20  mber of [ATTACH 
29aa0 7c 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  | attached datab
29ab0 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a  ases].)^</dd>.**
29ac0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
29ad0 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
29ae0 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64  LENGTH]].** ^(<d
29af0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  t>SQLITE_LIMIT_L
29b00 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
29b10 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
29b20 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
29b30 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e  h of the pattern
29b40 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
29b50 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47   [LIKE] or.** [G
29b60 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c  LOB] operators.<
29b70 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
29b80 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
29b90 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a  ABLE_NUMBER]].**
29ba0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
29bb0 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
29bc0 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  BER</dt>.** <dd>
29bd0 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65  The maximum inde
29be0 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79 20  x number of any 
29bf0 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61  [parameter] in a
29c00 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  n SQL statement.
29c10 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
29c20 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f  E_LIMIT_TRIGGER_
29c30 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  DEPTH]] ^(<dt>SQ
29c40 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47  LITE_LIMIT_TRIGG
29c50 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a  ER_DEPTH</dt>.**
29c60 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
29c70 20 64 65 70 74 68 20 6f 66 20 72 65 63 75 72 73   depth of recurs
29c80 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73  ion for triggers
29c90 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
29ca0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f  [SQLITE_LIMIT_WO
29cb0 52 4b 45 52 5f 54 48 52 45 41 44 53 5d 5d 20 5e  RKER_THREADS]] ^
29cc0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
29cd0 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53  T_WORKER_THREADS
29ce0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
29cf0 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
29d00 6f 66 20 61 75 78 69 6c 69 61 72 79 20 77 6f 72  of auxiliary wor
29d10 6b 65 72 20 74 68 72 65 61 64 73 20 74 68 61 74  ker threads that
29d20 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 70 72   a single.** [pr
29d30 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
29d40 5d 20 6d 61 79 20 73 74 61 72 74 2e 3c 2f 64 64  ] may start.</dd
29d50 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  >)^.** </dl>.*/.
29d60 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
29d70 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 20  IMIT_LENGTH     
29d80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
29d90 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
29da0 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48  LIMIT_SQL_LENGTH
29db0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
29dc0 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
29dd0 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20  _LIMIT_COLUMN   
29de0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
29df0 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
29e00 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
29e10 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
29e20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
29e30 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e  TE_LIMIT_COMPOUN
29e40 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20  D_SELECT        
29e50 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
29e60 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f  ITE_LIMIT_VDBE_O
29e70 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  P               
29e80 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51      5.#define SQ
29e90 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
29ea0 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20 20  ION_ARG         
29eb0 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53       6.#define S
29ec0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41  QLITE_LIMIT_ATTA
29ed0 43 48 45 44 20 20 20 20 20 20 20 20 20 20 20 20  CHED            
29ee0 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20        7.#define 
29ef0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b  SQLITE_LIMIT_LIK
29f00 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48  E_PATTERN_LENGTH
29f10 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65         8.#define
29f20 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41   SQLITE_LIMIT_VA
29f30 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20  RIABLE_NUMBER   
29f40 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e          9.#defin
29f50 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54  e SQLITE_LIMIT_T
29f60 52 49 47 47 45 52 5f 44 45 50 54 48 20 20 20 20  RIGGER_DEPTH    
29f70 20 20 20 20 20 20 20 20 31 30 0a 23 64 65 66 69          10.#defi
29f80 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
29f90 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 20 20  WORKER_THREADS  
29fa0 20 20 20 20 20 20 20 20 20 31 31 0a 0a 0a 2f 2a           11.../*
29fb0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
29fc0 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53  mpiling An SQL S
29fd0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57  tatement.** KEYW
29fe0 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65  ORDS: {SQL state
29ff0 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a  ment compiler}.*
2a000 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2a010 33 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52  3.** CONSTRUCTOR
2a020 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2a030 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20  *.** To execute 
2a040 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74  an SQL query, it
2a050 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20 63   must first be c
2a060 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62  ompiled into a b
2a070 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67  yte-code.** prog
2a080 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66  ram using one of
2a090 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
2a0a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
2a0b0 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c   argument, "db",
2a0c0 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 20   is a [database 
2a0d0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61  connection] obta
2a0e0 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70  ined from a.** p
2a0f0 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20  rior successful 
2a100 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2a110 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
2a120 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72  e3_open_v2()] or
2a130 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
2a140 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74  n16()].  The dat
2a150 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2a160 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62   must not have b
2a170 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a  een closed..**.*
2a180 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67  * The second arg
2a190 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69  ument, "zSql", i
2a1a0 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  s the statement 
2a1b0 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20  to be compiled, 
2a1c0 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69  encoded.** as ei
2a1d0 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54  ther UTF-8 or UT
2a1e0 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74  F-16.  The sqlit
2a1f0 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64  e3_prepare() and
2a200 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2a210 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  _v2().** interfa
2a220 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61  ces use UTF-8, a
2a230 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
2a240 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74  re16() and sqlit
2a250 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2a260 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e  ).** use UTF-16.
2a270 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e  .**.** ^If the n
2a280 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73  Byte argument is
2a290 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
2a2a0 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 70 20  zSql is read up 
2a2b0 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20  to the.** first 
2a2c0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
2a2d0 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 70 6f   ^If nByte is po
2a2e0 73 69 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20  sitive, then it 
2a2f0 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
2a300 20 6f 66 20 62 79 74 65 73 20 72 65 61 64 20 66   of bytes read f
2a310 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 49 66 20 6e  rom zSql.  ^If n
2a320 42 79 74 65 20 69 73 20 7a 65 72 6f 2c 20 74 68  Byte is zero, th
2a330 65 6e 20 6e 6f 20 70 72 65 70 61 72 65 64 0a 2a  en no prepared.*
2a340 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 67  * statement is g
2a350 65 6e 65 72 61 74 65 64 2e 0a 2a 2a 20 49 66 20  enerated..** If 
2a360 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73  the caller knows
2a370 20 74 68 61 74 20 74 68 65 20 73 75 70 70 6c 69   that the suppli
2a380 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c  ed string is nul
2a390 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65  -terminated, the
2a3a0 6e 0a 2a 2a 20 74 68 65 72 65 20 69 73 20 61 20  n.** there is a 
2a3b0 73 6d 61 6c 6c 20 70 65 72 66 6f 72 6d 61 6e 63  small performanc
2a3c0 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20 70  e advantage to p
2a3d0 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20  assing an nByte 
2a3e0 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a  parameter that.*
2a3f0 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  * is the number 
2a400 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
2a410 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e  input string <i>
2a420 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a  including</i>.**
2a430 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61   the nul-termina
2a440 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70  tor..**.** ^If p
2a450 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c  zTail is not NUL
2a460 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69  L then *pzTail i
2a470 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20  s made to point 
2a480 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79 74  to the first byt
2a490 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65 6e  e.** past the en
2a4a0 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 53  d of the first S
2a4b0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  QL statement in 
2a4c0 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75  zSql.  These rou
2a4d0 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f  tines only.** co
2a4e0 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 74 20  mpile the first 
2a4f0 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71  statement in zSq
2a500 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73  l, so *pzTail is
2a510 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74   left pointing t
2a520 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 6e  o.** what remain
2a530 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a  s uncompiled..**
2a540 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73 20  .** ^*ppStmt is 
2a550 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f  left pointing to
2a560 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65   a compiled [pre
2a570 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2a580 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20   that can be.** 
2a590 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b  executed using [
2a5a0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
2a5b0 20 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 61    ^If there is a
2a5c0 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74  n error, *ppStmt
2a5d0 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55   is set.** to NU
2a5e0 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e 70  LL.  ^If the inp
2a5f0 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73  ut text contains
2a600 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20   no SQL (if the 
2a610 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74  input is an empt
2a620 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61  y.** string or a
2a630 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a   comment) then *
2a640 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f  ppStmt is set to
2a650 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61   NULL..** The ca
2a660 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20  lling procedure 
2a670 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
2a680 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20  or deleting the 
2a690 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20  compiled.** SQL 
2a6a0 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20  statement using 
2a6b0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2a6c0 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 61  e()] after it ha
2a6d0 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
2a6e0 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61  it..** ppStmt ma
2a6f0 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a  y not be NULL..*
2a700 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73  *.** ^On success
2a710 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70 72  , the sqlite3_pr
2a720 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20 6f  epare() family o
2a730 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  f routines retur
2a740 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a  n [SQLITE_OK];.*
2a750 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b  * otherwise an [
2a760 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
2a770 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  eturned..**.** T
2a780 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
2a790 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69  re_v2() and sqli
2a7a0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
2a7b0 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  () interfaces ar
2a7c0 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e.** recommended
2a7d0 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f   for all new pro
2a7e0 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f  grams. The two o
2a7f0 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73 20  lder interfaces 
2a800 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20  are retained.** 
2a810 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f  for backwards co
2a820 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74  mpatibility, but
2a830 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64 69   their use is di
2a840 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49  scouraged..** ^I
2a850 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  n the "v2" inter
2a860 66 61 63 65 73 2c 20 74 68 65 20 70 72 65 70 61  faces, the prepa
2a870 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  red statement.**
2a880 20 74 68 61 74 20 69 73 20 72 65 74 75 72 6e 65   that is returne
2a890 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  d (the [sqlite3_
2a8a0 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f  stmt] object) co
2a8b0 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66  ntains a copy of
2a8c0 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c   the.** original
2a8d0 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20   SQL text. This 
2a8e0 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69  causes the [sqli
2a8f0 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65  te3_step()] inte
2a900 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61  rface to.** beha
2a910 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69  ve differently i
2a920 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a  n three ways:.**
2a930 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ol>.** <li>
2a940 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61  .** ^If the data
2a950 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e  base schema chan
2a960 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20  ges, instead of 
2a970 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54  returning [SQLIT
2a980 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a  E_SCHEMA] as it.
2a990 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20 74  ** always used t
2a9a0 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73  o do, [sqlite3_s
2a9b0 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f  tep()] will auto
2a9c0 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70  matically recomp
2a9d0 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73  ile the SQL.** s
2a9e0 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79  tatement and try
2a9f0 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e   to run it again
2aa00 2e 20 41 73 20 6d 61 6e 79 20 61 73 20 5b 53 51  . As many as [SQ
2aa10 4c 49 54 45 5f 4d 41 58 5f 53 43 48 45 4d 41 5f  LITE_MAX_SCHEMA_
2aa20 52 45 54 52 59 5d 0a 2a 2a 20 72 65 74 72 69 65  RETRY].** retrie
2aa30 73 20 77 69 6c 6c 20 6f 63 63 75 72 20 62 65 66  s will occur bef
2aa40 6f 72 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70  ore sqlite3_step
2aa50 28 29 20 67 69 76 65 73 20 75 70 20 61 6e 64 20  () gives up and 
2aa60 72 65 74 75 72 6e 73 20 61 6e 20 65 72 72 6f 72  returns an error
2aa70 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a  ..** </li>.**.**
2aa80 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61   <li>.** ^When a
2aa90 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20  n error occurs, 
2aaa0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2aab0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65   will return one
2aac0 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65 64   of the detailed
2aad0 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  .** [error codes
2aae0 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65  ] or [extended e
2aaf0 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54  rror codes].  ^T
2ab00 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69  he legacy behavi
2ab10 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b  or was that.** [
2ab20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2ab30 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72  would only retur
2ab40 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c  n a generic [SQL
2ab50 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c  ITE_ERROR] resul
2ab60 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68  t code.** and th
2ab70 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f  e application wo
2ab80 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65  uld have to make
2ab90 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74   a second call t
2aba0 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  o [sqlite3_reset
2abb0 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20  ()].** in order 
2abc0 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65  to find the unde
2abd0 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20  rlying cause of 
2abe0 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74  the problem. Wit
2abf0 68 20 74 68 65 20 22 76 32 22 20 70 72 65 70 61  h the "v2" prepa
2ac00 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  re.** interfaces
2ac10 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  , the underlying
2ac20 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20   reason for the 
2ac30 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
2ac40 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a  d immediately..*
2ac50 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c  * </li>.**.** <l
2ac60 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70  i>.** ^If the sp
2ac70 65 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f 75  ecific value bou
2ac80 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72  nd to [parameter
2ac90 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65   | host paramete
2aca0 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48  r] in the .** WH
2acb0 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68 74  ERE clause might
2acc0 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 63   influence the c
2acd0 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70  hoice of query p
2ace0 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65 6d  lan for a statem
2acf0 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ent,.** then the
2ad00 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20   statement will 
2ad10 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  be automatically
2ad20 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20   recompiled, as 
2ad30 69 66 20 74 68 65 72 65 20 68 61 64 20 62 65 65  if there had bee
2ad40 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20 63  n .** a schema c
2ad50 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66 69  hange, on the fi
2ad60 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73 74  rst  [sqlite3_st
2ad70 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f  ep()] call follo
2ad80 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 0a  wing any change.
2ad90 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  ** to the [sqlit
2ada0 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 62  e3_bind_text | b
2adb0 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61 74  indings] of that
2adc0 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a   [parameter]. .*
2add0 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69 63 20  * ^The specific 
2ade0 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d 63  value of WHERE-c
2adf0 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65 72  lause [parameter
2ae00 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63  ] might influenc
2ae10 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65  e the .** choice
2ae20 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 69   of query plan i
2ae30 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
2ae40 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e 64  is the left-hand
2ae50 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45   side of a [LIKE
2ae60 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f  ].** or [GLOB] o
2ae70 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74 68  perator or if th
2ae80 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 63  e parameter is c
2ae90 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69 6e  ompared to an in
2aea0 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  dexed column.** 
2aeb0 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  and the [SQLITE_
2aec0 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20 63 6f  ENABLE_STAT3] co
2aed0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
2aee0 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  n is enabled..**
2aef0 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a   </li>.** </ol>.
2af00 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  */.int sqlite3_p
2af10 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65  repare(.  sqlite
2af20 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
2af30 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
2af40 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2af50 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
2af60 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
2af70 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  nt, UTF-8 encode
2af80 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
2af90 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
2afa0 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
2afb0 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
2afc0 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
2afd0 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
2afe0 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
2aff0 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
2b000 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69  nst char **pzTai
2b010 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
2b020 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
2b030 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
2b040 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
2b050 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20  3_prepare_v2(.  
2b060 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
2b070 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
2b080 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
2b090 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
2b0a0 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
2b0b0 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20  tatement, UTF-8 
2b0c0 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
2b0d0 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
2b0e0 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
2b0f0 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
2b100 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
2b110 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
2b120 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
2b130 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
2b140 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
2b150 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
2b160 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
2b170 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
2b180 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20   zSql */.);.int 
2b190 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2b1a0 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  6(.  sqlite3 *db
2b1b0 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
2b1c0 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
2b1d0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
2b1e0 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
2b1f0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
2b200 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f  TF-16 encoded */
2b210 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
2b220 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
2b230 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
2b240 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
2b250 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
2b260 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
2b270 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
2b280 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2b290 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20  void **pzTail   
2b2a0 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
2b2b0 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
2b2c0 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
2b2d0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  ;.int sqlite3_pr
2b2e0 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71  epare16_v2(.  sq
2b2f0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
2b300 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
2b310 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
2b320 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
2b330 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
2b340 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
2b350 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
2b360 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
2b370 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
2b380 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
2b390 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
2b3a0 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
2b3b0 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
2b3c0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
2b3d0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
2b3e0 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
2b3f0 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
2b400 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
2b410 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  zSql */.);../*.*
2b420 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 72  * CAPI3REF: Retr
2b430 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74  ieving Statement
2b440 20 53 51 4c 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20   SQL.** METHOD: 
2b450 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2b460 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2b470 73 71 6c 28 50 29 20 69 6e 74 65 72 66 61 63 65  sql(P) interface
2b480 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
2b490 65 72 20 74 6f 20 61 20 63 6f 70 79 20 6f 66 20  er to a copy of 
2b4a0 74 68 65 20 55 54 46 2d 38 0a 2a 2a 20 53 51 4c  the UTF-8.** SQL
2b4b0 20 74 65 78 74 20 75 73 65 64 20 74 6f 20 63 72   text used to cr
2b4c0 65 61 74 65 20 5b 70 72 65 70 61 72 65 64 20 73  eate [prepared s
2b4d0 74 61 74 65 6d 65 6e 74 5d 20 50 20 69 66 20 50  tatement] P if P
2b4e0 20 77 61 73 0a 2a 2a 20 63 72 65 61 74 65 64 20   was.** created 
2b4f0 62 79 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74  by either [sqlit
2b500 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2b510 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
2b520 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a  pare16_v2()]..**
2b530 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
2b540 70 61 6e 64 65 64 5f 73 71 6c 28 50 29 20 69 6e  panded_sql(P) in
2b550 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2b560 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 55  a pointer to a U
2b570 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 63  TF-8.** string c
2b580 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 53 51  ontaining the SQ
2b590 4c 20 74 65 78 74 20 6f 66 20 70 72 65 70 61 72  L text of prepar
2b5a0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20 77  ed statement P w
2b5b0 69 74 68 0a 2a 2a 20 5b 62 6f 75 6e 64 20 70 61  ith.** [bound pa
2b5c0 72 61 6d 65 74 65 72 73 5d 20 65 78 70 61 6e 64  rameters] expand
2b5d0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20  ed..**.** ^(For 
2b5e0 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 20 70 72  example, if a pr
2b5f0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2b600 20 69 73 20 63 72 65 61 74 65 64 20 75 73 69 6e   is created usin
2b610 67 20 74 68 65 20 53 51 4c 0a 2a 2a 20 74 65 78  g the SQL.** tex
2b620 74 20 22 53 45 4c 45 43 54 20 24 61 62 63 2c 3a  t "SELECT $abc,:
2b630 78 79 7a 22 20 61 6e 64 20 69 66 20 70 61 72 61  xyz" and if para
2b640 6d 65 74 65 72 20 24 61 62 63 20 69 73 20 62 6f  meter $abc is bo
2b650 75 6e 64 20 74 6f 20 69 6e 74 65 67 65 72 20 32  und to integer 2
2b660 33 34 35 0a 2a 2a 20 61 6e 64 20 70 61 72 61 6d  345.** and param
2b670 65 74 65 72 20 3a 78 79 7a 20 69 73 20 75 6e 62  eter :xyz is unb
2b680 6f 75 6e 64 2c 20 74 68 65 6e 20 73 71 6c 69 74  ound, then sqlit
2b690 65 33 5f 73 71 6c 28 29 20 77 69 6c 6c 20 72 65  e3_sql() will re
2b6a0 74 75 72 6e 0a 2a 2a 20 74 68 65 20 6f 72 69 67  turn.** the orig
2b6b0 69 6e 61 6c 20 73 74 72 69 6e 67 2c 20 22 53 45  inal string, "SE
2b6c0 4c 45 43 54 20 24 61 62 63 2c 3a 78 79 7a 22 20  LECT $abc,:xyz" 
2b6d0 62 75 74 20 73 71 6c 69 74 65 33 5f 65 78 70 61  but sqlite3_expa
2b6e0 6e 64 65 64 5f 73 71 6c 28 29 0a 2a 2a 20 77 69  nded_sql().** wi
2b6f0 6c 6c 20 72 65 74 75 72 6e 20 22 53 45 4c 45 43  ll return "SELEC
2b700 54 20 32 33 34 35 2c 4e 55 4c 4c 22 2e 29 5e 0a  T 2345,NULL".)^.
2b710 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2b720 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28  e3_expanded_sql(
2b730 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2b740 72 6e 73 20 4e 55 4c 4c 20 69 66 20 69 6e 73 75  rns NULL if insu
2b750 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 0a  fficient memory.
2b760 2a 2a 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20  ** is available 
2b770 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75  to hold the resu
2b780 6c 74 2c 20 6f 72 20 69 66 20 74 68 65 20 72 65  lt, or if the re
2b790 73 75 6c 74 20 77 6f 75 6c 64 20 65 78 63 65 65  sult would excee
2b7a0 64 20 74 68 65 0a 2a 2a 20 74 68 65 20 6d 61 78  d the.** the max
2b7b0 69 6d 75 6d 20 73 74 72 69 6e 67 20 6c 65 6e 67  imum string leng
2b7c0 74 68 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79  th determined by
2b7d0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4c 49 4d   the [SQLITE_LIM
2b7e0 49 54 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 0a 2a  IT_LENGTH]..**.*
2b7f0 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 54  * ^The [SQLITE_T
2b800 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d  RACE_SIZE_LIMIT]
2b810 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
2b820 74 69 6f 6e 20 6c 69 6d 69 74 73 20 74 68 65 20  tion limits the 
2b830 73 69 7a 65 20 6f 66 0a 2a 2a 20 62 6f 75 6e 64  size of.** bound
2b840 20 70 61 72 61 6d 65 74 65 72 20 65 78 70 61 6e   parameter expan
2b850 73 69 6f 6e 73 2e 20 20 5e 54 68 65 20 5b 53 51  sions.  ^The [SQ
2b860 4c 49 54 45 5f 4f 4d 49 54 5f 54 52 41 43 45 5d  LITE_OMIT_TRACE]
2b870 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a   compile-time.**
2b880 20 6f 70 74 69 6f 6e 20 63 61 75 73 65 73 20 73   option causes s
2b890 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f  qlite3_expanded_
2b8a0 73 71 6c 28 29 20 74 6f 20 61 6c 77 61 79 73 20  sql() to always 
2b8b0 72 65 74 75 72 6e 20 4e 55 4c 4c 2e 0a 2a 2a 0a  return NULL..**.
2b8c0 2a 2a 20 5e 54 68 65 20 73 74 72 69 6e 67 20 72  ** ^The string r
2b8d0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
2b8e0 65 33 5f 73 71 6c 28 50 29 20 69 73 20 6d 61 6e  e3_sql(P) is man
2b8f0 61 67 65 64 20 62 79 20 53 51 4c 69 74 65 20 61  aged by SQLite a
2b900 6e 64 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74  nd is.** automat
2b910 69 63 61 6c 6c 79 20 66 72 65 65 64 20 77 68 65  ically freed whe
2b920 6e 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  n the prepared s
2b930 74 61 74 65 6d 65 6e 74 20 69 73 20 66 69 6e 61  tatement is fina
2b940 6c 69 7a 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73  lized..** ^The s
2b950 74 72 69 6e 67 20 72 65 74 75 72 6e 65 64 20 62  tring returned b
2b960 79 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64  y sqlite3_expand
2b970 65 64 5f 73 71 6c 28 50 29 2c 20 6f 6e 20 74 68  ed_sql(P), on th
2b980 65 20 6f 74 68 65 72 20 68 61 6e 64 2c 0a 2a 2a  e other hand,.**
2b990 20 69 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f   is obtained fro
2b9a0 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
2b9b0 63 28 29 5d 20 61 6e 64 20 6d 75 73 74 20 62 65  c()] and must be
2b9c0 20 66 72 65 65 20 62 79 20 74 68 65 20 61 70 70   free by the app
2b9d0 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 62 79 20 70  lication.** by p
2b9e0 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71  assing it to [sq
2b9f0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a  lite3_free()]..*
2ba00 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
2ba10 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65  lite3_sql(sqlite
2ba20 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
2ba30 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 78  char *sqlite3_ex
2ba40 70 61 6e 64 65 64 5f 73 71 6c 28 73 71 6c 69 74  panded_sql(sqlit
2ba50 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
2ba60 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2ba70 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
2ba80 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  n SQL Statement 
2ba90 57 72 69 74 65 73 20 54 68 65 20 44 61 74 61 62  Writes The Datab
2baa0 61 73 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ase.** METHOD: s
2bab0 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
2bac0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73  * ^The sqlite3_s
2bad0 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20  tmt_readonly(X) 
2bae0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2baf0 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f  s true (non-zero
2bb00 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79  ) if.** and only
2bb10 20 69 66 20 74 68 65 20 5b 70 72 65 70 61 72 65   if the [prepare
2bb20 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 20 6d  d statement] X m
2bb30 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74 20 63  akes no direct c
2bb40 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68 65  hanges to.** the
2bb50 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
2bb60 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a  database file..*
2bb70 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b  *.** Note that [
2bb80 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2bb90 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
2bba0 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 61  s] or.** [virtua
2bbb0 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68 74 20  l tables] might 
2bbc0 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62  change the datab
2bbd0 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79 20 61  ase indirectly a
2bbe0 73 20 61 20 73 69 64 65 20 65 66 66 65 63 74 2e  s a side effect.
2bbf0 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d    .** ^(For exam
2bc00 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70 6c 69  ple, if an appli
2bc10 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73 20 61  cation defines a
2bc20 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c 28   function "eval(
2bc30 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c 6c  )" that .** call
2bc40 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  s [sqlite3_exec(
2bc50 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 6c  )], then the fol
2bc60 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61 74 65  lowing SQL state
2bc70 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 68  ment would.** ch
2bc80 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73  ange the databas
2bc90 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68 20 73  e file through s
2bca0 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a 0a  ide-effects:.**.
2bcb0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
2bcc0 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 43  pre>.**    SELEC
2bcd0 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45 20 46  T eval('DELETE F
2bce0 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20 74 32  ROM t1') FROM t2
2bcf0 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
2bd00 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42  ckquote>.**.** B
2bd10 75 74 20 62 65 63 61 75 73 65 20 74 68 65 20 5b  ut because the [
2bd20 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
2bd30 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67  t does not chang
2bd40 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  e the database f
2bd50 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2c  ile.** directly,
2bd60 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
2bd70 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20 73  adonly() would s
2bd80 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72 75 65  till return true
2bd90 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73  .)^.**.** ^Trans
2bda0 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73  action control s
2bdb0 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68 20 61  tatements such a
2bdc0 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d  s [BEGIN], [COMM
2bdd0 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c  IT], [ROLLBACK],
2bde0 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d 2c  .** [SAVEPOINT],
2bdf0 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20 63   and [RELEASE] c
2be00 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73 74 6d  ause sqlite3_stm
2be10 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20  t_readonly() to 
2be20 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a 20  return true,.** 
2be30 73 69 6e 63 65 20 74 68 65 20 73 74 61 74 65 6d  since the statem
2be40 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65 73 20  ents themselves 
2be50 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20  do not actually 
2be60 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62  modify the datab
2be70 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74 68 65  ase but.** rathe
2be80 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20 74  r they control t
2be90 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77 68 65  he timing of whe
2bea0 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d 65 6e  n other statemen
2beb0 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20 0a 2a  ts modify the .*
2bec0 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e 54 68  * database.  ^Th
2bed0 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64 20 5b  e [ATTACH] and [
2bee0 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d 65 6e  DETACH] statemen
2bef0 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a 2a  ts also cause.**
2bf00 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
2bf10 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75  adonly() to retu
2bf20 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c 20 77  rn true since, w
2bf30 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61 74 65  hile those state
2bf40 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65 20  ments.** change 
2bf50 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
2bf60 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73 65 20  n of a database 
2bf70 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65 79  connection, they
2bf80 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a   do not make .**
2bf90 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20   changes to the 
2bfa0 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64  content of the d
2bfb0 61 74 61 62 61 73 65 20 66 69 6c 65 73 20 6f 6e  atabase files on
2bfc0 20 64 69 73 6b 2e 0a 2a 2a 20 5e 54 68 65 20 73   disk..** ^The s
2bfd0 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
2bfe0 6f 6e 6c 79 28 29 20 69 6e 74 65 72 66 61 63 65  only() interface
2bff0 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 66 6f   returns true fo
2c000 72 20 5b 42 45 47 49 4e 5d 20 73 69 6e 63 65 0a  r [BEGIN] since.
2c010 2a 2a 20 5b 42 45 47 49 4e 5d 20 6d 65 72 65 6c  ** [BEGIN] merel
2c020 79 20 73 65 74 73 20 69 6e 74 65 72 6e 61 6c 20  y sets internal 
2c030 66 6c 61 67 73 2c 20 62 75 74 20 74 68 65 20 5b  flags, but the [
2c040 42 45 47 49 4e 7c 42 45 47 49 4e 20 49 4d 4d 45  BEGIN|BEGIN IMME
2c050 44 49 41 54 45 5d 20 61 6e 64 0a 2a 2a 20 5b 42  DIATE] and.** [B
2c060 45 47 49 4e 7c 42 45 47 49 4e 20 45 58 43 4c 55  EGIN|BEGIN EXCLU
2c070 53 49 56 45 5d 20 63 6f 6d 6d 61 6e 64 73 20 64  SIVE] commands d
2c080 6f 20 74 6f 75 63 68 20 74 68 65 20 64 61 74 61  o touch the data
2c090 62 61 73 65 20 61 6e 64 20 73 6f 0a 2a 2a 20 73  base and so.** s
2c0a0 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
2c0b0 6f 6e 6c 79 28 29 20 72 65 74 75 72 6e 73 20 66  only() returns f
2c0c0 61 6c 73 65 20 66 6f 72 20 74 68 6f 73 65 20 63  alse for those c
2c0d0 6f 6d 6d 61 6e 64 73 2e 0a 2a 2f 0a 69 6e 74 20  ommands..*/.int 
2c0e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
2c0f0 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73 74  donly(sqlite3_st
2c100 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
2c110 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74  ** CAPI3REF: Det
2c120 65 72 6d 69 6e 65 20 49 66 20 41 20 50 72 65 70  ermine If A Prep
2c130 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 48  ared Statement H
2c140 61 73 20 42 65 65 6e 20 52 65 73 65 74 0a 2a 2a  as Been Reset.**
2c150 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2c160 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _stmt.**.** ^The
2c170 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75   sqlite3_stmt_bu
2c180 73 79 28 53 29 20 69 6e 74 65 72 66 61 63 65 20  sy(S) interface 
2c190 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f  returns true (no
2c1a0 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68 65 0a 2a  n-zero) if the.*
2c1b0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
2c1c0 65 6d 65 6e 74 5d 20 53 20 68 61 73 20 62 65 65  ement] S has bee
2c1d0 6e 20 73 74 65 70 70 65 64 20 61 74 20 6c 65 61  n stepped at lea
2c1e0 73 74 20 6f 6e 63 65 20 75 73 69 6e 67 20 0a 2a  st once using .*
2c1f0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
2c200 53 29 5d 20 62 75 74 20 68 61 73 20 6e 65 69 74  S)] but has neit
2c210 68 65 72 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c  her run to compl
2c220 65 74 69 6f 6e 20 28 72 65 74 75 72 6e 65 64 0a  etion (returned.
2c230 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  ** [SQLITE_DONE]
2c240 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73   from [sqlite3_s
2c250 74 65 70 28 53 29 5d 29 20 6e 6f 72 0a 2a 2a 20  tep(S)]) nor.** 
2c260 62 65 65 6e 20 72 65 73 65 74 20 75 73 69 6e 67  been reset using
2c270 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2c280 53 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  S)].  ^The sqlit
2c290 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 0a  e3_stmt_busy(S).
2c2a0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  ** interface ret
2c2b0 75 72 6e 73 20 66 61 6c 73 65 20 69 66 20 53 20  urns false if S 
2c2c0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
2c2d0 72 2e 20 20 49 66 20 53 20 69 73 20 6e 6f 74 20  r.  If S is not 
2c2e0 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74  a .** NULL point
2c2f0 65 72 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  er and is not a 
2c300 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c  pointer to a val
2c310 69 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  id [prepared sta
2c320 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63  tement].** objec
2c330 74 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  t, then the beha
2c340 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
2c350 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75  d and probably u
2c360 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a  ndesirable..**.*
2c370 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  * This interface
2c380 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 20   can be used in 
2c390 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c  combination [sql
2c3a0 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29  ite3_next_stmt()
2c3b0 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61  ].** to locate a
2c3c0 6c 6c 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ll prepared stat
2c3d0 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65  ements associate
2c3e0 64 20 77 69 74 68 20 61 20 64 61 74 61 62 61 73  d with a databas
2c3f0 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  e .** connection
2c400 20 74 68 61 74 20 61 72 65 20 69 6e 20 6e 65 65   that are in nee
2c410 64 20 6f 66 20 62 65 69 6e 67 20 72 65 73 65 74  d of being reset
2c420 2e 20 20 54 68 69 73 20 63 61 6e 20 62 65 20 75  .  This can be u
2c430 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d  sed,.** for exam
2c440 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74  ple, in diagnost
2c450 69 63 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 73  ic routines to s
2c460 65 61 72 63 68 20 66 6f 72 20 70 72 65 70 61 72  earch for prepar
2c470 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  ed .** statement
2c480 73 20 74 68 61 74 20 61 72 65 20 68 6f 6c 64 69  s that are holdi
2c490 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  ng a transaction
2c4a0 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71   open..*/.int sq
2c4b0 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28  lite3_stmt_busy(
2c4c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
2c4d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2c4e0 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70   Dynamically Typ
2c4f0 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a  ed Value Object.
2c500 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72  ** KEYWORDS: {pr
2c510 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2c520 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63  value} {unprotec
2c530 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2c540 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  e}.**.** SQLite 
2c550 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 33  uses the sqlite3
2c560 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f  _value object to
2c570 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76   represent all v
2c580 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61  alues.** that ca
2c590 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61  n be stored in a
2c5a0 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e   database table.
2c5b0 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e   SQLite uses dyn
2c5c0 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66  amic typing.** f
2c5d0 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 74  or the values it
2c5e0 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65   stores.  ^Value
2c5f0 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69  s stored in sqli
2c600 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2c610 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65  s.** can be inte
2c620 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70  gers, floating p
2c630 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72  oint values, str
2c640 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20  ings, BLOBs, or 
2c650 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73  NULL..**.** An s
2c660 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2c670 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 65  ect may be eithe
2c680 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72  r "protected" or
2c690 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a   "unprotected"..
2c6a0 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63  ** Some interfac
2c6b0 65 73 20 72 65 71 75 69 72 65 20 61 20 70 72 6f  es require a pro
2c6c0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2c6d0 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74  alue.  Other int
2c6e0 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20  erfaces.** will 
2c6f0 61 63 63 65 70 74 20 65 69 74 68 65 72 20 61 20  accept either a 
2c700 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20  protected or an 
2c710 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2c720 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76  te3_value..** Ev
2c730 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 68  ery interface th
2c740 61 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 74  at accepts sqlit
2c750 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e  e3_value argumen
2c760 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  ts specifies.** 
2c770 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69  whether or not i
2c780 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72 6f  t requires a pro
2c790 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2c7a0 61 6c 75 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73  alue.  The.** [s
2c7b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70  qlite3_value_dup
2c7c0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 61  ()] interface ca
2c7d0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 6f 6e  n be used to con
2c7e0 73 74 72 75 63 74 20 61 20 6e 65 77 20 0a 2a 2a  struct a new .**
2c7f0 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
2c800 65 33 5f 76 61 6c 75 65 20 66 72 6f 6d 20 61 6e  e3_value from an
2c810 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
2c820 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  ite3_value..**.*
2c830 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f  * The terms "pro
2c840 74 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70  tected" and "unp
2c850 72 6f 74 65 63 74 65 64 22 20 72 65 66 65 72 20  rotected" refer 
2c860 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  to whether or no
2c870 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20  t.** a mutex is 
2c880 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65 72 6e  held.  An intern
2c890 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64  al mutex is held
2c8a0 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64   for a protected
2c8b0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
2c8c0 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20  e object but no 
2c8d0 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f  mutex is held fo
2c8e0 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64  r an unprotected
2c8f0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
2c900 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51  e object.  If SQ
2c910 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
2c920 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68   to be single-th
2c930 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20  readed.** (with 
2c940 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
2c950 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b  FE=0] and with [
2c960 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61  sqlite3_threadsa
2c970 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20  fe()] returning 
2c980 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69  0).** or if SQLi
2c990 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65  te is run in one
2c9a0 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74 65   of reduced mute
2c9b0 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c  x modes .** [SQL
2c9c0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
2c9d0 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c  ETHREAD] or [SQL
2c9e0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
2c9f0 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20  THREAD].** then 
2ca00 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74  there is no dist
2ca10 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  inction between 
2ca20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e  protected and un
2ca30 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
2ca40 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2ca50 74 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20  ts and they can 
2ca60 62 65 20 75 73 65 64 20 69 6e 74 65 72 63 68 61  be used intercha
2ca70 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65  ngeably.  Howeve
2ca80 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75  r,.** for maximu
2ca90 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69  m code portabili
2caa0 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65  ty it is recomme
2cab0 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63  nded that applic
2cac0 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20  ations.** still 
2cad0 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63  make the distinc
2cae0 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f  tion between pro
2caf0 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f  tected and unpro
2cb00 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
2cb10 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
2cb20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74  even when not st
2cb30 72 69 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e  rictly required.
2cb40 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2cb50 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2cb60 73 20 74 68 61 74 20 61 72 65 20 70 61 73 73 65  s that are passe
2cb70 64 20 61 73 20 70 61 72 61 6d 65 74 65 72 73 20  d as parameters 
2cb80 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c  into the.** impl
2cb90 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61  ementation of [a
2cba0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2cbb0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
2cbc0 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e  ] are protected.
2cbd0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2cbe0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65  _value object re
2cbf0 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
2cc00 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
2cc10 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65  ue()] is unprote
2cc20 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65  cted..** Unprote
2cc30 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2cc40 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f  ue objects may o
2cc50 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68  nly be used with
2cc60 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
2cc70 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64  ult_value()] and
2cc80 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76   [sqlite3_bind_v
2cc90 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  alue()]..** The 
2cca0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
2ccb0 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61  lob | sqlite3_va
2ccc0 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69  lue_type()] fami
2ccd0 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61  ly of.** interfa
2cce0 63 65 73 20 72 65 71 75 69 72 65 20 70 72 6f 74  ces require prot
2ccf0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2cd00 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a  lue objects..*/.
2cd10 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
2cd20 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 73 71 6c  qlite3_value sql
2cd30 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a  ite3_value;../*.
2cd40 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c  ** CAPI3REF: SQL
2cd50 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78   Function Contex
2cd60 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54  t Object.**.** T
2cd70 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68  he context in wh
2cd80 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74  ich an SQL funct
2cd90 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 20  ion executes is 
2cda0 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20  stored in an.** 
2cdb0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
2cdc0 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e  object.  ^A poin
2cdd0 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65  ter to an sqlite
2cde0 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74  3_context object
2cdf0 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69  .** is always fi
2ce00 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
2ce10 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
2ce20 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
2ce30 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70  ons]..** The app
2ce40 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2ce50 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d   SQL function im
2ce60 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c  plementation wil
2ce70 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70  l pass this.** p
2ce80 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69  ointer through i
2ce90 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  nto calls to [sq
2cea0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
2ceb0 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c   | sqlite3_resul
2cec0 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  t()],.** [sqlite
2ced0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
2cee0 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ext()], [sqlite3
2cef0 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a  _user_data()],.*
2cf00 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  * [sqlite3_conte
2cf10 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c  xt_db_handle()],
2cf20 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75   [sqlite3_get_au
2cf30 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64  xdata()],.** and
2cf40 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  /or [sqlite3_set
2cf50 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a  _auxdata()]..*/.
2cf60 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
2cf70 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73  qlite3_context s
2cf80 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a  qlite3_context;.
2cf90 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2cfa0 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20   Binding Values 
2cfb0 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 74  To Prepared Stat
2cfc0 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52  ements.** KEYWOR
2cfd0 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  DS: {host parame
2cfe0 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d  ter} {host param
2cff0 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72  eters} {host par
2d000 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20  ameter name}.** 
2d010 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70  KEYWORDS: {SQL p
2d020 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70  arameter} {SQL p
2d030 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61  arameters} {para
2d040 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a  meter binding}.*
2d050 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2d060 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 49  3_stmt.**.** ^(I
2d070 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  n the SQL statem
2d080 65 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20 74  ent text input t
2d090 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  o [sqlite3_prepa
2d0a0 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73  re_v2()] and its
2d0b0 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69   variants,.** li
2d0c0 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65  terals may be re
2d0d0 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61 72  placed by a [par
2d0e0 61 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61 74  ameter] that mat
2d0f0 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c  ches one of foll
2d100 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74  owing.** templat
2d110 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  es:.**.** <ul>.*
2d120 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69  * <li>  ?.** <li
2d130 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20  >  ?NNN.** <li> 
2d140 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40   :VVV.** <li>  @
2d150 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56  VVV.** <li>  $VV
2d160 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  V.** </ul>.**.**
2d170 20 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74 65   In the template
2d180 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70  s above, NNN rep
2d190 72 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65 67  resents an integ
2d1a0 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61  er literal,.** a
2d1b0 6e 64 20 56 56 56 20 72 65 70 72 65 73 65 6e 74  nd VVV represent
2d1c0 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69  s an alphanumeri
2d1d0 63 20 69 64 65 6e 74 69 66 69 65 72 2e 29 5e 20  c identifier.)^ 
2d1e0 20 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20   ^The values of 
2d1f0 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74  these.** paramet
2d200 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64  ers (also called
2d210 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   "host parameter
2d220 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20   names" or "SQL 
2d230 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20  parameters").** 
2d240 63 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67  can be set using
2d250 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
2d260 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64  d_*() routines d
2d270 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a  efined here..**.
2d280 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
2d290 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71  gument to the sq
2d2a0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
2d2b0 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79  outines is alway
2d2c0 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74  s.** a pointer t
2d2d0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  o the [sqlite3_s
2d2e0 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75  tmt] object retu
2d2f0 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71  rned from.** [sq
2d300 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2d310 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
2d320 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
2d330 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
2d340 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  is the index of 
2d350 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65  the SQL paramete
2d360 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20  r to be set..** 
2d370 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51  ^The leftmost SQ
2d380 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20  L parameter has 
2d390 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20  an index of 1.  
2d3a0 5e 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e  ^When the same n
2d3b0 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61  amed.** SQL para
2d3c0 6d 65 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f  meter is used mo
2d3d0 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65  re than once, se
2d3e0 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75  cond and subsequ
2d3f0 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63  ent.** occurrenc
2d400 65 73 20 68 61 76 65 20 74 68 65 20 73 61 6d 65  es have the same
2d410 20 69 6e 64 65 78 20 61 73 20 74 68 65 20 66 69   index as the fi
2d420 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a  rst occurrence..
2d430 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66 6f  ** ^The index fo
2d440 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65  r named paramete
2d450 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64  rs can be looked
2d460 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a   up using the.**
2d470 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2d480 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
2d490 5d 20 41 50 49 20 69 66 20 64 65 73 69 72 65 64  ] API if desired
2d4a0 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a  .  ^The index.**
2d4b0 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61   for "?NNN" para
2d4c0 6d 65 74 65 72 73 20 69 73 20 74 68 65 20 76 61  meters is the va
2d4d0 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e  lue of NNN..** ^
2d4e0 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75  The NNN value mu
2d4f0 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 20  st be between 1 
2d500 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33  and the [sqlite3
2d510 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72  _limit()].** par
2d520 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c  ameter [SQLITE_L
2d530 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
2d540 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76  MBER] (default v
2d550 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a  alue: 999)..**.*
2d560 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67  * ^The third arg
2d570 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c  ument is the val
2d580 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68  ue to bind to th
2d590 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  e parameter..** 
2d5a0 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61  ^If the third pa
2d5b0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
2d5c0 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f  e3_bind_text() o
2d5d0 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  r sqlite3_bind_t
2d5e0 65 78 74 31 36 28 29 0a 2a 2a 20 6f 72 20 73 71  ext16().** or sq
2d5f0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
2d600 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ) is a NULL poin
2d610 74 65 72 20 74 68 65 6e 20 74 68 65 20 66 6f 75  ter then the fou
2d620 72 74 68 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  rth parameter.**
2d630 20 69 73 20 69 67 6e 6f 72 65 64 20 61 6e 64 20   is ignored and 
2d640 74 68 65 20 65 6e 64 20 72 65 73 75 6c 74 20 69  the end result i
2d650 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 73 71  s the same as sq
2d660 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28  lite3_bind_null(
2d670 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68  )..**.** ^(In th
2d680 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61  ose routines tha
2d690 74 20 68 61 76 65 20 61 20 66 6f 75 72 74 68 20  t have a fourth 
2d6a0 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61  argument, its va
2d6b0 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75  lue is the.** nu
2d6c0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
2d6d0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20   the parameter. 
2d6e0 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68   To be clear: th
2d6f0 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a  e value is the.*
2d700 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62  * number of <u>b
2d710 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20  ytes</u> in the 
2d720 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e  value, not the n
2d730 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
2d740 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68  ers.)^.** ^If th
2d750 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
2d760 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  er to sqlite3_bi
2d770 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c  nd_text() or sql
2d780 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
2d790 28 29 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76  ().** is negativ
2d7a0 65 2c 20 74 68 65 6e 20 74 68 65 20 6c 65 6e 67  e, then the leng
2d7b0 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67  th of the string
2d7c0 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65   is.** the numbe
2d7d0 72 20 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f  r of bytes up to
2d7e0 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
2d7f0 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49  terminator..** I
2d800 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
2d810 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
2d820 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73  3_bind_blob() is
2d830 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 0a   negative, then.
2d840 2a 2a 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  ** the behavior 
2d850 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
2d860 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69   If a non-negati
2d870 76 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  ve fourth parame
2d880 74 65 72 20 69 73 20 70 72 6f 76 69 64 65 64 20  ter is provided 
2d890 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
2d8a0 74 65 78 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  text().** or sql
2d8b0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
2d8c0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  () or sqlite3_bi
2d8d0 6e 64 5f 74 65 78 74 36 34 28 29 20 74 68 65 6e  nd_text64() then
2d8e0 0a 2a 2a 20 74 68 61 74 20 70 61 72 61 6d 65 74  .** that paramet
2d8f0 65 72 20 6d 75 73 74 20 62 65 20 74 68 65 20 62  er must be the b
2d900 79 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68  yte offset.** wh
2d910 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d  ere the NUL term
2d920 69 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63  inator would occ
2d930 75 72 20 61 73 73 75 6d 69 6e 67 20 74 68 65 20  ur assuming the 
2d940 73 74 72 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a  string were NUL.
2d950 2a 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  ** terminated.  
2d960 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61  If any NUL chara
2d970 63 74 65 72 73 20 6f 63 63 75 72 20 61 74 20 62  cters occur at b
2d980 79 74 65 20 6f 66 66 73 65 74 73 20 6c 65 73 73  yte offsets less
2d990 20 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61   than .** the va
2d9a0 6c 75 65 20 6f 66 20 74 68 65 20 66 6f 75 72 74  lue of the fourt
2d9b0 68 20 70 61 72 61 6d 65 74 65 72 20 74 68 65 6e  h parameter then
2d9c0 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73   the resulting s
2d9d0 74 72 69 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c  tring value will
2d9e0 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65  .** contain embe
2d9f0 64 64 65 64 20 4e 55 4c 73 2e 20 20 54 68 65 20  dded NULs.  The 
2da00 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73  result of expres
2da10 73 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20  sions involving 
2da20 73 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20  strings.** with 
2da30 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73  embedded NULs is
2da40 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
2da50 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67  * ^The fifth arg
2da60 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 42 4c 4f  ument to the BLO
2da70 42 20 61 6e 64 20 73 74 72 69 6e 67 20 62 69 6e  B and string bin
2da80 64 69 6e 67 20 69 6e 74 65 72 66 61 63 65 73 0a  ding interfaces.
2da90 2a 2a 20 69 73 20 61 20 64 65 73 74 72 75 63 74  ** is a destruct
2daa0 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f  or used to dispo
2dab0 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f  se of the BLOB o
2dac0 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65  r.** string afte
2dad0 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e  r SQLite has fin
2dae0 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 20  ished with it.  
2daf0 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20  ^The destructor 
2db00 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20  is called.** to 
2db10 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42  dispose of the B
2db20 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 65 76  LOB or string ev
2db30 65 6e 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74  en if the call t
2db40 6f 20 62 69 6e 64 20 41 50 49 20 66 61 69 6c 73  o bind API fails
2db50 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66  ..** ^If the fif
2db60 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a  th argument is.*
2db70 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 76 61  * the special va
2db80 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54  lue [SQLITE_STAT
2db90 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  IC], then SQLite
2dba0 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68   assumes that th
2dbb0 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  e.** information
2dbc0 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75   is in static, u
2dbd0 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 61  nmanaged space a
2dbe0 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  nd does not need
2dbf0 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a   to be freed..**
2dc00 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61   ^If the fifth a
2dc10 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20  rgument has the 
2dc20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52  value [SQLITE_TR
2dc30 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a  ANSIENT], then.*
2dc40 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69  * SQLite makes i
2dc50 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63  ts own private c
2dc60 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 20  opy of the data 
2dc70 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66  immediately, bef
2dc80 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74  ore.** the sqlit
2dc90 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
2dca0 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  ine returns..**.
2dcb0 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 20 61 72  ** ^The sixth ar
2dcc0 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
2dcd0 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20  3_bind_text64() 
2dce0 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 0a 2a  must be one of.*
2dcf0 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c  * [SQLITE_UTF8],
2dd00 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c   [SQLITE_UTF16],
2dd10 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45   [SQLITE_UTF16BE
2dd20 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54  ], or [SQLITE_UT
2dd30 46 31 36 4c 45 5d 0a 2a 2a 20 74 6f 20 73 70 65  F16LE].** to spe
2dd40 63 69 66 79 20 74 68 65 20 65 6e 63 6f 64 69 6e  cify the encodin
2dd50 67 20 6f 66 20 74 68 65 20 74 65 78 74 20 69 6e  g of the text in
2dd60 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
2dd70 65 74 65 72 2e 20 20 49 66 0a 2a 2a 20 74 68 65  eter.  If.** the
2dd80 20 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20   sixth argument 
2dd90 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
2dda0 74 65 78 74 36 34 28 29 20 69 73 20 6e 6f 74 20  text64() is not 
2ddb0 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 61 6c  one of the.** al
2ddc0 6c 6f 77 65 64 20 76 61 6c 75 65 73 20 73 68 6f  lowed values sho
2ddd0 77 6e 20 61 62 6f 76 65 2c 20 6f 72 20 69 66 20  wn above, or if 
2dde0 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  the text encodin
2ddf0 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 0a 2a  g is different.*
2de00 2a 20 66 72 6f 6d 20 74 68 65 20 65 6e 63 6f 64  * from the encod
2de10 69 6e 67 20 73 70 65 63 69 66 69 65 64 20 62 79  ing specified by
2de20 20 74 68 65 20 73 69 78 74 68 20 70 61 72 61 6d   the sixth param
2de30 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 62  eter, then the b
2de40 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75 6e  ehavior.** is un
2de50 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
2de60 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  The sqlite3_bind
2de70 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74  _zeroblob() rout
2de80 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42  ine binds a BLOB
2de90 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61   of length N tha
2dea0 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77  t.** is filled w
2deb0 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20  ith zeroes.  ^A 
2dec0 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20  zeroblob uses a 
2ded0 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20  fixed amount of 
2dee0 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20  memory.** (just 
2def0 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f  an integer to ho
2df00 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77 68 69  ld its size) whi
2df10 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67 20 70  le it is being p
2df20 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72  rocessed..** Zer
2df30 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e  oblobs are inten
2df40 64 65 64 20 74 6f 20 73 65 72 76 65 20 61 73 20  ded to serve as 
2df50 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72  placeholders for
2df60 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20   BLOBs whose.** 
2df70 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72  content is later
2df80 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a   written using.*
2df90 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  * [sqlite3_blob_
2dfa0 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74  open | increment
2dfb0 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75  al BLOB I/O] rou
2dfc0 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67  tines..** ^A neg
2dfd0 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20  ative value for 
2dfe0 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73  the zeroblob res
2dff0 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c  ults in a zero-l
2e000 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a  ength BLOB..**.*
2e010 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20 74 68 65  * ^If any of the
2e020 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
2e030 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  ) routines are c
2e040 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c  alled with a NUL
2e050 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72  L pointer.** for
2e060 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2e070 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74  tatement] or wit
2e080 68 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61  h a prepared sta
2e090 74 65 6d 65 6e 74 20 66 6f 72 20 77 68 69 63 68  tement for which
2e0a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
2e0b0 70 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61  p()] has been ca
2e0c0 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63 65 6e 74  lled more recent
2e0d0 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69 74 65 33  ly than [sqlite3
2e0e0 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68  _reset()],.** th
2e0f0 65 6e 20 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c  en the call will
2e100 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
2e110 4d 49 53 55 53 45 5d 2e 20 20 49 66 20 61 6e 79  MISUSE].  If any
2e120 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29   sqlite3_bind_()
2e130 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73 20 70  .** routine is p
2e140 61 73 73 65 64 20 61 20 5b 70 72 65 70 61 72 65  assed a [prepare
2e150 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
2e160 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c  t has been final
2e170 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73  ized, the.** res
2e180 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ult is undefined
2e190 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 68 61   and probably ha
2e1a0 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69  rmful..**.** ^Bi
2e1b0 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63  ndings are not c
2e1c0 6c 65 61 72 65 64 20 62 79 20 74 68 65 20 5b 73  leared by the [s
2e1d0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2e1e0 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62  routine..** ^Unb
2e1f0 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20  ound parameters 
2e200 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20  are interpreted 
2e210 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  as NULL..**.** ^
2e220 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  The sqlite3_bind
2e230 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  _* routines retu
2e240 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  rn [SQLITE_OK] o
2e250 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e 0a  n success or an.
2e260 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ** [error code] 
2e270 69 66 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73  if anything goes
2e280 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c   wrong..** ^[SQL
2e290 49 54 45 5f 54 4f 4f 42 49 47 5d 20 6d 69 67 68  ITE_TOOBIG] migh
2e2a0 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 69 66  t be returned if
2e2b0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 20 73   the size of a s
2e2c0 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 0a 2a 2a  tring or BLOB.**
2e2d0 20 65 78 63 65 65 64 73 20 6c 69 6d 69 74 73 20   exceeds limits 
2e2e0 69 6d 70 6f 73 65 64 20 62 79 20 5b 73 71 6c 69  imposed by [sqli
2e2f0 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49  te3_limit]([SQLI
2e300 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d  TE_LIMIT_LENGTH]
2e310 29 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ) or.** [SQLITE_
2e320 4d 41 58 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 20  MAX_LENGTH]..** 
2e330 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20  ^[SQLITE_RANGE] 
2e340 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74  is returned if t
2e350 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  he parameter.** 
2e360 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20  index is out of 
2e370 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45  range.  ^[SQLITE
2e380 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72  _NOMEM] is retur
2e390 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20  ned if malloc() 
2e3a0 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  fails..**.** See
2e3b0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
2e3c0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
2e3d0 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  ount()],.** [sql
2e3e0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2e3f0 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64  ter_name()], and
2e400 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2e410 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
2e420 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
2e430 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69  3_bind_blob(sqli
2e440 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
2e450 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
2e460 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   n, void(*)(void
2e470 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  *));.int sqlite3
2e480 5f 62 69 6e 64 5f 62 6c 6f 62 36 34 28 73 71 6c  _bind_blob64(sql
2e490 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
2e4a0 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 73 71   const void*, sq
2e4b0 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20  lite3_uint64,.  
2e4c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2e4d0 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28 76 6f        void(*)(vo
2e4e0 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74  id*));.int sqlit
2e4f0 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73  e3_bind_double(s
2e500 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2e510 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20  t, double);.int 
2e520 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74  sqlite3_bind_int
2e530 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2e540 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73  int, int);.int s
2e550 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36  qlite3_bind_int6
2e560 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
2e570 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e   int, sqlite3_in
2e580 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  t64);.int sqlite
2e590 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69  3_bind_null(sqli
2e5a0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b  te3_stmt*, int);
2e5b0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
2e5c0 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73  d_text(sqlite3_s
2e5d0 74 6d 74 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63  tmt*,int,const c
2e5e0 68 61 72 2a 2c 69 6e 74 2c 76 6f 69 64 28 2a 29  har*,int,void(*)
2e5f0 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
2e600 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
2e610 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2e620 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
2e630 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
2e640 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c  void*));.int sql
2e650 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34  ite3_bind_text64
2e660 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2e670 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  int, const char*
2e680 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  , sqlite3_uint64
2e690 2c 0a 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 20 76 6f 69 64 28             void(
2e6b0 2a 29 28 76 6f 69 64 2a 29 2c 20 75 6e 73 69 67  *)(void*), unsig
2e6c0 6e 65 64 20 63 68 61 72 20 65 6e 63 6f 64 69 6e  ned char encodin
2e6d0 67 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  g);.int sqlite3_
2e6e0 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74  bind_value(sqlit
2e6f0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
2e700 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  onst sqlite3_val
2e710 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
2e720 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28  3_bind_zeroblob(
2e730 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2e740 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 69 6e 74 20  nt, int n);.int 
2e750 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
2e760 6f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 5f  oblob64(sqlite3_
2e770 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69  stmt*, int, sqli
2e780 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 0a 2f 2a  te3_uint64);../*
2e790 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
2e7a0 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61  mber Of SQL Para
2e7b0 6d 65 74 65 72 73 0a 2a 2a 20 4d 45 54 48 4f 44  meters.** METHOD
2e7c0 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2e7d0 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
2e7e0 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ne can be used t
2e7f0 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65  o find the numbe
2e800 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65  r of [SQL parame
2e810 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70  ters].** in a [p
2e820 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2e830 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74  t].  SQL paramet
2e840 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f  ers are tokens o
2e850 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f  f the.** form "?
2e860 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41  ", "?NNN", ":AAA
2e870 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40  ", "$AAA", or "@
2e880 41 41 41 22 20 74 68 61 74 20 73 65 72 76 65 20  AAA" that serve 
2e890 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65  as.** placeholde
2e8a0 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68  rs for values th
2e8b0 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f  at are [sqlite3_
2e8c0 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e  bind_blob | boun
2e8d0 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72  d].** to the par
2e8e0 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61 74  ameters at a lat
2e8f0 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e  er time..**.** ^
2e900 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63  (This routine ac
2e910 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74  tually returns t
2e920 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
2e930 6c 61 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f  largest (rightmo
2e940 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  st).** parameter
2e950 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20  . For all forms 
2e960 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69  except ?NNN, thi
2e970 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e  s will correspon
2e980 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  d to the.** numb
2e990 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72  er of unique par
2e9a0 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61 72  ameters.  If par
2e9b0 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f  ameters of the ?
2e9c0 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75 73 65  NNN form are use
2e9d0 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20  d,.** there may 
2e9e0 62 65 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c  be gaps in the l
2e9f0 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65  ist.)^.**.** See
2ea00 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
2ea10 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
2ea20 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
2ea30 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2ea40 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61  meter_name()], a
2ea50 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
2ea60 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
2ea70 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  dex()]..*/.int s
2ea80 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2ea90 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69  meter_count(sqli
2eaa0 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
2eab0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d  ** CAPI3REF: Nam
2eac0 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61  e Of A Host Para
2ead0 6d 65 74 65 72 0a 2a 2a 20 4d 45 54 48 4f 44 3a  meter.** METHOD:
2eae0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2eaf0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2eb00 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2eb10 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66  name(P,N) interf
2eb20 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  ace returns.** t
2eb30 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e  he name of the N
2eb40 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74  -th [SQL paramet
2eb50 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70  er] in the [prep
2eb60 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2eb70 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61  P..** ^(SQL para
2eb80 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f  meters of the fo
2eb90 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41  rm "?NNN" or ":A
2eba0 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72  AA" or "@AAA" or
2ebb0 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20   "$AAA".** have 
2ebc0 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20  a name which is 
2ebd0 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e  the string "?NNN
2ebe0 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22  " or ":AAA" or "
2ebf0 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a  @AAA" or "$AAA".
2ec00 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  ** respectively.
2ec10 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  .** In other wor
2ec20 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20  ds, the initial 
2ec30 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40  ":" or "$" or "@
2ec40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69  " or "?".** is i
2ec50 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 74 20  ncluded as part 
2ec60 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a  of the name.)^.*
2ec70 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66  * ^Parameters of
2ec80 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69   the form "?" wi
2ec90 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e  thout a followin
2eca0 67 20 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e  g integer have n
2ecb0 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72  o name.** and ar
2ecc0 65 20 72 65 66 65 72 72 65 64 20 74 6f 20 61 73  e referred to as
2ecd0 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22   "nameless" or "
2ece0 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65  anonymous parame
2ecf0 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ters"..**.** ^Th
2ed00 65 20 66 69 72 73 74 20 68 6f 73 74 20 70 61 72  e first host par
2ed10 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e  ameter has an in
2ed20 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e  dex of 1, not 0.
2ed30 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76  .**.** ^If the v
2ed40 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66  alue N is out of
2ed50 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65   range or if the
2ed60 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20   N-th parameter 
2ed70 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20  is.** nameless, 
2ed80 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74  then NULL is ret
2ed90 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74  urned.  ^The ret
2eda0 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a  urned string is.
2edb0 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46  ** always in UTF
2edc0 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e  -8 encoding even
2edd0 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61   if the named pa
2ede0 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f  rameter was.** o
2edf0 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66  riginally specif
2ee00 69 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  ied as UTF-16 in
2ee10 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2ee20 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  e16()] or.** [sq
2ee30 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2ee40 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  v2()]..**.** See
2ee50 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
2ee60 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
2ee70 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
2ee80 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2ee90 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20  meter_count()], 
2eea0 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
2eeb0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
2eec0 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73  ndex()]..*/.cons
2eed0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
2eee0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
2eef0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
2ef00 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *, int);../*.** 
2ef10 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20  CAPI3REF: Index 
2ef20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57  Of A Parameter W
2ef30 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65  ith A Given Name
2ef40 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2ef50 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
2ef60 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78  Return the index
2ef70 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d   of an SQL param
2ef80 65 74 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e  eter given its n
2ef90 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e  ame.  ^The.** in
2efa0 64 65 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e  dex value return
2efb0 65 64 20 69 73 20 73 75 69 74 61 62 6c 65 20 66  ed is suitable f
2efc0 6f 72 20 75 73 65 20 61 73 20 74 68 65 20 73 65  or use as the se
2efd0 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65  cond.** paramete
2efe0 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69  r to [sqlite3_bi
2eff0 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
2f000 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72  bind()].  ^A zer
2f010 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  o.** is returned
2f020 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20   if no matching 
2f030 70 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75  parameter is fou
2f040 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65  nd.  ^The parame
2f050 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74  ter.** name must
2f060 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46   be given in UTF
2f070 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f  -8 even if the o
2f080 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e  riginal statemen
2f090 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65  t.** was prepare
2f0a0 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65  d from UTF-16 te
2f0b0 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  xt using [sqlite
2f0c0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
2f0d0 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  ]..**.** See als
2f0e0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
2f0f0 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
2f100 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
2f110 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2f120 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a  r_count()], and.
2f130 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
2f140 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
2f150 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
2f160 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2f170 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f  r_index(sqlite3_
2f180 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  stmt*, const cha
2f190 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a  r *zName);../*.*
2f1a0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65  * CAPI3REF: Rese
2f1b0 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f  t All Bindings O
2f1c0 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  n A Prepared Sta
2f1d0 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44  tement.** METHOD
2f1e0 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2f1f0 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74  *.** ^Contrary t
2f200 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20  o the intuition 
2f210 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65  of many, [sqlite
2f220 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20  3_reset()] does 
2f230 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65  not reset.** the
2f240 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2f250 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20  lob | bindings] 
2f260 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  on a [prepared s
2f270 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55  tatement]..** ^U
2f280 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  se this routine 
2f290 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73  to reset all hos
2f2a0 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  t parameters to 
2f2b0 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  NULL..*/.int sql
2f2c0 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69  ite3_clear_bindi
2f2d0 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ngs(sqlite3_stmt
2f2e0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
2f2f0 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43  REF: Number Of C
2f300 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75  olumns In A Resu
2f310 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44  lt Set.** METHOD
2f320 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2f330 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65  *.** ^Return the
2f340 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
2f350 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
2f360 20 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79   set returned by
2f370 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
2f380 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 49  d statement]. ^I
2f390 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72  f this routine r
2f3a0 65 74 75 72 6e 73 20 30 2c 20 74 68 61 74 20 6d  eturns 0, that m
2f3b0 65 61 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 70 72  eans the .** [pr
2f3c0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2f3d0 5d 20 72 65 74 75 72 6e 73 20 6e 6f 20 64 61 74  ] returns no dat
2f3e0 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61  a (for example a
2f3f0 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 20  n [UPDATE])..** 
2f400 5e 48 6f 77 65 76 65 72 2c 20 6a 75 73 74 20 62  ^However, just b
2f410 65 63 61 75 73 65 20 74 68 69 73 20 72 6f 75 74  ecause this rout
2f420 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ine returns a po
2f430 73 69 74 69 76 65 20 6e 75 6d 62 65 72 20 64 6f  sitive number do
2f440 65 73 20 6e 6f 74 0a 2a 2a 20 6d 65 61 6e 20 74  es not.** mean t
2f450 68 61 74 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  hat one or more 
2f460 72 6f 77 73 20 6f 66 20 64 61 74 61 20 77 69 6c  rows of data wil
2f470 6c 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 20  l be returned.  
2f480 5e 41 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d  ^A SELECT statem
2f490 65 6e 74 0a 2a 2a 20 77 69 6c 6c 20 61 6c 77 61  ent.** will alwa
2f4a0 79 73 20 68 61 76 65 20 61 20 70 6f 73 69 74 69  ys have a positi
2f4b0 76 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ve sqlite3_colum
2f4c0 6e 5f 63 6f 75 6e 74 28 29 20 62 75 74 20 64 65  n_count() but de
2f4d0 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 0a 2a  pending on the.*
2f4e0 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 63  * WHERE clause c
2f4f0 6f 6e 73 74 72 61 69 6e 74 73 20 61 6e 64 20 74  onstraints and t
2f500 68 65 20 74 61 62 6c 65 20 63 6f 6e 74 65 6e 74  he table content
2f510 2c 20 69 74 20 6d 69 67 68 74 20 72 65 74 75 72  , it might retur
2f520 6e 20 6e 6f 20 72 6f 77 73 2e 0a 2a 2a 0a 2a 2a  n no rows..**.**
2f530 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
2f540 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29  te3_data_count()
2f550 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
2f560 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71  _column_count(sq
2f570 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
2f580 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2f590 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65  REF: Column Name
2f5a0 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65  s In A Result Se
2f5b0 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
2f5c0 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
2f5d0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
2f5e0 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20  return the name 
2f5f0 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61  assigned to a pa
2f600 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a  rticular column.
2f610 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ** in the result
2f620 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43   set of a [SELEC
2f630 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e  T] statement.  ^
2f640 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  The sqlite3_colu
2f650 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74  mn_name().** int
2f660 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
2f670 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65   pointer to a ze
2f680 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
2f690 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e  F-8 string.** an
2f6a0 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
2f6b0 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e  _name16() return
2f6c0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
2f6d0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
2f6e0 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e  .** UTF-16 strin
2f6f0 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 70  g.  ^The first p
2f700 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
2f710 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2f720 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70  ent].** that imp
2f730 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c  lements the [SEL
2f740 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20  ECT] statement. 
2f750 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
2f760 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
2f770 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20  column number.  
2f780 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f  ^The leftmost co
2f790 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30  lumn is number 0
2f7a0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74  ..**.** ^The ret
2f7b0 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69  urned string poi
2f7c0 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e  nter is valid un
2f7d0 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b  til either the [
2f7e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2f7f0 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f  nt].** is destro
2f800 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  yed by [sqlite3_
2f810 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75  finalize()] or u
2f820 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65  ntil the stateme
2f830 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61  nt is automatica
2f840 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65  lly.** reprepare
2f850 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63  d by the first c
2f860 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2f870 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61  step()] for a pa
2f880 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20  rticular run.** 
2f890 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78  or until the nex
2f8a0 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c  t call to.** sql
2f8b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
2f8c0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  () or sqlite3_co
2f8d0 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e  lumn_name16() on
2f8e0 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e   the same column
2f8f0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  ..**.** ^If sqli
2f900 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69  te3_malloc() fai
2f910 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 72  ls during the pr
2f920 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68  ocessing of eith
2f930 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66  er routine.** (f
2f940 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e  or example durin
2f950 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66  g a conversion f
2f960 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46  rom UTF-8 to UTF
2f970 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e  -16) then a.** N
2f980 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72  ULL pointer is r
2f990 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
2f9a0 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65  The name of a re
2f9b0 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74  sult column is t
2f9c0 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
2f9d0 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a  "AS" clause for.
2f9e0 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20  ** that column, 
2f9f0 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 41  if there is an A
2fa00 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68  S clause.  If th
2fa10 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61  ere is no AS cla
2fa20 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  use.** then the 
2fa30 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75  name of the colu
2fa40 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 65  mn is unspecifie
2fa50 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65  d and may change
2fa60 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c   from.** one rel
2fa70 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74  ease of SQLite t
2fa80 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63  o the next..*/.c
2fa90 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
2faa0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73  e3_column_name(s
2fab0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2fac0 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  t N);.const void
2fad0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2fae0 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
2faf0 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a  stmt*, int N);..
2fb00 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2fb10 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49  Source Of Data I
2fb20 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74  n A Query Result
2fb30 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2fb40 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
2fb50 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70  These routines p
2fb60 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74  rovide a means t
2fb70 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  o determine the 
2fb80 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
2fb90 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f   and.** table co
2fba0 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68 65  lumn that is the
2fbb0 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61 72   origin of a par
2fbc0 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20 63  ticular result c
2fbd0 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c  olumn in.** [SEL
2fbe0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a  ECT] statement..
2fbf0 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  ** ^The name of 
2fc00 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 20  the database or 
2fc10 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20  table or column 
2fc20 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20  can be returned 
2fc30 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55  as.** either a U
2fc40 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73  TF-8 or UTF-16 s
2fc50 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61  tring.  ^The _da
2fc60 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73  tabase_ routines
2fc70 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64   return.** the d
2fc80 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68  atabase name, th
2fc90 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e  e _table_ routin
2fca0 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 61  es return the ta
2fcb0 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a  ble name, and.**
2fcc0 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75   the origin_ rou
2fcd0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
2fce0 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a   column name..**
2fcf0 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
2fd00 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75  tring is valid u
2fd10 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72  ntil the [prepar
2fd20 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73  ed statement] is
2fd30 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73   destroyed.** us
2fd40 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
2fd50 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69  alize()] or unti
2fd60 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  l the statement 
2fd70 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  is automatically
2fd80 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62  .** reprepared b
2fd90 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c  y the first call
2fda0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
2fdb0 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69  p()] for a parti
2fdc0 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20  cular run.** or 
2fdd0 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69  until the same i
2fde0 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65  nformation is re
2fdf0 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e  quested.** again
2fe00 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20   in a different 
2fe10 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  encoding..**.** 
2fe20 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72  ^The names retur
2fe30 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67  ned are the orig
2fe40 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20  inal un-aliased 
2fe50 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20  names of the.** 
2fe60 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
2fe70 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a   and column..**.
2fe80 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
2fe90 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 20  gument to these 
2fea0 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 61 20  interfaces is a 
2feb0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2fec0 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20  ent]..** ^These 
2fed0 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
2fee0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
2fef0 75 74 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c  ut the Nth resul
2ff00 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65  t column returne
2ff10 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74  d by.** the stat
2ff20 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69  ement, where N i
2ff30 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e  s the second fun
2ff40 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a  ction argument..
2ff50 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73  ** ^The left-mos
2ff60 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75  t column is colu
2ff70 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65 20 72  mn 0 for these r
2ff80 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  outines..**.** ^
2ff90 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  If the Nth colum
2ffa0 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  n returned by th
2ffb0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
2ffc0 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a  n expression or.
2ffd0 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64 20  ** subquery and 
2ffe0 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20  is not a column 
2fff0 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20  value, then all 
30000 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  of these functio
30010 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c  ns return.** NUL
30020 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69  L.  ^These routi
30030 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65  ne might also re
30040 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d  turn NULL if a m
30050 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
30060 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73   error.** occurs
30070 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 74  .  ^Otherwise, t
30080 68 65 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e  hey return the n
30090 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 63  ame of the attac
300a0 68 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 61  hed database, ta
300b0 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d  ble,.** or colum
300c0 6e 20 74 68 61 74 20 71 75 65 72 79 20 72 65 73  n that query res
300d0 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65  ult column was e
300e0 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a  xtracted from..*
300f0 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 6c  *.** ^As with al
30100 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41  l other SQLite A
30110 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 65  PIs, those whose
30120 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68 20   names end with 
30130 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55  "16" return.** U
30140 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74  TF-16 encoded st
30150 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f 74  rings and the ot
30160 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  her functions re
30170 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a  turn UTF-8..**.*
30180 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20 61 72  * ^These APIs ar
30190 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  e only available
301a0 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20   if the library 
301b0 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  was compiled wit
301c0 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  h the.** [SQLITE
301d0 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d  _ENABLE_COLUMN_M
301e0 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72  ETADATA] C-prepr
301f0 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a  ocessor symbol..
30200 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20  **.** If two or 
30210 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c  more threads cal
30220 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66  l one or more of
30230 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
30240 61 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65  against the same
30250 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61  .** prepared sta
30260 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d  tement and colum
30270 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  n at the same ti
30280 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  me then the resu
30290 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66  lts are.** undef
302a0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  ined..**.** If t
302b0 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61  wo or more threa
302c0 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d  ds call one or m
302d0 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ore.** [sqlite3_
302e0 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
302f0 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65  name | column me
30300 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 65  tadata interface
30310 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61  s].** for the sa
30320 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  me [prepared sta
30330 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75  tement] and resu
30340 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20  lt column.** at 
30350 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68  the same time th
30360 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
30370 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f  re undefined..*/
30380 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
30390 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
303a0 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65  base_name(sqlite
303b0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
303c0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
303d0 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
303e0 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  e_name16(sqlite3
303f0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
30400 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
30410 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61  _column_table_na
30420 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
30430 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
30440 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
30450 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73  n_table_name16(s
30460 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
30470 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
30480 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72  qlite3_column_or
30490 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65  igin_name(sqlite
304a0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
304b0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
304c0 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f  3_column_origin_
304d0 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
304e0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  tmt*,int);../*.*
304f0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c  * CAPI3REF: Decl
30500 61 72 65 64 20 44 61 74 61 74 79 70 65 20 4f 66  ared Datatype Of
30510 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a   A Query Result.
30520 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
30530 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28  e3_stmt.**.** ^(
30540 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
30550 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 72  ter is a [prepar
30560 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
30570 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65 6d  * If this statem
30580 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54  ent is a [SELECT
30590 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  ] statement and 
305a0 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
305b0 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65  f the.** returne
305c0 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  d result set of 
305d0 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73  that [SELECT] is
305e0 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20   a table column 
305f0 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65  (not an.** expre
30600 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72  ssion or subquer
30610 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c  y) then the decl
30620 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65  ared type of the
30630 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e   table.** column
30640 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20   is returned.)^ 
30650 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c   ^If the Nth col
30660 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c  umn of the resul
30670 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65  t set is an.** e
30680 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
30690 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55  query, then a NU
306a0 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  LL pointer is re
306b0 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  turned..** ^The 
306c0 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
306d0 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20  is always UTF-8 
306e0 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  encoded..**.** ^
306f0 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69  (For example, gi
30700 76 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  ven the database
30710 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43   schema:.**.** C
30720 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 63  REATE TABLE t1(c
30730 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a  1 VARIANT);.**.*
30740 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77  * and the follow
30750 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  ing statement to
30760 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a   be compiled:.**
30770 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20  .** SELECT c1 + 
30780 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a  1, c1 FROM t1;.*
30790 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e  *.** this routin
307a0 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74  e would return t
307b0 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 41  he string "VARIA
307c0 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f  NT" for the seco
307d0 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c  nd result.** col
307e0 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20  umn (i==1), and 
307f0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66  a NULL pointer f
30800 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65 73  or the first res
30810 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30  ult column (i==0
30820 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  ).)^.**.** ^SQLi
30830 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20  te uses dynamic 
30840 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e  run-time typing.
30850 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75    ^So just becau
30860 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  se a column.** i
30870 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f  s declared to co
30880 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c  ntain a particul
30890 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74  ar type does not
308a0 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a   mean that the.*
308b0 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e  * data stored in
308c0 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20   that column is 
308d0 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20  of the declared 
308e0 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73  type.  SQLite is
308f0 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70  .** strongly typ
30900 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69  ed, but the typi
30910 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f  ng is dynamic no
30920 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65  t static.  ^Type
30930 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65  .** is associate
30940 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61  d with individua
30950 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69  l values, not wi
30960 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72  th the container
30970 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c  s.** used to hol
30980 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a  d those values..
30990 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
309a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
309b0 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73  cltype(sqlite3_s
309c0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
309d0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
309e0 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36  olumn_decltype16
309f0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
30a00 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
30a10 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41  3REF: Evaluate A
30a20 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a  n SQL Statement.
30a30 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
30a40 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 41 66  e3_stmt.**.** Af
30a50 74 65 72 20 61 20 5b 70 72 65 70 61 72 65 64 20  ter a [prepared 
30a60 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62  statement] has b
30a70 65 65 6e 20 70 72 65 70 61 72 65 64 20 75 73 69  een prepared usi
30a80 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71  ng either.** [sq
30a90 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
30aa0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
30ab0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
30ac0 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65  or one of the le
30ad0 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
30ae0 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  es [sqlite3_prep
30af0 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  are()] or [sqlit
30b00 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c  e3_prepare16()],
30b10 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a   this function.*
30b20 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  * must be called
30b30 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d   one or more tim
30b40 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74  es to evaluate t
30b50 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  he statement..**
30b60 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20  .** The details 
30b70 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  of the behavior 
30b80 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  of the sqlite3_s
30b90 74 65 70 28 29 20 69 6e 74 65 72 66 61 63 65 20  tep() interface 
30ba0 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65  depend.** on whe
30bb0 74 68 65 72 20 74 68 65 20 73 74 61 74 65 6d 65  ther the stateme
30bc0 6e 74 20 77 61 73 20 70 72 65 70 61 72 65 64 20  nt was prepared 
30bd0 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20  using the newer 
30be0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a  "v2" interface.*
30bf0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
30c00 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
30c10 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
30c20 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64  v2()] or the old
30c30 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  er legacy.** int
30c40 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f  erface [sqlite3_
30c50 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b  prepare()] and [
30c60 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
30c70 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f  6()].  The use o
30c80 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32  f the.** new "v2
30c90 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72  " interface is r
30ca0 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e  ecommended for n
30cb0 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ew applications 
30cc0 62 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a  but the legacy.*
30cd0 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  * interface will
30ce0 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20   continue to be 
30cf0 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a  supported..**.**
30d00 20 5e 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20   ^In the legacy 
30d10 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72  interface, the r
30d20 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c  eturn value will
30d30 20 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49   be either [SQLI
30d40 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51  TE_BUSY],.** [SQ
30d50 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c  LITE_DONE], [SQL
30d60 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54  ITE_ROW], [SQLIT
30d70 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51  E_ERROR], or [SQ
30d80 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a  LITE_MISUSE]..**
30d90 20 5e 57 69 74 68 20 74 68 65 20 22 76 32 22 20   ^With the "v2" 
30da0 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f  interface, any o
30db0 66 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73  f the other [res
30dc0 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a  ult codes] or.**
30dd0 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
30de0 74 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62  t codes] might b
30df0 65 20 72 65 74 75 72 6e 65 64 20 61 73 20 77 65  e returned as we
30e00 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49  ll..**.** ^[SQLI
30e10 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74  TE_BUSY] means t
30e20 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65  hat the database
30e30 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62   engine was unab
30e40 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20 74 68  le to acquire th
30e50 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f  e.** database lo
30e60 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20  cks it needs to 
30e70 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66  do its job.  ^If
30e80 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
30e90 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20  s a [COMMIT].** 
30ea0 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64  or occurs outsid
30eb0 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74  e of an explicit
30ec0 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68   transaction, th
30ed0 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79  en you can retry
30ee0 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   the.** statemen
30ef0 74 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65  t.  If the state
30f00 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43  ment is not a [C
30f10 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72  OMMIT] and occur
30f20 73 20 77 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65  s within an.** e
30f30 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
30f40 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f  ion then you sho
30f50 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65  uld rollback the
30f60 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66   transaction bef
30f70 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e  ore.** continuin
30f80 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54  g..**.** ^[SQLIT
30f90 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68  E_DONE] means th
30fa0 61 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  at the statement
30fb0 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78   has finished ex
30fc0 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65  ecuting.** succe
30fd0 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65  ssfully.  sqlite
30fe0 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20  3_step() should 
30ff0 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67  not be called ag
31000 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74  ain on this virt
31010 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77  ual.** machine w
31020 69 74 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c  ithout first cal
31030 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
31040 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20  set()] to reset 
31050 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d  the virtual.** m
31060 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69  achine back to i
31070 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65  ts initial state
31080 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
31090 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65  SQL statement be
310a0 69 6e 67 20 65 78 65 63 75 74 65 64 20 72 65 74  ing executed ret
310b0 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74  urns any data, t
310c0 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  hen [SQLITE_ROW]
310d0 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
310e0 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20  each time a new 
310f0 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20 72  row of data is r
31100 65 61 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73  eady for process
31110 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61  ing by the.** ca
31120 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73  ller. The values
31130 20 6d 61 79 20 62 65 20 61 63 63 65 73 73 65 64   may be accessed
31140 20 75 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75   using the [colu
31150 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
31160 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33  ons]..** sqlite3
31170 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65  _step() is calle
31180 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69  d again to retri
31190 65 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77  eve the next row
311a0 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20   of data..**.** 
311b0 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20  ^[SQLITE_ERROR] 
311c0 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e  means that a run
311d0 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63  -time error (suc
311e0 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e  h as a constrain
311f0 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20  t.** violation) 
31200 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73  has occurred.  s
31210 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68  qlite3_step() sh
31220 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c  ould not be call
31230 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74  ed again on.** t
31240 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f  he VM. More info
31250 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66  rmation may be f
31260 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20  ound by calling 
31270 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
31280 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65  )]..** ^With the
31290 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
312a0 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66  e, a more specif
312b0 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66  ic error code (f
312c0 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b  or example,.** [
312d0 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
312e0 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  ], [SQLITE_SCHEM
312f0 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52  A], [SQLITE_CORR
31300 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72  UPT], and so for
31310 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62  th).** can be ob
31320 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e  tained by callin
31330 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
31340 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70  ()] on the.** [p
31350 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
31360 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22 76 32  t].  ^In the "v2
31370 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20  " interface,.** 
31380 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69  the more specifi
31390 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20  c error code is 
313a0 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c  returned directl
313b0 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65  y by sqlite3_ste
313c0 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49  p()..**.** [SQLI
313d0 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73  TE_MISUSE] means
313e0 20 74 68 61 74 20 74 68 65 20 74 68 69 73 20 72   that the this r
313f0 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65  outine was calle
31400 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c  d inappropriatel
31410 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74  y..** Perhaps it
31420 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61   was called on a
31430 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
31440 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a  ment] that has.*
31450 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b  * already been [
31460 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
31470 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72   | finalized] or
31480 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64   on one that had
31490 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72  .** previously r
314a0 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
314b0 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54  ERROR] or [SQLIT
314c0 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20  E_DONE].  Or it 
314d0 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20  could.** be the 
314e0 63 61 73 65 20 74 68 61 74 20 74 68 65 20 73 61  case that the sa
314f0 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
31500 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20  ection is being 
31510 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a  used by two or.*
31520 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61  * more threads a
31530 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e  t the same momen
31540 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  t in time..**.**
31550 20 46 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e   For all version
31560 73 20 6f 66 20 53 51 4c 69 74 65 20 75 70 20 74  s of SQLite up t
31570 6f 20 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20  o and including 
31580 33 2e 36 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c  3.6.23.1, a call
31590 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
315a0 72 65 73 65 74 28 29 5d 20 77 61 73 20 72 65 71  reset()] was req
315b0 75 69 72 65 64 20 61 66 74 65 72 20 73 71 6c 69  uired after sqli
315c0 74 65 33 5f 73 74 65 70 28 29 20 72 65 74 75 72  te3_step() retur
315d0 6e 65 64 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20  ned anything.** 
315e0 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
315f0 54 45 5f 52 4f 57 5d 20 62 65 66 6f 72 65 20 61  TE_ROW] before a
31600 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e  ny subsequent in
31610 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73  vocation of.** s
31620 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
31630 46 61 69 6c 75 72 65 20 74 6f 20 72 65 73 65 74  Failure to reset
31640 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
31650 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a  atement using .*
31660 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
31670 28 29 5d 20 77 6f 75 6c 64 20 72 65 73 75 6c 74  ()] would result
31680 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d   in an [SQLITE_M
31690 49 53 55 53 45 5d 20 72 65 74 75 72 6e 20 66 72  ISUSE] return fr
316a0 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  om.** sqlite3_st
316b0 65 70 28 29 2e 20 20 42 75 74 20 61 66 74 65 72  ep().  But after
316c0 20 5b 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33   [version 3.6.23
316d0 2e 31 5d 20 28 5b 64 61 74 65 6f 66 3a 33 2e 36  .1] ([dateof:3.6
316e0 2e 32 33 2e 31 5d 2c 0a 2a 2a 20 73 71 6c 69 74  .23.1],.** sqlit
316f0 65 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a  e3_step() began.
31700 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  ** calling [sqli
31710 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74  te3_reset()] aut
31720 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68  omatically in th
31730 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20  is circumstance 
31740 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72  rather.** than r
31750 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45  eturning [SQLITE
31760 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20  _MISUSE].  This 
31770 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65  is not considere
31780 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  d a compatibilit
31790 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75  y.** break becau
317a0 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69  se any applicati
317b0 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72 65 63  on that ever rec
317c0 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f  eives an SQLITE_
317d0 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20  MISUSE error.** 
317e0 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66  is broken by def
317f0 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53  inition.  The [S
31800 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52  QLITE_OMIT_AUTOR
31810 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  ESET] compile-ti
31820 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e  me option.** can
31830 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 73 74   be used to rest
31840 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79 20 62  ore the legacy b
31850 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c  ehavior..**.** <
31860 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63  b>Goofy Interfac
31870 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20  e Alert:</b> In 
31880 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
31890 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65  face, the sqlite
318a0 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20  3_step().** API 
318b0 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61  always returns a
318c0 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63   generic error c
318d0 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52  ode, [SQLITE_ERR
318e0 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  OR], following a
318f0 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65  ny.** error othe
31900 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42  r than [SQLITE_B
31910 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45  USY] and [SQLITE
31920 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d  _MISUSE].  You m
31930 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c  ust call.** [sql
31940 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
31950 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
31960 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74  ze()] in order t
31970 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68  o find one of th
31980 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65  e.** specific [e
31990 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74  rror codes] that
319a0 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65   better describe
319b0 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20  s the error..** 
319c0 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68  We admit that th
319d0 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65  is is a goofy de
319e0 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c  sign.  The probl
319f0 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65  em has been fixe
31a00 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76  d.** with the "v
31a10 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49  2" interface.  I
31a20 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c  f you prepare al
31a30 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74  l of your SQL st
31a40 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e  atements.** usin
31a50 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65  g either [sqlite
31a60 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
31a70 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
31a80 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74  are16_v2()] inst
31a90 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65  ead.** of the le
31aa0 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  gacy [sqlite3_pr
31ab0 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71  epare()] and [sq
31ac0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
31ad0 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a  )] interfaces,.*
31ae0 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20  * then the more 
31af0 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20  specific [error 
31b00 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 72  codes] are retur
31b10 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  ned directly.** 
31b20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  by sqlite3_step(
31b30 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74  ).  The use of t
31b40 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
31b50 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e is recommended
31b60 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
31b70 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74  _step(sqlite3_st
31b80 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
31b90 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66  I3REF: Number of
31ba0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65   columns in a re
31bb0 73 75 6c 74 20 73 65 74 0a 2a 2a 20 4d 45 54 48  sult set.** METH
31bc0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
31bd0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
31be0 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
31bf0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
31c00 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
31c10 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
31c20 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f 77 20  .** current row 
31c30 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
31c40 74 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73  t of [prepared s
31c50 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20  tatement] P..** 
31c60 5e 49 66 20 70 72 65 70 61 72 65 64 20 73 74 61  ^If prepared sta
31c70 74 65 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f  tement P does no
31c80 74 20 68 61 76 65 20 72 65 73 75 6c 74 73 20 72  t have results r
31c90 65 61 64 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a  eady to return.*
31ca0 2a 20 28 76 69 61 20 63 61 6c 6c 73 20 74 6f 20  * (via calls to 
31cb0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  the [sqlite3_col
31cc0 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65  umn_int | sqlite
31cd0 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66  3_column_*()] of
31ce0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 29 20  .** interfaces) 
31cf0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 64 61 74  then sqlite3_dat
31d00 61 5f 63 6f 75 6e 74 28 50 29 20 72 65 74 75 72  a_count(P) retur
31d10 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  ns 0..** ^The sq
31d20 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
31d30 28 50 29 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f  (P) routine also
31d40 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 50 20   returns 0 if P 
31d50 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
31d60 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  r..** ^The sqlit
31d70 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
31d80 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
31d90 20 30 20 69 66 20 74 68 65 20 70 72 65 76 69 6f   0 if the previo
31da0 75 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  us call to.** [s
31db0 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20  qlite3_step](P) 
31dc0 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
31dd0 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71  _DONE].  ^The sq
31de0 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
31df0 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75  (P).** will retu
31e00 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70  rn non-zero if p
31e10 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20  revious call to 
31e20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50  [sqlite3_step](P
31e30 29 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53  ) returned.** [S
31e40 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65  QLITE_ROW], exce
31e50 70 74 20 69 6e 20 74 68 65 20 63 61 73 65 20 6f  pt in the case o
31e60 66 20 74 68 65 20 5b 50 52 41 47 4d 41 20 69 6e  f the [PRAGMA in
31e70 63 72 65 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d  cremental_vacuum
31e80 5d 0a 2a 2a 20 77 68 65 72 65 20 69 74 20 61 6c  ].** where it al
31e90 77 61 79 73 20 72 65 74 75 72 6e 73 20 7a 65 72  ways returns zer
31ea0 6f 20 73 69 6e 63 65 20 65 61 63 68 20 73 74 65  o since each ste
31eb0 70 20 6f 66 20 74 68 61 74 20 6d 75 6c 74 69 2d  p of that multi-
31ec0 73 74 65 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72  step.** pragma r
31ed0 65 74 75 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73  eturns 0 columns
31ee0 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20   of data..**.** 
31ef0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
31f00 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
31f10 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  )].*/.int sqlite
31f20 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c  3_data_count(sql
31f30 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
31f40 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
31f50 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20  EF: Fundamental 
31f60 44 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59  Datatypes.** KEY
31f70 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45  WORDS: SQLITE_TE
31f80 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79  XT.**.** ^(Every
31f90 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65   value in SQLite
31fa0 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65   has one of five
31fb0 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74   fundamental dat
31fc0 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  atypes:.**.** <u
31fd0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69  l>.** <li> 64-bi
31fe0 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
31ff0 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20  .** <li> 64-bit 
32000 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f  IEEE floating po
32010 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c  int number.** <l
32020 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69  i> string.** <li
32030 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e  > BLOB.** <li> N
32040 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a  ULL.** </ul>)^.*
32050 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
32060 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 66  ants are codes f
32070 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65  or each of those
32080 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f   types..**.** No
32090 74 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 49  te that the SQLI
320a0 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74  TE_TEXT constant
320b0 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69   was also used i
320c0 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  n SQLite version
320d0 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70   2.** for a comp
320e0 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74  letely different
320f0 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77   meaning.  Softw
32100 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61  are that links a
32110 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53  gainst both.** S
32120 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20  QLite version 2 
32130 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69  and SQLite versi
32140 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20  on 3 should use 
32150 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f  SQLITE3_TEXT, no
32160 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54  t.** SQLITE_TEXT
32170 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
32180 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23  ITE_INTEGER  1.#
32190 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c  define SQLITE_FL
321a0 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65  OAT    2.#define
321b0 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20   SQLITE_BLOB    
321c0 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
321d0 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66  E_NULL     5.#if
321e0 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  def SQLITE_TEXT.
321f0 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54  # undef SQLITE_T
32200 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69  EXT.#else.# defi
32210 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20  ne SQLITE_TEXT  
32220 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66     3.#endif.#def
32230 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54  ine SQLITE3_TEXT
32240 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41       3../*.** CA
32250 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56  PI3REF: Result V
32260 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65  alues From A Que
32270 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ry.** KEYWORDS: 
32280 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66  {column access f
32290 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54  unctions}.** MET
322a0 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
322b0 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  t.**.** ^These r
322c0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69  outines return i
322d0 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74  nformation about
322e0 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e   a single column
322f0 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a   of the current.
32300 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66  ** result row of
32310 20 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20 65   a query.  ^In e
32320 76 65 72 79 20 63 61 73 65 20 74 68 65 20 66 69  very case the fi
32330 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
32340 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  a pointer.** to 
32350 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
32360 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73  atement] that is
32370 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64   being evaluated
32380 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73   (the [sqlite3_s
32390 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61  tmt*].** that wa
323a0 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20  s returned from 
323b0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
323c0 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66  _v2()] or one of
323d0 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a   its variants).*
323e0 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  * and the second
323f0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
32400 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f   index of the co
32410 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69  lumn for which i
32420 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68  nformation.** sh
32430 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64  ould be returned
32440 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20  . ^The leftmost 
32450 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65  column of the re
32460 73 75 6c 74 20 73 65 74 20 68 61 73 20 74 68 65  sult set has the
32470 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68   index 0..** ^Th
32480 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
32490 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c  mns in the resul
324a0 74 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69  t can be determi
324b0 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ned using.** [sq
324c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75  lite3_column_cou
324d0 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  nt()]..**.** If 
324e0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
324f0 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65  t does not curre
32500 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20  ntly point to a 
32510 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66  valid row, or if
32520 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69   the.** column i
32530 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72  ndex is out of r
32540 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74  ange, the result
32550 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
32560 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
32570 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c   may only be cal
32580 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73  led when the mos
32590 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
325a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
325b0 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65  p()] has returne
325c0 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61  d [SQLITE_ROW] a
325d0 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73  nd neither.** [s
325e0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
325f0 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  nor [sqlite3_fin
32600 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65  alize()] have be
32610 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71  en called subseq
32620 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e  uently..** If an
32630 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  y of these routi
32640 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61  nes are called a
32650 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  fter [sqlite3_re
32660 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  set()] or.** [sq
32670 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
32680 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69  ] or after [sqli
32690 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
326a0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65  returned.** some
326b0 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e  thing other than
326c0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74   [SQLITE_ROW], t
326d0 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
326e0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20  ndefined..** If 
326f0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
32700 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   or [sqlite3_res
32710 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  et()] or [sqlite
32720 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a  3_finalize()].**
32730 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d   are called from
32740 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 72   a different thr
32750 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66  ead while any of
32760 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a   these routines.
32770 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20  ** are pending, 
32780 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
32790 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
327a0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
327b0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
327c0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
327d0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
327e0 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79  INTEGER | dataty
327f0 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65  pe code] for the
32800 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79   initial data ty
32810 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73  pe.** of the res
32820 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68  ult column.  ^Th
32830 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65  e returned value
32840 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   is one of [SQLI
32850 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20  TE_INTEGER],.** 
32860 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20  [SQLITE_FLOAT], 
32870 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b  [SQLITE_TEXT], [
32880 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72  SQLITE_BLOB], or
32890 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20   [SQLITE_NULL]. 
328a0 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65   The value.** re
328b0 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
328c0 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
328d0 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66  is only meaningf
328e0 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a  ul if no type.**
328f0 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76   conversions hav
32900 65 20 6f 63 63 75 72 72 65 64 20 61 73 20 64 65  e occurred as de
32910 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20  scribed below.  
32920 41 66 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e  After a type con
32930 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20  version,.** the 
32940 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
32950 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
32960 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64 65 66  _type() is undef
32970 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a  ined.  Future.**
32980 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
32990 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74  ite may change t
329a0 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73  he behavior of s
329b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
329c0 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  pe().** followin
329d0 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73  g a type convers
329e0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ion..**.** ^If t
329f0 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42  he result is a B
32a00 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72  LOB or UTF-8 str
32a10 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c  ing then the sql
32a20 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
32a30 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72  s().** routine r
32a40 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
32a50 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
32a60 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e  at BLOB or strin
32a70 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
32a80 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36  sult is a UTF-16
32a90 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71   string, then sq
32aa0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
32ab0 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a  es() converts.**
32ac0 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55   the string to U
32ad0 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65  TF-8 and then re
32ae0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
32af0 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49   of bytes..** ^I
32b00 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
32b10 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20  a numeric value 
32b20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
32b30 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73  umn_bytes() uses
32b40 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  .** [sqlite3_snp
32b50 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76  rintf()] to conv
32b60 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74  ert that value t
32b70 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67  o a UTF-8 string
32b80 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20   and returns.** 
32b90 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
32ba0 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69  tes in that stri
32bb0 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
32bc0 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74  esult is NULL, t
32bd0 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
32be0 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75 72  mn_bytes() retur
32bf0 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e  ns zero..**.** ^
32c00 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
32c10 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31   a BLOB or UTF-1
32c20 36 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68  6 string then th
32c30 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
32c40 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f  _bytes16().** ro
32c50 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
32c60 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
32c70 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f  s in that BLOB o
32c80 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  r string..** ^If
32c90 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
32ca0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20 74   UTF-8 string, t
32cb0 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
32cc0 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f 6e  mn_bytes16() con
32cd0 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72  verts.** the str
32ce0 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61 6e  ing to UTF-16 an
32cf0 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74  d then returns t
32d00 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
32d10 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  es..** ^If the r
32d20 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72  esult is a numer
32d30 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71  ic value then sq
32d40 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
32d50 65 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b  es16() uses.** [
32d60 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
32d70 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ()] to convert t
32d80 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55  hat value to a U
32d90 54 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e 64  TF-16 string and
32da0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20   returns.** the 
32db0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
32dc0 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a  in that string..
32dd0 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
32de0 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  t is NULL, then 
32df0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
32e00 79 74 65 73 31 36 28 29 20 72 65 74 75 72 6e 73  ytes16() returns
32e10 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   zero..**.** ^Th
32e20 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65  e values returne
32e30 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d by [sqlite3_co
32e40 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e  lumn_bytes()] an
32e50 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  d .** [sqlite3_c
32e60 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d  olumn_bytes16()]
32e70 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20   do not include 
32e80 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  the zero termina
32e90 74 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64 0a  tors at the end.
32ea0 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67  ** of the string
32eb0 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a  .  ^For clarity:
32ec0 20 74 68 65 20 76 61 6c 75 65 73 20 72 65 74 75   the values retu
32ed0 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
32ee0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
32ef0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
32f00 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
32f10 29 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62 65  )] are the numbe
32f20 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e  r of.** bytes in
32f30 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74   the string, not
32f40 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
32f50 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a  haracters..**.**
32f60 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e   ^Strings return
32f70 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
32f80 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20  lumn_text() and 
32f90 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
32fa0 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e  ext16(),.** even
32fb0 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20   empty strings, 
32fc0 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d  are always zero-
32fd0 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68  terminated.  ^Th
32fe0 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75  e return.** valu
32ff0 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63  e from sqlite3_c
33000 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72  olumn_blob() for
33010 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42   a zero-length B
33020 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  LOB is a NULL po
33030 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  inter..**.** <b>
33040 57 61 72 6e 69 6e 67 3a 3c 2f 62 3e 20 5e 54 68  Warning:</b> ^Th
33050 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  e object returne
33060 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d by [sqlite3_co
33070 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73  lumn_value()] is
33080 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63   an.** [unprotec
33090 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
330a0 65 5d 20 6f 62 6a 65 63 74 2e 20 20 49 6e 20 61  e] object.  In a
330b0 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 20 65   multithreaded e
330c0 6e 76 69 72 6f 6e 6d 65 6e 74 2c 0a 2a 2a 20 61  nvironment,.** a
330d0 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  n unprotected sq
330e0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
330f0 63 74 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75  ct may only be u
33100 73 65 64 20 73 61 66 65 6c 79 20 77 69 74 68 0a  sed safely with.
33110 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
33120 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73  _value()] and [s
33130 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
33140 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68  lue()]..** If th
33150 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  e [unprotected s
33160 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
33170 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79  ject returned by
33180 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
33190 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
331a0 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65  used in any othe
331b0 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67  r way, including
331c0 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75   calls.** to rou
331d0 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69  tines like [sqli
331e0 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d  te3_value_int()]
331f0 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
33200 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20  _text()],.** or 
33210 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
33220 79 74 65 73 28 29 5d 2c 20 74 68 65 20 62 65 68  ytes()], the beh
33230 61 76 69 6f 72 20 69 73 20 6e 6f 74 20 74 68 72  avior is not thr
33240 65 61 64 73 61 66 65 2e 0a 2a 2a 0a 2a 2a 20 54  eadsafe..**.** T
33250 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74  hese routines at
33260 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74  tempt to convert
33270 20 74 68 65 20 76 61 6c 75 65 20 77 68 65 72 65   the value where
33280 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20 5e   appropriate.  ^
33290 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20  For.** example, 
332a0 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  if the internal 
332b0 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69  representation i
332c0 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65  s FLOAT and a te
332d0 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20  xt result.** is 
332e0 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69  requested, [sqli
332f0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
33300 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c  is used internal
33310 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68  ly to perform th
33320 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20  e.** conversion 
33330 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20  automatically.  
33340 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  ^(The following 
33350 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68  table details th
33360 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a  e conversions.**
33370 20 74 68 61 74 20 61 72 65 20 61 70 70 6c 69 65   that are applie
33380 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  d:.**.** <blockq
33390 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20  uote>.** <table 
333a0 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c  border="1">.** <
333b0 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c  tr><th> Internal
333c0 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65  <br>Type <th> Re
333d0 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20  quested<br>Type 
333e0 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e  <th>  Conversion
333f0 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  .**.** <tr><td> 
33400 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e   NULL    <td> IN
33410 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73  TEGER   <td> Res
33420 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e  ult is 0.** <tr>
33430 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
33440 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
33450 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a  > Result is 0.0.
33460 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
33470 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54  L    <td>   TEXT
33480 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
33490 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
334a0 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  r.** <tr><td>  N
334b0 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c  ULL    <td>   BL
334c0 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  OB    <td> Resul
334d0 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  t is a NULL poin
334e0 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ter.** <tr><td> 
334f0 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46  INTEGER  <td>  F
33500 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e  LOAT    <td> Con
33510 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65  vert from intege
33520 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74  r to float.** <t
33530 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20  r><td> INTEGER  
33540 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
33550 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72  td> ASCII render
33560 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67  ing of the integ
33570 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49  er.** <tr><td> I
33580 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42  NTEGER  <td>   B
33590 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65  LOB    <td> Same
335a0 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58   as INTEGER->TEX
335b0 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  T.** <tr><td>  F
335c0 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45  LOAT   <td> INTE
335d0 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54  GER   <td> [CAST
335e0 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20  ] to INTEGER.** 
335f0 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
33600 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
33610 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64   <td> ASCII rend
33620 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f  ering of the flo
33630 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  at.** <tr><td>  
33640 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42  FLOAT   <td>   B
33650 4c 4f 42 20 20 20 20 3c 74 64 3e 20 5b 43 41 53  LOB    <td> [CAS
33660 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a 20 3c 74  T] to BLOB.** <t
33670 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
33680 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
33690 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e  td> [CAST] to IN
336a0 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64  TEGER.** <tr><td
336b0 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
336c0 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b   FLOAT    <td> [
336d0 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a  CAST] to REAL.**
336e0 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
336f0 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
33700 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65    <td> No change
33710 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
33720 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  OB    <td> INTEG
33730 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d  ER   <td> [CAST]
33740 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c   to INTEGER.** <
33750 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
33760 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
33770 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52  <td> [CAST] to R
33780 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  EAL.** <tr><td> 
33790 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20   BLOB    <td>   
337a0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64  TEXT    <td> Add
337b0 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74   a zero terminat
337c0 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20  or if needed.** 
337d0 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c  </table>.** </bl
337e0 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a  ockquote>)^.**.*
337f0 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e  * Note that when
33800 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
33810 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72  s occur, pointer
33820 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72  s returned by pr
33830 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ior.** calls to 
33840 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
33850 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63  lob(), sqlite3_c
33860 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e  olumn_text(), an
33870 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  d/or.** sqlite3_
33880 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
33890 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74  may be invalidat
338a0 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76  ed..** Type conv
338b0 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e  ersions and poin
338c0 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e  ter invalidation
338d0 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a  s might occur.**
338e0 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   in the followin
338f0 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c  g cases:.**.** <
33900 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  ul>.** <li> The 
33910 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
33920 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71  is a BLOB and sq
33930 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
33940 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73  t() or.**      s
33950 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
33960 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64  xt16() is called
33970 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  .  A zero-termin
33980 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20  ator might.**   
33990 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64     need to be ad
339a0 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e  ded to the strin
339b0 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20  g.</li>.** <li> 
339c0 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
339d0 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 78  ent is UTF-8 tex
339e0 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  t and sqlite3_co
339f0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f  lumn_bytes16() o
33a00 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65  r.**      sqlite
33a10 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
33a20 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68  ) is called.  Th
33a30 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62  e content must b
33a40 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20  e converted.**  
33a50 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f      to UTF-16.</
33a60 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  li>.** <li> The 
33a70 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
33a80 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61  is UTF-16 text a
33a90 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
33aa0 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20  n_bytes() or.** 
33ab0 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c       sqlite3_col
33ac0 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61  umn_text() is ca
33ad0 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65  lled.  The conte
33ae0 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  nt must be conve
33af0 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20  rted.**      to 
33b00 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c  UTF-8.</li>.** <
33b10 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76  /ul>.**.** ^Conv
33b20 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20  ersions between 
33b30 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46  UTF-16be and UTF
33b40 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73  -16le are always
33b50 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61   done in place a
33b60 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76  nd do.** not inv
33b70 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20  alidate a prior 
33b80 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20  pointer, though 
33b90 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f  of course the co
33ba0 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66  ntent of the buf
33bb0 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  fer.** that the 
33bc0 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 65  prior pointer re
33bd0 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 61  ferences will ha
33be0 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64  ve been modified
33bf0 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a  .  Other kinds.*
33c00 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20  * of conversion 
33c10 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63  are done in plac
33c20 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73  e when it is pos
33c30 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74  sible, but somet
33c40 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65  imes they.** are
33c50 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e   not possible an
33c60 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73  d in those cases
33c70 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20   prior pointers 
33c80 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e  are invalidated.
33c90 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73  .**.** The safes
33ca0 74 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69  t policy is to i
33cb0 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74  nvoke these rout
33cc0 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f  ines.** in one o
33cd0 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
33ce0 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ways:.**.** <ul>
33cf0 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
33d00 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66  _column_text() f
33d10 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
33d20 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
33d30 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  )</li>.**  <li>s
33d40 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
33d50 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  ob() followed by
33d60 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
33d70 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  bytes()</li>.** 
33d80 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
33d90 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c  umn_text16() fol
33da0 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
33db0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
33dc0 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  )</li>.** </ul>.
33dd0 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77  **.** In other w
33de0 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64  ords, you should
33df0 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f   call sqlite3_co
33e00 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20  lumn_text(),.** 
33e10 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
33e20 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65  lob(), or sqlite
33e30 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
33e40 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65  ) first to force
33e50 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69   the result.** i
33e60 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 20  nto the desired 
33e70 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76  format, then inv
33e80 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  oke sqlite3_colu
33e90 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a  mn_bytes() or.**
33ea0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
33eb0 62 79 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e  bytes16() to fin
33ec0 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  d the size of th
33ed0 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f  e result.  Do no
33ee0 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74  t mix calls.** t
33ef0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
33f00 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74  _text() or sqlit
33f10 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
33f20 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a   with calls to.*
33f30 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
33f40 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20  _bytes16(), and 
33f50 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73  do not mix calls
33f60 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
33f70 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77  mn_text16().** w
33f80 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  ith calls to sql
33f90 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
33fa0 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  s()..**.** ^The 
33fb0 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
33fc0 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69  d are valid unti
33fd0 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73  l a type convers
33fe0 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a  ion occurs as.**
33ff0 20 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 65   described above
34000 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69  , or until [sqli
34010 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b  te3_step()] or [
34020 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
34030 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
34040 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63  finalize()] is c
34050 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d  alled.  ^The mem
34060 6f 72 79 20 73 70 61 63 65 20 75 73 65 64 20 74  ory space used t
34070 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a  o hold strings.*
34080 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66  * and BLOBs is f
34090 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c  reed automatical
340a0 6c 79 2e 20 20 44 6f 20 3c 65 6d 3e 6e 6f 74 3c  ly.  Do <em>not<
340b0 2f 65 6d 3e 20 70 61 73 73 20 74 68 65 20 70 6f  /em> pass the po
340c0 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a  inters returned.
340d0 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ** from [sqlite3
340e0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c  _column_blob()],
340f0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
34100 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69  _text()], etc. i
34110 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nto.** [sqlite3_
34120 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  free()]..**.** ^
34130 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c  (If a memory all
34140 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63  ocation error oc
34150 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 65 20  curs during the 
34160 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e  evaluation of an
34170 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f  y.** of these ro
34180 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c  utines, a defaul
34190 74 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72  t value is retur
341a0 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c  ned.  The defaul
341b0 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69  t value.** is ei
341c0 74 68 65 72 20 74 68 65 20 69 6e 74 65 67 65 72  ther the integer
341d0 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67   0, the floating
341e0 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e   point number 0.
341f0 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20  0, or a NULL.** 
34200 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71  pointer.  Subseq
34210 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73  uent calls to [s
34220 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
34230 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a  ] will return.**
34240 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e   [SQLITE_NOMEM].
34250 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64  )^.*/.const void
34260 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
34270 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  _blob(sqlite3_st
34280 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
34290 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
342a0 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33  mn_bytes(sqlite3
342b0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
342c0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
342d0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71  olumn_bytes16(sq
342e0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
342f0 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73   iCol);.double s
34300 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f  qlite3_column_do
34310 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  uble(sqlite3_stm
34320 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
34330 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
34340 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  n_int(sqlite3_st
34350 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
34360 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
34370 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
34380 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
34390 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e  , int iCol);.con
343a0 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72  st unsigned char
343b0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
343c0 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74  _text(sqlite3_st
343d0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
343e0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
343f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
34400 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
34410 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20   int iCol);.int 
34420 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
34430 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ype(sqlite3_stmt
34440 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71  *, int iCol);.sq
34450 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c  lite3_value *sql
34460 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
34470 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
34480 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a   int iCol);../*.
34490 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 73  ** CAPI3REF: Des
344a0 74 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 20  troy A Prepared 
344b0 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
344c0 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f 52 3a 20  .** DESTRUCTOR: 
344d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
344e0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
344f0 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74  finalize() funct
34500 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f  ion is called to
34510 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61   delete a [prepa
34520 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
34530 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  ** ^If the most 
34540 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f  recent evaluatio
34550 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65  n of the stateme
34560 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e  nt encountered n
34570 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 20 69  o errors.** or i
34580 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
34590 69 73 20 6e 65 76 65 72 20 62 65 65 6e 20 65 76  is never been ev
345a0 61 6c 75 61 74 65 64 2c 20 74 68 65 6e 20 73 71  aluated, then sq
345b0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
345c0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49   returns.** SQLI
345d0 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65 20  TE_OK.  ^If the 
345e0 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c  most recent eval
345f0 75 61 74 69 6f 6e 20 6f 66 20 73 74 61 74 65 6d  uation of statem
34600 65 6e 74 20 53 20 66 61 69 6c 65 64 2c 20 74 68  ent S failed, th
34610 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69  en.** sqlite3_fi
34620 6e 61 6c 69 7a 65 28 53 29 20 72 65 74 75 72 6e  nalize(S) return
34630 73 20 74 68 65 20 61 70 70 72 6f 70 72 69 61 74  s the appropriat
34640 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f  e [error code] o
34650 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 65  r.** [extended e
34660 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a  rror code]..**.*
34670 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66  * ^The sqlite3_f
34680 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75 74 69  inalize(S) routi
34690 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64  ne can be called
346a0 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75   at any point du
346b0 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66 65  ring.** the life
346c0 20 63 79 63 6c 65 20 6f 66 20 5b 70 72 65 70 61   cycle of [prepa
346d0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
346e0 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74 61 74  :.** before stat
346f0 65 6d 65 6e 74 20 53 20 69 73 20 65 76 65 72 20  ement S is ever 
34700 65 76 61 6c 75 61 74 65 64 2c 20 61 66 74 65 72  evaluated, after
34710 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  .** one or more 
34720 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
34730 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72 20 61  3_reset()], or a
34740 66 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a  fter any call.**
34750 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
34760 70 28 29 5d 20 72 65 67 61 72 64 6c 65 73 73 20  p()] regardless 
34770 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
34780 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  t the statement 
34790 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64  has.** completed
347a0 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a   execution..**.*
347b0 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c 69  * ^Invoking sqli
347c0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 6f  te3_finalize() o
347d0 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  n a NULL pointer
347e0 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e   is a harmless n
347f0 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  o-op..**.** The 
34800 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
34810 20 66 69 6e 61 6c 69 7a 65 20 65 76 65 72 79 20   finalize every 
34820 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
34830 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f  ent] in order to
34840 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 72   avoid.** resour
34850 63 65 20 6c 65 61 6b 73 2e 20 20 49 74 20 69 73  ce leaks.  It is
34860 20 61 20 67 72 69 65 76 6f 75 73 20 65 72 72 6f   a grievous erro
34870 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63  r for the applic
34880 61 74 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f 20  ation to try to 
34890 75 73 65 0a 2a 2a 20 61 20 70 72 65 70 61 72 65  use.** a prepare
348a0 64 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65  d statement afte
348b0 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69  r it has been fi
348c0 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75 73  nalized.  Any us
348d0 65 20 6f 66 20 61 20 70 72 65 70 61 72 65 64 0a  e of a prepared.
348e0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74  ** statement aft
348f0 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 66  er it has been f
34900 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72 65 73  inalized can res
34910 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64  ult in undefined
34920 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72 61   and.** undesira
34930 62 6c 65 20 62 65 68 61 76 69 6f 72 20 73 75 63  ble behavior suc
34940 68 20 61 73 20 73 65 67 66 61 75 6c 74 73 20 61  h as segfaults a
34950 6e 64 20 68 65 61 70 20 63 6f 72 72 75 70 74 69  nd heap corrupti
34960 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  on..*/.int sqlit
34970 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69  e3_finalize(sqli
34980 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
34990 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
349a0 46 3a 20 52 65 73 65 74 20 41 20 50 72 65 70 61  F: Reset A Prepa
349b0 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  red Statement Ob
349c0 6a 65 63 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ject.** METHOD: 
349d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
349e0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
349f0 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20  eset() function 
34a00 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73  is called to res
34a10 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  et a [prepared s
34a20 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a  tatement].** obj
34a30 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20  ect back to its 
34a40 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72  initial state, r
34a50 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78  eady to be re-ex
34a60 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20  ecuted..** ^Any 
34a70 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61  SQL statement va
34a80 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64  riables that had
34a90 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f   values bound to
34aa0 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74   them using.** t
34ab0 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
34ac0 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
34ad0 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65  bind_*() API] re
34ae0 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65  tain their value
34af0 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74  s..** Use [sqlit
34b00 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67  e3_clear_binding
34b10 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68  s()] to reset th
34b20 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a  e bindings..**.*
34b30 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
34b40 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66  reset(S)] interf
34b50 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20 5b  ace resets the [
34b60 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
34b70 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f  nt] S.** back to
34b80 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
34b90 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a  f its program..*
34ba0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73  *.** ^If the mos
34bb0 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
34bc0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
34bd0 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70  )] for the.** [p
34be0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
34bf0 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53  t] S returned [S
34c00 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53  QLITE_ROW] or [S
34c10 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20  QLITE_DONE],.** 
34c20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73  or if [sqlite3_s
34c30 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65  tep(S)] has neve
34c40 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61  r before been ca
34c50 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68  lled on S,.** th
34c60 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  en [sqlite3_rese
34c70 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53  t(S)] returns [S
34c80 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a  QLITE_OK]..**.**
34c90 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
34ca0 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
34cb0 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66  lite3_step(S)] f
34cc0 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  or the.** [prepa
34cd0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
34ce0 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72   indicated an er
34cf0 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71  ror, then.** [sq
34d00 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
34d10 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f  returns an appro
34d20 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f  priate [error co
34d30 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  de]..**.** ^The 
34d40 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
34d50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65  )] interface doe
34d60 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
34d70 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e   values.** of an
34d80 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  y [sqlite3_bind_
34d90 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f  blob|bindings] o
34da0 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  n the [prepared 
34db0 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f  statement] S..*/
34dc0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73  .int sqlite3_res
34dd0 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  et(sqlite3_stmt 
34de0 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
34df0 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65  CAPI3REF: Create
34e00 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c   Or Redefine SQL
34e10 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45   Functions.** KE
34e20 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f  YWORDS: {functio
34e30 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69  n creation routi
34e40 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  nes}.** KEYWORDS
34e50 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  : {application-d
34e60 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
34e70 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ion}.** KEYWORDS
34e80 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  : {application-d
34e90 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
34ea0 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a  ions}.** METHOD:
34eb0 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
34ec0 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
34ed0 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e  (collectively kn
34ee0 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e  own as "function
34ef0 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e   creation routin
34f00 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64  es").** are used
34f10 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63   to add SQL func
34f20 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61  tions or aggrega
34f30 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69  tes or to redefi
34f40 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a  ne the behavior.
34f50 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53  ** of existing S
34f60 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20  QL functions or 
34f70 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 65  aggregates.  The
34f80 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65   only difference
34f90 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65  s between.** the
34fa0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
34fb0 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  the text encodin
34fc0 67 20 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a  g expected for.*
34fd0 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * the second par
34fe0 61 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65  ameter (the name
34ff0 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
35000 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a   being created).
35010 2a 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73 65  ** and the prese
35020 6e 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f  nce or absence o
35030 66 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 63  f a destructor c
35040 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74  allback for.** t
35050 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
35060 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ata pointer..**.
35070 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61  ** ^The first pa
35080 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b  rameter is the [
35090 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
350a0 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68  ion] to which th
350b0 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f  e SQL.** functio
350c0 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64 65 64  n is to be added
350d0 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63  .  ^If an applic
350e0 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20  ation uses more 
350f0 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73  than one databas
35100 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
35110 74 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  then application
35120 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
35130 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61  ctions must be a
35140 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20  dded.** to each 
35150 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
35160 69 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a  ion separately..
35170 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e  **.** ^The secon
35180 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
35190 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53  he name of the S
351a0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  QL function to b
351b0 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20  e created or.** 
351c0 72 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65  redefined.  ^The
351d0 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e   length of the n
351e0 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74  ame is limited t
351f0 6f 20 32 35 35 20 62 79 74 65 73 20 69 6e 20 61  o 255 bytes in a
35200 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73   UTF-8.** repres
35210 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73  entation, exclus
35220 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d  ive of the zero-
35230 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f  terminator.  ^No
35240 74 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65  te that the name
35250 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74  .** length limit
35260 20 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74   is in UTF-8 byt
35270 65 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65  es, not characte
35280 72 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79  rs nor UTF-16 by
35290 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61  tes.  .** ^Any a
352a0 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65  ttempt to create
352b0 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68   a function with
352c0 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a   a longer name.*
352d0 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e  * will result in
352e0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
352f0 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e   being returned.
35300 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72  .**.** ^The thir
35310 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72  d parameter (nAr
35320 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d  g).** is the num
35330 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
35340 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 66 75   that the SQL fu
35350 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67  nction or.** agg
35360 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49  regate takes. ^I
35370 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72  f this parameter
35380 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65   is -1, then the
35390 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
353a0 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61  .** aggregate ma
353b0 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65  y take any numbe
353c0 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62  r of arguments b
353d0 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65  etween 0 and the
353e0 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79   limit.** set by
353f0 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d   [sqlite3_limit]
35400 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  ([SQLITE_LIMIT_F
35410 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20  UNCTION_ARG]).  
35420 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  If the third.** 
35430 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73  parameter is les
35440 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65  s than -1 or gre
35450 61 74 65 72 20 74 68 61 6e 20 31 32 37 20 74 68  ater than 127 th
35460 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
35470 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e  is.** undefined.
35480 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72  .**.** ^The four
35490 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54  th parameter, eT
354a0 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 65  extRep, specifie
354b0 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54  s what.** [SQLIT
354c0 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e  E_UTF8 | text en
354d0 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c  coding] this SQL
354e0 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72   function prefer
354f0 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72  s for.** its par
35500 61 6d 65 74 65 72 73 2e 20 20 54 68 65 20 61 70  ameters.  The ap
35510 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
35520 20 73 65 74 20 74 68 69 73 20 70 61 72 61 6d 65   set this parame
35530 74 65 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54  ter to.** [SQLIT
35540 45 5f 55 54 46 31 36 4c 45 5d 20 69 66 20 74 68  E_UTF16LE] if th
35550 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  e function imple
35560 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65  mentation invoke
35570 73 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  s .** [sqlite3_v
35580 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 5d  alue_text16le()]
35590 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72   on an input, or
355a0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45   [SQLITE_UTF16BE
355b0 5d 20 69 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c  ] if the.** impl
355c0 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b  ementation invok
355d0 65 73 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  es [sqlite3_valu
355e0 65 5f 74 65 78 74 31 36 62 65 28 29 5d 20 6f 6e  e_text16be()] on
355f0 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 0a 2a 2a   an input, or.**
35600 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20   [SQLITE_UTF16] 
35610 69 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  if [sqlite3_valu
35620 65 5f 74 65 78 74 31 36 28 29 5d 20 69 73 20 75  e_text16()] is u
35630 73 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  sed, or [SQLITE_
35640 55 54 46 38 5d 0a 2a 2a 20 6f 74 68 65 72 77 69  UTF8].** otherwi
35650 73 65 2e 20 20 5e 54 68 65 20 73 61 6d 65 20 53  se.  ^The same S
35660 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20  QL function may 
35670 62 65 20 72 65 67 69 73 74 65 72 65 64 20 6d 75  be registered mu
35680 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 73 69  ltiple times usi
35690 6e 67 0a 2a 2a 20 64 69 66 66 65 72 65 6e 74 20  ng.** different 
356a0 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65  preferred text e
356b0 6e 63 6f 64 69 6e 67 73 2c 20 77 69 74 68 20 64  ncodings, with d
356c0 69 66 66 65 72 65 6e 74 20 69 6d 70 6c 65 6d 65  ifferent impleme
356d0 6e 74 61 74 69 6f 6e 73 20 66 6f 72 0a 2a 2a 20  ntations for.** 
356e0 65 61 63 68 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a  each encoding..*
356f0 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65  * ^When multiple
35700 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
35710 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e   of the same fun
35720 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61  ction are availa
35730 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77  ble, SQLite.** w
35740 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65  ill pick the one
35750 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74   that involves t
35760 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20  he least amount 
35770 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69  of data conversi
35780 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  on..**.** ^The f
35790 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
357a0 6d 61 79 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 62  may optionally b
357b0 65 20 4f 52 65 64 20 77 69 74 68 20 5b 53 51 4c  e ORed with [SQL
357c0 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49  ITE_DETERMINISTI
357d0 43 5d 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20  C].** to signal 
357e0 74 68 61 74 20 74 68 65 20 66 75 6e 63 74 69 6f  that the functio
357f0 6e 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65  n will always re
35800 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20 72 65  turn the same re
35810 73 75 6c 74 20 67 69 76 65 6e 0a 2a 2a 20 74 68  sult given.** th
35820 65 20 73 61 6d 65 20 69 6e 70 75 74 73 20 77 69  e same inputs wi
35830 74 68 69 6e 20 61 20 73 69 6e 67 6c 65 20 53 51  thin a single SQ
35840 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 4d 6f  L statement.  Mo
35850 73 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  st SQL functions
35860 20 61 72 65 0a 2a 2a 20 64 65 74 65 72 6d 69 6e   are.** determin
35870 69 73 74 69 63 2e 20 20 54 68 65 20 62 75 69 6c  istic.  The buil
35880 74 2d 69 6e 20 5b 72 61 6e 64 6f 6d 28 29 5d 20  t-in [random()] 
35890 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
358a0 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 61 0a  an example of a.
358b0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  ** function that
358c0 20 69 73 20 6e 6f 74 20 64 65 74 65 72 6d 69 6e   is not determin
358d0 69 73 74 69 63 2e 20 20 54 68 65 20 53 51 4c 69  istic.  The SQLi
358e0 74 65 20 71 75 65 72 79 20 70 6c 61 6e 6e 65 72  te query planner
358f0 20 69 73 20 61 62 6c 65 20 74 6f 0a 2a 2a 20 70   is able to.** p
35900 65 72 66 6f 72 6d 20 61 64 64 69 74 69 6f 6e 61  erform additiona
35910 6c 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20  l optimizations 
35920 6f 6e 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63  on deterministic
35930 20 66 75 6e 63 74 69 6f 6e 73 2c 20 73 6f 20 75   functions, so u
35940 73 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51  se.** of the [SQ
35950 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54  LITE_DETERMINIST
35960 49 43 5d 20 66 6c 61 67 20 69 73 20 72 65 63 6f  IC] flag is reco
35970 6d 6d 65 6e 64 65 64 20 77 68 65 72 65 20 70 6f  mmended where po
35980 73 73 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ssible..**.** ^(
35990 54 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65  The fifth parame
359a0 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72  ter is an arbitr
359b0 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68  ary pointer.  Th
359c0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
359d0 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74   of the.** funct
359e0 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63  ion can gain acc
359f0 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e  ess to this poin
35a00 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ter using [sqlit
35a10 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e  e3_user_data()].
35a20 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69  )^.**.** ^The si
35a30 78 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e 64  xth, seventh and
35a40 20 65 69 67 68 74 68 20 70 61 72 61 6d 65 74 65   eighth paramete
35a50 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70  rs, xFunc, xStep
35a60 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65   and xFinal, are
35a70 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  .** pointers to 
35a80 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74  C-language funct
35a90 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d  ions that implem
35aa0 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  ent the SQL func
35ab0 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
35ac0 67 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20  gate. ^A scalar 
35ad0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  SQL function req
35ae0 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65  uires an impleme
35af0 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78  ntation of the x
35b00 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  Func.** callback
35b10 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e   only; NULL poin
35b20 74 65 72 73 20 6d 75 73 74 20 62 65 20 70 61 73  ters must be pas
35b30 73 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70  sed as the xStep
35b40 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70   and xFinal.** p
35b50 61 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61  arameters. ^An a
35b60 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
35b70 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61  ction requires a
35b80 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
35b90 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64   of xStep.** and
35ba0 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c   xFinal and NULL
35bb0 20 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 65   pointer must be
35bc0 20 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e   passed for xFun
35bd0 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e  c. ^To delete an
35be0 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c   existing.** SQL
35bf0 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67   function or agg
35c00 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c  regate, pass NUL
35c10 4c 20 70 6f 69 6e 74 65 72 73 20 66 6f 72 20 61  L pointers for a
35c20 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f  ll three functio
35c30 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a  n.** callbacks..
35c40 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e  **.** ^(If the n
35c50 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  inth parameter t
35c60 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  o sqlite3_create
35c70 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69  _function_v2() i
35c80 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74  s not NULL,.** t
35c90 68 65 6e 20 69 74 20 69 73 20 64 65 73 74 72 75  hen it is destru
35ca0 63 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70  ctor for the app
35cb0 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
35cc0 69 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64  inter. .** The d
35cd0 65 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e 76  estructor is inv
35ce0 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66 75  oked when the fu
35cf0 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65  nction is delete
35d00 64 2c 20 65 69 74 68 65 72 20 62 79 20 62 65 69  d, either by bei
35d10 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64  ng.** overloaded
35d20 20 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61 74   or when the dat
35d30 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
35d40 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54   closes.)^.** ^T
35d50 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73  he destructor is
35d60 20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66   also invoked if
35d70 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20   the call to.** 
35d80 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
35d90 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 69  unction_v2() fai
35da0 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65  ls..** ^When the
35db0 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c   destructor call
35dc0 62 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e 74  back of the tent
35dd0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69  h parameter is i
35de0 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73  nvoked, it.** is
35df0 20 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c 65   passed a single
35e00 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
35e10 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
35e20 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
35e30 61 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68  a .** pointer wh
35e40 69 63 68 20 77 61 73 20 74 68 65 20 66 69 66 74  ich was the fift
35e50 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
35e60 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
35e70 6e 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  nction_v2()..**.
35e80 2a 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74  ** ^It is permit
35e90 74 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20  ted to register 
35ea0 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65  multiple impleme
35eb0 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ntations of the 
35ec0 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  same.** function
35ed0 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  s with the same 
35ee0 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69  name but with ei
35ef0 74 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e  ther differing n
35f00 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67  umbers of.** arg
35f10 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72  uments or differ
35f20 69 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 65  ing preferred te
35f30 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e  xt encodings.  ^
35f40 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a  SQLite will use.
35f50 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ** the implement
35f60 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20  ation that most 
35f70 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20  closely matches 
35f80 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68  the way in which
35f90 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63   the.** SQL func
35fa0 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e  tion is used.  ^
35fb0 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  A function imple
35fc0 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61  mentation with a
35fd0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a   non-negative.**
35fe0 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72 20   nArg parameter 
35ff0 69 73 20 61 20 62 65 74 74 65 72 20 6d 61 74 63  is a better matc
36000 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
36010 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
36020 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74   with.** a negat
36030 69 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75  ive nArg.  ^A fu
36040 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
36050 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
36060 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63  encoding.** matc
36070 68 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  hes the database
36080 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62   encoding is a b
36090 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74  etter.** match t
360a0 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  han a function w
360b0 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e  here the encodin
360c0 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20  g is different. 
360d0 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e   .** ^A function
360e0 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64   where the encod
360f0 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69  ing difference i
36100 73 20 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c  s between UTF16l
36110 65 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a  e and UTF16be.**
36120 20 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74   is a closer mat
36130 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69  ch than a functi
36140 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63  on where the enc
36150 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65  oding difference
36160 20 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55   is.** between U
36170 54 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a  TF8 and UTF16..*
36180 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66  *.** ^Built-in f
36190 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20  unctions may be 
361a0 6f 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65  overloaded by ne
361b0 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  w application-de
361c0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e  fined functions.
361d0 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69  .**.** ^An appli
361e0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
361f0 75 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69  unction is permi
36200 74 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68  tted to call oth
36210 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74  er.** SQLite int
36220 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65  erfaces.  Howeve
36230 72 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75  r, such calls mu
36240 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20  st not.** close 
36250 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
36260 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61  nection nor fina
36270 6c 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68  lize or reset th
36280 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  e prepared.** st
36290 61 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68  atement in which
362a0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73   the function is
362b0 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74   running..*/.int
362c0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
362d0 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69  function(.  sqli
362e0 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74  te3 *db,.  const
362f0 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e   char *zFunction
36300 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67  Name,.  int nArg
36310 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
36320 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a  ,.  void *pApp,.
36330 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28    void (*xFunc)(
36340 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
36350 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
36360 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
36370 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63  xStep)(sqlite3_c
36380 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
36390 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
363a0 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73  void (*xFinal)(s
363b0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
363c0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
363d0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
363e0 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  6(.  sqlite3 *db
363f0 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  ,.  const void *
36400 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20  zFunctionName,. 
36410 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74   int nArg,.  int
36420 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69   eTextRep,.  voi
36430 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20  d *pApp,.  void 
36440 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33  (*xFunc)(sqlite3
36450 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
36460 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
36470 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28    void (*xStep)(
36480 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
36490 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
364a0 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
364b0 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f  xFinal)(sqlite3_
364c0 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74  context*).);.int
364d0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
364e0 66 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73  function_v2(.  s
364f0 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f  qlite3 *db,.  co
36500 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74  nst char *zFunct
36510 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e  ionName,.  int n
36520 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  Arg,.  int eText
36530 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70  Rep,.  void *pAp
36540 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e  p,.  void (*xFun
36550 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
36560 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
36570 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
36580 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65   (*xStep)(sqlite
36590 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
365a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
365b0 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c  .  void (*xFinal
365c0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
365d0 74 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65  t*),.  void(*xDe
365e0 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b  stroy)(void*).);
365f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
36600 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73  : Text Encodings
36610 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
36620 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74  stant define int
36630 65 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 20  eger codes that 
36640 72 65 70 72 65 73 65 6e 74 20 74 68 65 20 76 61  represent the va
36650 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e  rious.** text en
36660 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65  codings supporte
36670 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  d by SQLite..*/.
36680 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
36690 54 46 38 20 20 20 20 20 20 20 20 20 20 20 31 20  TF8           1 
366a0 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 33 37 35     /* IMP: R-375
366b0 31 34 2d 33 35 35 36 36 20 2a 2f 0a 23 64 65 66  14-35566 */.#def
366c0 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
366d0 4c 45 20 20 20 20 20 20 20 20 32 20 20 20 20 2f  LE        2    /
366e0 2a 20 49 4d 50 3a 20 52 2d 30 33 33 37 31 2d 33  * IMP: R-03371-3
366f0 37 36 33 37 20 2a 2f 0a 23 64 65 66 69 6e 65 20  7637 */.#define 
36700 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20  SQLITE_UTF16BE  
36710 20 20 20 20 20 20 33 20 20 20 20 2f 2a 20 49 4d        3    /* IM
36720 50 3a 20 52 2d 35 31 39 37 31 2d 33 34 31 35 34  P: R-51971-34154
36730 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
36740 54 45 5f 55 54 46 31 36 20 20 20 20 20 20 20 20  TE_UTF16        
36750 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61    4    /* Use na
36760 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
36770 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
36780 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20 20  E_ANY           
36790 20 35 20 20 20 20 2f 2a 20 44 65 70 72 65 63 61   5    /* Depreca
367a0 74 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ted */.#define S
367b0 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47  QLITE_UTF16_ALIG
367c0 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c  NED  8    /* sql
367d0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
367e0 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f  ation only */../
367f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
36800 75 6e 63 74 69 6f 6e 20 46 6c 61 67 73 0a 2a 2a  unction Flags.**
36810 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
36820 6e 74 73 20 6d 61 79 20 62 65 20 4f 52 65 64 20  nts may be ORed 
36830 74 6f 67 65 74 68 65 72 20 77 69 74 68 20 74 68  together with th
36840 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54  e .** [SQLITE_UT
36850 46 38 20 7c 20 70 72 65 66 65 72 72 65 64 20 74  F8 | preferred t
36860 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 61 73  ext encoding] as
36870 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75   the fourth argu
36880 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69  ment.** to [sqli
36890 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
368a0 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ion()], [sqlite3
368b0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
368c0 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71  16()], or.** [sq
368d0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
368e0 63 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a  ction_v2()]..*/.
368f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
36900 45 54 45 52 4d 49 4e 49 53 54 49 43 20 20 20 20  ETERMINISTIC    
36910 30 78 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  0x800../*.** CAP
36920 49 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 65  I3REF: Deprecate
36930 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44  d Functions.** D
36940 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20  EPRECATED.**.** 
36950 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
36960 61 72 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d  are [deprecated]
36970 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d  .  In order to m
36980 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77  aintain.** backw
36990 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
369a0 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f  ty with older co
369b0 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69  de, these functi
369c0 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a  ons continue .**
369d0 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
369e0 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20  .  However, new 
369f0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f  applications sho
36a00 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65  uld avoid.** the
36a10 20 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 75   use of these fu
36a20 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 65 6e 63  nctions.  To enc
36a30 6f 75 72 61 67 65 20 70 72 6f 67 72 61 6d 6d 65  ourage programme
36a40 72 73 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 74  rs to avoid.** t
36a50 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20  hese functions, 
36a60 77 65 20 77 69 6c 6c 20 6e 6f 74 20 65 78 70 6c  we will not expl
36a70 61 69 6e 20 77 68 61 74 20 74 68 65 79 20 64 6f  ain what they do
36a80 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c  ..*/.#ifndef SQL
36a90 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41  ITE_OMIT_DEPRECA
36aa0 54 45 44 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  TED.SQLITE_DEPRE
36ab0 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
36ac0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e  3_aggregate_coun
36ad0 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
36ae0 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52  t*);.SQLITE_DEPR
36af0 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
36b00 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74  e3_expired(sqlit
36b10 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54  e3_stmt*);.SQLIT
36b20 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
36b30 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65   sqlite3_transfe
36b40 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74  r_bindings(sqlit
36b50 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65  e3_stmt*, sqlite
36b60 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45  3_stmt*);.SQLITE
36b70 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
36b80 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72  sqlite3_global_r
36b90 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51  ecover(void);.SQ
36ba0 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
36bb0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72  void sqlite3_thr
36bc0 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64  ead_cleanup(void
36bd0 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  );.SQLITE_DEPREC
36be0 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
36bf0 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f  _memory_alarm(vo
36c00 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
36c10 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 0a  te3_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 20 76 6f 69 64 2a 2c 73 71 6c 69        void*,sqli
36c40 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64  te3_int64);.#end
36c50 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  if../*.** CAPI3R
36c60 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51  EF: Obtaining SQ
36c70 4c 20 56 61 6c 75 65 73 0a 2a 2a 20 4d 45 54 48  L Values.** METH
36c80 4f 44 3a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  OD: sqlite3_valu
36c90 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61  e.**.** The C-la
36ca0 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74  nguage implement
36cb0 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e  ation of SQL fun
36cc0 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65  ctions and aggre
36cd0 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68  gates uses.** th
36ce0 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66  is set of interf
36cf0 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ace routines to 
36d00 61 63 63 65 73 73 20 74 68 65 20 70 61 72 61 6d  access the param
36d10 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a  eter values on.*
36d20 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f  * the function o
36d30 72 20 61 67 67 72 65 67 61 74 65 2e 20 20 0a 2a  r aggregate.  .*
36d40 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28  *.** The xFunc (
36d50 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74  for scalar funct
36d60 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28  ions) or xStep (
36d70 66 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 20  for aggregates) 
36d80 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f  parameters.** to
36d90 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
36da0 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64  _function()] and
36db0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
36dc0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a  _function16()].*
36dd0 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63  * define callbac
36de0 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ks that implemen
36df0 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
36e00 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74  ons and aggregat
36e10 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20 70  es..** The 3rd p
36e20 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73  arameter to thes
36e30 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61  e callbacks is a
36e40 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
36e50 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65  ers to.** [prote
36e60 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
36e70 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68  ue] objects.  Th
36e80 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69  ere is one [sqli
36e90 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
36ea0 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61  t for.** each pa
36eb0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53  rameter to the S
36ec0 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68  QL function.  Th
36ed0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
36ee0 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72   used to.** extr
36ef0 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20  act values from 
36f00 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
36f10 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a  ue] objects..**.
36f20 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
36f30 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68  s work only with
36f40 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
36f50 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
36f60 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d  ts..** Any attem
36f70 70 74 20 74 6f 20 75 73 65 20 74 68 65 73 65 20  pt to use these 
36f80 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b  routines on an [
36f90 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
36fa0 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62  te3_value].** ob
36fb0 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20  ject results in 
36fc0 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69  undefined behavi
36fd0 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  or..**.** ^These
36fe0 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a   routines work j
36ff0 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72  ust like the cor
37000 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75  responding [colu
37010 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
37020 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74  ons].** except t
37030 68 61 74 20 74 68 65 73 65 20 72 6f 75 74 69 6e  hat these routin
37040 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65  es take a single
37050 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
37060 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
37070 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73  t.** pointer ins
37080 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74  tead of a [sqlit
37090 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65  e3_stmt*] pointe
370a0 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72  r and an integer
370b0 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a   column number..
370c0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
370d0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
370e0 29 20 69 6e 74 65 72 66 61 63 65 20 65 78 74 72  ) interface extr
370f0 61 63 74 73 20 61 20 55 54 46 2d 31 36 20 73 74  acts a UTF-16 st
37100 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e  ring.** in the n
37110 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72  ative byte-order
37120 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63   of the host mac
37130 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73  hine.  ^The.** s
37140 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
37150 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69  t16be() and sqli
37160 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
37170 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a  le() interfaces.
37180 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d 31  ** extract UTF-1
37190 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 69 67  6 strings as big
371a0 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74  -endian and litt
371b0 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63  le-endian respec
371c0 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28  tively..**.** ^(
371d0 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
371e0 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29  e_numeric_type()
371f0 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
37200 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20  pts to apply.** 
37210 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79  numeric affinity
37220 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20   to the value.  
37230 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20  This means that 
37240 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a  an attempt is.**
37250 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74   made to convert
37260 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e   the value to an
37270 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61   integer or floa
37280 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a  ting point.  If.
37290 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72  ** such a conver
372a0 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65  sion is possible
372b0 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66   without loss of
372c0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e   information (in
372d0 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c   other.** words,
372e0 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 69 73   if the value is
372f0 20 61 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c   a string that l
37300 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62  ooks like a numb
37310 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  er).** then the 
37320 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65  conversion is pe
37330 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77  rformed.  Otherw
37340 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f  ise no conversio
37350 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65  n occurs..** The
37360 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
37370 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66 74   | datatype] aft
37380 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73  er conversion is
37390 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a   returned.)^.**.
373a0 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70 61  ** Please pay pa
373b0 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69  rticular attenti
373c0 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20 74  on to the fact t
373d0 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20  hat the pointer 
373e0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d  returned.** from
373f0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
37400 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65  blob()], [sqlite
37410 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c  3_value_text()],
37420 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
37430 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20  value_text16()] 
37440 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74  can be invalidat
37450 65 64 20 62 79 20 61 20 73 75 62 73 65 71 75 65  ed by a subseque
37460 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  nt call to.** [s
37470 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
37480 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  es()], [sqlite3_
37490 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d  value_bytes16()]
374a0 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
374b0 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20  _text()],.** or 
374c0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
374d0 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  ext16()]..**.** 
374e0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  These routines m
374f0 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
37500 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
37510 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c  ad as.** the SQL
37520 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73   function that s
37530 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c  upplied the [sql
37540 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72  ite3_value*] par
37550 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63 6f 6e 73  ameters..*/.cons
37560 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
37570 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74  value_blob(sqlit
37580 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
37590 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
375a0 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  tes(sqlite3_valu
375b0 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
375c0 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73  _value_bytes16(s
375d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
375e0 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76  double sqlite3_v
375f0 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69  alue_double(sqli
37600 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
37610 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69   sqlite3_value_i
37620 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt(sqlite3_value
37630 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  *);.sqlite3_int6
37640 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  4 sqlite3_value_
37650 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61  int64(sqlite3_va
37660 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73  lue*);.const uns
37670 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69  igned char *sqli
37680 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73  te3_value_text(s
37690 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
376a0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
376b0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
376c0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
376d0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
376e0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
376f0 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  16le(sqlite3_val
37700 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  ue*);.const void
37710 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
37720 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33  text16be(sqlite3
37730 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
37740 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65  lite3_value_type
37750 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
37760 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
37770 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65  lue_numeric_type
37780 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
37790 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
377a0 46 3a 20 46 69 6e 64 69 6e 67 20 54 68 65 20 53  F: Finding The S
377b0 75 62 74 79 70 65 20 4f 66 20 53 51 4c 20 56 61  ubtype Of SQL Va
377c0 6c 75 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  lues.** METHOD: 
377d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 0a 2a 2a  sqlite3_value.**
377e0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
377f0 76 61 6c 75 65 5f 73 75 62 74 79 70 65 28 56 29  value_subtype(V)
37800 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
37810 73 20 74 68 65 20 73 75 62 74 79 70 65 20 66 6f  s the subtype fo
37820 72 0a 2a 2a 20 61 6e 20 5b 61 70 70 6c 69 63 61  r.** an [applica
37830 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
37840 20 66 75 6e 63 74 69 6f 6e 5d 20 61 72 67 75 6d   function] argum
37850 65 6e 74 20 56 2e 20 20 54 68 65 20 73 75 62 74  ent V.  The subt
37860 79 70 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  ype.** informati
37870 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  on can be used t
37880 6f 20 70 61 73 73 20 61 20 6c 69 6d 69 74 65 64  o pass a limited
37890 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 74 65   amount of conte
378a0 78 74 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 53  xt from.** one S
378b0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 61  QL function to a
378c0 6e 6f 74 68 65 72 2e 20 20 55 73 65 20 74 68 65  nother.  Use the
378d0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
378e0 5f 73 75 62 74 79 70 65 28 29 5d 0a 2a 2a 20 72  _subtype()].** r
378f0 6f 75 74 69 6e 65 20 74 6f 20 73 65 74 20 74 68  outine to set th
37900 65 20 73 75 62 74 79 70 65 20 66 6f 72 20 74 68  e subtype for th
37910 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
37920 66 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f  f an SQL functio
37930 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  n..**.** SQLite 
37940 6d 61 6b 65 73 20 6e 6f 20 75 73 65 20 6f 66 20  makes no use of 
37950 73 75 62 74 79 70 65 20 69 74 73 65 6c 66 2e 20  subtype itself. 
37960 20 49 74 20 6d 65 72 65 6c 79 20 70 61 73 73 65   It merely passe
37970 73 20 74 68 65 20 73 75 62 74 79 70 65 0a 2a 2a  s the subtype.**
37980 20 66 72 6f 6d 20 74 68 65 20 72 65 73 75 6c 74   from the result
37990 20 6f 66 20 6f 6e 65 20 5b 61 70 70 6c 69 63 61   of one [applica
379a0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
379b0 20 66 75 6e 63 74 69 6f 6e 5d 20 69 6e 74 6f 20   function] into 
379c0 74 68 65 0a 2a 2a 20 69 6e 70 75 74 20 6f 66 20  the.** input of 
379d0 61 6e 6f 74 68 65 72 2e 0a 2a 2f 0a 75 6e 73 69  another..*/.unsi
379e0 67 6e 65 64 20 69 6e 74 20 73 71 6c 69 74 65 33  gned int sqlite3
379f0 5f 76 61 6c 75 65 5f 73 75 62 74 79 70 65 28 73  _value_subtype(s
37a00 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
37a10 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
37a20 20 43 6f 70 79 20 41 6e 64 20 46 72 65 65 20 53   Copy And Free S
37a30 51 4c 20 56 61 6c 75 65 73 0a 2a 2a 20 4d 45 54  QL Values.** MET
37a40 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 76 61 6c  HOD: sqlite3_val
37a50 75 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ue.**.** ^The sq
37a60 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28  lite3_value_dup(
37a70 56 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b  V) interface mak
37a80 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
37a90 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
37aa0 0a 2a 2a 20 6f 62 6a 65 63 74 20 44 20 61 6e 64  .** object D and
37ab0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
37ac0 65 72 20 74 6f 20 74 68 61 74 20 63 6f 70 79 2e  er to that copy.
37ad0 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f    ^The [sqlite3_
37ae0 76 61 6c 75 65 5d 20 72 65 74 75 72 6e 65 64 0a  value] returned.
37af0 2a 2a 20 69 73 20 61 20 5b 70 72 6f 74 65 63 74  ** is a [protect
37b00 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
37b10 5d 20 6f 62 6a 65 63 74 20 65 76 65 6e 20 69 66  ] object even if
37b20 20 74 68 65 20 69 6e 70 75 74 20 69 73 20 6e 6f   the input is no
37b30 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  t..** ^The sqlit
37b40 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 56 29 20  e3_value_dup(V) 
37b50 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
37b60 73 20 4e 55 4c 4c 20 69 66 20 56 20 69 73 20 4e  s NULL if V is N
37b70 55 4c 4c 20 6f 72 20 69 66 20 61 0a 2a 2a 20 6d  ULL or if a.** m
37b80 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
37b90 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54   fails..**.** ^T
37ba0 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
37bb0 5f 66 72 65 65 28 56 29 20 69 6e 74 65 72 66 61  _free(V) interfa
37bc0 63 65 20 66 72 65 65 73 20 61 6e 20 5b 73 71 6c  ce frees an [sql
37bd0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
37be0 63 74 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  ct.** previously
37bf0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
37c00 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75  sqlite3_value_du
37c10 70 28 29 5d 2e 20 20 5e 49 66 20 56 20 69 73 20  p()].  ^If V is 
37c20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
37c30 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 76  * then sqlite3_v
37c40 61 6c 75 65 5f 66 72 65 65 28 56 29 20 69 73 20  alue_free(V) is 
37c50 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  a harmless no-op
37c60 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 76 61 6c  ..*/.sqlite3_val
37c70 75 65 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  ue *sqlite3_valu
37c80 65 5f 64 75 70 28 63 6f 6e 73 74 20 73 71 6c 69  e_dup(const sqli
37c90 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69  te3_value*);.voi
37ca0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  d sqlite3_value_
37cb0 66 72 65 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  free(sqlite3_val
37cc0 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ue*);../*.** CAP
37cd0 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67  I3REF: Obtain Ag
37ce0 67 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e  gregate Function
37cf0 20 43 6f 6e 74 65 78 74 0a 2a 2a 20 4d 45 54 48   Context.** METH
37d00 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  OD: sqlite3_cont
37d10 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d  ext.**.** Implem
37d20 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61 67 67  entations of agg
37d30 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
37d40 69 6f 6e 73 20 75 73 65 20 74 68 69 73 0a 2a 2a  ions use this.**
37d50 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f   routine to allo
37d60 63 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20  cate memory for 
37d70 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74  storing their st
37d80 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ate..**.** ^The 
37d90 66 69 72 73 74 20 74 69 6d 65 20 74 68 65 20 73  first time the s
37da0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
37db0 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f  _context(C,N) ro
37dc0 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20  utine is called 
37dd0 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72 74 69 63  .** for a partic
37de0 75 6c 61 72 20 61 67 67 72 65 67 61 74 65 20 66  ular aggregate f
37df0 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a  unction, SQLite.
37e00 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f  ** allocates N o
37e10 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73  f memory, zeroes
37e20 20 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 79   out that memory
37e30 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  , and returns a 
37e40 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68  pointer.** to th
37e50 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f  e new memory. ^O
37e60 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62  n second and sub
37e70 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
37e80 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72  .** sqlite3_aggr
37e90 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
37ea0 66 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67 67  for the same agg
37eb0 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20  regate function 
37ec0 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65  instance,.** the
37ed0 20 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 20   same buffer is 
37ee0 72 65 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 74  returned.  Sqlit
37ef0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
37f00 74 65 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c  text() is normal
37f10 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63  ly.** called onc
37f20 65 20 66 6f 72 20 65 61 63 68 20 69 6e 76 6f 63  e for each invoc
37f30 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 74  ation of the xSt
37f40 65 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20  ep callback and 
37f50 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74  then one.** last
37f60 20 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20 78   time when the x
37f70 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69  Final callback i
37f80 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68  s invoked.  ^(Wh
37f90 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68  en no rows match
37fa0 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67 61 74 65  .** an aggregate
37fb0 20 71 75 65 72 79 2c 20 74 68 65 20 78 53 74 65   query, the xSte
37fc0 70 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20  p() callback of 
37fd0 74 68 65 20 61 67 67 72 65 67 61 74 65 20 66 75  the aggregate fu
37fe0 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d  nction.** implem
37ff0 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 65  entation is neve
38000 72 20 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 69  r called and xFi
38010 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 20  nal() is called 
38020 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a  exactly once..**
38030 20 49 6e 20 74 68 6f 73 65 20 63 61 73 65 73 2c   In those cases,
38040 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
38050 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 67  te_context() mig
38060 68 74 20 62 65 20 63 61 6c 6c 65 64 20 66 6f 72  ht be called for
38070 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 69   the.** first ti
38080 6d 65 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 78  me from within x
38090 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a  Final().)^.**.**
380a0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 61 67   ^The sqlite3_ag
380b0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
380c0 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 74  C,N) routine ret
380d0 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
380e0 74 65 72 20 0a 2a 2a 20 77 68 65 6e 20 66 69 72  ter .** when fir
380f0 73 74 20 63 61 6c 6c 65 64 20 69 66 20 4e 20 69  st called if N i
38100 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65  s less than or e
38110 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20  qual to zero or 
38120 69 66 20 61 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  if a memory.** a
38130 6c 6c 6f 63 61 74 65 20 65 72 72 6f 72 20 6f 63  llocate error oc
38140 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  curs..**.** ^(Th
38150 65 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63  e amount of spac
38160 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73  e allocated by s
38170 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
38180 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69 73  _context(C,N) is
38190 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64 20 62  .** determined b
381a0 79 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65  y the N paramete
381b0 72 20 6f 6e 20 66 69 72 73 74 20 73 75 63 63 65  r on first succe
381c0 73 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61  ssful call.  Cha
381d0 6e 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c  nging the.** val
381e0 75 65 20 6f 66 20 4e 20 69 6e 20 73 75 62 73 65  ue of N in subse
381f0 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71  quent call to sq
38200 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
38210 63 6f 6e 74 65 78 74 28 29 20 77 69 74 68 69 6e  context() within
38220 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 61 67 67  .** the same agg
38230 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20  regate function 
38240 69 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f  instance will no
38250 74 20 72 65 73 69 7a 65 20 74 68 65 20 6d 65 6d  t resize the mem
38260 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f  ory.** allocatio
38270 6e 2e 29 5e 20 20 57 69 74 68 69 6e 20 74 68 65  n.)^  Within the
38280 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b   xFinal callback
38290 2c 20 69 74 20 69 73 20 63 75 73 74 6f 6d 61 72  , it is customar
382a0 79 20 74 6f 20 73 65 74 0a 2a 2a 20 4e 3d 30 20  y to set.** N=0 
382b0 69 6e 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  in calls to sqli
382c0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
382d0 6e 74 65 78 74 28 43 2c 4e 29 20 73 6f 20 74 68  ntext(C,N) so th
382e0 61 74 20 6e 6f 20 0a 2a 2a 20 70 6f 69 6e 74 6c  at no .** pointl
382f0 65 73 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ess memory alloc
38300 61 74 69 6f 6e 73 20 6f 63 63 75 72 2e 0a 2a 2a  ations occur..**
38310 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 6f  .** ^SQLite auto
38320 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20  matically frees 
38330 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
38340 61 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69  ated by .** sqli
38350 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
38360 6e 74 65 78 74 28 29 20 77 68 65 6e 20 74 68 65  ntext() when the
38370 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79   aggregate query
38380 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a   concludes..**.*
38390 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61  * The first para
383a0 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 61 20  meter must be a 
383b0 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  copy of the.** [
383c0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
383d0 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63  | SQL function c
383e0 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 20  ontext] that is 
383f0 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
38400 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53  ter.** to the xS
38410 74 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 61  tep or xFinal ca
38420 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74  llback routine t
38430 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  hat implements t
38440 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20  he aggregate.** 
38450 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
38460 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73  This routine mus
38470 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
38480 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
38490 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
384a0 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
384b0 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
384c0 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  ng..*/.void *sql
384d0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
384e0 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63  ontext(sqlite3_c
384f0 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79  ontext*, int nBy
38500 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tes);../*.** CAP
38510 49 33 52 45 46 3a 20 55 73 65 72 20 44 61 74 61  I3REF: User Data
38520 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a   For Functions.*
38530 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
38540 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20  3_context.**.** 
38550 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73 65  ^The sqlite3_use
38560 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  r_data() interfa
38570 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70  ce returns a cop
38580 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e  y of.** the poin
38590 74 65 72 20 74 68 61 74 20 77 61 73 20 74 68 65  ter that was the
385a0 20 70 55 73 65 72 44 61 74 61 20 70 61 72 61 6d   pUserData param
385b0 65 74 65 72 20 28 74 68 65 20 35 74 68 20 70 61  eter (the 5th pa
385c0 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74  rameter).** of t
385d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
385e0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a  te_function()].*
385f0 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  * and [sqlite3_c
38600 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
38610 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61  ()] routines tha
38620 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20  t originally.** 
38630 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61  registered the a
38640 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e  pplication defin
38650 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  ed function..**.
38660 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
38670 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
38680 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
38690 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  ead in which.** 
386a0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
386b0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
386c0 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a   is running..*/.
386d0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 73  void *sqlite3_us
386e0 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65 33 5f  er_data(sqlite3_
386f0 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a  context*);../*.*
38700 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61  * CAPI3REF: Data
38710 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20  base Connection 
38720 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  For Functions.**
38730 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
38740 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 5e  _context.**.** ^
38750 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  The sqlite3_cont
38760 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20  ext_db_handle() 
38770 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
38780 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  s a copy of.** t
38790 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68  he pointer to th
387a0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
387b0 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74  ection] (the 1st
387c0 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f   parameter).** o
387d0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  f the [sqlite3_c
387e0 72 65 61 74 65