System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact e0521c0f38f962b6963f6bb5dfa5c2e8b03bd5e4:


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 33 2e 31 38 2e 30 22 0a 23 64       "3.18.0".#d
1180: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52  efine SQLITE_VER
1190: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 33 30 31 38  SION_NUMBER 3018
11a0: 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  000.#define SQLI
11b0: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 20 20 20  TE_SOURCE_ID    
11c0: 20 20 22 32 30 31 37 2d 30 33 2d 32 38 20 31 38    "2017-03-28 18
11d0: 3a 34 38 3a 34 33 20 34 32 34 61 30 64 33 38 30  :48:43 424a0d380
11e0: 33 33 32 38 35 38 65 65 35 35 62 64 65 62 63 34  332858ee55bdebc4
11f0: 61 66 33 37 38 39 66 37 34 65 37 30 61 32 62 33  af3789f74e70a2b3
1200: 62 61 31 63 66 32 39 64 38 34 62 39 62 34 62 63  ba1cf29d84b9b4bc
1210: 66 33 65 32 65 33 37 22 0a 0a 2f 2a 0a 2a 2a 20  f3e2e37"../*.** 
1220: 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69  CAPI3REF: Run-Ti
1230: 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69  me Library Versi
1240: 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45  on Numbers.** KE
1250: 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f  YWORDS: sqlite3_
1260: 76 65 72 73 69 6f 6e 20 73 71 6c 69 74 65 33 5f  version sqlite3_
1270: 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54  sourceid.**.** T
1280: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
1290: 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65  provide the same
12a0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20   information as 
12b0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  the [SQLITE_VERS
12c0: 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  ION],.** [SQLITE
12d0: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d  _VERSION_NUMBER]
12e0: 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f  , and [SQLITE_SO
12f0: 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72  URCE_ID] C prepr
1300: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a  ocessor macros.*
1310: 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69  * but are associ
1320: 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69  ated with the li
1330: 62 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66  brary instead of
1340: 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65   the header file
1350: 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a  .  ^(Cautious.**
1360: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
1370: 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72  ht include asser
1380: 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69  t() statements i
1390: 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74  n their applicat
13a0: 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79  ion to.** verify
13b0: 20 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74   that values ret
13c0: 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69  urned by these i
13d0: 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20  nterfaces match 
13e0: 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a  the macros in.**
13f0: 20 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64   the header, and
1400: 20 74 68 75 73 20 65 6e 73 75 72 65 20 74 68 61   thus ensure tha
1410: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
1420: 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  n is.** compiled
1430: 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c   with matching l
1440: 69 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65  ibrary and heade
1450: 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c  r files..**.** <
1460: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1470: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69  .** assert( sqli
1480: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
1490: 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f  umber()==SQLITE_
14a0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29  VERSION_NUMBER )
14b0: 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72  ;.** assert( str
14c0: 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72  cmp(sqlite3_sour
14d0: 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f  ceid(),SQLITE_SO
14e0: 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a  URCE_ID)==0 );.*
14f0: 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70  * assert( strcmp
1500: 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73  (sqlite3_libvers
1510: 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52  ion(),SQLITE_VER
1520: 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c  SION)==0 );.** <
1530: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1540: 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e>)^.**.** ^The 
1550: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
1560: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
1570: 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74  t contains the t
1580: 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56  ext of [SQLITE_V
1590: 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f  ERSION].** macro
15a0: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
15b0: 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e  libversion() fun
15c0: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20  ction returns a 
15d0: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
15e0: 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  * to the sqlite3
15f0: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
1600: 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65  g constant.  The
1610: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1620: 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f  ion().** functio
1630: 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f  n is provided fo
1640: 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69  r use in DLLs si
1650: 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73  nce DLL users us
1660: 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76  ually do not hav
1670: 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65  e.** direct acce
1680: 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e  ss to string con
1690: 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68  stants within th
16a0: 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20  e DLL.  ^The.** 
16b0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
16c0: 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63  on_number() func
16d0: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20  tion returns an 
16e0: 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f  integer equal to
16f0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  .** [SQLITE_VERS
1700: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54  ION_NUMBER].  ^T
1710: 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  he sqlite3_sourc
1720: 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  eid() function r
1730: 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69  eturns .** a poi
1740: 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67  nter to a string
1750: 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20   constant whose 
1760: 76 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d  value is the sam
1770: 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51  e as the .** [SQ
1780: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20  LITE_SOURCE_ID] 
1790: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
17a0: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  acro..**.** See 
17b0: 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65  also: [sqlite_ve
17c0: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
17d0: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
17e0: 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
17f0: 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63   SQLITE_EXTERN c
1800: 6f 6e 73 74 20 63 68 61 72 20 73 71 6c 69 74 65  onst char sqlite
1810: 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b 0a 53 51 4c  3_version[];.SQL
1820: 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
1830: 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62 76  ar *sqlite3_libv
1840: 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 53 51  ersion(void);.SQ
1850: 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
1860: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75  har *sqlite3_sou
1870: 72 63 65 69 64 28 76 6f 69 64 29 3b 0a 53 51 4c  rceid(void);.SQL
1880: 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
1890: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
18a0: 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a 0a 2f 2a  umber(void);../*
18b0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75  .** CAPI3REF: Ru
18c0: 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 43  n-Time Library C
18d0: 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70 74 69 6f  ompilation Optio
18e0: 6e 73 20 44 69 61 67 6e 6f 73 74 69 63 73 0a 2a  ns Diagnostics.*
18f0: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1900: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
1910: 75 73 65 64 28 29 20 66 75 6e 63 74 69 6f 6e 20  used() function 
1920: 72 65 74 75 72 6e 73 20 30 20 6f 72 20 31 20 0a  returns 0 or 1 .
1930: 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 77 68  ** indicating wh
1940: 65 74 68 65 72 20 74 68 65 20 73 70 65 63 69 66  ether the specif
1950: 69 65 64 20 6f 70 74 69 6f 6e 20 77 61 73 20 64  ied option was d
1960: 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a 20 63 6f  efined at .** co
1970: 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20 5e 54 68  mpile time.  ^Th
1980: 65 20 53 51 4c 49 54 45 5f 20 70 72 65 66 69 78  e SQLITE_ prefix
1990: 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 65 64 20   may be omitted 
19a0: 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20 6f 70 74  from the .** opt
19b0: 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73 65 64 20  ion name passed 
19c0: 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  to sqlite3_compi
19d0: 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 2e  leoption_used().
19e0: 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71    .**.** ^The sq
19f0: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1a00: 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e 63 74 69  ion_get() functi
1a10: 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65 72 61 74  on allows iterat
1a20: 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20  ing.** over the 
1a30: 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f 6e 73 20  list of options 
1a40: 74 68 61 74 20 77 65 72 65 20 64 65 66 69 6e 65  that were define
1a50: 64 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d  d at compile tim
1a60: 65 20 62 79 0a 2a 2a 20 72 65 74 75 72 6e 69 6e  e by.** returnin
1a70: 67 20 74 68 65 20 4e 2d 74 68 20 63 6f 6d 70 69  g the N-th compi
1a80: 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f 6e 20 73  le time option s
1a90: 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e 20 69 73  tring.  ^If N is
1aa0: 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 0a 2a   out of range,.*
1ab0: 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  * sqlite3_compil
1ac0: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 72 65  eoption_get() re
1ad0: 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
1ae0: 6e 74 65 72 2e 20 20 5e 54 68 65 20 53 51 4c 49  nter.  ^The SQLI
1af0: 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69 78 20 69  TE_ .** prefix i
1b00: 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 61  s omitted from a
1b10: 6e 79 20 73 74 72 69 6e 67 73 20 72 65 74 75 72  ny strings retur
1b20: 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74  ned by .** sqlit
1b30: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
1b40: 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 53  _get()..**.** ^S
1b50: 75 70 70 6f 72 74 20 66 6f 72 20 74 68 65 20 64  upport for the d
1b60: 69 61 67 6e 6f 73 74 69 63 20 66 75 6e 63 74 69  iagnostic functi
1b70: 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  ons sqlite3_comp
1b80: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
1b90: 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  .** and sqlite3_
1ba0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65  compileoption_ge
1bb0: 74 28 29 20 6d 61 79 20 62 65 20 6f 6d 69 74 74  t() may be omitt
1bc0: 65 64 20 62 79 20 73 70 65 63 69 66 79 69 6e 67  ed by specifying
1bd0: 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45   the .** [SQLITE
1be0: 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54  _OMIT_COMPILEOPT
1bf0: 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70 74 69 6f  ION_DIAGS] optio
1c00: 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d  n at compile tim
1c10: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
1c20: 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  o: SQL functions
1c30: 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65   [sqlite_compile
1c40: 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 5d 20 61  option_used()] a
1c50: 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 63 6f  nd.** [sqlite_co
1c60: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
1c70: 29 5d 20 61 6e 64 20 74 68 65 20 5b 63 6f 6d 70  )] and the [comp
1c80: 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70 72 61 67  ile_options prag
1c90: 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20  ma]..*/.#ifndef 
1ca0: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50  SQLITE_OMIT_COMP
1cb0: 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 0a  ILEOPTION_DIAGS.
1cc0: 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
1cd0: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1ce0: 74 69 6f 6e 5f 75 73 65 64 28 63 6f 6e 73 74 20  tion_used(const 
1cf0: 63 68 61 72 20 2a 7a 4f 70 74 4e 61 6d 65 29 3b  char *zOptName);
1d00: 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
1d10: 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
1d20: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65  compileoption_ge
1d30: 74 28 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66  t(int N);.#endif
1d40: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1d50: 3a 20 54 65 73 74 20 54 6f 20 53 65 65 20 49 66  : Test To See If
1d60: 20 54 68 65 20 4c 69 62 72 61 72 79 20 49 73 20   The Library Is 
1d70: 54 68 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a  Threadsafe.**.**
1d80: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68   ^The sqlite3_th
1d90: 72 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74  readsafe() funct
1da0: 69 6f 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  ion returns zero
1db0: 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a   if and only if.
1dc0: 2a 2a 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f  ** SQLite was co
1dd0: 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65  mpiled with mute
1de0: 78 69 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65  xing code omitte
1df0: 64 20 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20  d due to the.** 
1e00: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
1e10: 46 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  FE] compile-time
1e20: 20 6f 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65   option being se
1e30: 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51  t to 0..**.** SQ
1e40: 4c 69 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70  Lite can be comp
1e50: 69 6c 65 64 20 77 69 74 68 20 6f 72 20 77 69 74  iled with or wit
1e60: 68 6f 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57  hout mutexes.  W
1e70: 68 65 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  hen.** the [SQLI
1e80: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43  TE_THREADSAFE] C
1e90: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
1ea0: 63 72 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d  cro is 1 or 2, m
1eb0: 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e  utexes.** are en
1ec0: 61 62 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65  abled and SQLite
1ed0: 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2e 20   is threadsafe. 
1ee0: 20 57 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51   When the.** [SQ
1ef0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d  LITE_THREADSAFE]
1f00: 20 6d 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a   macro is 0, .**
1f10: 20 74 68 65 20 6d 75 74 65 78 65 73 20 61 72 65   the mutexes are
1f20: 20 6f 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f   omitted.  Witho
1f30: 75 74 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20  ut the mutexes, 
1f40: 69 74 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a  it is not safe.*
1f50: 2a 20 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20  * to use SQLite 
1f60: 63 6f 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f  concurrently fro
1f70: 6d 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  m more than one 
1f80: 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e  thread..**.** En
1f90: 61 62 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69  abling mutexes i
1fa0: 6e 63 75 72 73 20 61 20 6d 65 61 73 75 72 61 62  ncurs a measurab
1fb0: 6c 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70  le performance p
1fc0: 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66  enalty..** So if
1fd0: 20 73 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d   speed is of utm
1fe0: 6f 73 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20  ost importance, 
1ff0: 69 74 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74  it makes sense t
2000: 6f 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65  o disable.** the
2010: 20 6d 75 74 65 78 65 73 2e 20 20 42 75 74 20 66   mutexes.  But f
2020: 6f 72 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74  or maximum safet
2030: 79 2c 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c  y, mutexes shoul
2040: 64 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  d be enabled..**
2050: 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 65   ^The default be
2060: 68 61 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75  havior is for mu
2070: 74 65 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62  texes to be enab
2080: 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  led..**.** This 
2090: 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65  interface can be
20a0: 20 75 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c   used by an appl
20b0: 69 63 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20  ication to make 
20c0: 73 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a  sure that the.**
20d0: 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69   version of SQLi
20e0: 74 65 20 74 68 61 74 20 69 74 20 69 73 20 6c 69  te that it is li
20f0: 6e 6b 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61  nking against wa
2100: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
2110: 2a 2a 20 74 68 65 20 64 65 73 69 72 65 64 20 73  ** the desired s
2120: 65 74 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53  etting of the [S
2130: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
2140: 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54  ] macro..**.** T
2150: 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e  his interface on
2160: 6c 79 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68  ly reports on th
2170: 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d  e compile-time m
2180: 75 74 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20  utex setting.** 
2190: 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  of the [SQLITE_T
21a0: 48 52 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e  HREADSAFE] flag.
21b0: 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63    If SQLite is c
21c0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
21d0: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
21e0: 45 3d 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d  E=1 or =2 then m
21f0: 75 74 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c  utexes are enabl
2200: 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 62 75  ed by default bu
2210: 74 0a 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c  t.** can be full
2220: 79 20 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64  y or partially d
2230: 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20  isabled using a 
2240: 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2250: 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69  _config()].** wi
2260: 74 68 20 74 68 65 20 76 65 72 62 73 20 5b 53 51  th the verbs [SQ
2270: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
2280: 4c 45 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49  LETHREAD], [SQLI
2290: 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
22a0: 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53  HREAD],.** or [S
22b0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
22c0: 49 41 4c 49 5a 45 44 5d 2e 20 20 5e 28 54 68 65  IALIZED].  ^(The
22d0: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
22e0: 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   the.** sqlite3_
22f0: 74 68 72 65 61 64 73 61 66 65 28 29 20 66 75 6e  threadsafe() fun
2300: 63 74 69 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79  ction shows only
2310: 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d   the compile-tim
2320: 65 20 73 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20  e setting of.** 
2330: 74 68 72 65 61 64 20 73 61 66 65 74 79 2c 20 6e  thread safety, n
2340: 6f 74 20 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20  ot any run-time 
2350: 63 68 61 6e 67 65 73 20 74 6f 20 74 68 61 74 20  changes to that 
2360: 73 65 74 74 69 6e 67 20 6d 61 64 65 20 62 79 0a  setting made by.
2370: 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  ** sqlite3_confi
2380: 67 28 29 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f  g(). In other wo
2390: 72 64 73 2c 20 74 68 65 20 72 65 74 75 72 6e 20  rds, the return 
23a0: 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74  value from sqlit
23b0: 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 0a  e3_threadsafe().
23c0: 2a 2a 20 69 73 20 75 6e 63 68 61 6e 67 65 64 20  ** is unchanged 
23d0: 62 79 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  by calls to sqli
23e0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a  te3_config().)^.
23f0: 2a 2a 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b 74  **.** See the [t
2400: 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64  hreading mode] d
2410: 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72  ocumentation for
2420: 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
2430: 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49  rmation..*/.SQLI
2440: 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2450: 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f  e3_threadsafe(vo
2460: 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  id);../*.** CAPI
2470: 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43  3REF: Database C
2480: 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65  onnection Handle
2490: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64  .** KEYWORDS: {d
24a0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
24b0: 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f  on} {database co
24c0: 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a  nnections}.**.**
24d0: 20 45 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74   Each open SQLit
24e0: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 72 65  e database is re
24f0: 70 72 65 73 65 6e 74 65 64 20 62 79 20 61 20 70  presented by a p
2500: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
2510: 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20  tance of.** the 
2520: 6f 70 61 71 75 65 20 73 74 72 75 63 74 75 72 65  opaque structure
2530: 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22   named "sqlite3"
2540: 2e 20 20 49 74 20 69 73 20 75 73 65 66 75 6c 20  .  It is useful 
2550: 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73  to think of an s
2560: 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65  qlite3.** pointe
2570: 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20  r as an object. 
2580: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70   The [sqlite3_op
2590: 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
25a0: 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a  open16()], and.*
25b0: 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  * [sqlite3_open_
25c0: 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  v2()] interfaces
25d0: 20 61 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75   are its constru
25e0: 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69  ctors, and [sqli
25f0: 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20  te3_close()].** 
2600: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  and [sqlite3_clo
2610: 73 65 5f 76 32 28 29 5d 20 61 72 65 20 69 74 73  se_v2()] are its
2620: 20 64 65 73 74 72 75 63 74 6f 72 73 2e 20 20 54   destructors.  T
2630: 68 65 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74  here are many ot
2640: 68 65 72 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  her.** interface
2650: 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73  s (such as.** [s
2660: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2670: 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63  2()], [sqlite3_c
2680: 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
2690: 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
26a0: 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
26b0: 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74  )] to name but t
26c0: 68 72 65 65 29 20 74 68 61 74 20 61 72 65 20 6d  hree) that are m
26d0: 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20  ethods on an.** 
26e0: 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a  sqlite3 object..
26f0: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
2700: 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65  t sqlite3 sqlite
2710: 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  3;../*.** CAPI3R
2720: 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67  EF: 64-Bit Integ
2730: 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57  er Types.** KEYW
2740: 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74  ORDS: sqlite_int
2750: 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  64 sqlite_uint64
2760: 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74  .**.** Because t
2770: 68 65 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73  here is no cross
2780: 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f  -platform way to
2790: 20 73 70 65 63 69 66 79 20 36 34 2d 62 69 74 20   specify 64-bit 
27a0: 69 6e 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a  integer types.**
27b0: 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73   SQLite includes
27c0: 20 74 79 70 65 64 65 66 73 20 66 6f 72 20 36 34   typedefs for 64
27d0: 2d 62 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20  -bit signed and 
27e0: 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  unsigned integer
27f0: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  s..**.** The sql
2800: 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73  ite3_int64 and s
2810: 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72  qlite3_uint64 ar
2820: 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20  e the preferred 
2830: 74 79 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73  type definitions
2840: 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f  ..** The sqlite_
2850: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
2860: 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 61 72  _uint64 types ar
2870: 65 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20  e supported for 
2880: 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d  backwards.** com
2890: 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e  patibility only.
28a0: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
28b0: 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71  te3_int64 and sq
28c0: 6c 69 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73  lite_int64 types
28d0: 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67   can store integ
28e0: 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74  er values.** bet
28f0: 77 65 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36  ween -9223372036
2900: 38 35 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39  854775808 and +9
2910: 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38  2233720368547758
2920: 30 37 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e  07 inclusive.  ^
2930: 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75  The.** sqlite3_u
2940: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
2950: 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 63 61  _uint64 types ca
2960: 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20  n store integer 
2970: 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65  values .** betwe
2980: 65 6e 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37  en 0 and +184467
2990: 34 34 30 37 33 37 30 39 35 35 31 36 31 35 20 69  44073709551615 i
29a0: 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66  nclusive..*/.#if
29b0: 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34  def SQLITE_INT64
29c0: 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65 66 20  _TYPE.  typedef 
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 69 6e 74 36 34 3b 0a  E sqlite_int64;.
29f0: 23 20 69 66 64 65 66 20 53 51 4c 49 54 45 5f 55  # ifdef SQLITE_U
2a00: 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 20 20 74  INT64_TYPE.    t
2a10: 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f 55 49  ypedef SQLITE_UI
2a20: 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65  NT64_TYPE sqlite
2a30: 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6c 73 65 20  _uint64;.# else 
2a40: 20 0a 20 20 20 20 74 79 70 65 64 65 66 20 75 6e   .    typedef un
2a50: 73 69 67 6e 65 64 20 53 51 4c 49 54 45 5f 49 4e  signed SQLITE_IN
2a60: 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f  T64_TYPE sqlite_
2a70: 75 69 6e 74 36 34 3b 0a 23 20 65 6e 64 69 66 0a  uint64;.# endif.
2a80: 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d  #elif defined(_M
2a90: 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e  SC_VER) || defin
2aa0: 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29  ed(__BORLANDC__)
2ab0: 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74  .  typedef __int
2ac0: 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b  64 sqlite_int64;
2ad0: 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67  .  typedef unsig
2ae0: 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69  ned __int64 sqli
2af0: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65  te_uint64;.#else
2b00: 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20  .  typedef long 
2b10: 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f  long int sqlite_
2b20: 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66  int64;.  typedef
2b30: 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c   unsigned long l
2b40: 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75  ong int sqlite_u
2b50: 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79  int64;.#endif.ty
2b60: 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74  pedef sqlite_int
2b70: 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  64 sqlite3_int64
2b80: 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65  ;.typedef sqlite
2b90: 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  _uint64 sqlite3_
2ba0: 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49  uint64;../*.** I
2bb0: 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20  f compiling for 
2bc0: 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74  a processor that
2bd0: 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20   lacks floating 
2be0: 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a  point support,.*
2bf0: 2a 20 73 75 62 73 74 69 74 75 74 65 20 69 6e 74  * substitute int
2c00: 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e  eger for floatin
2c10: 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64  g-point..*/.#ifd
2c20: 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46  ef SQLITE_OMIT_F
2c30: 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20  LOATING_POINT.# 
2c40: 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71  define double sq
2c50: 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64  lite3_int64.#end
2c60: 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  if../*.** CAPI3R
2c70: 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61  EF: Closing A Da
2c80: 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
2c90: 6e 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f 52 3a  n.** DESTRUCTOR:
2ca0: 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
2cb0: 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  The sqlite3_clos
2cc0: 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
2cd0: 63 6c 6f 73 65 5f 76 32 28 29 20 72 6f 75 74 69  close_v2() routi
2ce0: 6e 65 73 20 61 72 65 20 64 65 73 74 72 75 63 74  nes are destruct
2cf0: 6f 72 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b  ors.** for the [
2d00: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e  sqlite3] object.
2d10: 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71  .** ^Calls to sq
2d20: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e  lite3_close() an
2d30: 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f  d sqlite3_close_
2d40: 76 32 28 29 20 72 65 74 75 72 6e 20 5b 53 51 4c  v2() return [SQL
2d50: 49 54 45 5f 4f 4b 5d 20 69 66 0a 2a 2a 20 74 68  ITE_OK] if.** th
2d60: 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
2d70: 63 74 20 69 73 20 73 75 63 63 65 73 73 66 75 6c  ct is successful
2d80: 6c 79 20 64 65 73 74 72 6f 79 65 64 20 61 6e 64  ly destroyed and
2d90: 20 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 0a   all associated.
2da0: 2a 2a 20 72 65 73 6f 75 72 63 65 73 20 61 72 65  ** resources are
2db0: 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e 0a 2a 2a   deallocated..**
2dc0: 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61  .** ^If the data
2dd0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2de0: 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  is associated wi
2df0: 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70  th unfinalized p
2e00: 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65  repared.** state
2e10: 6d 65 6e 74 73 20 6f 72 20 75 6e 66 69 6e 69 73  ments or unfinis
2e20: 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61 63 6b  hed sqlite3_back
2e30: 75 70 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20  up objects then 
2e40: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 0a  sqlite3_close().
2e50: 2a 2a 20 77 69 6c 6c 20 6c 65 61 76 65 20 74 68  ** will leave th
2e60: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
2e70: 63 74 69 6f 6e 20 6f 70 65 6e 20 61 6e 64 20 72  ction open and r
2e80: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55  eturn [SQLITE_BU
2e90: 53 59 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  SY]..** ^If sqli
2ea0: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69  te3_close_v2() i
2eb0: 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 75 6e  s called with un
2ec0: 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72  finalized prepar
2ed0: 65 64 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  ed statements.**
2ee0: 20 61 6e 64 2f 6f 72 20 75 6e 66 69 6e 69 73 68   and/or unfinish
2ef0: 65 64 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  ed sqlite3_backu
2f00: 70 73 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74  ps, then the dat
2f10: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2f20: 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e 20 75   becomes.** an u
2f30: 6e 75 73 61 62 6c 65 20 22 7a 6f 6d 62 69 65 22  nusable "zombie"
2f40: 20 77 68 69 63 68 20 77 69 6c 6c 20 61 75 74 6f   which will auto
2f50: 6d 61 74 69 63 61 6c 6c 79 20 62 65 20 64 65 61  matically be dea
2f60: 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e 20 74 68  llocated when th
2f70: 65 0a 2a 2a 20 6c 61 73 74 20 70 72 65 70 61 72  e.** last prepar
2f80: 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  ed statement is 
2f90: 66 69 6e 61 6c 69 7a 65 64 20 6f 72 20 74 68 65  finalized or the
2fa0: 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 62 61   last sqlite3_ba
2fb0: 63 6b 75 70 20 69 73 0a 2a 2a 20 66 69 6e 69 73  ckup is.** finis
2fc0: 68 65 64 2e 20 20 54 68 65 20 73 71 6c 69 74 65  hed.  The sqlite
2fd0: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 6e 74  3_close_v2() int
2fe0: 65 72 66 61 63 65 20 69 73 20 69 6e 74 65 6e 64  erface is intend
2ff0: 65 64 20 66 6f 72 20 75 73 65 20 77 69 74 68 0a  ed for use with.
3000: 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 75 61 67 65  ** host language
3010: 73 20 74 68 61 74 20 61 72 65 20 67 61 72 62 61  s that are garba
3020: 67 65 20 63 6f 6c 6c 65 63 74 65 64 2c 20 61 6e  ge collected, an
3030: 64 20 77 68 65 72 65 20 74 68 65 20 6f 72 64 65  d where the orde
3040: 72 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 64 65  r in which.** de
3050: 73 74 72 75 63 74 6f 72 73 20 61 72 65 20 63 61  structors are ca
3060: 6c 6c 65 64 20 69 73 20 61 72 62 69 74 72 61 72  lled is arbitrar
3070: 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61  y..**.** Applica
3080: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 5b 73 71  tions should [sq
3090: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c  lite3_finalize |
30a0: 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b   finalize] all [
30b0: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
30c0: 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  nts],.** [sqlite
30d0: 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63  3_blob_close | c
30e0: 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20  lose] all [BLOB 
30f0: 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 20 0a 2a  handles], and .*
3100: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  * [sqlite3_backu
3110: 70 5f 66 69 6e 69 73 68 20 7c 20 66 69 6e 69 73  p_finish | finis
3120: 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f  h] all [sqlite3_
3130: 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20  backup] objects 
3140: 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69  associated.** wi
3150: 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d  th the [sqlite3]
3160: 20 6f 62 6a 65 63 74 20 70 72 69 6f 72 20 74 6f   object prior to
3170: 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 63   attempting to c
3180: 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65 63 74 2e  lose the object.
3190: 20 20 5e 49 66 0a 2a 2a 20 73 71 6c 69 74 65 33    ^If.** sqlite3
31a0: 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73 20 63  _close_v2() is c
31b0: 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64 61 74 61  alled on a [data
31c0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
31d0: 20 74 68 61 74 20 73 74 69 6c 6c 20 68 61 73 0a   that still has.
31e0: 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 5b  ** outstanding [
31f0: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
3200: 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64  nts], [BLOB hand
3210: 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20  les], and/or.** 
3220: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d  [sqlite3_backup]
3230: 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20 69 74   objects then it
3240: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
3250: 5f 4f 4b 5d 20 61 6e 64 20 74 68 65 20 64 65 61  _OK] and the dea
3260: 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  llocation.** of 
3270: 72 65 73 6f 75 72 63 65 73 20 69 73 20 64 65 66  resources is def
3280: 65 72 72 65 64 20 75 6e 74 69 6c 20 61 6c 6c 20  erred until all 
3290: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
32a0: 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e  ents], [BLOB han
32b0: 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73  dles],.** and [s
32c0: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f  qlite3_backup] o
32d0: 62 6a 65 63 74 73 20 61 72 65 20 61 6c 73 6f 20  bjects are also 
32e0: 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a 2a 2a  destroyed..**.**
32f0: 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74 65 33   ^If an [sqlite3
3300: 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 65 73 74  ] object is dest
3310: 72 6f 79 65 64 20 77 68 69 6c 65 20 61 20 74 72  royed while a tr
3320: 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65  ansaction is ope
3330: 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61  n,.** the transa
3340: 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74  ction is automat
3350: 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61  ically rolled ba
3360: 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20  ck..**.** The C 
3370: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
3380: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20  lite3_close(C)] 
3390: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  and [sqlite3_clo
33a0: 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d 75 73  se_v2(C)].** mus
33b0: 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e 55  t be either a NU
33c0: 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f 72  LL.** pointer or
33d0: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62   an [sqlite3] ob
33e0: 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62 74  ject pointer obt
33f0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
3400: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
3410: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
3420: 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  )], or.** [sqlit
3430: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61  e3_open_v2()], a
3440: 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73 6c  nd not previousl
3450: 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43 61  y closed..** ^Ca
3460: 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6c  lling sqlite3_cl
3470: 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ose() or sqlite3
3480: 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 69 74 68  _close_v2() with
3490: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a   a NULL pointer.
34a0: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  ** argument is a
34b0: 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e   harmless no-op.
34c0: 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
34d0: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nt sqlite3_close
34e0: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49  (sqlite3*);.SQLI
34f0: 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
3500: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 73 71 6c 69  e3_close_v2(sqli
3510: 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68  te3*);../*.** Th
3520: 65 20 74 79 70 65 20 66 6f 72 20 61 20 63 61 6c  e type for a cal
3530: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a  lback function..
3540: 2a 2a 20 54 68 69 73 20 69 73 20 6c 65 67 61 63  ** This is legac
3550: 79 20 61 6e 64 20 64 65 70 72 65 63 61 74 65 64  y and deprecated
3560: 2e 20 20 49 74 20 69 73 20 69 6e 63 6c 75 64 65  .  It is include
3570: 64 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c  d for historical
3580: 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  .** compatibilit
3590: 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63  y and is not doc
35a0: 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65  umented..*/.type
35b0: 64 65 66 20 69 6e 74 20 28 2a 73 71 6c 69 74 65  def int (*sqlite
35c0: 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64  3_callback)(void
35d0: 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68  *,int,char**, ch
35e0: 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ar**);../*.** CA
35f0: 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70  PI3REF: One-Step
3600: 20 51 75 65 72 79 20 45 78 65 63 75 74 69 6f 6e   Query Execution
3610: 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a 20 4d 45   Interface.** ME
3620: 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
3630: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
3640: 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65  exec() interface
3650: 20 69 73 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63   is a convenienc
3660: 65 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64  e wrapper around
3670: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
3680: 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c  pare_v2()], [sql
3690: 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e  ite3_step()], an
36a0: 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  d [sqlite3_final
36b0: 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74 68 61 74 20  ize()],.** that 
36c0: 61 6c 6c 6f 77 73 20 61 6e 20 61 70 70 6c 69 63  allows an applic
36d0: 61 74 69 6f 6e 20 74 6f 20 72 75 6e 20 6d 75 6c  ation to run mul
36e0: 74 69 70 6c 65 20 73 74 61 74 65 6d 65 6e 74 73  tiple statements
36f0: 20 6f 66 20 53 51 4c 0a 2a 2a 20 77 69 74 68 6f   of SQL.** witho
3700: 75 74 20 68 61 76 69 6e 67 20 74 6f 20 75 73 65  ut having to use
3710: 20 61 20 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65   a lot of C code
3720: 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  . .**.** ^The sq
3730: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74  lite3_exec() int
3740: 65 72 66 61 63 65 20 72 75 6e 73 20 7a 65 72 6f  erface runs zero
3750: 20 6f 72 20 6d 6f 72 65 20 55 54 46 2d 38 20 65   or more UTF-8 e
3760: 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73 65 6d 69 63  ncoded,.** semic
3770: 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 20 53 51  olon-separate SQ
3780: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73  L statements pas
3790: 73 65 64 20 69 6e 74 6f 20 69 74 73 20 32 6e 64  sed into its 2nd
37a0: 20 61 72 67 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e   argument,.** in
37b0: 20 74 68 65 20 63 6f 6e 74 65 78 74 20 6f 66 20   the context of 
37c0: 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
37d0: 6e 6e 65 63 74 69 6f 6e 5d 20 70 61 73 73 65 64  nnection] passed
37e0: 20 69 6e 20 61 73 20 69 74 73 20 31 73 74 0a 2a   in as its 1st.*
37f0: 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66  * argument.  ^If
3800: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75   the callback fu
3810: 6e 63 74 69 6f 6e 20 6f 66 20 74 68 65 20 33 72  nction of the 3r
3820: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
3830: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3840: 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65  is not NULL, the
3850: 6e 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 20  n it is invoked 
3860: 66 6f 72 20 65 61 63 68 20 72 65 73 75 6c 74 20  for each result 
3870: 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75  row.** coming ou
3880: 74 20 6f 66 20 74 68 65 20 65 76 61 6c 75 61 74  t of the evaluat
3890: 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
38a0: 73 2e 20 20 5e 54 68 65 20 34 74 68 20 61 72 67  s.  ^The 4th arg
38b0: 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69  ument to.** sqli
38c0: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 65  te3_exec() is re
38d0: 6c 61 79 65 64 20 74 68 72 6f 75 67 68 20 74 6f  layed through to
38e0: 20 74 68 65 20 31 73 74 20 61 72 67 75 6d 65 6e   the 1st argumen
38f0: 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20 63 61 6c  t of each.** cal
3900: 6c 62 61 63 6b 20 69 6e 76 6f 63 61 74 69 6f 6e  lback invocation
3910: 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62  .  ^If the callb
3920: 61 63 6b 20 70 6f 69 6e 74 65 72 20 74 6f 20 73  ack pointer to s
3930: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
3940: 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e   is NULL, then n
3950: 6f 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 65 76  o callback is ev
3960: 65 72 20 69 6e 76 6f 6b 65 64 20 61 6e 64 20 72  er invoked and r
3970: 65 73 75 6c 74 20 72 6f 77 73 20 61 72 65 0a 2a  esult rows are.*
3980: 2a 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a  * ignored..**.**
3990: 20 5e 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 63   ^If an error oc
39a0: 63 75 72 73 20 77 68 69 6c 65 20 65 76 61 6c 75  curs while evalu
39b0: 61 74 69 6e 67 20 74 68 65 20 53 51 4c 20 73 74  ating the SQL st
39c0: 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20  atements passed 
39d0: 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  into.** sqlite3_
39e0: 65 78 65 63 28 29 2c 20 74 68 65 6e 20 65 78 65  exec(), then exe
39f0: 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 63 75  cution of the cu
3a00: 72 72 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 20  rrent statement 
3a10: 73 74 6f 70 73 20 61 6e 64 0a 2a 2a 20 73 75 62  stops and.** sub
3a20: 73 65 71 75 65 6e 74 20 73 74 61 74 65 6d 65 6e  sequent statemen
3a30: 74 73 20 61 72 65 20 73 6b 69 70 70 65 64 2e 20  ts are skipped. 
3a40: 20 5e 49 66 20 74 68 65 20 35 74 68 20 70 61 72   ^If the 5th par
3a50: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
3a60: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 6e  3_exec().** is n
3a70: 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 61 6e 79  ot NULL then any
3a80: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69   error message i
3a90: 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d  s written into m
3aa0: 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 0a 2a  emory obtained.*
3ab0: 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
3ac0: 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 70 61  malloc()] and pa
3ad0: 73 73 65 64 20 62 61 63 6b 20 74 68 72 6f 75 67  ssed back throug
3ae0: 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  h the 5th parame
3af0: 74 65 72 2e 0a 2a 2a 20 54 6f 20 61 76 6f 69 64  ter..** To avoid
3b00: 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 73 2c 20 74   memory leaks, t
3b10: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
3b20: 68 6f 75 6c 64 20 69 6e 76 6f 6b 65 20 5b 73 71  hould invoke [sq
3b30: 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a  lite3_free()].**
3b40: 20 6f 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   on error messag
3b50: 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e  e strings return
3b60: 65 64 20 74 68 72 6f 75 67 68 20 74 68 65 20 35  ed through the 5
3b70: 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 0a  th parameter of.
3b80: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  ** sqlite3_exec(
3b90: 29 20 61 66 74 65 72 20 74 68 65 20 65 72 72 6f  ) after the erro
3ba0: 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
3bb0: 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65   is no longer ne
3bc0: 65 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  eded..** ^If the
3bd0: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
3be0: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
3bf0: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64   is not NULL and
3c00: 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 63   no errors.** oc
3c10: 63 75 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  cur, then sqlite
3c20: 33 5f 65 78 65 63 28 29 20 73 65 74 73 20 74 68  3_exec() sets th
3c30: 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 69 74 73  e pointer in its
3c40: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
3c50: 6f 0a 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f 72 65  o.** NULL before
3c60: 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a   returning..**.*
3c70: 2a 20 5e 49 66 20 61 6e 20 73 71 6c 69 74 65 33  * ^If an sqlite3
3c80: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
3c90: 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
3ca0: 6f 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65  o, the sqlite3_e
3cb0: 78 65 63 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  xec().** routine
3cc0: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f   returns SQLITE_
3cd0: 41 42 4f 52 54 20 77 69 74 68 6f 75 74 20 69 6e  ABORT without in
3ce0: 76 6f 6b 69 6e 67 20 74 68 65 20 63 61 6c 6c 62  voking the callb
3cf0: 61 63 6b 20 61 67 61 69 6e 20 61 6e 64 0a 2a 2a  ack again and.**
3d00: 20 77 69 74 68 6f 75 74 20 72 75 6e 6e 69 6e 67   without running
3d10: 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20   any subsequent 
3d20: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
3d30: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 32 6e 64 20 61  **.** ^The 2nd a
3d40: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
3d50: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61  qlite3_exec() ca
3d60: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
3d70: 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
3d80: 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
3d90: 68 65 20 72 65 73 75 6c 74 2e 20 20 5e 54 68 65  he result.  ^The
3da0: 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f   3rd argument to
3db0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   the sqlite3_exe
3dc0: 63 28 29 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  c().** callback 
3dd0: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
3de0: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
3df0: 67 73 20 6f 62 74 61 69 6e 65 64 20 61 73 20 69  gs obtained as i
3e00: 66 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74  f from.** [sqlit
3e10: 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
3e20: 5d 2c 20 6f 6e 65 20 66 6f 72 20 65 61 63 68 20  ], one for each 
3e30: 63 6f 6c 75 6d 6e 2e 20 20 5e 49 66 20 61 6e 20  column.  ^If an 
3e40: 65 6c 65 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20  element of a.** 
3e50: 72 65 73 75 6c 74 20 72 6f 77 20 69 73 20 4e 55  result row is NU
3e60: 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f 72 72  LL then the corr
3e70: 65 73 70 6f 6e 64 69 6e 67 20 73 74 72 69 6e 67  esponding string
3e80: 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65   pointer for the
3e90: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3ea0: 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  () callback is a
3eb0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
3ec0: 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e  ^The 4th argumen
3ed0: 74 20 74 6f 20 74 68 65 0a 2a 2a 20 73 71 6c 69  t to the.** sqli
3ee0: 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62  te3_exec() callb
3ef0: 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20  ack is an array 
3f00: 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73  of pointers to s
3f10: 74 72 69 6e 67 73 20 77 68 65 72 65 20 65 61 63  trings where eac
3f20: 68 0a 2a 2a 20 65 6e 74 72 79 20 72 65 70 72 65  h.** entry repre
3f30: 73 65 6e 74 73 20 74 68 65 20 6e 61 6d 65 20 6f  sents the name o
3f40: 66 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  f corresponding 
3f50: 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 61 73  result column as
3f60: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
3f70: 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  m [sqlite3_colum
3f80: 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  n_name()]..**.**
3f90: 20 5e 49 66 20 74 68 65 20 32 6e 64 20 70 61 72   ^If the 2nd par
3fa0: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
3fb0: 33 5f 65 78 65 63 28 29 20 69 73 20 61 20 4e 55  3_exec() is a NU
3fc0: 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 61 20 70 6f  LL pointer, a po
3fd0: 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 61 6e 20 65  inter.** to an e
3fe0: 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 6f 72 20  mpty string, or 
3ff0: 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 63  a pointer that c
4000: 6f 6e 74 61 69 6e 73 20 6f 6e 6c 79 20 77 68 69  ontains only whi
4010: 74 65 73 70 61 63 65 20 61 6e 64 2f 6f 72 20 0a  tespace and/or .
4020: 2a 2a 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c  ** SQL comments,
4030: 20 74 68 65 6e 20 6e 6f 20 53 51 4c 20 73 74 61   then no SQL sta
4040: 74 65 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c  tements are eval
4050: 75 61 74 65 64 20 61 6e 64 20 74 68 65 20 64 61  uated and the da
4060: 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 6e 6f 74  tabase.** is not
4070: 20 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20   changed..**.** 
4080: 52 65 73 74 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a  Restrictions:.**
4090: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
40a0: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
40b0: 20 6d 75 73 74 20 65 6e 73 75 72 65 20 74 68 61   must ensure tha
40c0: 74 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65  t the 1st parame
40d0: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
40e0: 78 65 63 28 29 0a 2a 2a 20 20 20 20 20 20 69 73  xec().**      is
40f0: 20 61 20 76 61 6c 69 64 20 61 6e 64 20 6f 70 65   a valid and ope
4100: 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
4110: 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e  ection]..** <li>
4120: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
4130: 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20   must not close 
4140: 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
4150: 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66  nnection] specif
4160: 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 74  ied by.**      t
4170: 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72  he 1st parameter
4180: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
4190: 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33  () while sqlite3
41a0: 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69  _exec() is runni
41b0: 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  ng..** <li> The 
41c0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
41d0: 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20   not modify the 
41e0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65  SQL statement te
41f0: 78 74 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a  xt passed into.*
4200: 2a 20 20 20 20 20 20 74 68 65 20 32 6e 64 20 70  *      the 2nd p
4210: 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69  arameter of sqli
4220: 74 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65  te3_exec() while
4230: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
4240: 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c  is running..** <
4250: 2f 75 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  /ul>.*/.SQLITE_A
4260: 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  PI int sqlite3_e
4270: 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  xec(.  sqlite3*,
4280: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4290: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
42a0: 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74    /* An open dat
42b0: 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  abase */.  const
42c0: 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 20   char *sql,     
42d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
42e0: 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20        /* SQL to 
42f0: 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a  be evaluated */.
4300: 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b    int (*callback
4310: 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72  )(void*,int,char
4320: 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20  **,char**),  /* 
4330: 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  Callback functio
4340: 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20  n */.  void *,  
4350: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4360: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4370: 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65 6e    /* 1st argumen
4380: 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f  t to callback */
4390: 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67  .  char **errmsg
43a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
43b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
43c0: 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74   Error msg writt
43d0: 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f  en here */.);../
43e0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
43f0: 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b  esult Codes.** K
4400: 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74  EYWORDS: {result
4410: 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f 6e   code definition
4420: 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51  s}.**.** Many SQ
4430: 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  Lite functions r
4440: 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 72  eturn an integer
4450: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72 6f   result code fro
4460: 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e 0a  m the set shown.
4470: 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65 72  ** here in order
4480: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75 63   to indicate suc
4490: 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65 2e  cess or failure.
44a0: 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f 72  .**.** New error
44b0: 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61 64   codes may be ad
44c0: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76 65  ded in future ve
44d0: 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
44e0: 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
44f0: 3a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  : [extended resu
4500: 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69  lt code definiti
4510: 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ons].*/.#define 
4520: 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20  SQLITE_OK       
4530: 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65      0   /* Succe
4540: 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a  ssful result */.
4550: 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d  /* beginning-of-
4560: 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23  error-codes */.#
4570: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52  define SQLITE_ER
4580: 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20 2f  ROR        1   /
4590: 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d  * SQL error or m
45a0: 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 65 20  issing database 
45b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
45c0: 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32  E_INTERNAL     2
45d0: 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c     /* Internal l
45e0: 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51  ogic error in SQ
45f0: 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  Lite */.#define 
4600: 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20  SQLITE_PERM     
4610: 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73      3   /* Acces
4620: 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e  s permission den
4630: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ied */.#define S
4640: 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20  QLITE_ABORT     
4650: 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61     4   /* Callba
4660: 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65  ck routine reque
4670: 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f  sted an abort */
4680: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4690: 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20 20  BUSY         5  
46a0: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65   /* The database
46b0: 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20   file is locked 
46c0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
46d0: 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36  E_LOCKED       6
46e0: 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e     /* A table in
46f0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
4700: 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69   locked */.#defi
4710: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20  ne SQLITE_NOMEM 
4720: 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20         7   /* A 
4730: 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20  malloc() failed 
4740: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4750: 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38  E_READONLY     8
4760: 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f     /* Attempt to
4770: 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c   write a readonl
4780: 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64  y database */.#d
4790: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
47a0: 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a  ERRUPT    9   /*
47b0: 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69   Operation termi
47c0: 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  nated by sqlite3
47d0: 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23  _interrupt()*/.#
47e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
47f0: 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20 2f  ERR       10   /
4800: 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64  * Some kind of d
4810: 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63  isk I/O error oc
4820: 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e  curred */.#defin
4830: 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54  e SQLITE_CORRUPT
4840: 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65       11   /* The
4850: 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20 69   database disk i
4860: 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65  mage is malforme
4870: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4880: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20  ITE_NOTFOUND    
4890: 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20  12   /* Unknown 
48a0: 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74 65  opcode in sqlite
48b0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
48c0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
48d0: 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31  TE_FULL        1
48e0: 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e  3   /* Insertion
48f0: 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65 20   failed because 
4900: 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c  database is full
4910: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4920: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31  TE_CANTOPEN    1
4930: 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f  4   /* Unable to
4940: 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61   open the databa
4950: 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69  se file */.#defi
4960: 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43  ne SQLITE_PROTOC
4970: 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44 61  OL    15   /* Da
4980: 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74  tabase lock prot
4990: 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64  ocol error */.#d
49a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50  efine SQLITE_EMP
49b0: 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a  TY       16   /*
49c0: 20 44 61 74 61 62 61 73 65 20 69 73 20 65 6d 70   Database is emp
49d0: 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ty */.#define SQ
49e0: 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20  LITE_SCHEMA     
49f0: 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74   17   /* The dat
4a00: 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
4a10: 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nged */.#define 
4a20: 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20  SQLITE_TOOBIG   
4a30: 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e     18   /* Strin
4a40: 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64  g or BLOB exceed
4a50: 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a  s size limit */.
4a60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
4a70: 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 20  ONSTRAINT  19   
4a80: 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20  /* Abort due to 
4a90: 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
4aa0: 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  tion */.#define 
4ab0: 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20  SQLITE_MISMATCH 
4ac0: 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20     20   /* Data 
4ad0: 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f  type mismatch */
4ae0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4af0: 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20  MISUSE      21  
4b00: 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64   /* Library used
4b10: 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a   incorrectly */.
4b20: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
4b30: 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20  OLFS       22   
4b40: 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75  /* Uses OS featu
4b50: 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65  res not supporte
4b60: 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65  d on host */.#de
4b70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48  fine SQLITE_AUTH
4b80: 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20          23   /* 
4b90: 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65  Authorization de
4ba0: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
4bb0: 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20  SQLITE_FORMAT   
4bc0: 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c     24   /* Auxil
4bd0: 69 61 72 79 20 64 61 74 61 62 61 73 65 20 66 6f  iary database fo
4be0: 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64  rmat error */.#d
4bf0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e  efine SQLITE_RAN
4c00: 47 45 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a  GE       25   /*
4c10: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74   2nd parameter t
4c20: 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f  o sqlite3_bind o
4c30: 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23  ut of range */.#
4c40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
4c50: 54 41 44 42 20 20 20 20 20 20 32 36 20 20 20 2f  TADB      26   /
4c60: 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68  * File opened th
4c70: 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61  at is not a data
4c80: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65  base file */.#de
4c90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
4ca0: 43 45 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20  CE      27   /* 
4cb0: 4e 6f 74 69 66 69 63 61 74 69 6f 6e 73 20 66 72  Notifications fr
4cc0: 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  om sqlite3_log()
4cd0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4ce0: 54 45 5f 57 41 52 4e 49 4e 47 20 20 20 20 20 32  TE_WARNING     2
4cf0: 38 20 20 20 2f 2a 20 57 61 72 6e 69 6e 67 73 20  8   /* Warnings 
4d00: 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67  from sqlite3_log
4d10: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
4d20: 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20  LITE_ROW        
4d30: 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33   100  /* sqlite3
4d40: 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74  _step() has anot
4d50: 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f  her row ready */
4d60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4d70: 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31 20  DONE        101 
4d80: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70   /* sqlite3_step
4d90: 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  () has finished 
4da0: 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20  executing */./* 
4db0: 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64  end-of-error-cod
4dc0: 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  es */../*.** CAP
4dd0: 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20  I3REF: Extended 
4de0: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
4df0: 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e  KEYWORDS: {exten
4e00: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20  ded result code 
4e10: 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a  definitions}.**.
4e20: 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61 75 6c  ** In its defaul
4e30: 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c  t configuration,
4e40: 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75 74   SQLite API rout
4e50: 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65 20  ines return one 
4e60: 6f 66 20 33 30 20 69 6e 74 65 67 65 72 0a 2a 2a  of 30 integer.**
4e70: 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e   [result codes].
4e80: 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70 65 72    However, exper
4e90: 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77 6e 20  ience has shown 
4ea0: 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20  that many of.** 
4eb0: 74 68 65 73 65 20 72 65 73 75 6c 74 20 63 6f 64  these result cod
4ec0: 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61 72 73  es are too coars
4ed0: 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68 65 79  e-grained.  They
4ee0: 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65 20   do not provide 
4ef0: 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72  as.** much infor
4f00: 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f  mation about pro
4f10: 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72 61 6d  blems as program
4f20: 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e  mers might like.
4f30: 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74 20 74    In an effort t
4f40: 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74 68 69  o.** address thi
4f50: 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e  s, newer version
4f60: 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76 65 72  s of SQLite (ver
4f70: 73 69 6f 6e 20 33 2e 33 2e 38 20 5b 64 61 74 65  sion 3.3.8 [date
4f80: 6f 66 3a 33 2e 33 2e 38 5d 0a 2a 2a 20 61 6e 64  of:3.3.8].** and
4f90: 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a   later) include.
4fa0: 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61  ** support for a
4fb0: 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74  dditional result
4fc0: 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76   codes that prov
4fd0: 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65  ide more detaile
4fe0: 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a  d information.**
4ff0: 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 54   about errors. T
5000: 68 65 73 65 20 5b 65 78 74 65 6e 64 65 64 20 72  hese [extended r
5010: 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 61 72 65  esult codes] are
5020: 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61   enabled or disa
5030: 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72  bled.** on a per
5040: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
5050: 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67  tion basis using
5060: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
5070: 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
5080: 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 20 20  _codes()] API.  
5090: 4f 72 2c 20 74 68 65 20 65 78 74 65 6e 64 65 64  Or, the extended
50a0: 20 63 6f 64 65 20 66 6f 72 0a 2a 2a 20 74 68 65   code for.** the
50b0: 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 72 72   most recent err
50c0: 6f 72 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e  or can be obtain
50d0: 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  ed using.** [sql
50e0: 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72  ite3_extended_er
50f0: 72 63 6f 64 65 28 29 5d 2e 0a 2a 2f 0a 23 64 65  rcode()]..*/.#de
5100: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5110: 52 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20  R_READ          
5120: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5130: 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  R | (1<<8)).#def
5140: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5150: 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20  _SHORT_READ     
5160: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5170: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
5180: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5190: 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20  WRITE           
51a0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
51b0: 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (3<<8)).#defin
51c0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46  e SQLITE_IOERR_F
51d0: 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20  SYNC            
51e0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
51f0: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (4<<8)).#define
5200: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49   SQLITE_IOERR_DI
5210: 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20  R_FSYNC         
5220: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5230: 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (5<<8)).#define 
5240: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55  SQLITE_IOERR_TRU
5250: 4e 43 41 54 45 20 20 20 20 20 20 20 20 20 20 28  NCATE          (
5260: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5270: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
5280: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41  QLITE_IOERR_FSTA
5290: 54 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53  T             (S
52a0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37  QLITE_IOERR | (7
52b0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
52c0: 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43  LITE_IOERR_UNLOC
52d0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  K            (SQ
52e0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c  LITE_IOERR | (8<
52f0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5300: 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b  ITE_IOERR_RDLOCK
5310: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5320: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c  ITE_IOERR | (9<<
5330: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5340: 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20  TE_IOERR_DELETE 
5350: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5360: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c  TE_IOERR | (10<<
5370: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5380: 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
5390: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
53a0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c  TE_IOERR | (11<<
53b0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
53c0: 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20  TE_IOERR_NOMEM  
53d0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
53e0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c  TE_IOERR | (12<<
53f0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5400: 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20  TE_IOERR_ACCESS 
5410: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5420: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c  TE_IOERR | (13<<
5430: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5440: 54 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45  TE_IOERR_CHECKRE
5450: 53 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49  SERVEDLOCK (SQLI
5460: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c  TE_IOERR | (14<<
5470: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5480: 54 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20  TE_IOERR_LOCK   
5490: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
54a0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c  TE_IOERR | (15<<
54b0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
54c0: 54 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20  TE_IOERR_CLOSE  
54d0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
54e0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c  TE_IOERR | (16<<
54f0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5500: 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f  TE_IOERR_DIR_CLO
5510: 53 45 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  SE         (SQLI
5520: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c  TE_IOERR | (17<<
5530: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5540: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4f 50 45 4e  TE_IOERR_SHMOPEN
5550: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5560: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 38 3c 3c  TE_IOERR | (18<<
5570: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5580: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 53 49 5a 45  TE_IOERR_SHMSIZE
5590: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
55a0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 39 3c 3c  TE_IOERR | (19<<
55b0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
55c0: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b  TE_IOERR_SHMLOCK
55d0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
55e0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 30 3c 3c  TE_IOERR | (20<<
55f0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5600: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4d 41 50 20  TE_IOERR_SHMMAP 
5610: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5620: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 31 3c 3c  TE_IOERR | (21<<
5630: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5640: 54 45 5f 49 4f 45 52 52 5f 53 45 45 4b 20 20 20  TE_IOERR_SEEK   
5650: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5660: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 32 3c 3c  TE_IOERR | (22<<
5670: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5680: 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 5f  TE_IOERR_DELETE_
5690: 4e 4f 45 4e 54 20 20 20 20 20 20 28 53 51 4c 49  NOENT      (SQLI
56a0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 33 3c 3c  TE_IOERR | (23<<
56b0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
56c0: 54 45 5f 49 4f 45 52 52 5f 4d 4d 41 50 20 20 20  TE_IOERR_MMAP   
56d0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
56e0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 34 3c 3c  TE_IOERR | (24<<
56f0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5700: 54 45 5f 49 4f 45 52 52 5f 47 45 54 54 45 4d 50  TE_IOERR_GETTEMP
5710: 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49  PATH       (SQLI
5720: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 35 3c 3c  TE_IOERR | (25<<
5730: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5740: 54 45 5f 49 4f 45 52 52 5f 43 4f 4e 56 50 41 54  TE_IOERR_CONVPAT
5750: 48 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  H          (SQLI
5760: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 36 3c 3c  TE_IOERR | (26<<
5770: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5780: 54 45 5f 49 4f 45 52 52 5f 56 4e 4f 44 45 20 20  TE_IOERR_VNODE  
5790: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
57a0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 37 3c 3c  TE_IOERR | (27<<
57b0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
57c0: 54 45 5f 49 4f 45 52 52 5f 41 55 54 48 20 20 20  TE_IOERR_AUTH   
57d0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
57e0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 38 3c 3c  TE_IOERR | (28<<
57f0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5800: 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44  TE_LOCKED_SHARED
5810: 43 41 43 48 45 20 20 20 20 20 20 28 53 51 4c 49  CACHE      (SQLI
5820: 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c  TE_LOCKED |  (1<
5830: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5840: 49 54 45 5f 42 55 53 59 5f 52 45 43 4f 56 45 52  ITE_BUSY_RECOVER
5850: 59 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  Y           (SQL
5860: 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28 31  ITE_BUSY   |  (1
5870: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5880: 4c 49 54 45 5f 42 55 53 59 5f 53 4e 41 50 53 48  LITE_BUSY_SNAPSH
5890: 4f 54 20 20 20 20 20 20 20 20 20 20 20 28 53 51  OT           (SQ
58a0: 4c 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28  LITE_BUSY   |  (
58b0: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
58c0: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e  QLITE_CANTOPEN_N
58d0: 4f 54 45 4d 50 44 49 52 20 20 20 20 20 20 28 53  OTEMPDIR      (S
58e0: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c  QLITE_CANTOPEN |
58f0: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
5900: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e   SQLITE_CANTOPEN
5910: 5f 49 53 44 49 52 20 20 20 20 20 20 20 20 20 20  _ISDIR          
5920: 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  (SQLITE_CANTOPEN
5930: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
5940: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  ne SQLITE_CANTOP
5950: 45 4e 5f 46 55 4c 4c 50 41 54 48 20 20 20 20 20  EN_FULLPATH     
5960: 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50    (SQLITE_CANTOP
5970: 45 4e 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65  EN | (3<<8)).#de
5980: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54  fine SQLITE_CANT
5990: 4f 50 45 4e 5f 43 4f 4e 56 50 41 54 48 20 20 20  OPEN_CONVPATH   
59a0: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54      (SQLITE_CANT
59b0: 4f 50 45 4e 20 7c 20 28 34 3c 3c 38 29 29 0a 23  OPEN | (4<<8)).#
59c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
59d0: 52 52 55 50 54 5f 56 54 41 42 20 20 20 20 20 20  RRUPT_VTAB      
59e0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
59f0: 52 52 55 50 54 20 7c 20 28 31 3c 3c 38 29 29 0a  RRUPT | (1<<8)).
5a00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
5a10: 45 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 52 59  EADONLY_RECOVERY
5a20: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52         (SQLITE_R
5a30: 45 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38 29  EADONLY | (1<<8)
5a40: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5a50: 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c 4f  _READONLY_CANTLO
5a60: 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  CK       (SQLITE
5a70: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32 3c 3c  _READONLY | (2<<
5a80: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5a90: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 4f 4c 4c  TE_READONLY_ROLL
5aa0: 42 41 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49  BACK       (SQLI
5ab0: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 33  TE_READONLY | (3
5ac0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5ad0: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 44 42  LITE_READONLY_DB
5ae0: 4d 4f 56 45 44 20 20 20 20 20 20 20 20 28 53 51  MOVED        (SQ
5af0: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20  LITE_READONLY | 
5b00: 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (4<<8)).#define 
5b10: 53 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c  SQLITE_ABORT_ROL
5b20: 4c 42 41 43 4b 20 20 20 20 20 20 20 20 20 20 28  LBACK          (
5b30: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28  SQLITE_ABORT | (
5b40: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
5b50: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5b60: 5f 43 48 45 43 4b 20 20 20 20 20 20 20 20 28 53  _CHECK        (S
5b70: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5b80: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
5b90: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5ba0: 41 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20  AINT_COMMITHOOK 
5bb0: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5bc0: 41 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23  AINT | (2<<8)).#
5bd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5be0: 4e 53 54 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e  NSTRAINT_FOREIGN
5bf0: 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f  KEY   (SQLITE_CO
5c00: 4e 53 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38  NSTRAINT | (3<<8
5c10: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5c20: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e  E_CONSTRAINT_FUN
5c30: 43 54 49 4f 4e 20 20 20 20 20 28 53 51 4c 49 54  CTION     (SQLIT
5c40: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5c50: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
5c60: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5c70: 5f 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28 53  _NOTNULL      (S
5c80: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5c90: 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69   | (5<<8)).#defi
5ca0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5cb0: 41 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59 20  AINT_PRIMARYKEY 
5cc0: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5cd0: 41 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23  AINT | (6<<8)).#
5ce0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5cf0: 4e 53 54 52 41 49 4e 54 5f 54 52 49 47 47 45 52  NSTRAINT_TRIGGER
5d00: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5d10: 4e 53 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38  NSTRAINT | (7<<8
5d20: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5d30: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49  E_CONSTRAINT_UNI
5d40: 51 55 45 20 20 20 20 20 20 20 28 53 51 4c 49 54  QUE       (SQLIT
5d50: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5d60: 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  8<<8)).#define S
5d70: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5d80: 5f 56 54 41 42 20 20 20 20 20 20 20 20 20 28 53  _VTAB         (S
5d90: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5da0: 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69   | (9<<8)).#defi
5db0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5dc0: 41 49 4e 54 5f 52 4f 57 49 44 20 20 20 20 20 20  AINT_ROWID      
5dd0: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5de0: 41 49 4e 54 20 7c 28 31 30 3c 3c 38 29 29 0a 23  AINT |(10<<8)).#
5df0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
5e00: 54 49 43 45 5f 52 45 43 4f 56 45 52 5f 57 41 4c  TICE_RECOVER_WAL
5e10: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4e 4f        (SQLITE_NO
5e20: 54 49 43 45 20 7c 20 28 31 3c 3c 38 29 29 0a 23  TICE | (1<<8)).#
5e30: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
5e40: 54 49 43 45 5f 52 45 43 4f 56 45 52 5f 52 4f 4c  TICE_RECOVER_ROL
5e50: 4c 42 41 43 4b 20 28 53 51 4c 49 54 45 5f 4e 4f  LBACK (SQLITE_NO
5e60: 54 49 43 45 20 7c 20 28 32 3c 3c 38 29 29 0a 23  TICE | (2<<8)).#
5e70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41  define SQLITE_WA
5e80: 52 4e 49 4e 47 5f 41 55 54 4f 49 4e 44 45 58 20  RNING_AUTOINDEX 
5e90: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 57 41        (SQLITE_WA
5ea0: 52 4e 49 4e 47 20 7c 20 28 31 3c 3c 38 29 29 0a  RNING | (1<<8)).
5eb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
5ec0: 55 54 48 5f 55 53 45 52 20 20 20 20 20 20 20 20  UTH_USER        
5ed0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41         (SQLITE_A
5ee0: 55 54 48 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  UTH | (1<<8)).#d
5ef0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 5f  efine SQLITE_OK_
5f00: 4c 4f 41 44 5f 50 45 52 4d 41 4e 45 4e 54 4c 59  LOAD_PERMANENTLY
5f10: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4f 4b 20       (SQLITE_OK 
5f20: 7c 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a  | (1<<8))../*.**
5f30: 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73   CAPI3REF: Flags
5f40: 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f   For File Open O
5f50: 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  perations.**.** 
5f60: 54 68 65 73 65 20 62 69 74 20 76 61 6c 75 65 73  These bit values
5f70: 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f   are intended fo
5f80: 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20  r use in the.** 
5f90: 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
5fa0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70   the [sqlite3_op
5fb0: 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61  en_v2()] interfa
5fc0: 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65  ce and.** in the
5fd0: 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
5fe0: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  o the [sqlite3_v
5ff0: 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64  fs.xOpen] method
6000: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
6010: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
6020: 59 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30  Y         0x0000
6030: 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0001  /* Ok for 
6040: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
6050: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
6060: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
6070: 54 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30  TE        0x0000
6080: 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0002  /* Ok for 
6090: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
60a0: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
60b0: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20  ITE_OPEN_CREATE 
60c0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
60d0: 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0004  /* Ok for 
60e0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
60f0: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
6100: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
6110: 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30  NCLOSE    0x0000
6120: 30 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0008  /* VFS onl
6130: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
6140: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
6150: 56 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30  VE        0x0000
6160: 30 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0010  /* VFS onl
6170: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
6180: 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f  ITE_OPEN_AUTOPRO
6190: 58 59 20 20 20 20 20 20 20 20 30 78 30 30 30 30  XY        0x0000
61a0: 30 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0020  /* VFS onl
61b0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
61c0: 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20  ITE_OPEN_URI    
61d0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
61e0: 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0040  /* Ok for 
61f0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
6200: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
6210: 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20  ITE_OPEN_MEMORY 
6220: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6230: 30 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0080  /* Ok for 
6240: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
6250: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
6260: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
6270: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6280: 30 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0100  /* VFS onl
6290: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
62a0: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42  ITE_OPEN_TEMP_DB
62b0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
62c0: 30 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0200  /* VFS onl
62d0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
62e0: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45  ITE_OPEN_TRANSIE
62f0: 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 30  NT_DB     0x0000
6300: 30 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0400  /* VFS onl
6310: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
6320: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f  ITE_OPEN_MAIN_JO
6330: 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30  URNAL     0x0000
6340: 30 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0800  /* VFS onl
6350: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
6360: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f  ITE_OPEN_TEMP_JO
6370: 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30  URNAL     0x0000
6380: 31 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  1000  /* VFS onl
6390: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
63a0: 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52  ITE_OPEN_SUBJOUR
63b0: 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 30  NAL       0x0000
63c0: 32 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  2000  /* VFS onl
63d0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
63e0: 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f  ITE_OPEN_MASTER_
63f0: 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30  JOURNAL   0x0000
6400: 34 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  4000  /* VFS onl
6410: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
6420: 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
6430: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6440: 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  8000  /* Ok for 
6450: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
6460: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
6470: 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54  ITE_OPEN_FULLMUT
6480: 45 58 20 20 20 20 20 20 20 20 30 78 30 30 30 31  EX        0x0001
6490: 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0000  /* Ok for 
64a0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
64b0: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
64c0: 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
64d0: 41 43 48 45 20 20 20 20 20 20 30 78 30 30 30 32  ACHE      0x0002
64e0: 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0000  /* Ok for 
64f0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
6500: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
6510: 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
6520: 43 41 43 48 45 20 20 20 20 20 30 78 30 30 30 34  CACHE     0x0004
6530: 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0000  /* Ok for 
6540: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
6550: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
6560: 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20  ITE_OPEN_WAL    
6570: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 38            0x0008
6580: 30 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0000  /* VFS onl
6590: 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65  y */../* Reserve
65a0: 64 3a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  d:              
65b0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 46             0x00F
65c0: 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  00000 */../*.** 
65d0: 43 41 50 49 33 52 45 46 3a 20 44 65 76 69 63 65  CAPI3REF: Device
65e0: 20 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73   Characteristics
65f0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69  .**.** The xDevi
6600: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63  ceCharacteristic
6610: 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  s method of the 
6620: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
6630: 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72  ods].** object r
6640: 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65  eturns an intege
6650: 72 20 77 68 69 63 68 20 69 73 20 61 20 76 65 63  r which is a vec
6660: 74 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  tor of these.** 
6670: 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65  bit values expre
6680: 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63  ssing I/O charac
6690: 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65  teristics of the
66a0: 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a   mass storage.**
66b0: 20 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c   device that hol
66c0: 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74  ds the file that
66d0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
66e0: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66  _methods].** ref
66f0: 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68  ers to..**.** Th
6700: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6710: 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d  TOMIC property m
6720: 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72  eans that all wr
6730: 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73  ites of.** any s
6740: 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  ize are atomic. 
6750: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6760: 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75  P_ATOMICnnn valu
6770: 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20  es.** mean that 
6780: 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73  writes of blocks
6790: 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79   that are nnn by
67a0: 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a  tes in size and.
67b0: 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74  ** are aligned t
67c0: 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69  o an address whi
67d0: 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ch is an integer
67e0: 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20   multiple of.** 
67f0: 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  nnn are atomic. 
6800: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6810: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61  P_SAFE_APPEND va
6820: 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61  lue means.** tha
6830: 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61  t when data is a
6840: 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c  ppended to a fil
6850: 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61  e, the data is a
6860: 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74  ppended.** first
6870: 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f   then the size o
6880: 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78  f the file is ex
6890: 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68  tended, never th
68a0: 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61  e other.** way a
68b0: 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49  round.  The SQLI
68c0: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
68d0: 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61  IAL property mea
68e0: 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72  ns that.** infor
68f0: 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65  mation is writte
6900: 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65  n to disk in the
6910: 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63   same order as c
6920: 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74  alls.** to xWrit
6930: 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45  e().  The SQLITE
6940: 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45  _IOCAP_POWERSAFE
6950: 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f 70 65  _OVERWRITE prope
6960: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a  rty means that.*
6970: 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66  * after reboot f
6980: 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68  ollowing a crash
6990: 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20   or power loss, 
69a0: 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69  the only bytes i
69b0: 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74  n a.** file that
69c0: 20 77 65 72 65 20 77 72 69 74 74 65 6e 20 61 74   were written at
69d0: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
69e0: 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76   level might hav
69f0: 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64  e changed.** and
6a00: 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62   that adjacent b
6a10: 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73  ytes, even bytes
6a20: 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65   within the same
6a30: 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67   sector are.** g
6a40: 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20  uaranteed to be 
6a50: 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20  unchanged.  The 
6a60: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44  SQLITE_IOCAP_UND
6a70: 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50  ELETABLE_WHEN_OP
6a80: 45 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e 64 69 63  EN.** flag indic
6a90: 61 74 65 73 20 74 68 61 74 20 61 20 66 69 6c 65  ates that a file
6aa0: 20 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65 74   cannot be delet
6ab0: 65 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20 54  ed when open.  T
6ac0: 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 43  he.** SQLITE_IOC
6ad0: 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c 61  AP_IMMUTABLE fla
6ae0: 67 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74  g indicates that
6af0: 20 74 68 65 20 66 69 6c 65 20 69 73 20 6f 6e 0a   the file is on.
6b00: 2a 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64  ** read-only med
6b10: 69 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62 65  ia and cannot be
6b20: 20 63 68 61 6e 67 65 64 20 65 76 65 6e 20 62 79   changed even by
6b30: 20 70 72 6f 63 65 73 73 65 73 20 77 69 74 68 0a   processes with.
6b40: 2a 2a 20 65 6c 65 76 61 74 65 64 20 70 72 69 76  ** elevated priv
6b50: 69 6c 65 67 65 73 2e 0a 2a 2f 0a 23 64 65 66 69  ileges..*/.#defi
6b60: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6b70: 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20  ATOMIC          
6b80: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
6b90: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
6ba0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32  _IOCAP_ATOMIC512
6bb0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6bc0: 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65  00000002.#define
6bd0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6be0: 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 20 20  OMIC1K          
6bf0: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0a       0x00000004.
6c00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6c10: 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20  OCAP_ATOMIC2K   
6c20: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6c30: 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53  000008.#define S
6c40: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6c50: 49 43 34 4b 20 20 20 20 20 20 20 20 20 20 20 20  IC4K            
6c60: 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23 64     0x00000010.#d
6c70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6c80: 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20 20  AP_ATOMIC8K     
6c90: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6ca0: 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0020.#define SQL
6cb0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6cc0: 31 36 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  16K             
6cd0: 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 65 66   0x00000040.#def
6ce0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6cf0: 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20  _ATOMIC32K      
6d00: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6d10: 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  80.#define SQLIT
6d20: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34  E_IOCAP_ATOMIC64
6d30: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  K              0
6d40: 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e  x00000100.#defin
6d50: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
6d60: 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20 20  AFE_APPEND      
6d70: 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30        0x00000200
6d80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6d90: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
6da0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6db0: 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20  0000400.#define 
6dc0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44  SQLITE_IOCAP_UND
6dd0: 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50  ELETABLE_WHEN_OP
6de0: 45 4e 20 20 30 78 30 30 30 30 30 38 30 30 0a 23  EN  0x00000800.#
6df0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6e00: 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  CAP_POWERSAFE_OV
6e10: 45 52 57 52 49 54 45 20 20 20 20 30 78 30 30 30  ERWRITE    0x000
6e20: 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51  01000.#define SQ
6e30: 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54  LITE_IOCAP_IMMUT
6e40: 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 20  ABLE            
6e50: 20 20 30 78 30 30 30 30 32 30 30 30 0a 0a 2f 2a    0x00002000../*
6e60: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69  .** CAPI3REF: Fi
6e70: 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c  le Locking Level
6e80: 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75  s.**.** SQLite u
6e90: 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65  ses one of these
6ea0: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
6eb0: 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  as the second.**
6ec0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c   argument to cal
6ed0: 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74  ls it makes to t
6ee0: 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78  he xLock() and x
6ef0: 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73  Unlock() methods
6f00: 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74  .** of an [sqlit
6f10: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
6f20: 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e  bject..*/.#defin
6f30: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f  e SQLITE_LOCK_NO
6f40: 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a 23 64  NE          0.#d
6f50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
6f60: 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 20  K_SHARED        
6f70: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
6f80: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20  _LOCK_RESERVED  
6f90: 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
6fa0: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e  LITE_LOCK_PENDIN
6fb0: 47 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e  G       3.#defin
6fc0: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58  e SQLITE_LOCK_EX
6fd0: 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f  CLUSIVE     4../
6fe0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
6ff0: 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54  ynchronization T
7000: 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20  ype Flags.**.** 
7010: 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f  When SQLite invo
7020: 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28 29 20  kes the xSync() 
7030: 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20  method of an.** 
7040: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
7050: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75  ods] object it u
7060: 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f  ses a combinatio
7070: 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e  n of.** these in
7080: 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20  teger values as 
7090: 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
70a0: 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  ent..**.** When 
70b0: 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  the SQLITE_SYNC_
70c0: 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73  DATAONLY flag is
70d0: 20 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20   used, it means 
70e0: 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63  that the.** sync
70f0: 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20   operation only 
7100: 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64  needs to flush d
7110: 61 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72  ata to mass stor
7120: 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69  age.  Inode.** i
7130: 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20  nformation need 
7140: 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20  not be flushed. 
7150: 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75  If the lower fou
7160: 72 20 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c  r bits of the fl
7170: 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49  ag.** equal SQLI
7180: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20  TE_SYNC_NORMAL, 
7190: 74 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73  that means to us
71a0: 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29  e normal fsync()
71b0: 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49   semantics..** I
71c0: 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72  f the lower four
71d0: 20 62 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49   bits equal SQLI
71e0: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68  TE_SYNC_FULL, th
71f0: 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75  at means.** to u
7200: 73 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c  se Mac OS X styl
7210: 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65  e fullsync inste
7220: 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a  ad of fsync()..*
7230: 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66  *.** Do not conf
7240: 75 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f 53  use the SQLITE_S
7250: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53  YNC_NORMAL and S
7260: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
7270: 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20 74 68  flags.** with th
7280: 65 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72  e [PRAGMA synchr
7290: 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e  onous]=NORMAL an
72a0: 64 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72  d [PRAGMA synchr
72b0: 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73  onous]=FULL.** s
72c0: 65 74 74 69 6e 67 73 2e 20 20 54 68 65 20 5b 73  ettings.  The [s
72d0: 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d  ynchronous pragm
72e0: 61 5d 20 64 65 74 65 72 6d 69 6e 65 73 20 77 68  a] determines wh
72f0: 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a  en calls to the.
7300: 2a 2a 20 78 53 79 6e 63 20 56 46 53 20 6d 65 74  ** xSync VFS met
7310: 68 6f 64 20 6f 63 63 75 72 20 61 6e 64 20 61 70  hod occur and ap
7320: 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20  plies uniformly 
7330: 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66  across all platf
7340: 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  orms..** The SQL
7350: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20  ITE_SYNC_NORMAL 
7360: 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  and SQLITE_SYNC_
7370: 46 55 4c 4c 20 66 6c 61 67 73 20 64 65 74 65 72  FULL flags deter
7380: 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72  mine how.** ener
7390: 67 65 74 69 63 20 6f 72 20 72 69 67 6f 72 6f 75  getic or rigorou
73a0: 73 20 6f 72 20 66 6f 72 63 65 66 75 6c 20 74 68  s or forceful th
73b0: 65 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e  e sync operation
73c0: 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c  s are and.** onl
73d0: 79 20 6d 61 6b 65 20 61 20 64 69 66 66 65 72 65  y make a differe
73e0: 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66  nce on Mac OSX f
73f0: 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74 20 53  or the default S
7400: 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28  QLite code..** (
7410: 54 68 69 72 64 2d 70 61 72 74 79 20 56 46 53 20  Third-party VFS 
7420: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
7430: 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20  might also make 
7440: 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a  the distinction.
7450: 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54  ** between SQLIT
7460: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e  E_SYNC_NORMAL an
7470: 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  d SQLITE_SYNC_FU
7480: 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74 68  LL, but among th
7490: 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20 73  e.** operating s
74a0: 79 73 74 65 6d 73 20 6e 61 74 69 76 65 6c 79 20  ystems natively 
74b0: 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c  supported by SQL
74c0: 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53  ite, only Mac OS
74d0: 58 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f 75 74  X.** cares about
74e0: 20 74 68 65 20 64 69 66 66 65 72 65 6e 63 65 2e   the difference.
74f0: 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ).*/.#define SQL
7500: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20  ITE_SYNC_NORMAL 
7510: 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a 23         0x00002.#
7520: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59  define SQLITE_SY
7530: 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20  NC_FULL         
7540: 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65   0x00003.#define
7550: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54   SQLITE_SYNC_DAT
7560: 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30  AONLY      0x000
7570: 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  10../*.** CAPI3R
7580: 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65  EF: OS Interface
7590: 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c   Open File Handl
75a0: 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69  e.**.** An [sqli
75b0: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
75c0: 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f   represents an o
75d0: 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 20  pen file in the 
75e0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  .** [sqlite3_vfs
75f0: 20 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20   | OS interface 
7600: 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69 64  layer].  Individ
7610: 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 65  ual OS interface
7620: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
7630: 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74  ons will.** want
7640: 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69   to subclass thi
7650: 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65  s object by appe
7660: 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c  nding additional
7670: 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74   fields.** for t
7680: 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54  heir own use.  T
7690: 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72  he pMethods entr
76a0: 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  y is a pointer t
76b0: 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  o an.** [sqlite3
76c0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
76d0: 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73  ect that defines
76e0: 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72   methods for per
76f0: 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f  forming.** I/O o
7700: 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65  perations on the
7710: 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74   open file..*/.t
7720: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
7730: 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74  lite3_file sqlit
7740: 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20  e3_file;.struct 
7750: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20  sqlite3_file {. 
7760: 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71   const struct sq
7770: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
7780: 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20   *pMethods;  /* 
7790: 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f  Methods for an o
77a0: 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a  pen file */.};..
77b0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
77c0: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c  OS Interface Fil
77d0: 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64  e Virtual Method
77e0: 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45  s Object.**.** E
77f0: 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64  very file opened
7800: 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
7810: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
7820: 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a  od populates an.
7830: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
7840: 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f  ] object (or, mo
7850: 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73  re commonly, a s
7860: 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a  ubclass of the.*
7870: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  * [sqlite3_file]
7880: 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61 20   object) with a 
7890: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
78a0: 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
78b0: 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f  bject..** This o
78c0: 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68  bject defines th
78d0: 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74  e methods used t
78e0: 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75  o perform variou
78f0: 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20  s operations.** 
7900: 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e  against the open
7910: 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74 65   file represente
7920: 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
7930: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a  3_file] object..
7940: 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73 71  **.** If the [sq
7950: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
7960: 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68 65   method sets the
7970: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
7980: 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a  ethods element .
7990: 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c  ** to a non-NULL
79a0: 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 74   pointer, then t
79b0: 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  he sqlite3_io_me
79c0: 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74  thods.xClose met
79d0: 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e  hod.** may be in
79e0: 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74 68  voked even if th
79f0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
7a00: 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65 64 20 74  Open] reported t
7a10: 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20 20  hat it failed.  
7a20: 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20  The.** only way 
7a30: 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61 6c  to prevent a cal
7a40: 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c  l to xClose foll
7a50: 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20 5b  owing a failed [
7a60: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
7a70: 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68 65  n].** is for the
7a80: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
7a90: 70 65 6e 5d 20 74 6f 20 73 65 74 20 74 68 65 20  pen] to set the 
7aa0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
7ab0: 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a  thods element.**
7ac0: 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   to NULL..**.** 
7ad0: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
7ae0: 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20  nt to xSync may 
7af0: 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  be one of [SQLIT
7b00: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f  E_SYNC_NORMAL] o
7b10: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e  r.** [SQLITE_SYN
7b20: 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69  C_FULL].  The fi
7b30: 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 68  rst choice is th
7b40: 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29  e normal fsync()
7b50: 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
7b60: 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20  choice is a Mac 
7b70: 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73  OS X style fulls
7b80: 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ync.  The [SQLIT
7b90: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d  E_SYNC_DATAONLY]
7ba0: 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20  .** flag may be 
7bb0: 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63  ORed in to indic
7bc0: 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68  ate that only th
7bd0: 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 69  e data of the fi
7be0: 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74  le.** and not it
7bf0: 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f  s inode needs to
7c00: 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a   be synced..**.*
7c10: 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61  * The integer va
7c20: 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20  lues to xLock() 
7c30: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72  and xUnlock() ar
7c40: 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e  e one of.** <ul>
7c50: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
7c60: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20  _LOCK_NONE],.** 
7c70: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
7c80: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c  K_SHARED],.** <l
7c90: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
7ca0: 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c  RESERVED],.** <l
7cb0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
7cc0: 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20  PENDING], or.** 
7cd0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
7ce0: 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a  K_EXCLUSIVE]..**
7cf0: 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28   </ul>.** xLock(
7d00: 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20  ) increases the 
7d10: 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20  lock. xUnlock() 
7d20: 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f  decreases the lo
7d30: 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63  ck..** The xChec
7d40: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20  kReservedLock() 
7d50: 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68  method checks wh
7d60: 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62 61  ether any databa
7d70: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a  se connection,.*
7d80: 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 73  * either in this
7d90: 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73   process or in s
7da0: 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73  ome other proces
7db0: 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  s, is holding a 
7dc0: 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e  RESERVED,.** PEN
7dd0: 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49  DING, or EXCLUSI
7de0: 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66  VE lock on the f
7df0: 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73  ile.  It returns
7e00: 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68   true.** if such
7e10: 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61   a lock exists a
7e20: 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69  nd false otherwi
7e30: 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46  se..**.** The xF
7e40: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74  ileControl() met
7e50: 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 63  hod is a generic
7e60: 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
7e70: 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a  allows custom.**
7e80: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
7e90: 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79  ions to directly
7ea0: 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e   control an open
7eb0: 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a   file using the.
7ec0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
7ed0: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65  _control()] inte
7ee0: 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f  rface.  The seco
7ef0: 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74  nd "op" argument
7f00: 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65   is an.** intege
7f10: 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74  r opcode.  The t
7f20: 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
7f30: 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74   a generic point
7f40: 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a  er intended to.*
7f50: 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72  * point to a str
7f60: 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 20  ucture that may 
7f70: 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74  contain argument
7f80: 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68  s or space in wh
7f90: 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20  ich to.** write 
7fa0: 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20  return values.  
7fb0: 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66  Potential uses f
7fc0: 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28  or xFileControl(
7fd0: 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75  ) might be.** fu
7fe0: 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c  nctions to enabl
7ff0: 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73  e blocking locks
8000: 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20   with timeouts, 
8010: 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a  to change the.**
8020: 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67   locking strateg
8030: 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74  y (for example t
8040: 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c  o use dot-file l
8050: 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72  ocks), to inquir
8060: 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73  e.** about the s
8070: 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c  tatus of a lock,
8080: 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61   or to break sta
8090: 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53  le locks.  The S
80a0: 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65  QLite.** core re
80b0: 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64  serves all opcod
80c0: 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30  es less than 100
80d0: 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65   for its own use
80e0: 2e 0a 2a 2a 20 41 20 5b 66 69 6c 65 20 63 6f 6e  ..** A [file con
80f0: 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 7c 20 6c  trol opcodes | l
8100: 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20  ist of opcodes] 
8110: 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 69 73  less than 100 is
8120: 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41   available..** A
8130: 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
8140: 20 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d   define a custom
8150: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
8160: 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20  thod should use 
8170: 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74  opcodes.** great
8180: 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61  er than 100 to a
8190: 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20  void conflicts. 
81a0: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
81b0: 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72  ions should.** r
81c0: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f  eturn [SQLITE_NO
81d0: 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65  TFOUND] for file
81e0: 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73   control opcodes
81f0: 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f   that they do no
8200: 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a  t.** recognize..
8210: 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f  **.** The xSecto
8220: 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72  rSize() method r
8230: 65 74 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f  eturns the secto
8240: 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a  r size of the.**
8250: 20 64 65 76 69 63 65 20 74 68 61 74 20 75 6e 64   device that und
8260: 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e  erlies the file.
8270: 20 20 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a    The sector siz
8280: 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69  e is the.** mini
8290: 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74 20 63  mum write that c
82a0: 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20  an be performed 
82b0: 77 69 74 68 6f 75 74 20 64 69 73 74 75 72 62 69  without disturbi
82c0: 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65  ng.** other byte
82d0: 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20  s in the file.  
82e0: 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61  The xDeviceChara
82f0: 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20  cteristics().** 
8300: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61  method returns a
8310: 20 62 69 74 20 76 65 63 74 6f 72 20 64 65 73 63   bit vector desc
8320: 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73  ribing behaviors
8330: 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72   of the.** under
8340: 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a  lying device:.**
8350: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
8360: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8370: 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  TOMIC].** <li> [
8380: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8390: 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC512].** <li> 
83a0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
83b0: 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC1K].** <li> 
83c0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
83d0: 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC2K].** <li> 
83e0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
83f0: 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC4K].** <li> 
8400: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
8410: 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC8K].** <li> 
8420: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
8430: 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC16K].** <li>
8440: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8450: 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC32K].** <li
8460: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8470: 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC64K].** <l
8480: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
8490: 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a  _SAFE_APPEND].**
84a0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
84b0: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a  CAP_SEQUENTIAL].
84c0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
84d0: 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c  IOCAP_UNDELETABL
84e0: 45 5f 57 48 45 4e 5f 4f 50 45 4e 5d 0a 2a 2a 20  E_WHEN_OPEN].** 
84f0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
8500: 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  AP_POWERSAFE_OVE
8510: 52 57 52 49 54 45 5d 0a 2a 2a 20 3c 6c 69 3e 20  RWRITE].** <li> 
8520: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d  [SQLITE_IOCAP_IM
8530: 4d 55 54 41 42 4c 45 5d 0a 2a 2a 20 3c 2f 75 6c  MUTABLE].** </ul
8540: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  >.**.** The SQLI
8550: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
8560: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
8570: 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f  hat all writes o
8580: 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72  f.** any size ar
8590: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
85a0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
85b0: 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20  ICnnn values.** 
85c0: 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73  mean that writes
85d0: 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20   of blocks that 
85e0: 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e  are nnn bytes in
85f0: 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65   size and.** are
8600: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61   aligned to an a
8610: 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20  ddress which is 
8620: 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69  an integer multi
8630: 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72  ple of.** nnn ar
8640: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
8650: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
8660: 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65  _APPEND value me
8670: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e  ans.** that when
8680: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
8690: 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65  d to a file, the
86a0: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
86b0: 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20  d.** first then 
86c0: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
86d0: 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64  file is extended
86e0: 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65  , never the othe
86f0: 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e  r.** way around.
8700: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
8710: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72  AP_SEQUENTIAL pr
8720: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
8730: 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  t.** information
8740: 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64   is written to d
8750: 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20  isk in the same 
8760: 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a  order as calls.*
8770: 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a  * to xWrite()..*
8780: 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20  *.** If xRead() 
8790: 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49  returns SQLITE_I
87a0: 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20  OERR_SHORT_READ 
87b0: 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c  it must also fil
87c0: 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65  l.** in the unre
87d0: 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74  ad portions of t
87e0: 68 65 20 62 75 66 66 65 72 20 77 69 74 68 20 7a  he buffer with z
87f0: 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61  eros.  A VFS tha
8800: 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65  t.** fails to ze
8810: 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65  ro-fill short re
8820: 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74  ads might seem t
8830: 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72  o work.  However
8840: 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20  ,.** failure to 
8850: 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20  zero-fill short 
8860: 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74  reads will event
8870: 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a  ually lead to.**
8880: 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70   database corrup
8890: 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  tion..*/.typedef
88a0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
88b0: 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74  io_methods sqlit
88c0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73  e3_io_methods;.s
88d0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
88e0: 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74  _methods {.  int
88f0: 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74   iVersion;.  int
8900: 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74   (*xClose)(sqlit
8910: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
8920: 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65   (*xRead)(sqlite
8930: 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20  3_file*, void*, 
8940: 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65  int iAmt, sqlite
8950: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a  3_int64 iOfst);.
8960: 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28    int (*xWrite)(
8970: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63  sqlite3_file*, c
8980: 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20  onst void*, int 
8990: 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e  iAmt, sqlite3_in
89a0: 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e  t64 iOfst);.  in
89b0: 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73  t (*xTruncate)(s
89c0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
89d0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65  lite3_int64 size
89e0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63  );.  int (*xSync
89f0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8a00: 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69   int flags);.  i
8a10: 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28  nt (*xFileSize)(
8a20: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
8a30: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53  qlite3_int64 *pS
8a40: 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c  ize);.  int (*xL
8a50: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
8a60: 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20  e*, int);.  int 
8a70: 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74  (*xUnlock)(sqlit
8a80: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a  e3_file*, int);.
8a90: 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65    int (*xCheckRe
8aa0: 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69  servedLock)(sqli
8ab0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a  te3_file*, int *
8ac0: 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20  pResOut);.  int 
8ad0: 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28  (*xFileControl)(
8ae0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8af0: 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72  nt op, void *pAr
8b00: 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63  g);.  int (*xSec
8b10: 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33  torSize)(sqlite3
8b20: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  _file*);.  int (
8b30: 2a 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65  *xDeviceCharacte
8b40: 72 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33  ristics)(sqlite3
8b50: 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65  _file*);.  /* Me
8b60: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
8b70: 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f  valid for versio
8b80: 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  n 1 */.  int (*x
8b90: 53 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33 5f  ShmMap)(sqlite3_
8ba0: 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20  file*, int iPg, 
8bb0: 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76  int pgsz, int, v
8bc0: 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b  oid volatile**);
8bd0: 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63  .  int (*xShmLoc
8be0: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
8bf0: 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e  , int offset, in
8c00: 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b  t n, int flags);
8c10: 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42 61  .  void (*xShmBa
8c20: 72 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f 66  rrier)(sqlite3_f
8c30: 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ile*);.  int (*x
8c40: 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74 65  ShmUnmap)(sqlite
8c50: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c  3_file*, int del
8c60: 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d  eteFlag);.  /* M
8c70: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
8c80: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69   valid for versi
8c90: 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  on 2 */.  int (*
8ca0: 78 46 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f  xFetch)(sqlite3_
8cb0: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
8cc0: 6e 74 36 34 20 69 4f 66 73 74 2c 20 69 6e 74 20  nt64 iOfst, int 
8cd0: 69 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29  iAmt, void **pp)
8ce0: 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66 65 74  ;.  int (*xUnfet
8cf0: 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ch)(sqlite3_file
8d00: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
8d10: 20 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a 70 29   iOfst, void *p)
8d20: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
8d30: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
8d40: 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a  or version 3 */.
8d50: 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20    /* Additional 
8d60: 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61  methods may be a
8d70: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
8d80: 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f  eleases */.};../
8d90: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
8da0: 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e  tandard File Con
8db0: 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 20  trol Opcodes.** 
8dc0: 4b 45 59 57 4f 52 44 53 3a 20 7b 66 69 6c 65 20  KEYWORDS: {file 
8dd0: 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 7d  control opcodes}
8de0: 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f   {file control o
8df0: 70 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  pcode}.**.** The
8e00: 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
8e10: 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73  ants are opcodes
8e20: 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f   for the xFileCo
8e30: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20  ntrol method.** 
8e40: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
8e50: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
8e60: 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b  ct and for the [
8e70: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
8e80: 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  trol()].** inter
8e90: 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  face..**.** <ul>
8ea0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
8eb0: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
8ec0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
8ed0: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
8ee0: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  E] opcode is use
8ef0: 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e  d for debugging.
8f00: 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65    This.** opcode
8f10: 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c   causes the xFil
8f20: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20  eControl method 
8f30: 74 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 72  to write the cur
8f40: 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a  rent state of.**
8f50: 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f   the lock (one o
8f60: 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e  f [SQLITE_LOCK_N
8f70: 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f  ONE], [SQLITE_LO
8f80: 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b  CK_SHARED],.** [
8f90: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
8fa0: 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c  RVED], [SQLITE_L
8fb0: 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72  OCK_PENDING], or
8fc0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58   [SQLITE_LOCK_EX
8fd0: 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74  CLUSIVE]).** int
8fe0: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61  o an integer tha
8ff0: 74 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d  t the pArg argum
9000: 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54  ent points to. T
9010: 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a  his capability.*
9020: 2a 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67  * is used during
9030: 20 74 65 73 74 69 6e 67 20 61 6e 64 20 69 73 20   testing and is 
9040: 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 77  only available w
9050: 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 54  hen the SQLITE_T
9060: 45 53 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74  EST.** compile-t
9070: 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  ime option is us
9080: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ed..**.** <li>[[
9090: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
90a0: 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20  E_HINT]].** The 
90b0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49  [SQLITE_FCNTL_SI
90c0: 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20  ZE_HINT] opcode 
90d0: 69 73 20 75 73 65 64 20 62 79 20 53 51 4c 69 74  is used by SQLit
90e0: 65 20 74 6f 20 67 69 76 65 20 74 68 65 20 56 46  e to give the VF
90f0: 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e  S.** layer a hin
9100: 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74  t of how large t
9110: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
9120: 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65   will grow to be
9130: 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63   during the.** c
9140: 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69  urrent transacti
9150: 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69  on.  This hint i
9160: 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64  s not guaranteed
9170: 20 74 6f 20 62 65 20 61 63 63 75 72 61 74 65 20   to be accurate 
9180: 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74  but it.** is oft
9190: 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75  en close.  The u
91a0: 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69  nderlying VFS mi
91b0: 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72  ght choose to pr
91c0: 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61  eallocate databa
91d0: 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65  se.** file space
91e0: 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68   based on this h
91f0: 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  int in order to 
9200: 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74  help writes to t
9210: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66  he database.** f
9220: 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a  ile run faster..
9230: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9240: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
9250: 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  IZE]].** The [SQ
9260: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b  LITE_FCNTL_CHUNK
9270: 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73  _SIZE] opcode is
9280: 20 75 73 65 64 20 74 6f 20 72 65 71 75 65 73 74   used to request
9290: 20 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a 2a   that the VFS.**
92a0: 20 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72 75   extends and tru
92b0: 6e 63 61 74 65 73 20 74 68 65 20 64 61 74 61 62  ncates the datab
92c0: 61 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75 6e  ase file in chun
92d0: 6b 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70 65  ks of a size spe
92e0: 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65  cified.** by the
92f0: 20 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72 74   user. The fourt
9300: 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73  h argument to [s
9310: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
9320: 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a  rol()] should .*
9330: 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e  * point to an in
9340: 74 65 67 65 72 20 28 74 79 70 65 20 69 6e 74 29  teger (type int)
9350: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
9360: 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74  new chunk-size t
9370: 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65  o use.** for the
9380: 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 62   nominated datab
9390: 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20  ase. Allocating 
93a0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 73 70  database file sp
93b0: 61 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20  ace in large.** 
93c0: 63 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 20  chunks (say 1MB 
93d0: 61 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 20  at a time), may 
93e0: 72 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73 74  reduce file-syst
93f0: 65 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e  em fragmentation
9400: 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20   and.** improve 
9410: 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73  performance on s
9420: 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a  ome systems..**.
9430: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
9440: 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54  FCNTL_FILE_POINT
9450: 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ER]].** The [SQL
9460: 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50  ITE_FCNTL_FILE_P
9470: 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69  OINTER] opcode i
9480: 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  s used to obtain
9490: 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
94a0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
94b0: 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63  le] object assoc
94c0: 69 61 74 65 64 20 77 69 74 68 20 61 20 70 61 72  iated with a par
94d0: 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65  ticular database
94e0: 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  .** connection. 
94f0: 20 53 65 65 20 61 6c 73 6f 20 5b 53 51 4c 49 54   See also [SQLIT
9500: 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f  E_FCNTL_JOURNAL_
9510: 50 4f 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20  POINTER]..**.** 
9520: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
9530: 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54  TL_JOURNAL_POINT
9540: 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ER]].** The [SQL
9550: 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41  ITE_FCNTL_JOURNA
9560: 4c 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64  L_POINTER] opcod
9570: 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74  e is used to obt
9580: 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  ain a pointer.**
9590: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
95a0: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73  _file] object as
95b0: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
95c0: 65 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 28  e journal file (
95d0: 65 69 74 68 65 72 0a 2a 2a 20 74 68 65 20 5b 72  either.** the [r
95e0: 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 5d  ollback journal]
95f0: 20 6f 72 20 74 68 65 20 5b 77 72 69 74 65 2d 61   or the [write-a
9600: 68 65 61 64 20 6c 6f 67 5d 29 20 66 6f 72 20 61  head log]) for a
9610: 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61   particular data
9620: 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
9630: 6f 6e 2e 20 20 53 65 65 20 61 6c 73 6f 20 5b 53  on.  See also [S
9640: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45  QLITE_FCNTL_FILE
9650: 5f 50 4f 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a  _POINTER]..**.**
9660: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
9670: 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44  NTL_SYNC_OMITTED
9680: 5d 5d 0a 2a 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20  ]].** No longer 
9690: 69 6e 20 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  in use..**.** <l
96a0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
96b0: 5f 53 59 4e 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b  _SYNC]].** The [
96c0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e  SQLITE_FCNTL_SYN
96d0: 43 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65 6e  C] opcode is gen
96e0: 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c  erated internall
96f0: 79 20 62 79 20 53 51 4c 69 74 65 20 61 6e 64 0a  y by SQLite and.
9700: 2a 2a 20 73 65 6e 74 20 74 6f 20 74 68 65 20 56  ** sent to the V
9710: 46 53 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 62  FS immediately b
9720: 65 66 6f 72 65 20 74 68 65 20 78 53 79 6e 63 20  efore the xSync 
9730: 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65  method is invoke
9740: 64 20 6f 6e 20 61 0a 2a 2a 20 64 61 74 61 62 61  d on a.** databa
9750: 73 65 20 66 69 6c 65 20 64 65 73 63 72 69 70 74  se file descript
9760: 6f 72 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 78  or. Or, if the x
9770: 53 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 6e  Sync method is n
9780: 6f 74 20 69 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62  ot invoked .** b
9790: 65 63 61 75 73 65 20 74 68 65 20 75 73 65 72 20  ecause the user 
97a0: 68 61 73 20 63 6f 6e 66 69 67 75 72 65 64 20 53  has configured S
97b0: 51 4c 69 74 65 20 77 69 74 68 20 0a 2a 2a 20 5b  QLite with .** [
97c0: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
97d0: 75 73 20 7c 20 50 52 41 47 4d 41 20 73 79 6e 63  us | PRAGMA sync
97e0: 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 74 20  hronous=OFF] it 
97f0: 69 73 20 69 6e 76 6f 6b 65 64 20 69 6e 20 70 6c  is invoked in pl
9800: 61 63 65 20 0a 2a 2a 20 6f 66 20 74 68 65 20 78  ace .** of the x
9810: 53 79 6e 63 20 6d 65 74 68 6f 64 2e 20 49 6e 20  Sync method. In 
9820: 6d 6f 73 74 20 63 61 73 65 73 2c 20 74 68 65 20  most cases, the 
9830: 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74  pointer argument
9840: 20 70 61 73 73 65 64 20 77 69 74 68 0a 2a 2a 20   passed with.** 
9850: 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  this file-contro
9860: 6c 20 69 73 20 4e 55 4c 4c 2e 20 48 6f 77 65 76  l is NULL. Howev
9870: 65 72 2c 20 69 66 20 74 68 65 20 64 61 74 61 62  er, if the datab
9880: 61 73 65 20 66 69 6c 65 20 69 73 20 62 65 69 6e  ase file is bein
9890: 67 20 73 79 6e 63 65 64 0a 2a 2a 20 61 73 20 70  g synced.** as p
98a0: 61 72 74 20 6f 66 20 61 20 6d 75 6c 74 69 2d 64  art of a multi-d
98b0: 61 74 61 62 61 73 65 20 63 6f 6d 6d 69 74 2c 20  atabase commit, 
98c0: 74 68 65 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  the argument poi
98d0: 6e 74 73 20 74 6f 20 61 20 6e 75 6c 2d 74 65 72  nts to a nul-ter
98e0: 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e  minated.** strin
98f0: 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  g containing the
9900: 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 6d 61   transactions ma
9910: 73 74 65 72 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c  ster-journal fil
9920: 65 20 6e 61 6d 65 2e 20 56 46 53 65 73 20 74 68  e name. VFSes th
9930: 61 74 20 0a 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65  at .** do not ne
9940: 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20 73  ed this signal s
9950: 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69  hould silently i
9960: 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64  gnore this opcod
9970: 65 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  e. Applications 
9980: 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63  .** should not c
9990: 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  all [sqlite3_fil
99a0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74  e_control()] wit
99b0: 68 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61 73  h this opcode as
99c0: 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 0a 2a   doing so may .*
99d0: 2a 20 64 69 73 72 75 70 74 20 74 68 65 20 6f 70  * disrupt the op
99e0: 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73  eration of the s
99f0: 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73  pecialized VFSes
9a00: 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 65   that do require
9a10: 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69   it.  .**.** <li
9a20: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
9a30: 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d  COMMIT_PHASETWO]
9a40: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
9a50: 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48  _FCNTL_COMMIT_PH
9a60: 41 53 45 54 57 4f 5d 20 6f 70 63 6f 64 65 20 69  ASETWO] opcode i
9a70: 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65  s generated inte
9a80: 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65  rnally by SQLite
9a90: 0a 2a 2a 20 61 6e 64 20 73 65 6e 74 20 74 6f 20  .** and sent to 
9aa0: 74 68 65 20 56 46 53 20 61 66 74 65 72 20 61 20  the VFS after a 
9ab0: 74 72 61 6e 73 61 63 74 69 6f 6e 20 68 61 73 20  transaction has 
9ac0: 62 65 65 6e 20 63 6f 6d 6d 69 74 74 65 64 20 69  been committed i
9ad0: 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20 62 75  mmediately.** bu
9ae0: 74 20 62 65 66 6f 72 65 20 74 68 65 20 64 61 74  t before the dat
9af0: 61 62 61 73 65 20 69 73 20 75 6e 6c 6f 63 6b 65  abase is unlocke
9b00: 64 2e 20 56 46 53 65 73 20 74 68 61 74 20 64 6f  d. VFSes that do
9b10: 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73   not need this s
9b20: 69 67 6e 61 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20  ignal.** should 
9b30: 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20  silently ignore 
9b40: 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 41 70 70  this opcode. App
9b50: 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  lications should
9b60: 20 6e 6f 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71   not call.** [sq
9b70: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
9b80: 6f 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73 20  ol()] with this 
9b90: 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20  opcode as doing 
9ba0: 73 6f 20 6d 61 79 20 64 69 73 72 75 70 74 20 74  so may disrupt t
9bb0: 68 65 20 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e  he .** operation
9bc0: 20 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c 69   of the speciali
9bd0: 7a 65 64 20 56 46 53 65 73 20 74 68 61 74 20 64  zed VFSes that d
9be0: 6f 20 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a  o require it.  .
9bf0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9c00: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41  TE_FCNTL_WIN32_A
9c10: 56 5f 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68  V_RETRY]].** ^Th
9c20: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
9c30: 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 20  WIN32_AV_RETRY] 
9c40: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
9c50: 6f 20 63 6f 6e 66 69 67 75 72 65 20 61 75 74 6f  o configure auto
9c60: 6d 61 74 69 63 0a 2a 2a 20 72 65 74 72 79 20 63  matic.** retry c
9c70: 6f 75 6e 74 73 20 61 6e 64 20 69 6e 74 65 72 76  ounts and interv
9c80: 61 6c 73 20 66 6f 72 20 63 65 72 74 61 69 6e 20  als for certain 
9c90: 64 69 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69  disk I/O operati
9ca0: 6f 6e 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77  ons for the.** w
9cb0: 69 6e 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20  indows [VFS] in 
9cc0: 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65  order to provide
9cd0: 20 72 6f 62 75 73 74 6e 65 73 73 20 69 6e 20 74   robustness in t
9ce0: 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a  he presence of.*
9cf0: 2a 20 61 6e 74 69 2d 76 69 72 75 73 20 70 72 6f  * anti-virus pro
9d00: 67 72 61 6d 73 2e 20 20 42 79 20 64 65 66 61 75  grams.  By defau
9d10: 6c 74 2c 20 74 68 65 20 77 69 6e 64 6f 77 73 20  lt, the windows 
9d20: 56 46 53 20 77 69 6c 6c 20 72 65 74 72 79 20 66  VFS will retry f
9d30: 69 6c 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c  ile read,.** fil
9d40: 65 20 77 72 69 74 65 2c 20 61 6e 64 20 66 69 6c  e write, and fil
9d50: 65 20 64 65 6c 65 74 65 20 6f 70 65 72 61 74 69  e delete operati
9d60: 6f 6e 73 20 75 70 20 74 6f 20 31 30 20 74 69 6d  ons up to 10 tim
9d70: 65 73 2c 20 77 69 74 68 20 61 20 64 65 6c 61 79  es, with a delay
9d80: 0a 2a 2a 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73  .** of 25 millis
9d90: 65 63 6f 6e 64 73 20 62 65 66 6f 72 65 20 74 68  econds before th
9da0: 65 20 66 69 72 73 74 20 72 65 74 72 79 20 61 6e  e first retry an
9db0: 64 20 77 69 74 68 20 74 68 65 20 64 65 6c 61 79  d with the delay
9dc0: 20 69 6e 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62   increasing.** b
9dd0: 79 20 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20  y an additional 
9de0: 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  25 milliseconds 
9df0: 77 69 74 68 20 65 61 63 68 20 73 75 62 73 65 71  with each subseq
9e00: 75 65 6e 74 20 72 65 74 72 79 2e 20 20 54 68 69  uent retry.  Thi
9e10: 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f  s.** opcode allo
9e20: 77 73 20 74 68 65 73 65 20 74 77 6f 20 76 61 6c  ws these two val
9e30: 75 65 73 20 28 31 30 20 72 65 74 72 69 65 73 20  ues (10 retries 
9e40: 61 6e 64 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f  and 25 milliseco
9e50: 6e 64 73 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a  nds of delay).**
9e60: 20 74 6f 20 62 65 20 61 64 6a 75 73 74 65 64 2e   to be adjusted.
9e70: 20 20 54 68 65 20 76 61 6c 75 65 73 20 61 72 65    The values are
9e80: 20 63 68 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c   changed for all
9e90: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
9ea0: 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20  tions.** within 
9eb0: 74 68 65 20 73 61 6d 65 20 70 72 6f 63 65 73 73  the same process
9ec0: 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  .  The argument 
9ed0: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
9ee0: 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f 0a  an array of two.
9ef0: 2a 2a 20 69 6e 74 65 67 65 72 73 20 77 68 65 72  ** integers wher
9f00: 65 20 74 68 65 20 66 69 72 73 74 20 69 6e 74 65  e the first inte
9f10: 67 65 72 20 69 20 74 68 65 20 6e 65 77 20 72 65  ger i the new re
9f20: 74 72 79 20 63 6f 75 6e 74 20 61 6e 64 20 74 68  try count and th
9f30: 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65  e second.** inte
9f40: 67 65 72 20 69 73 20 74 68 65 20 64 65 6c 61 79  ger is the delay
9f50: 2e 20 20 49 66 20 65 69 74 68 65 72 20 69 6e 74  .  If either int
9f60: 65 67 65 72 20 69 73 20 6e 65 67 61 74 69 76 65  eger is negative
9f70: 2c 20 74 68 65 6e 20 74 68 65 20 73 65 74 74 69  , then the setti
9f80: 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61  ng.** is not cha
9f90: 6e 67 65 64 20 62 75 74 20 69 6e 73 74 65 61 64  nged but instead
9fa0: 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65   the prior value
9fb0: 20 6f 66 20 74 68 61 74 20 73 65 74 74 69 6e 67   of that setting
9fc0: 20 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69   is written.** i
9fd0: 6e 74 6f 20 74 68 65 20 61 72 72 61 79 20 65 6e  nto the array en
9fe0: 74 72 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68  try, allowing th
9ff0: 65 20 63 75 72 72 65 6e 74 20 72 65 74 72 79 20  e current retry 
a000: 73 65 74 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a  settings to be.*
a010: 2a 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e 20  * interrogated. 
a020: 20 54 68 65 20 7a 44 62 4e 61 6d 65 20 70 61 72   The zDbName par
a030: 61 6d 65 74 65 72 20 69 73 20 69 67 6e 6f 72 65  ameter is ignore
a040: 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  d..**.** <li>[[S
a050: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53  QLITE_FCNTL_PERS
a060: 49 53 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68  IST_WAL]].** ^Th
a070: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
a080: 50 45 52 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63  PERSIST_WAL] opc
a090: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 73  ode is used to s
a0a0: 65 74 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a  et or query the.
a0b0: 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20 5b 57  ** persistent [W
a0c0: 41 4c 20 7c 20 57 72 69 74 65 20 41 68 65 61 64  AL | Write Ahead
a0d0: 20 4c 6f 67 5d 20 73 65 74 74 69 6e 67 2e 20 20   Log] setting.  
a0e0: 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20  By default, the 
a0f0: 61 75 78 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69  auxiliary.** wri
a100: 74 65 20 61 68 65 61 64 20 6c 6f 67 20 61 6e 64  te ahead log and
a110: 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66   shared memory f
a120: 69 6c 65 73 20 75 73 65 64 20 66 6f 72 20 74 72  iles used for tr
a130: 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f  ansaction contro
a140: 6c 0a 2a 2a 20 61 72 65 20 61 75 74 6f 6d 61 74  l.** are automat
a150: 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 77  ically deleted w
a160: 68 65 6e 20 74 68 65 20 6c 61 74 65 73 74 20 63  hen the latest c
a170: 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 74 68 65  onnection to the
a180: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f   database.** clo
a190: 73 65 73 2e 20 20 53 65 74 74 69 6e 67 20 70 65  ses.  Setting pe
a1a0: 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64  rsistent WAL mod
a1b0: 65 20 63 61 75 73 65 73 20 74 68 6f 73 65 20 66  e causes those f
a1c0: 69 6c 65 73 20 74 6f 20 70 65 72 73 69 73 74 20  iles to persist 
a1d0: 61 66 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20  after.** close. 
a1e0: 20 50 65 72 73 69 73 74 69 6e 67 20 74 68 65 20   Persisting the 
a1f0: 66 69 6c 65 73 20 69 73 20 75 73 65 66 75 6c 20  files is useful 
a200: 77 68 65 6e 20 6f 74 68 65 72 20 70 72 6f 63 65  when other proce
a210: 73 73 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74  sses that do not
a220: 0a 2a 2a 20 68 61 76 65 20 77 72 69 74 65 20 70  .** have write p
a230: 65 72 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65  ermission on the
a240: 20 64 69 72 65 63 74 6f 72 79 20 63 6f 6e 74 61   directory conta
a250: 69 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61  ining the databa
a260: 73 65 20 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20  se file want.** 
a270: 74 6f 20 72 65 61 64 20 74 68 65 20 64 61 74 61  to read the data
a280: 62 61 73 65 20 66 69 6c 65 2c 20 61 73 20 74 68  base file, as th
a290: 65 20 57 41 4c 20 61 6e 64 20 73 68 61 72 65 64  e WAL and shared
a2a0: 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75   memory files mu
a2b0: 73 74 20 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f  st exist.** in o
a2c0: 72 64 65 72 20 66 6f 72 20 74 68 65 20 64 61 74  rder for the dat
a2d0: 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 61 64  abase to be read
a2e0: 61 62 6c 65 2e 20 20 54 68 65 20 66 6f 75 72 74  able.  The fourt
a2f0: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  h parameter to.*
a300: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  * [sqlite3_file_
a310: 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74  control()] for t
a320: 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c  his opcode shoul
a330: 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74  d be a pointer t
a340: 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a  o an integer..**
a350: 20 54 68 61 74 20 69 6e 74 65 67 65 72 20 69 73   That integer is
a360: 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 70 65   0 to disable pe
a370: 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64  rsistent WAL mod
a380: 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65  e or 1 to enable
a390: 20 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57   persistent.** W
a3a0: 41 4c 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65  AL mode.  If the
a3b0: 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20   integer is -1, 
a3c0: 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77  then it is overw
a3d0: 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20  ritten with the 
a3e0: 63 75 72 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70  current.** WAL p
a3f0: 65 72 73 69 73 74 65 6e 63 65 20 73 65 74 74 69  ersistence setti
a400: 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ng..**.** <li>[[
a410: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57  SQLITE_FCNTL_POW
a420: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45  ERSAFE_OVERWRITE
a430: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
a440: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41  TE_FCNTL_POWERSA
a450: 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70  FE_OVERWRITE] op
a460: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
a470: 73 65 74 20 6f 72 20 71 75 65 72 79 20 74 68 65  set or query the
a480: 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20 22  .** persistent "
a490: 70 6f 77 65 72 73 61 66 65 2d 6f 76 65 72 77 72  powersafe-overwr
a4a0: 69 74 65 22 20 6f 72 20 22 50 53 4f 57 22 20 73  ite" or "PSOW" s
a4b0: 65 74 74 69 6e 67 2e 20 20 54 68 65 20 50 53 4f  etting.  The PSO
a4c0: 57 20 73 65 74 74 69 6e 67 0a 2a 2a 20 64 65 74  W setting.** det
a4d0: 65 72 6d 69 6e 65 73 20 74 68 65 20 5b 53 51 4c  ermines the [SQL
a4e0: 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53  ITE_IOCAP_POWERS
a4f0: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 62  AFE_OVERWRITE] b
a500: 69 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78 44 65  it of the.** xDe
a510: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
a520: 69 63 73 20 6d 65 74 68 6f 64 73 2e 20 54 68 65  ics methods. The
a530: 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
a540: 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  r to.** [sqlite3
a550: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
a560: 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65   for this opcode
a570: 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69   should be a poi
a580: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
a590: 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65  er..** That inte
a5a0: 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61  ger is 0 to disa
a5b0: 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20  ble zero-damage 
a5c0: 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61  mode or 1 to ena
a5d0: 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 0a  ble zero-damage.
a5e0: 2a 2a 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65  ** mode.  If the
a5f0: 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20   integer is -1, 
a600: 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77  then it is overw
a610: 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20  ritten with the 
a620: 63 75 72 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d  current.** zero-
a630: 64 61 6d 61 67 65 20 6d 6f 64 65 20 73 65 74 74  damage mode sett
a640: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ing..**.** <li>[
a650: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56  [SQLITE_FCNTL_OV
a660: 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68  ERWRITE]].** ^Th
a670: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
a680: 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64  OVERWRITE] opcod
a690: 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20  e is invoked by 
a6a0: 53 51 4c 69 74 65 20 61 66 74 65 72 20 6f 70 65  SQLite after ope
a6b0: 6e 69 6e 67 0a 2a 2a 20 61 20 77 72 69 74 65 20  ning.** a write 
a6c0: 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69  transaction to i
a6d0: 6e 64 69 63 61 74 65 20 74 68 61 74 2c 20 75 6e  ndicate that, un
a6e0: 6c 65 73 73 20 69 74 20 69 73 20 72 6f 6c 6c 65  less it is rolle
a6f0: 64 20 62 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a  d back for some.
a700: 2a 2a 20 72 65 61 73 6f 6e 2c 20 74 68 65 20 65  ** reason, the e
a710: 6e 74 69 72 65 20 64 61 74 61 62 61 73 65 20 66  ntire database f
a720: 69 6c 65 20 77 69 6c 6c 20 62 65 20 6f 76 65 72  ile will be over
a730: 77 72 69 74 74 65 6e 20 62 79 20 74 68 65 20 63  written by the c
a740: 75 72 72 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73  urrent .** trans
a750: 61 63 74 69 6f 6e 2e 20 54 68 69 73 20 69 73 20  action. This is 
a760: 75 73 65 64 20 62 79 20 56 41 43 55 55 4d 20 6f  used by VACUUM o
a770: 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  perations..**.**
a780: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
a790: 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a  NTL_VFSNAME]].**
a7a0: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
a7b0: 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63  NTL_VFSNAME] opc
a7c0: 6f 64 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ode can be used 
a7d0: 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6e 61  to obtain the na
a7e0: 6d 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56  mes of.** all [V
a7f0: 46 53 65 73 5d 20 69 6e 20 74 68 65 20 56 46 53  FSes] in the VFS
a800: 20 73 74 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d   stack.  The nam
a810: 65 73 20 61 72 65 20 6f 66 20 61 6c 6c 20 56 46  es are of all VF
a820: 53 20 73 68 69 6d 73 20 61 6e 64 20 74 68 65 0a  S shims and the.
a830: 2a 2a 20 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d  ** final bottom-
a840: 6c 65 76 65 6c 20 56 46 53 20 61 72 65 20 77 72  level VFS are wr
a850: 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72  itten into memor
a860: 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
a870: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  .** [sqlite3_mal
a880: 6c 6f 63 28 29 5d 20 61 6e 64 20 74 68 65 20 72  loc()] and the r
a890: 65 73 75 6c 74 20 69 73 20 73 74 6f 72 65 64 20  esult is stored 
a8a0: 69 6e 20 74 68 65 20 63 68 61 72 2a 20 76 61 72  in the char* var
a8b0: 69 61 62 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68  iable.** that th
a8c0: 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
a8d0: 65 72 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66  er of [sqlite3_f
a8e0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70  ile_control()] p
a8f0: 6f 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65  oints to..** The
a900: 20 63 61 6c 6c 65 72 20 69 73 20 72 65 73 70 6f   caller is respo
a910: 6e 73 69 62 6c 65 20 66 6f 72 20 66 72 65 65 69  nsible for freei
a920: 6e 67 20 74 68 65 20 6d 65 6d 6f 72 79 20 77 68  ng the memory wh
a930: 65 6e 20 64 6f 6e 65 2e 20 20 41 73 20 77 69 74  en done.  As wit
a940: 68 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f  h.** all file-co
a950: 6e 74 72 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74  ntrol actions, t
a960: 68 65 72 65 20 69 73 20 6e 6f 20 67 75 61 72 61  here is no guara
a970: 6e 74 65 65 20 74 68 61 74 20 74 68 69 73 20 77  ntee that this w
a980: 69 6c 6c 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20  ill actually.** 
a990: 64 6f 20 61 6e 79 74 68 69 6e 67 2e 20 20 43 61  do anything.  Ca
a9a0: 6c 6c 65 72 73 20 73 68 6f 75 6c 64 20 69 6e 69  llers should ini
a9b0: 74 69 61 6c 69 7a 65 20 74 68 65 20 63 68 61 72  tialize the char
a9c0: 2a 20 76 61 72 69 61 62 6c 65 20 74 6f 20 61 20  * variable to a 
a9d0: 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  NULL.** pointer 
a9e0: 69 6e 20 63 61 73 65 20 74 68 69 73 20 66 69 6c  in case this fil
a9f0: 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74  e-control is not
aa00: 20 69 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54   implemented.  T
aa10: 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  his file-control
aa20: 0a 2a 2a 20 69 73 20 69 6e 74 65 6e 64 65 64 20  .** is intended 
aa30: 66 6f 72 20 64 69 61 67 6e 6f 73 74 69 63 20 75  for diagnostic u
aa40: 73 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c  se only..**.** <
aa50: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
aa60: 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 5d 5d 0a  L_VFS_POINTER]].
aa70: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
aa80: 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45  FCNTL_VFS_POINTE
aa90: 52 5d 20 6f 70 63 6f 64 65 20 66 69 6e 64 73 20  R] opcode finds 
aaa0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
aab0: 20 74 6f 70 2d 6c 65 76 65 6c 0a 2a 2a 20 5b 56   top-level.** [V
aac0: 46 53 65 73 5d 20 63 75 72 72 65 6e 74 6c 79 20  FSes] currently 
aad0: 69 6e 20 75 73 65 2e 20 20 5e 28 54 68 65 20 61  in use.  ^(The a
aae0: 72 67 75 6d 65 6e 74 20 58 20 69 6e 0a 2a 2a 20  rgument X in.** 
aaf0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
ab00: 74 72 6f 6c 28 64 62 2c 53 51 4c 49 54 45 5f 46  trol(db,SQLITE_F
ab10: 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52  CNTL_VFS_POINTER
ab20: 2c 58 29 20 6d 75 73 74 20 62 65 0a 2a 2a 20 6f  ,X) must be.** o
ab30: 66 20 74 79 70 65 20 22 5b 73 71 6c 69 74 65 33  f type "[sqlite3
ab40: 5f 76 66 73 5d 20 2a 2a 22 2e 20 20 54 68 69 73  _vfs] **".  This
ab50: 20 6f 70 63 6f 64 65 73 20 77 69 6c 6c 20 73 65   opcodes will se
ab60: 74 20 2a 58 0a 2a 2a 20 74 6f 20 61 20 70 6f 69  t *X.** to a poi
ab70: 6e 74 65 72 20 74 6f 20 74 68 65 20 74 6f 70 2d  nter to the top-
ab80: 6c 65 76 65 6c 20 56 46 53 2e 29 5e 0a 2a 2a 20  level VFS.)^.** 
ab90: 5e 57 68 65 6e 20 74 68 65 72 65 20 61 72 65 20  ^When there are 
aba0: 6d 75 6c 74 69 70 6c 65 20 56 46 53 20 73 68 69  multiple VFS shi
abb0: 6d 73 20 69 6e 20 74 68 65 20 73 74 61 63 6b 2c  ms in the stack,
abc0: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 66 69 6e   this opcode fin
abd0: 64 73 20 74 68 65 0a 2a 2a 20 75 70 70 65 72 2d  ds the.** upper-
abe0: 6d 6f 73 74 20 73 68 69 6d 20 6f 6e 6c 79 2e 0a  most shim only..
abf0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
ac00: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
ac10: 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20 61  ].** ^Whenever a
ac20: 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d   [PRAGMA] statem
ac30: 65 6e 74 20 69 73 20 70 61 72 73 65 64 2c 20 61  ent is parsed, a
ac40: 6e 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  n [SQLITE_FCNTL_
ac50: 50 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65  PRAGMA] .** file
ac60: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74   control is sent
ac70: 20 74 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73 71   to the open [sq
ac80: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
ac90: 63 74 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  ct corresponding
aca0: 0a 2a 2a 20 74 6f 20 74 68 65 20 64 61 74 61 62  .** to the datab
acb0: 61 73 65 20 66 69 6c 65 20 74 6f 20 77 68 69 63  ase file to whic
acc0: 68 20 74 68 65 20 70 72 61 67 6d 61 20 73 74 61  h the pragma sta
acd0: 74 65 6d 65 6e 74 20 72 65 66 65 72 73 2e 20 5e  tement refers. ^
ace0: 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  The argument.** 
acf0: 74 6f 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46  to the [SQLITE_F
ad00: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c  CNTL_PRAGMA] fil
ad10: 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20  e control is an 
ad20: 61 72 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e  array of.** poin
ad30: 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20  ters to strings 
ad40: 28 63 68 61 72 2a 2a 29 20 69 6e 20 77 68 69 63  (char**) in whic
ad50: 68 20 74 68 65 20 73 65 63 6f 6e 64 20 65 6c 65  h the second ele
ad60: 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 72 72 61  ment of the arra
ad70: 79 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65  y.** is the name
ad80: 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 61   of the pragma a
ad90: 6e 64 20 74 68 65 20 74 68 69 72 64 20 65 6c 65  nd the third ele
ada0: 6d 65 6e 74 20 69 73 20 74 68 65 20 61 72 67 75  ment is the argu
adb0: 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70  ment to the.** p
adc0: 72 61 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66  ragma or NULL if
add0: 20 74 68 65 20 70 72 61 67 6d 61 20 68 61 73 20   the pragma has 
ade0: 6e 6f 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54  no argument.  ^T
adf0: 68 65 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61  he handler for a
ae00: 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e  n.** [SQLITE_FCN
ae10: 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20  TL_PRAGMA] file 
ae20: 63 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69  control can opti
ae30: 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20  onally make the 
ae40: 66 69 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a  first element.**
ae50: 20 6f 66 20 74 68 65 20 63 68 61 72 2a 2a 20 61   of the char** a
ae60: 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f  rgument point to
ae70: 20 61 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e   a string obtain
ae80: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
ae90: 5f 6d 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f  _mprintf()].** o
aea0: 72 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74  r the equivalent
aeb0: 20 61 6e 64 20 74 68 61 74 20 73 74 72 69 6e 67   and that string
aec0: 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65   will become the
aed0: 20 72 65 73 75 6c 74 20 6f 66 20 74 68 65 20 70   result of the p
aee0: 72 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20  ragma or.** the 
aef0: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69 66  error message if
af00: 20 74 68 65 20 70 72 61 67 6d 61 20 66 61 69 6c   the pragma fail
af10: 73 2e 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53  s. ^If the.** [S
af20: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
af30: 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  MA] file control
af40: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
af50: 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e  _NOTFOUND], then
af60: 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41   normal .** [PRA
af70: 47 4d 41 5d 20 70 72 6f 63 65 73 73 69 6e 67 20  GMA] processing 
af80: 63 6f 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66 20  continues.  ^If 
af90: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  the [SQLITE_FCNT
afa0: 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c  L_PRAGMA].** fil
afb0: 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e  e control return
afc0: 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74  s [SQLITE_OK], t
afd0: 68 65 6e 20 74 68 65 20 70 61 72 73 65 72 20 61  hen the parser a
afe0: 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a  ssumes that the.
aff0: 2a 2a 20 56 46 53 20 68 61 73 20 68 61 6e 64 6c  ** VFS has handl
b000: 65 64 20 74 68 65 20 50 52 41 47 4d 41 20 69 74  ed the PRAGMA it
b010: 73 65 6c 66 20 61 6e 64 20 74 68 65 20 70 61 72  self and the par
b020: 73 65 72 20 67 65 6e 65 72 61 74 65 73 20 61 20  ser generates a 
b030: 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65  no-op.** prepare
b040: 64 20 73 74 61 74 65 6d 65 6e 74 20 69 66 20 72  d statement if r
b050: 65 73 75 6c 74 20 73 74 72 69 6e 67 20 69 73 20  esult string is 
b060: 4e 55 4c 4c 2c 20 6f 72 20 74 68 61 74 20 72 65  NULL, or that re
b070: 74 75 72 6e 73 20 61 20 63 6f 70 79 0a 2a 2a 20  turns a copy.** 
b080: 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 74  of the result st
b090: 72 69 6e 67 20 69 66 20 74 68 65 20 73 74 72 69  ring if the stri
b0a0: 6e 67 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 2e 0a  ng is non-NULL..
b0b0: 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49  ** ^If the [SQLI
b0c0: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
b0d0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65   file control re
b0e0: 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73  turns.** any res
b0f0: 75 6c 74 20 63 6f 64 65 20 6f 74 68 65 72 20 74  ult code other t
b100: 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  han [SQLITE_OK] 
b110: 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  or [SQLITE_NOTFO
b120: 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73  UND], that means
b130: 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 56 46 53  .** that the VFS
b140: 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e 20   encountered an 
b150: 65 72 72 6f 72 20 77 68 69 6c 65 20 68 61 6e 64  error while hand
b160: 6c 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41  ling the [PRAGMA
b170: 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d  ] and the.** com
b180: 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  pilation of the 
b190: 50 52 41 47 4d 41 20 66 61 69 6c 73 20 77 69 74  PRAGMA fails wit
b1a0: 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68  h an error.  ^Th
b1b0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
b1c0: 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20  PRAGMA].** file 
b1d0: 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20 61  control occurs a
b1e0: 74 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  t the beginning 
b1f0: 6f 66 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d  of pragma statem
b200: 65 6e 74 20 61 6e 61 6c 79 73 69 73 20 61 6e 64  ent analysis and
b210: 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c   so.** it is abl
b220: 65 20 74 6f 20 6f 76 65 72 72 69 64 65 20 62 75  e to override bu
b230: 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20  ilt-in [PRAGMA] 
b240: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
b250: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
b260: 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52  CNTL_BUSYHANDLER
b270: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
b280: 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e  TE_FCNTL_BUSYHAN
b290: 44 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f  DLER].** file-co
b2a0: 6e 74 72 6f 6c 20 6d 61 79 20 62 65 20 69 6e 76  ntrol may be inv
b2b0: 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 6f  oked by SQLite o
b2c0: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
b2d0: 69 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 73 68  ile handle.** sh
b2e0: 6f 72 74 6c 79 20 61 66 74 65 72 20 69 74 20 69  ortly after it i
b2f0: 73 20 6f 70 65 6e 65 64 20 69 6e 20 6f 72 64 65  s opened in orde
b300: 72 20 74 6f 20 70 72 6f 76 69 64 65 20 61 20 63  r to provide a c
b310: 75 73 74 6f 6d 20 56 46 53 20 77 69 74 68 20 61  ustom VFS with a
b320: 63 63 65 73 73 0a 2a 2a 20 74 6f 20 74 68 65 20  ccess.** to the 
b330: 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 75 73 79  connections busy
b340: 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63  -handler callbac
b350: 6b 2e 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  k. The argument 
b360: 69 73 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64  is of type (void
b370: 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61 72 72   **).** - an arr
b380: 61 79 20 6f 66 20 74 77 6f 20 28 76 6f 69 64 20  ay of two (void 
b390: 2a 29 20 76 61 6c 75 65 73 2e 20 54 68 65 20 66  *) values. The f
b3a0: 69 72 73 74 20 28 76 6f 69 64 20 2a 29 20 61 63  irst (void *) ac
b3b0: 74 75 61 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a  tually points.**
b3c0: 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f   to a function o
b3d0: 66 20 74 79 70 65 20 28 69 6e 74 20 28 2a 29 28  f type (int (*)(
b3e0: 76 6f 69 64 20 2a 29 29 2e 20 49 6e 20 6f 72 64  void *)). In ord
b3f0: 65 72 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65  er to invoke the
b400: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20   connections.** 
b410: 62 75 73 79 2d 68 61 6e 64 6c 65 72 2c 20 74 68  busy-handler, th
b420: 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75  is function shou
b430: 6c 64 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69  ld be invoked wi
b440: 74 68 20 74 68 65 20 73 65 63 6f 6e 64 20 28 76  th the second (v
b450: 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a 20 74 68 65  oid *) in.** the
b460: 20 61 72 72 61 79 20 61 73 20 74 68 65 20 6f 6e   array as the on
b470: 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20 49 66 20  ly argument. If 
b480: 69 74 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  it returns non-z
b490: 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 6f 70  ero, then the op
b4a0: 65 72 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c  eration.** shoul
b4b0: 64 20 62 65 20 72 65 74 72 69 65 64 2e 20 49 66  d be retried. If
b4c0: 20 69 74 20 72 65 74 75 72 6e 73 20 7a 65 72 6f   it returns zero
b4d0: 2c 20 74 68 65 20 63 75 73 74 6f 6d 20 56 46 53  , the custom VFS
b4e0: 20 73 68 6f 75 6c 64 20 61 62 61 6e 64 6f 6e 20   should abandon 
b4f0: 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 6f  the.** current o
b500: 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  peration..**.** 
b510: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
b520: 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d  TL_TEMPFILENAME]
b530: 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63 61 74 69 6f  ].** ^Applicatio
b540: 6e 20 63 61 6e 20 69 6e 76 6f 6b 65 20 74 68 65  n can invoke the
b550: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54   [SQLITE_FCNTL_T
b560: 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 20 66 69 6c  EMPFILENAME] fil
b570: 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20  e-control.** to 
b580: 68 61 76 65 20 53 51 4c 69 74 65 20 67 65 6e 65  have SQLite gene
b590: 72 61 74 65 20 61 0a 2a 2a 20 74 65 6d 70 6f 72  rate a.** tempor
b5a0: 61 72 79 20 66 69 6c 65 6e 61 6d 65 20 75 73 69  ary filename usi
b5b0: 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f  ng the same algo
b5c0: 72 69 74 68 6d 20 74 68 61 74 20 69 73 20 66 6f  rithm that is fo
b5d0: 6c 6c 6f 77 65 64 20 74 6f 20 67 65 6e 65 72 61  llowed to genera
b5e0: 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20  te.** temporary 
b5f0: 66 69 6c 65 6e 61 6d 65 73 20 66 6f 72 20 54 45  filenames for TE
b600: 4d 50 20 74 61 62 6c 65 73 20 61 6e 64 20 6f 74  MP tables and ot
b610: 68 65 72 20 69 6e 74 65 72 6e 61 6c 20 75 73 65  her internal use
b620: 73 2e 20 20 54 68 65 0a 2a 2a 20 61 72 67 75 6d  s.  The.** argum
b630: 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 61 20  ent should be a 
b640: 63 68 61 72 2a 2a 20 77 68 69 63 68 20 77 69 6c  char** which wil
b650: 6c 20 62 65 20 66 69 6c 6c 65 64 20 77 69 74 68  l be filled with
b660: 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a   the filename.**
b670: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65   written into me
b680: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
b690: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
b6a0: 6f 63 28 29 5d 2e 20 20 54 68 65 20 63 61 6c 6c  oc()].  The call
b6b0: 65 72 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76  er should.** inv
b6c0: 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  oke [sqlite3_fre
b6d0: 65 28 29 5d 20 6f 6e 20 74 68 65 20 72 65 73 75  e()] on the resu
b6e0: 6c 74 20 74 6f 20 61 76 6f 69 64 20 61 20 6d 65  lt to avoid a me
b6f0: 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a  mory leak..**.**
b700: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
b710: 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a  NTL_MMAP_SIZE]].
b720: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
b730: 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20  CNTL_MMAP_SIZE] 
b740: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20  file control is 
b750: 75 73 65 64 20 74 6f 20 71 75 65 72 79 20 6f 72  used to query or
b760: 20 73 65 74 20 74 68 65 0a 2a 2a 20 6d 61 78 69   set the.** maxi
b770: 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  mum number of by
b780: 74 65 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65  tes that will be
b790: 20 75 73 65 64 20 66 6f 72 20 6d 65 6d 6f 72 79   used for memory
b7a0: 2d 6d 61 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20  -mapped I/O..** 
b7b0: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
b7c0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76  a pointer to a v
b7d0: 61 6c 75 65 20 6f 66 20 74 79 70 65 20 73 71 6c  alue of type sql
b7e0: 69 74 65 33 5f 69 6e 74 36 34 20 74 68 61 74 0a  ite3_int64 that.
b7f0: 2a 2a 20 69 73 20 61 6e 20 61 64 76 69 73 6f 72  ** is an advisor
b800: 79 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  y maximum number
b810: 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
b820: 20 66 69 6c 65 20 74 6f 20 6d 65 6d 6f 72 79 20   file to memory 
b830: 6d 61 70 2e 20 20 54 68 65 0a 2a 2a 20 70 6f 69  map.  The.** poi
b840: 6e 74 65 72 20 69 73 20 6f 76 65 72 77 72 69 74  nter is overwrit
b850: 74 65 6e 20 77 69 74 68 20 74 68 65 20 6f 6c 64  ten with the old
b860: 20 76 61 6c 75 65 2e 20 20 54 68 65 20 6c 69 6d   value.  The lim
b870: 69 74 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65  it is not change
b880: 64 20 69 66 0a 2a 2a 20 74 68 65 20 76 61 6c 75  d if.** the valu
b890: 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 70 6f 69  e originally poi
b8a0: 6e 74 65 64 20 74 6f 20 69 73 20 6e 65 67 61 74  nted to is negat
b8b0: 69 76 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20  ive, and so the 
b8c0: 63 75 72 72 65 6e 74 20 6c 69 6d 69 74 20 0a 2a  current limit .*
b8d0: 2a 20 63 61 6e 20 62 65 20 71 75 65 72 69 65 64  * can be queried
b8e0: 20 62 79 20 70 61 73 73 69 6e 67 20 69 6e 20 61   by passing in a
b8f0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 65   pointer to a ne
b900: 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2e 20 20  gative number.  
b910: 54 68 69 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e  This.** file-con
b920: 74 72 6f 6c 20 69 73 20 75 73 65 64 20 69 6e 74  trol is used int
b930: 65 72 6e 61 6c 6c 79 20 74 6f 20 69 6d 70 6c 65  ernally to imple
b940: 6d 65 6e 74 20 5b 50 52 41 47 4d 41 20 6d 6d 61  ment [PRAGMA mma
b950: 70 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c  p_size]..**.** <
b960: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
b970: 4c 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20 54 68 65  L_TRACE]].** The
b980: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54   [SQLITE_FCNTL_T
b990: 52 41 43 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72  RACE] file contr
b9a0: 6f 6c 20 70 72 6f 76 69 64 65 73 20 61 64 76 69  ol provides advi
b9b0: 73 6f 72 79 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  sory information
b9c0: 0a 2a 2a 20 74 6f 20 74 68 65 20 56 46 53 20 61  .** to the VFS a
b9d0: 62 6f 75 74 20 77 68 61 74 20 74 68 65 20 68 69  bout what the hi
b9e0: 67 68 65 72 20 6c 61 79 65 72 73 20 6f 66 20 74  gher layers of t
b9f0: 68 65 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20  he SQLite stack 
ba00: 61 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68  are doing..** Th
ba10: 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  is file control 
ba20: 69 73 20 75 73 65 64 20 62 79 20 73 6f 6d 65 20  is used by some 
ba30: 56 46 53 20 61 63 74 69 76 69 74 79 20 74 72 61  VFS activity tra
ba40: 63 69 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a  cing [shims]..**
ba50: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   The argument is
ba60: 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
ba70: 65 64 20 73 74 72 69 6e 67 2e 20 20 48 69 67 68  ed string.  High
ba80: 65 72 20 6c 61 79 65 72 73 20 69 6e 20 74 68 65  er layers in the
ba90: 0a 2a 2a 20 53 51 4c 69 74 65 20 73 74 61 63 6b  .** SQLite stack
baa0: 20 6d 61 79 20 67 65 6e 65 72 61 74 65 20 69 6e   may generate in
bab0: 73 74 61 6e 63 65 73 20 6f 66 20 74 68 69 73 20  stances of this 
bac0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 66 0a  file control if.
bad0: 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55  ** the [SQLITE_U
bae0: 53 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20  SE_FCNTL_TRACE] 
baf0: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
bb00: 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a  ion is enabled..
bb10: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
bb20: 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56  TE_FCNTL_HAS_MOV
bb30: 45 44 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ED]].** The [SQL
bb40: 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f  ITE_FCNTL_HAS_MO
bb50: 56 45 44 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  VED] file contro
bb60: 6c 20 69 6e 74 65 72 70 72 65 74 73 20 69 74 73  l interprets its
bb70: 20 61 72 67 75 6d 65 6e 74 20 61 73 20 61 0a 2a   argument as a.*
bb80: 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  * pointer to an 
bb90: 69 6e 74 65 67 65 72 20 61 6e 64 20 69 74 20 77  integer and it w
bba0: 72 69 74 65 73 20 61 20 62 6f 6f 6c 65 61 6e 20  rites a boolean 
bbb0: 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65  into that intege
bbc0: 72 20 64 65 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f  r depending.** o
bbd0: 6e 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  n whether or not
bbe0: 20 74 68 65 20 66 69 6c 65 20 68 61 73 20 62 65   the file has be
bbf0: 65 6e 20 72 65 6e 61 6d 65 64 2c 20 6d 6f 76 65  en renamed, move
bc00: 64 2c 20 6f 72 20 64 65 6c 65 74 65 64 20 73 69  d, or deleted si
bc10: 6e 63 65 20 69 74 0a 2a 2a 20 77 61 73 20 66 69  nce it.** was fi
bc20: 72 73 74 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a  rst opened..**.*
bc30: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
bc40: 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48  CNTL_WIN32_GET_H
bc50: 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  ANDLE]].** The [
bc60: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
bc70: 33 32 5f 47 45 54 5f 48 41 4e 44 4c 45 5d 20 6f  32_GET_HANDLE] o
bc80: 70 63 6f 64 65 20 63 61 6e 20 62 65 20 75 73 65  pcode can be use
bc90: 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 0a  d to obtain the.
bca0: 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 6e 61  ** underlying na
bcb0: 74 69 76 65 20 66 69 6c 65 20 68 61 6e 64 6c 65  tive file handle
bcc0: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
bcd0: 20 61 20 66 69 6c 65 20 68 61 6e 64 6c 65 2e 20   a file handle. 
bce0: 20 54 68 69 73 20 66 69 6c 65 0a 2a 2a 20 63 6f   This file.** co
bcf0: 6e 74 72 6f 6c 20 69 6e 74 65 72 70 72 65 74 73  ntrol interprets
bd00: 20 69 74 73 20 61 72 67 75 6d 65 6e 74 20 61 73   its argument as
bd10: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
bd20: 6e 61 74 69 76 65 20 66 69 6c 65 20 68 61 6e 64  native file hand
bd30: 6c 65 20 61 6e 64 0a 2a 2a 20 77 72 69 74 65 73  le and.** writes
bd40: 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 76   the resulting v
bd50: 61 6c 75 65 20 74 68 65 72 65 2e 0a 2a 2a 0a 2a  alue there..**.*
bd60: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
bd70: 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48  CNTL_WIN32_SET_H
bd80: 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  ANDLE]].** The [
bd90: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
bda0: 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 20 6f  32_SET_HANDLE] o
bdb0: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f  pcode is used fo
bdc0: 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68  r debugging.  Th
bdd0: 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75  is.** opcode cau
bde0: 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e  ses the xFileCon
bdf0: 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 73  trol method to s
be00: 77 61 70 20 74 68 65 20 66 69 6c 65 20 68 61 6e  wap the file han
be10: 64 6c 65 20 77 69 74 68 20 74 68 65 20 6f 6e 65  dle with the one
be20: 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  .** pointed to b
be30: 79 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d  y the pArg argum
be40: 65 6e 74 2e 20 20 54 68 69 73 20 63 61 70 61 62  ent.  This capab
be50: 69 6c 69 74 79 20 69 73 20 75 73 65 64 20 64 75  ility is used du
be60: 72 69 6e 67 20 74 65 73 74 69 6e 67 0a 2a 2a 20  ring testing.** 
be70: 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74  and only needs t
be80: 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20 77  o be supported w
be90: 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 20  hen SQLITE_TEST 
bea0: 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a  is defined..**.*
beb0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
bec0: 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 5d  CNTL_WAL_BLOCK]]
bed0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
bee0: 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d  FCNTL_WAL_BLOCK]
bef0: 20 69 73 20 61 20 73 69 67 6e 61 6c 20 74 6f 20   is a signal to 
bf00: 74 68 65 20 56 46 53 20 6c 61 79 65 72 20 74 68  the VFS layer th
bf10: 61 74 20 69 74 20 6d 69 67 68 74 0a 2a 2a 20 62  at it might.** b
bf20: 65 20 61 64 76 61 6e 74 61 67 65 6f 75 73 20 74  e advantageous t
bf30: 6f 20 62 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 6e  o block on the n
bf40: 65 78 74 20 57 41 4c 20 6c 6f 63 6b 20 69 66 20  ext WAL lock if 
bf50: 74 68 65 20 6c 6f 63 6b 20 69 73 20 6e 6f 74 20  the lock is not 
bf60: 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20 61  immediately.** a
bf70: 76 61 69 6c 61 62 6c 65 2e 20 20 54 68 65 20 57  vailable.  The W
bf80: 41 4c 20 73 75 62 73 79 73 74 65 6d 20 69 73 73  AL subsystem iss
bf90: 75 65 73 20 74 68 69 73 20 73 69 67 6e 61 6c 20  ues this signal 
bfa0: 64 75 72 69 6e 67 20 72 61 72 65 0a 2a 2a 20 63  during rare.** c
bfb0: 69 72 63 75 6d 73 74 61 6e 63 65 73 20 69 6e 20  ircumstances in 
bfc0: 6f 72 64 65 72 20 74 6f 20 66 69 78 20 61 20 70  order to fix a p
bfd0: 72 6f 62 6c 65 6d 20 77 69 74 68 20 70 72 69 6f  roblem with prio
bfe0: 72 69 74 79 20 69 6e 76 65 72 73 69 6f 6e 2e 0a  rity inversion..
bff0: 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** Applications 
c000: 73 68 6f 75 6c 64 20 3c 65 6d 3e 6e 6f 74 3c 2f  should <em>not</
c010: 65 6d 3e 20 75 73 65 20 74 68 69 73 20 66 69 6c  em> use this fil
c020: 65 2d 63 6f 6e 74 72 6f 6c 2e 0a 2a 2a 0a 2a 2a  e-control..**.**
c030: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
c040: 4e 54 4c 5f 5a 49 50 56 46 53 5d 5d 0a 2a 2a 20  NTL_ZIPVFS]].** 
c050: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
c060: 4c 5f 5a 49 50 56 46 53 5d 20 6f 70 63 6f 64 65  L_ZIPVFS] opcode
c070: 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20   is implemented 
c080: 62 79 20 7a 69 70 76 66 73 20 6f 6e 6c 79 2e 20  by zipvfs only. 
c090: 41 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 56 46 53  All other.** VFS
c0a0: 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 53   should return S
c0b0: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66  QLITE_NOTFOUND f
c0c0: 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 0a  or this opcode..
c0d0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
c0e0: 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d 5d 0a 2a  TE_FCNTL_RBU]].*
c0f0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
c100: 4e 54 4c 5f 52 42 55 5d 20 6f 70 63 6f 64 65 20  NTL_RBU] opcode 
c110: 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62  is implemented b
c120: 79 20 74 68 65 20 73 70 65 63 69 61 6c 20 56 46  y the special VF
c130: 53 20 75 73 65 64 20 62 79 0a 2a 2a 20 74 68 65  S used by.** the
c140: 20 52 42 55 20 65 78 74 65 6e 73 69 6f 6e 20 6f   RBU extension o
c150: 6e 6c 79 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20  nly.  All other 
c160: 56 46 53 20 73 68 6f 75 6c 64 20 72 65 74 75 72  VFS should retur
c170: 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e  n SQLITE_NOTFOUN
c180: 44 20 66 6f 72 0a 2a 2a 20 74 68 69 73 20 6f 70  D for.** this op
c190: 63 6f 64 65 2e 20 20 0a 2a 2a 20 3c 2f 75 6c 3e  code.  .** </ul>
c1a0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
c1b0: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41  TE_FCNTL_LOCKSTA
c1c0: 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
c1d0: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
c1e0: 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b  E_FCNTL_GET_LOCK
c1f0: 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20  PROXYFILE       
c200: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
c210: 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50  _FCNTL_SET_LOCKP
c220: 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20 33  ROXYFILE       3
c230: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c240: 46 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f  FCNTL_LAST_ERRNO
c250: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 34 0a                4.
c260: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c270: 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20  CNTL_SIZE_HINT  
c280: 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23               5.#
c290: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
c2a0: 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20  NTL_CHUNK_SIZE  
c2b0: 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64              6.#d
c2c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
c2d0: 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20  TL_FILE_POINTER 
c2e0: 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65             7.#de
c2f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c300: 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20  L_SYNC_OMITTED  
c310: 20 20 20 20 20 20 20 20 20 20 38 0a 23 64 65 66            8.#def
c320: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c330: 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 20  _WIN32_AV_RETRY 
c340: 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69           9.#defi
c350: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c360: 50 45 52 53 49 53 54 5f 57 41 4c 20 20 20 20 20  PERSIST_WAL     
c370: 20 20 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e         10.#defin
c380: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f  e SQLITE_FCNTL_O
c390: 56 45 52 57 52 49 54 45 20 20 20 20 20 20 20 20  VERWRITE        
c3a0: 20 20 20 20 20 20 31 31 0a 23 64 65 66 69 6e 65        11.#define
c3b0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46   SQLITE_FCNTL_VF
c3c0: 53 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20  SNAME           
c3d0: 20 20 20 20 20 31 32 0a 23 64 65 66 69 6e 65 20       12.#define 
c3e0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57  SQLITE_FCNTL_POW
c3f0: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45  ERSAFE_OVERWRITE
c400: 20 20 20 20 31 33 0a 23 64 65 66 69 6e 65 20 53      13.#define S
c410: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
c420: 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MA              
c430: 20 20 20 31 34 0a 23 64 65 66 69 6e 65 20 53 51     14.#define SQ
c440: 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48  LITE_FCNTL_BUSYH
c450: 41 4e 44 4c 45 52 20 20 20 20 20 20 20 20 20 20  ANDLER          
c460: 20 20 31 35 0a 23 64 65 66 69 6e 65 20 53 51 4c    15.#define SQL
c470: 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49  ITE_FCNTL_TEMPFI
c480: 4c 45 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20  LENAME          
c490: 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   16.#define SQLI
c4a0: 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49  TE_FCNTL_MMAP_SI
c4b0: 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ZE              
c4c0: 31 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  18.#define SQLIT
c4d0: 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 20 20 20  E_FCNTL_TRACE   
c4e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
c4f0: 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  9.#define SQLITE
c500: 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44  _FCNTL_HAS_MOVED
c510: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30                20
c520: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c530: 46 43 4e 54 4c 5f 53 59 4e 43 20 20 20 20 20 20  FCNTL_SYNC      
c540: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31 0a               21.
c550: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c560: 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53  CNTL_COMMIT_PHAS
c570: 45 54 57 4f 20 20 20 20 20 20 20 20 32 32 0a 23  ETWO        22.#
c580: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
c590: 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41  NTL_WIN32_SET_HA
c5a0: 4e 44 4c 45 20 20 20 20 20 20 20 32 33 0a 23 64  NDLE       23.#d
c5b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
c5c0: 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 20 20 20 20  TL_WAL_BLOCK    
c5d0: 20 20 20 20 20 20 20 20 20 20 32 34 0a 23 64 65            24.#de
c5e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c5f0: 4c 5f 5a 49 50 56 46 53 20 20 20 20 20 20 20 20  L_ZIPVFS        
c600: 20 20 20 20 20 20 20 20 20 32 35 0a 23 64 65 66           25.#def
c610: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c620: 5f 52 42 55 20 20 20 20 20 20 20 20 20 20 20 20  _RBU            
c630: 20 20 20 20 20 20 20 20 32 36 0a 23 64 65 66 69          26.#defi
c640: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c650: 56 46 53 5f 50 4f 49 4e 54 45 52 20 20 20 20 20  VFS_POINTER     
c660: 20 20 20 20 20 20 20 32 37 0a 23 64 65 66 69 6e         27.#defin
c670: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a  e SQLITE_FCNTL_J
c680: 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 20 20  OURNAL_POINTER  
c690: 20 20 20 20 20 20 32 38 0a 23 64 65 66 69 6e 65        28.#define
c6a0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49   SQLITE_FCNTL_WI
c6b0: 4e 33 32 5f 47 45 54 5f 48 41 4e 44 4c 45 20 20  N32_GET_HANDLE  
c6c0: 20 20 20 20 20 32 39 0a 23 64 65 66 69 6e 65 20       29.#define 
c6d0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 44 42  SQLITE_FCNTL_PDB
c6e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
c6f0: 20 20 20 20 33 30 0a 0a 2f 2a 20 64 65 70 72 65      30../* depre
c700: 63 61 74 65 64 20 6e 61 6d 65 73 20 2a 2f 0a 23  cated names */.#
c710: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 45  define SQLITE_GE
c720: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20  T_LOCKPROXYFILE 
c730: 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54       SQLITE_FCNT
c740: 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  L_GET_LOCKPROXYF
c750: 49 4c 45 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  ILE.#define SQLI
c760: 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TE_SET_LOCKPROXY
c770: 46 49 4c 45 20 20 20 20 20 20 53 51 4c 49 54 45  FILE      SQLITE
c780: 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50  _FCNTL_SET_LOCKP
c790: 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 69 6e 65  ROXYFILE.#define
c7a0: 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52   SQLITE_LAST_ERR
c7b0: 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20 53  NO             S
c7c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54  QLITE_FCNTL_LAST
c7d0: 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a 20 43  _ERRNO.../*.** C
c7e0: 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48  API3REF: Mutex H
c7f0: 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20  andle.**.** The 
c800: 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74  mutex module wit
c810: 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e  hin SQLite defin
c820: 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  es [sqlite3_mute
c830: 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61  x] to be an.** a
c840: 62 73 74 72 61 63 74 20 74 79 70 65 20 66 6f 72  bstract type for
c850: 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e   a mutex object.
c860: 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72    The SQLite cor
c870: 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a  e never looks.**
c880: 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   at the internal
c890: 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20   representation 
c8a0: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d  of an [sqlite3_m
c8b0: 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a  utex].  It only.
c8c0: 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f  ** deals with po
c8d0: 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73  inters to the [s
c8e0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62  qlite3_mutex] ob
c8f0: 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65  ject..**.** Mute
c900: 78 65 73 20 61 72 65 20 63 72 65 61 74 65 64 20  xes are created 
c910: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  using [sqlite3_m
c920: 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  utex_alloc()]..*
c930: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
c940: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73   sqlite3_mutex s
c950: 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f  qlite3_mutex;../
c960: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c  *.** CAPI3REF: L
c970: 6f 61 64 61 62 6c 65 20 45 78 74 65 6e 73 69 6f  oadable Extensio
c980: 6e 20 54 68 75 6e 6b 0a 2a 2a 0a 2a 2a 20 41 20  n Thunk.**.** A 
c990: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6f  pointer to the o
c9a0: 70 61 71 75 65 20 73 71 6c 69 74 65 33 5f 61 70  paque sqlite3_ap
c9b0: 69 5f 72 6f 75 74 69 6e 65 73 20 73 74 72 75 63  i_routines struc
c9c0: 74 75 72 65 20 69 73 20 70 61 73 73 65 64 20 61  ture is passed a
c9d0: 73 0a 2a 2a 20 74 68 65 20 74 68 69 72 64 20 70  s.** the third p
c9e0: 61 72 61 6d 65 74 65 72 20 74 6f 20 65 6e 74 72  arameter to entr
c9f0: 79 20 70 6f 69 6e 74 73 20 6f 66 20 5b 6c 6f 61  y points of [loa
ca00: 64 61 62 6c 65 20 65 78 74 65 6e 73 69 6f 6e 73  dable extensions
ca10: 5d 2e 20 20 54 68 69 73 0a 2a 2a 20 73 74 72 75  ].  This.** stru
ca20: 63 74 75 72 65 20 6d 75 73 74 20 62 65 20 74 79  cture must be ty
ca30: 70 65 64 65 66 65 64 20 69 6e 20 6f 72 64 65 72  pedefed in order
ca40: 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20   to work around 
ca50: 63 6f 6d 70 69 6c 65 72 20 77 61 72 6e 69 6e 67  compiler warning
ca60: 73 0a 2a 2a 20 6f 6e 20 73 6f 6d 65 20 70 6c 61  s.** on some pla
ca70: 74 66 6f 72 6d 73 2e 0a 2a 2f 0a 74 79 70 65 64  tforms..*/.typed
ca80: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
ca90: 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73 20 73  3_api_routines s
caa0: 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74 69  qlite3_api_routi
cab0: 6e 65 73 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nes;../*.** CAPI
cac0: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61  3REF: OS Interfa
cad0: 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  ce Object.**.** 
cae0: 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
caf0: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  he sqlite3_vfs o
cb00: 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68  bject defines th
cb10: 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77  e interface betw
cb20: 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74  een.** the SQLit
cb30: 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75  e core and the u
cb40: 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74  nderlying operat
cb50: 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65  ing system.  The
cb60: 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65   "vfs".** in the
cb70: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a   name of the obj
cb80: 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22  ect stands for "
cb90: 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73  virtual file sys
cba0: 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74 68  tem".  See.** th
cbb0: 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f 63  e [VFS | VFS doc
cbc0: 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20  umentation] for 
cbd0: 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61 74  further informat
cbe0: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76  ion..**.** The v
cbf0: 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65 72  alue of the iVer
cc00: 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e  sion field is in
cc10: 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61  itially 1 but ma
cc20: 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a  y be larger in.*
cc30: 2a 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e  * future version
cc40: 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64  s of SQLite.  Ad
cc50: 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20  ditional fields 
cc60: 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20  may be appended 
cc70: 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63  to this.** objec
cc80: 74 20 77 68 65 6e 20 74 68 65 20 69 56 65 72 73  t when the iVers
cc90: 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63  ion value is inc
cca0: 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68  reased.  Note th
ccb0: 61 74 20 74 68 65 20 73 74 72 75 63 74 75 72 65  at the structure
ccc0: 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74  .** of the sqlit
ccd0: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68  e3_vfs object ch
cce0: 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72 61  anges in the tra
ccf0: 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e  nsaction between
cd00: 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69  .** SQLite versi
cd10: 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36  on 3.5.9 and 3.6
cd20: 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65 20 69  .0 and yet the i
cd30: 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61  Version field wa
cd40: 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65  s not.** modifie
cd50: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f  d..**.** The szO
cd60: 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74  sFile field is t
cd70: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73  he size of the s
cd80: 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74  ubclassed [sqlit
cd90: 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75  e3_file].** stru
cda0: 63 74 75 72 65 20 75 73 65 64 20 62 79 20 74 68  cture used by th
cdb0: 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e  is VFS.  mxPathn
cdc0: 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d  ame is the maxim
cdd0: 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20  um length of.** 
cde0: 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68  a pathname in th
cdf0: 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65  is VFS..**.** Re
ce00: 67 69 73 74 65 72 65 64 20 73 71 6c 69 74 65 33  gistered sqlite3
ce10: 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65  _vfs objects are
ce20: 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65   kept on a linke
ce30: 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79  d list formed by
ce40: 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f  .** the pNext po
ce50: 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c  inter.  The [sql
ce60: 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65  ite3_vfs_registe
ce70: 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  r()].** and [sql
ce80: 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73  ite3_vfs_unregis
ce90: 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ter()] interface
cea0: 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69  s manage this li
ceb0: 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61  st.** in a threa
cec0: 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68 65  d-safe way.  The
ced0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69   [sqlite3_vfs_fi
cee0: 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a  nd()] interface.
cef0: 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68 65 20  ** searches the 
cf00: 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74  list.  Neither t
cf10: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63  he application c
cf20: 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a  ode nor the VFS.
cf30: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
cf40: 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65  n should use the
cf50: 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a   pNext pointer..
cf60: 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20  **.** The pNext 
cf70: 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c  field is the onl
cf80: 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73  y field in the s
cf90: 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74  qlite3_vfs.** st
cfa0: 72 75 63 74 75 72 65 20 74 68 61 74 20 53 51 4c  ructure that SQL
cfb0: 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f  ite will ever mo
cfc0: 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69  dify.  SQLite wi
cfd0: 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a  ll only access.*
cfe0: 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73  * or modify this
cff0: 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c   field while hol
d000: 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61  ding a particula
d010: 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a  r static mutex..
d020: 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
d030: 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20  on should never 
d040: 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20  modify anything 
d050: 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74  within the sqlit
d060: 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74  e3_vfs.** object
d070: 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74   once the object
d080: 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 73 74   has been regist
d090: 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ered..**.** The 
d0a0: 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64  zName field hold
d0b0: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
d0c0: 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54  e VFS module.  T
d0d0: 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20  he name must.** 
d0e0: 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73  be unique across
d0f0: 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73   all VFS modules
d100: 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65  ..**.** [[sqlite
d110: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a  3_vfs.xOpen]].**
d120: 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74   ^SQLite guarant
d130: 65 65 73 20 74 68 61 74 20 74 68 65 20 7a 46 69  ees that the zFi
d140: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
d150: 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20   to xOpen.** is 
d160: 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f  either a NULL po
d170: 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67 20  inter or string 
d180: 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d  obtained.** from
d190: 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29   xFullPathname()
d1a0: 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61   with an optiona
d1b0: 6c 20 73 75 66 66 69 78 20 61 64 64 65 64 2e 0a  l suffix added..
d1c0: 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78 20  ** ^If a suffix 
d1d0: 69 73 20 61 64 64 65 64 20 74 6f 20 74 68 65 20  is added to the 
d1e0: 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  zFilename parame
d1f0: 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20  ter, it will.** 
d200: 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69 6e  consist of a sin
d210: 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74 65  gle "-" characte
d220: 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f  r followed by no
d230: 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31   more than.** 11
d240: 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61 6e   alphanumeric an
d250: 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63 74  d/or "-" charact
d260: 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ers..** ^SQLite 
d270: 66 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 65  further guarante
d280: 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73  es that.** the s
d290: 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61  tring will be va
d2a0: 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65  lid and unchange
d2b0: 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29  d until xClose()
d2c0: 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42   is.** called. B
d2d0: 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72  ecause of the pr
d2e0: 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c  evious sentence,
d2f0: 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
d300: 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c  _file] can safel
d310: 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65  y store a pointe
d320: 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65  r to the.** file
d330: 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73  name if it needs
d340: 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65   to remember the
d350: 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f   filename for so
d360: 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66  me reason..** If
d370: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70   the zFilename p
d380: 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65  arameter to xOpe
d390: 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  n is a NULL poin
d3a0: 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a  ter then xOpen.*
d3b0: 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74  * must invent it
d3c0: 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20  s own temporary 
d3d0: 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c  name for the fil
d3e0: 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74 68  e.  ^Whenever th
d3f0: 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20  e .** xFilename 
d400: 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c  parameter is NUL
d410: 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62  L it will also b
d420: 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20  e the case that 
d430: 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72  the.** flags par
d440: 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c  ameter will incl
d450: 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ude [SQLITE_OPEN
d460: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e  _DELETEONCLOSE].
d470: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73  .**.** The flags
d480: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70   argument to xOp
d490: 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c  en() includes al
d4a0: 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a  l bits set in.**
d4b0: 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   the flags argum
d4c0: 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ent to [sqlite3_
d4d0: 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20  open_v2()].  Or 
d4e0: 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  if [sqlite3_open
d4f0: 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  ()].** or [sqlit
d500: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20  e3_open16()] is 
d510: 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73  used, then flags
d520: 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61   includes at lea
d530: 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  st.** [SQLITE_OP
d540: 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20  EN_READWRITE] | 
d550: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
d560: 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70  ATE]. .** If xOp
d570: 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c  en() opens a fil
d580: 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e  e read-only then
d590: 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c   it sets *pOutFl
d5a0: 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64  ags to.** includ
d5b0: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  e [SQLITE_OPEN_R
d5c0: 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72  EADONLY].  Other
d5d0: 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c   bits in *pOutFl
d5e0: 61 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a  ags may be set..
d5f0: 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77  **.** ^(SQLite w
d600: 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65  ill also add one
d610: 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
d620: 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78  g flags to the x
d630: 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20  Open().** call, 
d640: 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
d650: 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70   object being op
d660: 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ened:.**.** <ul>
d670: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
d680: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a  E_OPEN_MAIN_DB].
d690: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
d6a0: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e  _OPEN_MAIN_JOURN
d6b0: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
d6c0: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44  LITE_OPEN_TEMP_D
d6d0: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  B].** <li>  [SQL
d6e0: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f  ITE_OPEN_TEMP_JO
d6f0: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
d700: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41  [SQLITE_OPEN_TRA
d710: 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c  NSIENT_DB].** <l
d720: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
d730: 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  _SUBJOURNAL].** 
d740: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
d750: 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41  EN_MASTER_JOURNA
d760: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
d770: 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a  ITE_OPEN_WAL].**
d780: 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54   </ul>)^.**.** T
d790: 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c  he file I/O impl
d7a0: 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75  ementation can u
d7b0: 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79  se the object ty
d7c0: 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63  pe flags to.** c
d7d0: 68 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 74  hange the way it
d7e0: 20 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65   deals with file
d7f0: 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  s.  For example,
d800: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a   an application.
d810: 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74  ** that does not
d820: 20 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73   care about cras
d830: 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f  h recovery or ro
d840: 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b  llback might mak
d850: 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66  e.** the open of
d860: 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20   a journal file 
d870: 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73  a no-op.  Writes
d880: 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c   to this journal
d890: 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62   would.** also b
d8a0: 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e  e no-ops, and an
d8b0: 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61  y attempt to rea
d8c0: 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f  d the journal wo
d8d0: 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51  uld return.** SQ
d8e0: 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20  LITE_IOERR.  Or 
d8f0: 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
d900: 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69  on might recogni
d910: 7a 65 20 74 68 61 74 20 61 20 64 61 74 61 62 61  ze that a databa
d920: 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20  se.** file will 
d930: 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c  be doing page-al
d940: 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61  igned sector rea
d950: 64 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e  ds and writes in
d960: 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64   a random.** ord
d970: 65 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 74  er and set up it
d980: 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20  s I/O subsystem 
d990: 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a  accordingly..**.
d9a0: 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20  ** SQLite might 
d9b0: 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20  also add one of 
d9c0: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c  the following fl
d9d0: 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ags to the xOpen
d9e0: 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c   method:.**.** <
d9f0: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
da00: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
da10: 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20  NCLOSE].** <li> 
da20: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43  [SQLITE_OPEN_EXC
da30: 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e  LUSIVE].** </ul>
da40: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  .**.** The [SQLI
da50: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
da60: 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e  CLOSE] flag mean
da70: 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c  s the file shoul
da80: 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20  d be.** deleted 
da90: 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65  when it is close
daa0: 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  d.  ^The [SQLITE
dab0: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
dac0: 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  OSE].** will be 
dad0: 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61 74  set for TEMP dat
dae0: 61 62 61 73 65 73 20 61 6e 64 20 74 68 65 69 72  abases and their
daf0: 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73   journals, trans
db00: 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73 65  ient.** database
db10: 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61  s, and subjourna
db20: 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  ls..**.** ^The [
db30: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
db40: 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61  USIVE] flag is a
db50: 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f  lways used in co
db60: 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74  njunction.** wit
db70: 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  h the [SQLITE_OP
db80: 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c  EN_CREATE] flag,
db90: 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 68 20   which are both 
dba0: 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c  directly.** anal
dbb0: 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45  ogous to the O_E
dbc0: 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20  XCL and O_CREAT 
dbd0: 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53  flags of the POS
dbe0: 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49  IX open().** API
dbf0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50  .  The SQLITE_OP
dc00: 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61  EN_EXCLUSIVE fla
dc10: 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20 77  g, when paired w
dc20: 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49  ith the .** SQLI
dc30: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20  TE_OPEN_CREATE, 
dc40: 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63  is used to indic
dc50: 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 73 68  ate that file sh
dc60: 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62  ould always.** b
dc70: 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74  e created, and t
dc80: 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 72 72  hat it is an err
dc90: 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 64 79  or if it already
dca0: 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69   exists..** It i
dcb0: 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65  s <i>not</i> use
dcc0: 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  d to indicate th
dcd0: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65  e file should be
dce0: 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20   opened .** for 
dcf0: 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73  exclusive access
dd00: 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73  ..**.** ^At leas
dd10: 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73  t szOsFile bytes
dd20: 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61   of memory are a
dd30: 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69  llocated by SQLi
dd40: 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68  te.** to hold th
dd50: 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  e  [sqlite3_file
dd60: 5d 20 73 74 72 75 63 74 75 72 65 20 70 61 73 73  ] structure pass
dd70: 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 0a  ed as the third.
dd80: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  ** argument to x
dd90: 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e  Open.  The xOpen
dda0: 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74   method does not
ddb0: 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f   have to.** allo
ddc0: 63 61 74 65 20 74 68 65 20 73 74 72 75 63 74 75  cate the structu
ddd0: 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75  re; it should ju
dde0: 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20  st fill it in.  
ddf0: 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  Note that.** the
de00: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75   xOpen method mu
de10: 73 74 20 73 65 74 20 74 68 65 20 73 71 6c 69 74  st set the sqlit
de20: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
de30: 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20   to either.** a 
de40: 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69  valid [sqlite3_i
de50: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
de60: 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78  t or to NULL.  x
de70: 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20  Open must do.** 
de80: 74 68 69 73 20 65 76 65 6e 20 69 66 20 74 68 65  this even if the
de90: 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51   open fails.  SQ
dea0: 4c 69 74 65 20 65 78 70 65 63 74 73 20 74 68 61  Lite expects tha
deb0: 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69  t the sqlite3_fi
dec0: 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65  le.pMethods.** e
ded0: 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76  lement will be v
dee0: 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e  alid after xOpen
def0: 20 72 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c   returns regardl
df00: 65 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 65  ess of the succe
df10: 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65  ss.** or failure
df20: 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61   of the xOpen ca
df30: 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69  ll..**.** [[sqli
df40: 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73 73 5d  te3_vfs.xAccess]
df50: 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73 20  ].** ^The flags 
df60: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 63  argument to xAcc
df70: 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53 51  ess() may be [SQ
df80: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
df90: 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66  TS].** to test f
dfa0: 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e 63 65  or the existence
dfb0: 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b   of a file, or [
dfc0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
dfd0: 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74  ADWRITE] to.** t
dfe0: 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69  est whether a fi
dff0: 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 20 61  le is readable a
e000: 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 20  nd writable, or 
e010: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52  [SQLITE_ACCESS_R
e020: 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20  EAD].** to test 
e030: 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69  whether a file i
e040: 73 20 61 74 20 6c 65 61 73 74 20 72 65 61 64 61  s at least reada
e050: 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65 20  ble.   The file 
e060: 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72 65  can be a.** dire
e070: 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51  ctory..**.** ^SQ
e080: 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73  Lite will always
e090: 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 61   allocate at lea
e0a0: 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20  st mxPathname+1 
e0b0: 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a  bytes for the.**
e0c0: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 78   output buffer x
e0d0: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54  FullPathname.  T
e0e0: 68 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f 66  he exact size of
e0f0: 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66   the output buff
e100: 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61  er.** is also pa
e110: 73 73 65 64 20 61 73 20 61 20 70 61 72 61 6d 65  ssed as a parame
e120: 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 74  ter to both  met
e130: 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75 74  hods. If the out
e140: 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73  put buffer.** is
e150: 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 67   not large enoug
e160: 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f  h, [SQLITE_CANTO
e170: 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20 72  PEN] should be r
e180: 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20 74  eturned. Since t
e190: 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65  his is.** handle
e1a0: 64 20 61 73 20 61 20 66 61 74 61 6c 20 65 72 72  d as a fatal err
e1b0: 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76 66  or by SQLite, vf
e1c0: 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  s implementation
e1d0: 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f  s should endeavo
e1e0: 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74 20  r.** to prevent 
e1f0: 74 68 69 73 20 62 79 20 73 65 74 74 69 6e 67 20  this by setting 
e200: 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 20  mxPathname to a 
e210: 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 72  sufficiently lar
e220: 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20  ge value..**.** 
e230: 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28  The xRandomness(
e240: 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43 75  ), xSleep(), xCu
e250: 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64  rrentTime(), and
e260: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74   xCurrentTimeInt
e270: 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  64().** interfac
e280: 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63  es are not stric
e290: 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74 68  tly a part of th
e2a0: 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75  e filesystem, bu
e2b0: 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e  t they are.** in
e2c0: 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56 46  cluded in the VF
e2d0: 53 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20  S structure for 
e2e0: 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a  completeness..**
e2f0: 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73   The xRandomness
e300: 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65  () function atte
e310: 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e  mpts to return n
e320: 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f  Bytes bytes.** o
e330: 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72  f good-quality r
e340: 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a  andomness into z
e350: 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e  Out.  The return
e360: 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65   value is.** the
e370: 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f   actual number o
e380: 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f  f bytes of rando
e390: 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a  mness obtained..
e3a0: 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29 20  ** The xSleep() 
e3b0: 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 74 68  method causes th
e3c0: 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64  e calling thread
e3d0: 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74   to sleep for at
e3e0: 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75  .** least the nu
e3f0: 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63  mber of microsec
e400: 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54 68  onds given.  ^Th
e410: 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29  e xCurrentTime()
e420: 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72  .** method retur
e430: 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20  ns a Julian Day 
e440: 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63  Number for the c
e450: 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64 20  urrent date and 
e460: 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f  time as.** a flo
e470: 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75  ating point valu
e480: 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72 72  e..** ^The xCurr
e490: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d  entTimeInt64() m
e4a0: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20 61  ethod returns, a
e4b0: 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68  s an integer, th
e4c0: 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20  e Julian.** Day 
e4d0: 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69 65  Number multiplie
e4e0: 64 20 62 79 20 38 36 34 30 30 30 30 30 20 28 74  d by 86400000 (t
e4f0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c  he number of mil
e500: 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a  liseconds in .**
e510: 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29 2e   a 24-hour day).
e520: 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69    .** ^SQLite wi
e530: 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75 72 72  ll use the xCurr
e540: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d  entTimeInt64() m
e550: 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68 65  ethod to get the
e560: 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65   current.** date
e570: 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68 61   and time if tha
e580: 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61 69  t method is avai
e590: 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72 73 69  lable (if iVersi
e5a0: 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67  on is 2 or .** g
e5b0: 72 65 61 74 65 72 20 61 6e 64 20 74 68 65 20 66  reater and the f
e5c0: 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20  unction pointer 
e5d0: 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64  is not NULL) and
e5e0: 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a   will fall back.
e5f0: 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54 69  ** to xCurrentTi
e600: 6d 65 28 29 20 69 66 20 78 43 75 72 72 65 6e 74  me() if xCurrent
e610: 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20 75  TimeInt64() is u
e620: 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a  navailable..**.*
e630: 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73 74 65  * ^The xSetSyste
e640: 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79 73  mCall(), xGetSys
e650: 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78  temCall(), and x
e660: 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28 29  NestSystemCall()
e670: 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61   interfaces.** a
e680: 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20 74  re not used by t
e690: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e 20  he SQLite core. 
e6a0: 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20   These optional 
e6b0: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 70  interfaces are p
e6c0: 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f  rovided.** by so
e6d0: 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61 63 69  me VFSes to faci
e6e0: 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67 20 6f  litate testing o
e6f0: 66 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e 20  f the VFS code. 
e700: 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a  By overriding .*
e710: 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 77  * system calls w
e720: 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e  ith functions un
e730: 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c  der its control,
e740: 20 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d 20   a test program 
e750: 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20  can.** simulate 
e760: 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f 72  faults and error
e770: 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61 74   conditions that
e780: 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73 65   would otherwise
e790: 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a   be difficult.**
e7a0: 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20 74   or impossible t
e7b0: 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20 73  o induce.  The s
e7c0: 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61 6c  et of system cal
e7d0: 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f  ls that can be o
e7e0: 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72  verridden.** var
e7f0: 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53  ies from one VFS
e800: 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64   to another, and
e810: 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f   from one versio
e820: 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56 46  n of the same VF
e830: 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74  S to the.** next
e840: 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  .  Applications 
e850: 74 68 61 74 20 75 73 65 20 74 68 65 73 65 20 69  that use these i
e860: 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74 20 62  nterfaces must b
e870: 65 20 70 72 65 70 61 72 65 64 20 66 6f 72 20 61  e prepared for a
e880: 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20  ny.** or all of 
e890: 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
e8a0: 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66   to be NULL or f
e8b0: 6f 72 20 74 68 65 69 72 20 62 65 68 61 76 69 6f  or their behavio
e8c0: 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66  r to change.** f
e8d0: 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 20  rom one release 
e8e0: 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41 70  to the next.  Ap
e8f0: 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20  plications must 
e900: 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20 61  not attempt to a
e910: 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20  ccess.** any of 
e920: 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69 66  these methods if
e930: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f 66   the iVersion of
e940: 20 74 68 65 20 56 46 53 20 69 73 20 6c 65 73 73   the VFS is less
e950: 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65   than 3..*/.type
e960: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
e970: 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76  e3_vfs sqlite3_v
e980: 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69 64  fs;.typedef void
e990: 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 63 61   (*sqlite3_sysca
e9a0: 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a 73  ll_ptr)(void);.s
e9b0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66  truct sqlite3_vf
e9c0: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  s {.  int iVersi
e9d0: 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f  on;            /
e9e0: 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72 73  * Structure vers
e9f0: 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72 72  ion number (curr
ea00: 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e  ently 3) */.  in
ea10: 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20  t szOsFile;     
ea20: 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f         /* Size o
ea30: 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c  f subclassed sql
ea40: 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69  ite3_file */.  i
ea50: 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20  nt mxPathname;  
ea60: 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
ea70: 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65  um file pathname
ea80: 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c   length */.  sql
ea90: 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b  ite3_vfs *pNext;
eaa0: 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65        /* Next re
eab0: 67 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a  gistered VFS */.
eac0: 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
ead0: 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61  ame;       /* Na
eae0: 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 74 75  me of this virtu
eaf0: 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a  al file system *
eb00: 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61  /.  void *pAppDa
eb10: 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ta;          /* 
eb20: 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69  Pointer to appli
eb30: 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20  cation-specific 
eb40: 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  data */.  int (*
eb50: 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76  xOpen)(sqlite3_v
eb60: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
eb70: 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f  *zName, sqlite3_
eb80: 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20  file*,.         
eb90: 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c        int flags,
eba0: 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29   int *pOutFlags)
ebb0: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74  ;.  int (*xDelet
ebc0: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
ebd0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
ebe0: 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29  me, int syncDir)
ebf0: 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73  ;.  int (*xAcces
ec00: 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  s)(sqlite3_vfs*,
ec10: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
ec20: 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 69  me, int flags, i
ec30: 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20  nt *pResOut);.  
ec40: 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e  int (*xFullPathn
ec50: 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ame)(sqlite3_vfs
ec60: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
ec70: 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20  Name, int nOut, 
ec80: 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76  char *zOut);.  v
ec90: 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28  oid *(*xDlOpen)(
eca0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
ecb0: 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e  nst char *zFilen
ecc0: 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  ame);.  void (*x
ecd0: 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33  DlError)(sqlite3
ece0: 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65  _vfs*, int nByte
ecf0: 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29  , char *zErrMsg)
ed00: 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c  ;.  void (*(*xDl
ed10: 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73  Sym)(sqlite3_vfs
ed20: 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63  *,void*, const c
ed30: 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76  har *zSymbol))(v
ed40: 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  oid);.  void (*x
ed50: 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33  DlClose)(sqlite3
ed60: 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20  _vfs*, void*);. 
ed70: 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65   int (*xRandomne
ed80: 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ss)(sqlite3_vfs*
ed90: 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61  , int nByte, cha
eda0: 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20  r *zOut);.  int 
edb0: 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65  (*xSleep)(sqlite
edc0: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72  3_vfs*, int micr
edd0: 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74  oseconds);.  int
ede0: 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29   (*xCurrentTime)
edf0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64  (sqlite3_vfs*, d
ee00: 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  ouble*);.  int (
ee10: 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29 28  *xGetLastError)(
ee20: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
ee30: 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a  t, char *);.  /*
ee40: 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64  .  ** The method
ee50: 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76  s above are in v
ee60: 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65 20  ersion 1 of the 
ee70: 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63  sqlite_vfs objec
ee80: 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f  t.  ** definitio
ee90: 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20 66  n.  Those that f
eea0: 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64 20  ollow are added 
eeb0: 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72 20  in version 2 or 
eec0: 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74  later.  */.  int
eed0: 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 49   (*xCurrentTimeI
eee0: 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76 66  nt64)(sqlite3_vf
eef0: 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  s*, sqlite3_int6
ef00: 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54  4*);.  /*.  ** T
ef10: 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  he methods above
ef20: 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73   are in versions
ef30: 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65 20   1 and 2 of the 
ef40: 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63  sqlite_vfs objec
ef50: 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62 65  t..  ** Those be
ef60: 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72 73  low are for vers
ef70: 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 74 65  ion 3 and greate
ef80: 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  r..  */.  int (*
ef90: 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28  xSetSystemCall)(
efa0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
efb0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
efc0: 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c   sqlite3_syscall
efd0: 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 65 33  _ptr);.  sqlite3
efe0: 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78  _syscall_ptr (*x
eff0: 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73  GetSystemCall)(s
f000: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
f010: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b  st char *zName);
f020: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 28  .  const char *(
f030: 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61 6c 6c  *xNextSystemCall
f040: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
f050: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
f060: 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68  e);.  /*.  ** Th
f070: 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  e methods above 
f080: 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20  are in versions 
f090: 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66 20 74  1 through 3 of t
f0a0: 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62  he sqlite_vfs ob
f0b0: 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66  ject..  ** New f
f0c0: 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70  ields may be app
f0d0: 65 6e 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  ended in future 
f0e0: 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69  versions.  The i
f0f0: 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c  Version.  ** val
f100: 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e  ue will incremen
f110: 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 73 20  t whenever this 
f120: 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d  happens. .  */.}
f130: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
f140: 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65  F: Flags for the
f150: 20 78 41 63 63 65 73 73 20 56 46 53 20 6d 65 74   xAccess VFS met
f160: 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  hod.**.** These 
f170: 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
f180: 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73  s can be used as
f190: 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
f1a0: 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78  eter to.** the x
f1b0: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66  Access method of
f1c0: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73   an [sqlite3_vfs
f1d0: 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79 20  ] object.  They 
f1e0: 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61  determine.** wha
f1f0: 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73  t kind of permis
f200: 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73  sions the xAcces
f210: 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b  s method is look
f220: 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68  ing for..** With
f230: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45   SQLITE_ACCESS_E
f240: 58 49 53 54 53 2c 20 74 68 65 20 78 41 63 63 65  XISTS, the xAcce
f250: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d  ss method.** sim
f260: 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74 68  ply checks wheth
f270: 65 72 20 74 68 65 20 66 69 6c 65 20 65 78 69 73  er the file exis
f280: 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49  ts..** With SQLI
f290: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
f2a0: 49 54 45 2c 20 74 68 65 20 78 41 63 63 65 73 73  ITE, the xAccess
f2b0: 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b   method.** check
f2c0: 73 20 77 68 65 74 68 65 72 20 74 68 65 20 6e 61  s whether the na
f2d0: 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20 69 73  med directory is
f2e0: 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20 61   both readable a
f2f0: 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28  nd writable.** (
f300: 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  in other words, 
f310: 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62 65 20  if files can be 
f320: 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20  added, removed, 
f330: 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 74 68  and renamed with
f340: 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 63 74  in.** the direct
f350: 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  ory)..** The SQL
f360: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
f370: 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 69 73  RITE constant is
f380: 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65 64 20   currently used 
f390: 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b  only by the.** [
f3a0: 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
f3b0: 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 74 68  tory pragma], th
f3c0: 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c 64 20  ough this could 
f3d0: 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75  change in a futu
f3e0: 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66  re.** release of
f3f0: 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68   SQLite..** With
f400: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
f410: 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 73 73  EAD, the xAccess
f420: 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b   method.** check
f430: 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69  s whether the fi
f440: 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e 20  le is readable. 
f450: 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45   The SQLITE_ACCE
f460: 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e 74  SS_READ constant
f470: 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79   is.** currently
f480: 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 68 20   unused, though 
f490: 69 74 20 6d 69 67 68 74 20 62 65 20 75 73 65 64  it might be used
f4a0: 20 69 6e 20 61 20 66 75 74 75 72 65 20 72 65 6c   in a future rel
f4b0: 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74  ease of.** SQLit
f4c0: 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e..*/.#define SQ
f4d0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
f4e0: 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20  TS    0.#define 
f4f0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
f500: 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a 20 55  ADWRITE 1   /* U
f510: 73 65 64 20 62 79 20 50 52 41 47 4d 41 20 74 65  sed by PRAGMA te
f520: 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f  mp_store_directo
f530: 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ry */.#define SQ
f540: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
f550: 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55 6e 75        2   /* Unu
f560: 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  sed */../*.** CA
f570: 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f  PI3REF: Flags fo
f580: 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56  r the xShmLock V
f590: 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20  FS method.**.** 
f5a0: 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f  These integer co
f5b0: 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 74  nstants define t
f5c0: 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69  he various locki
f5d0: 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a  ng operations.**
f5e0: 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 65 20   allowed by the 
f5f0: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20  xShmLock method 
f600: 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  of [sqlite3_io_m
f610: 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a  ethods].  The.**
f620: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74   following are t
f630: 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f  he only legal co
f640: 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c  mbinations of fl
f650: 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53  ags to the.** xS
f660: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a  hmLock method:.*
f670: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
f680: 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f  >  SQLITE_SHM_LO
f690: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
f6a0: 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20  SHARED.** <li>  
f6b0: 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
f6c0: 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43  | SQLITE_SHM_EXC
f6d0: 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20  LUSIVE.** <li>  
f6e0: 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43  SQLITE_SHM_UNLOC
f6f0: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53  K | SQLITE_SHM_S
f700: 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53  HARED.** <li>  S
f710: 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b  QLITE_SHM_UNLOCK
f720: 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58   | SQLITE_SHM_EX
f730: 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e  CLUSIVE.** </ul>
f740: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f  .**.** When unlo
f750: 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d 65 20  cking, the same 
f760: 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c 55 53  SHARED or EXCLUS
f770: 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20 62 65  IVE flag must be
f780: 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20   supplied as.** 
f790: 77 61 73 20 67 69 76 65 6e 20 6f 6e 20 74 68 65  was given on the
f7a0: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c   corresponding l
f7b0: 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65  ock.  .**.** The
f7c0: 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
f7d0: 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20   can transition 
f7e0: 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64  between unlocked
f7f0: 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72 0a 2a   and SHARED or.*
f800: 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b  * between unlock
f810: 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45  ed and EXCLUSIVE
f820: 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 72 61  .  It cannot tra
f830: 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  nsition between 
f840: 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58  SHARED.** and EX
f850: 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66  CLUSIVE..*/.#def
f860: 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55  ine SQLITE_SHM_U
f870: 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a 23 64  NLOCK       1.#d
f880: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
f890: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 32 0a  _LOCK         2.
f8a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
f8b0: 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20 20 20  HM_SHARED       
f8c0: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
f8d0: 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 20 20  _SHM_EXCLUSIVE  
f8e0: 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    8../*.** CAPI3
f8f0: 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68  REF: Maximum xSh
f900: 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a  mLock index.**.*
f910: 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d  * The xShmLock m
f920: 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65  ethod on [sqlite
f930: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61  3_io_methods] ma
f940: 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20  y use values.** 
f950: 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68  between 0 and th
f960: 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61  is upper bound a
f970: 73 20 69 74 73 20 22 6f 66 66 73 65 74 22 20 61  s its "offset" a
f980: 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20  rgument..** The 
f990: 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c 6c  SQLite core will
f9a0: 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74 20 74   never attempt t
f9b0: 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72 65 6c  o acquire or rel
f9c0: 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f  ease a.** lock o
f9d0: 75 74 73 69 64 65 20 6f 66 20 74 68 69 73 20 72  utside of this r
f9e0: 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ange.*/.#define 
f9f0: 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b  SQLITE_SHM_NLOCK
fa00: 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a          8.../*.*
fa10: 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74  * CAPI3REF: Init
fa20: 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74  ialize The SQLit
fa30: 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20  e Library.**.** 
fa40: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  ^The sqlite3_ini
fa50: 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e  tialize() routin
fa60: 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68  e initializes th
fa70: 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72  e.** SQLite libr
fa80: 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  ary.  ^The sqlit
fa90: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f  e3_shutdown() ro
faa0: 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63  utine.** dealloc
fab0: 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63  ates any resourc
fac0: 65 73 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c  es that were all
fad0: 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  ocated by sqlite
fae0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a  3_initialize()..
faf0: 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
fb00: 73 20 61 72 65 20 64 65 73 69 67 6e 65 64 20 74  s are designed t
fb10: 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65 73 73  o aid in process
fb20: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
fb30: 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20  and.** shutdown 
fb40: 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73 74  on embedded syst
fb50: 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f  ems.  Workstatio
fb60: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 75  n applications u
fb70: 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e  sing.** SQLite n
fb80: 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e  ormally do not n
fb90: 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69  eed to invoke ei
fba0: 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 72 6f  ther of these ro
fbb0: 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20  utines..**.** A 
fbc0: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
fbd0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
fbe0: 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63  an "effective" c
fbf0: 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20  all if it is.** 
fc00: 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73  the first time s
fc10: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
fc20: 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64  e() is invoked d
fc30: 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69  uring the lifeti
fc40: 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f  me of.** the pro
fc50: 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69  cess, or if it i
fc60: 73 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65  s the first time
fc70: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
fc80: 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
fc90: 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  .** following a 
fca0: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
fcb0: 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f  shutdown().  ^(O
fcc0: 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76 65  nly an effective
fcd0: 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69   call.** of sqli
fce0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
fcf0: 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 61   does any initia
fd00: 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f  lization.  All o
fd10: 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72  ther calls.** ar
fd20: 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  e harmless no-op
fd30: 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c  s.)^.**.** A cal
fd40: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
fd50: 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22 65  tdown() is an "e
fd60: 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69  ffective" call i
fd70: 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73  f it is the firs
fd80: 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c  t.** call to sql
fd90: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
fda0: 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20 73  since the last s
fdb0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
fdc0: 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20  e().  ^(Only.** 
fdd0: 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c  an effective cal
fde0: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
fdf0: 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e 79  tdown() does any
fe00: 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f   deinitializatio
fe10: 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20  n..** All other 
fe20: 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20 73  valid calls to s
fe30: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
fe40: 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e  ) are harmless n
fe50: 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54  o-ops.)^.**.** T
fe60: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
fe70: 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 61 63  alize() interfac
fe80: 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2c  e is threadsafe,
fe90: 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73 68 75   but sqlite3_shu
fea0: 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f  tdown().** is no
feb0: 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  t.  The sqlite3_
fec0: 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65 72  shutdown() inter
fed0: 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62  face must only b
fee0: 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a  e called from a.
fef0: 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64  ** single thread
ff00: 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74  .  All open [dat
ff10: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
ff20: 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f 73 65  s] must be close
ff30: 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68  d and all.** oth
ff40: 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f 75 72  er SQLite resour
ff50: 63 65 73 20 6d 75 73 74 20 62 65 20 64 65 61 6c  ces must be deal
ff60: 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20 74 6f  located prior to
ff70: 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c   invoking.** sql
ff80: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
ff90: 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68  .**.** Among oth
ffa0: 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69  er things, ^sqli
ffb0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
ffc0: 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20   will invoke.** 
ffd0: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
ffe0: 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e  ).  Similarly, ^
fff0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
10000 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b  ().** will invok
10010 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  e sqlite3_os_end
10020 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ()..**.** ^The s
10030 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
10040 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  e() routine retu
10050 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  rns [SQLITE_OK] 
10060 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e  on success..** ^
10070 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73  If for some reas
10080 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  on, sqlite3_init
10090 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62  ialize() is unab
100a0 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65  le to initialize
100b0 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20  .** the library 
100c0 28 70 65 72 68 61 70 73 20 69 74 20 69 73 20 75  (perhaps it is u
100d0 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
100e0 65 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75  e a needed resou
100f0 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61  rce such.** as a
10100 20 6d 75 74 65 78 29 20 69 74 20 72 65 74 75 72   mutex) it retur
10110 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  ns an [error cod
10120 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  e] other than [S
10130 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a  QLITE_OK]..**.**
10140 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
10150 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69  itialize() routi
10160 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74  ne is called int
10170 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20  ernally by many 
10180 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20  other.** SQLite 
10190 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74 68  interfaces so th
101a0 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  at an applicatio
101b0 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e  n usually does n
101c0 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e  ot need to.** in
101d0 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  voke sqlite3_ini
101e0 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74  tialize() direct
101f0 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65  ly.  For example
10200 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  , [sqlite3_open(
10210 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69  )].** calls sqli
10220 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
10230 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c   so the SQLite l
10240 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61  ibrary will be a
10250 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20  utomatically.** 
10260 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e  initialized when
10270 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
10280 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69  ] is called if i
10290 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69  t has not be ini
102a0 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65  tialized.** alre
102b0 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20  ady.  ^However, 
102c0 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  if SQLite is com
102d0 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 5b  piled with the [
102e0 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f  SQLITE_OMIT_AUTO
102f0 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65  INIT].** compile
10300 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68  -time option, th
10310 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63  en the automatic
10320 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
10330 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a  3_initialize().*
10340 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61 6e  * are omitted an
10350 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  d the applicatio
10360 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c 69  n must call sqli
10370 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
10380 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69   directly.** pri
10390 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20  or to using any 
103a0 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
103b0 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 78  erface.  For max
103c0 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 79  imum portability
103d0 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f 6d  ,.** it is recom
103e0 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c  mended that appl
103f0 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 20  ications always 
10400 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69  invoke sqlite3_i
10410 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64  nitialize().** d
10420 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74 6f  irectly prior to
10430 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72   using any other
10440 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
10450 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65 61  e.  Future relea
10460 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65  ses.** of SQLite
10470 20 6d 61 79 20 72 65 71 75 69 72 65 20 74 68 69   may require thi
10480 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  s.  In other wor
10490 64 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72  ds, the behavior
104a0 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 68   exhibited.** wh
104b0 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  en SQLite is com
104c0 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49  piled with [SQLI
104d0 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54  TE_OMIT_AUTOINIT
104e0 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 74  ] might become t
104f0 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 65  he.** default be
10500 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66  havior in some f
10510 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66  uture release of
10520 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54   SQLite..**.** T
10530 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  he sqlite3_os_in
10540 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65  it() routine doe
10550 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74  s operating-syst
10560 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 69  em specific.** i
10570 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66  nitialization of
10580 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
10590 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ary.  The sqlite
105a0 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f  3_os_end().** ro
105b0 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65  utine undoes the
105c0 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69 74   effect of sqlit
105d0 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54  e3_os_init().  T
105e0 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20  ypical tasks.** 
105f0 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68 65  performed by the
10600 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c  se routines incl
10610 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f  ude allocation o
10620 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  r deallocation.*
10630 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65 73 6f  * of static reso
10640 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a  urces, initializ
10650 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20  ation of global 
10660 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65  variables,.** se
10670 74 74 69 6e 67 20 75 70 20 61 20 64 65 66 61 75  tting up a defau
10680 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
10690 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 74   module, or sett
106a0 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 61  ing up.** a defa
106b0 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
106c0 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  n using [sqlite3
106d0 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a  _config()]..**.*
106e0 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
106f0 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 69  n should never i
10700 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71 6c  nvoke either sql
10710 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a  ite3_os_init().*
10720 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  * or sqlite3_os_
10730 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e 20  end() directly. 
10740 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
10750 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76   should only inv
10760 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69  oke.** sqlite3_i
10770 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 20  nitialize() and 
10780 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
10790 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ().  The sqlite3
107a0 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e  _os_init().** in
107b0 74 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c 65  terface is calle
107c0 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  d automatically 
107d0 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  by sqlite3_initi
107e0 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73  alize() and.** s
107f0 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20  qlite3_os_end() 
10800 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71 6c  is called by sql
10810 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
10820 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a    Appropriate.**
10830 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
10840 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f   for sqlite3_os_
10850 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74  init() and sqlit
10860 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61  e3_os_end().** a
10870 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  re built into SQ
10880 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69 73 20  Lite when it is 
10890 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e 69  compiled for Uni
108a0 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f  x, Windows, or O
108b0 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75  S/2..** When [cu
108c0 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62 75  stom builds | bu
108d0 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70 6c  ilt for other pl
108e0 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69  atforms].** (usi
108f0 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  ng the [SQLITE_O
10900 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69  S_OTHER=1] compi
10910 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f  le-time.** optio
10920 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  n) the applicati
10930 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61  on must supply a
10940 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d   suitable implem
10950 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20  entation for.** 
10960 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
10970 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73  ) and sqlite3_os
10980 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c  _end().  An appl
10990 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64  ication-supplied
109a0 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
109b0 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73  on of sqlite3_os
109c0 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74  _init() or sqlit
109d0 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d  e3_os_end().** m
109e0 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ust return [SQLI
109f0 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
10a00 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72  s and some other
10a10 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70   [error code] up
10a20 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a  on.** failure..*
10a30 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
10a40 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
10a50 69 7a 65 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54  ize(void);.SQLIT
10a60 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
10a70 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64 29  3_shutdown(void)
10a80 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
10a90 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
10aa0 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41  (void);.SQLITE_A
10ab0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  PI int sqlite3_o
10ac0 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a  s_end(void);../*
10ad0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
10ae0 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53 51  nfiguring The SQ
10af0 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a  Lite Library.**.
10b00 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
10b10 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
10b20 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b  e is used to mak
10b30 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75  e global configu
10b40 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65  ration.** change
10b50 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f  s to SQLite in o
10b60 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c  rder to tune SQL
10b70 69 74 65 20 74 6f 20 74 68 65 20 73 70 65 63 69  ite to the speci
10b80 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20  fic needs of.** 
10b90 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e  the application.
10ba0 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f    The default co
10bb0 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72  nfiguration is r
10bc0 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d  ecommended for m
10bd0 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  ost.** applicati
10be0 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20  ons and so this 
10bf0 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c  routine is usual
10c00 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79  ly not necessary
10c10 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76  .  It is.** prov
10c20 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20  ided to support 
10c30 72 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e  rare application
10c40 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e  s with unusual n
10c50 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 54  eeds..**.** <b>T
10c60 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  he sqlite3_confi
10c70 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  g() interface is
10c80 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e   not threadsafe.
10c90 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
10ca0 0a 2a 2a 20 6d 75 73 74 20 65 6e 73 75 72 65 20  .** must ensure 
10cb0 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51  that no other SQ
10cc0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20  Lite interfaces 
10cd0 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f  are invoked by o
10ce0 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20  ther.** threads 
10cf0 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f  while sqlite3_co
10d00 6e 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e  nfig() is runnin
10d10 67 2e 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  g.</b>.**.** The
10d20 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
10d30 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 6d  ) interface.** m
10d40 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b  ay only be invok
10d50 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72  ed prior to libr
10d60 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  ary initializati
10d70 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  on using.** [sql
10d80 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
10d90 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 74  )] or after shut
10da0 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33  down by [sqlite3
10db0 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a  _shutdown()]..**
10dc0 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e   ^If sqlite3_con
10dd0 66 69 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20  fig() is called 
10de0 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69  after [sqlite3_i
10df0 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64  nitialize()] and
10e00 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69   before.** [sqli
10e10 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20  te3_shutdown()] 
10e20 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74  then it will ret
10e30 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53  urn SQLITE_MISUS
10e40 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65  E..** Note, howe
10e50 76 65 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74  ver, that ^sqlit
10e60 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20  e3_config() can 
10e70 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72  be called as par
10e80 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c  t of the.** impl
10e90 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e  ementation of an
10ea0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
10eb0 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73  ined [sqlite3_os
10ec0 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _init()]..**.** 
10ed0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
10ee0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  nt to sqlite3_co
10ef0 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74  nfig() is an int
10f00 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75  eger.** [configu
10f10 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74  ration option] t
10f20 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a  hat determines.*
10f30 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74 79 20  * what property 
10f40 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20  of SQLite is to 
10f50 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20  be configured.  
10f60 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d  Subsequent argum
10f70 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70  ents.** vary dep
10f80 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63  ending on the [c
10f90 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
10fa0 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66  ion].** in the f
10fb0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  irst argument..*
10fc0 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e  *.** ^When a con
10fd0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
10fe0 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65  n is set, sqlite
10ff0 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72  3_config() retur
11000 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a  ns [SQLITE_OK]..
11010 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f  ** ^If the optio
11020 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20  n is unknown or 
11030 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65  SQLite is unable
11040 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69   to set the opti
11050 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20  on.** then this 
11060 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
11070 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  a non-zero [erro
11080 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 53 51 4c 49  r code]..*/.SQLI
11090 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
110a0 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e  e3_config(int, .
110b0 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ..);../*.** CAPI
110c0 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20  3REF: Configure 
110d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
110e0 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ions.** METHOD: 
110f0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68  sqlite3.**.** Th
11100 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  e sqlite3_db_con
11110 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
11120 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20  is used to make 
11130 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a  configuration.**
11140 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b 64   changes to a [d
11150 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
11160 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72 66  on].  The interf
11170 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74  ace is similar t
11180 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
11190 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74 20 74  nfig()] except t
111a0 68 61 74 20 74 68 65 20 63 68 61 6e 67 65 73 20  hat the changes 
111b0 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c  apply to a singl
111c0 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
111d0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65 63  onnection] (spec
111e0 69 66 69 65 64 20 69 6e 20 74 68 65 20 66 69 72  ified in the fir
111f0 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a  st argument)..**
11200 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61  .** The second a
11210 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
11220 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56  e3_db_config(D,V
11230 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a  ,...)  is the.**
11240 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49   [SQLITE_DBCONFI
11250 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 63 6f  G_LOOKASIDE | co
11260 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62  nfiguration verb
11270 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 63  ] - an integer c
11280 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64  ode .** that ind
11290 69 63 61 74 65 73 20 77 68 61 74 20 61 73 70 65  icates what aspe
112a0 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62  ct of the [datab
112b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
112c0 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 67 75  is being configu
112d0 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65  red..** Subseque
112e0 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76 61 72  nt arguments var
112f0 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  y depending on t
11300 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
11310 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61   verb..**.** ^Ca
11320 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 64  lls to sqlite3_d
11330 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72  b_config() retur
11340 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61  n SQLITE_OK if a
11350 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74 68  nd only if.** th
11360 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69 64  e call is consid
11370 65 72 65 64 20 73 75 63 63 65 73 73 66 75 6c 2e  ered successful.
11380 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
11390 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  nt sqlite3_db_co
113a0 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69  nfig(sqlite3*, i
113b0 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a  nt op, ...);../*
113c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
113d0 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20  mory Allocation 
113e0 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41  Routines.**.** A
113f0 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
11400 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  is object define
11410 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  s the interface 
11420 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a  between SQLite.*
11430 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20  * and low-level 
11440 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
11450 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  n routines..**.*
11460 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73  * This object is
11470 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e   used in only on
11480 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53  e place in the S
11490 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
114a0 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  .** A pointer to
114b0 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
114c0 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74  this object is t
114d0 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  he argument to.*
114e0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
114f0 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f  g()] when the co
11500 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
11510 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45  on is.** [SQLITE
11520 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20  _CONFIG_MALLOC] 
11530 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
11540 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a  G_GETMALLOC].  .
11550 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20 61  ** By creating a
11560 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
11570 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64  is object.** and
11580 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b   passing it to [
11590 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28  sqlite3_config](
115a0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
115b0 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e  ALLOC]).** durin
115c0 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c  g configuration,
115d0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
115e0 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61  can specify an a
115f0 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65  lternative.** me
11600 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
11610 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51  subsystem for SQ
11620 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20  Lite to use for 
11630 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79  all of its.** dy
11640 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65  namic memory nee
11650 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  ds..**.** Note t
11660 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73  hat SQLite comes
11670 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62   with several [b
11680 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
11690 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68  llocators].** th
116a0 61 74 20 61 72 65 20 70 65 72 66 65 63 74 6c 79  at are perfectly
116b0 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74 68   adequate for th
116c0 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d  e overwhelming m
116d0 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69  ajority of appli
116e0 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74  cations.** and t
116f0 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20  hat this object 
11700 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74  is only useful t
11710 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74  o a tiny minorit
11720 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e  y of application
11730 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61  s.** with specia
11740 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  lized memory all
11750 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d  ocation requirem
11760 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65  ents.  This obje
11770 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73  ct is.** also us
11780 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
11790 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f  g of SQLite in o
117a0 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79 20  rder to specify 
117b0 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a  an alternative.*
117c0 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
117d0 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65  or that simulate
117e0 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d  s memory out-of-
117f0 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e  memory condition
11800 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f  s in.** order to
11810 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51 4c   verify that SQL
11820 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72 61  ite recovers gra
11830 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63  cefully from suc
11840 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e  h.** conditions.
11850 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c  .**.** The xMall
11860 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e  oc, xRealloc, an
11870 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20  d xFree methods 
11880 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74  must work like t
11890 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20  he.** malloc(), 
118a0 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72  realloc() and fr
118b0 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66  ee() functions f
118c0 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64  rom the standard
118d0 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e   C library..** ^
118e0 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65  SQLite guarantee
118f0 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e  s that the secon
11900 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
11910 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77   xRealloc is alw
11920 61 79 73 20 61 20 76 61 6c 75 65 20 72 65 74 75  ays a value retu
11930 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72 20  rned by a prior 
11940 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70  call to xRoundup
11950 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68  ..**.** xSize sh
11960 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20  ould return the 
11970 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f  allocated size o
11980 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
11990 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75  ation.** previou
119a0 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  sly obtained fro
119b0 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65  m xMalloc or xRe
119c0 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f  alloc.  The allo
119d0 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73  cated size.** is
119e0 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74   always at least
119f0 20 61 73 20 62 69 67 20 61 73 20 74 68 65 20 72   as big as the r
11a00 65 71 75 65 73 74 65 64 20 73 69 7a 65 20 62 75  equested size bu
11a10 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e  t may be larger.
11a20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e  .**.** The xRoun
11a30 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72  dup method retur
11a40 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65  ns what would be
11a50 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   the allocated s
11a60 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f  ize of.** a memo
11a70 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69  ry allocation gi
11a80 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72  ven a particular
11a90 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e   requested size.
11aa0 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a    Most memory.**
11ab0 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e   allocators roun
11ac0 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  d up memory allo
11ad0 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74  cations at least
11ae0 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c   to the next mul
11af0 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20  tiple.** of 8.  
11b00 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20  Some allocators 
11b10 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61  round up to a la
11b20 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72  rger multiple or
11b30 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32   to a power of 2
11b40 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72  ..** Every memor
11b50 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71  y allocation req
11b60 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74  uest coming in t
11b70 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f  hrough [sqlite3_
11b80 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20  malloc()].** or 
11b90 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
11ba0 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20  ()] first calls 
11bb0 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52  xRoundup.  If xR
11bc0 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30  oundup returns 0
11bd0 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65  , .** that cause
11be0 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  s the correspond
11bf0 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ing memory alloc
11c00 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a  ation to fail..*
11c10 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d  *.** The xInit m
11c20 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65  ethod initialize
11c30 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  s the memory all
11c40 6f 63 61 74 6f 72 2e 20 20 46 6f 72 20 65 78 61  ocator.  For exa
11c50 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68  mple,.** it migh
11c60 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72  t allocate any r
11c70 65 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f  equire mutexes o
11c80 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74  r initialize int
11c90 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74  ernal data.** st
11ca0 72 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 78  ructures.  The x
11cb0 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20  Shutdown method 
11cc0 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69  is invoked (indi
11cd0 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73  rectly) by.** [s
11ce0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
11cf0 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65  )] and should de
11d00 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73  allocate any res
11d10 6f 75 72 63 65 73 20 61 63 71 75 69 72 65 64 0a  ources acquired.
11d20 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68  ** by xInit.  Th
11d30 65 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74  e pAppData point
11d40 65 72 20 69 73 20 75 73 65 64 20 61 73 20 74 68  er is used as th
11d50 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72  e only parameter
11d60 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64   to.** xInit and
11d70 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a   xShutdown..**.*
11d80 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74  * SQLite holds t
11d90 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58  he [SQLITE_MUTEX
11da0 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20  _STATIC_MASTER] 
11db0 6d 75 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e  mutex when it in
11dc0 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e  vokes.** the xIn
11dd0 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68  it method, so th
11de0 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e  e xInit method n
11df0 65 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61  eed not be threa
11e00 64 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78  dsafe.  The.** x
11e10 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20  Shutdown method 
11e20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66  is only called f
11e30 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  rom [sqlite3_shu
11e40 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64  tdown()] so it d
11e50 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20  oes.** not need 
11e60 74 6f 20 62 65 20 74 68 72 65 61 64 73 61 66 65  to be threadsafe
11e70 20 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c   either.  For al
11e80 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c  l other methods,
11e90 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73   SQLite.** holds
11ea0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54   the [SQLITE_MUT
11eb0 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d  EX_STATIC_MEM] m
11ec0 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20  utex as long as 
11ed0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  the.** [SQLITE_C
11ee0 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
11ef0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
11f00 70 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20  ption is turned 
11f10 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20  on (which.** it 
11f20 69 73 20 62 79 20 64 65 66 61 75 6c 74 29 20 61  is by default) a
11f30 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64  nd so the method
11f40 73 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61  s are automatica
11f50 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a  lly serialized..
11f60 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b  ** However, if [
11f70 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
11f80 4d 53 54 41 54 55 53 5d 20 69 73 20 64 69 73 61  MSTATUS] is disa
11f90 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f  bled, then the o
11fa0 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20  ther.** methods 
11fb0 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61  must be threadsa
11fc0 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20  fe or else make 
11fd0 74 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67  their own arrang
11fe0 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65  ements for.** se
11ff0 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a  rialization..**.
12000 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e  ** SQLite will n
12010 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69  ever invoke xIni
12020 74 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  t() more than on
12030 63 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e  ce without an in
12040 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c  tervening.** cal
12050 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29  l to xShutdown()
12060 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
12070 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  uct sqlite3_mem_
12080 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f  methods sqlite3_
12090 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72  mem_methods;.str
120a0 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  uct sqlite3_mem_
120b0 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64  methods {.  void
120c0 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74   *(*xMalloc)(int
120d0 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65  );         /* Me
120e0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
120f0 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f  function */.  vo
12100 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64  id (*xFree)(void
12110 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  *);          /* 
12120 46 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c  Free a prior all
12130 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69  ocation */.  voi
12140 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76  d *(*xRealloc)(v
12150 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52  oid*,int);  /* R
12160 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74  esize an allocat
12170 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ion */.  int (*x
12180 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20  Size)(void*);   
12190 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72          /* Retur
121a0 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e  n the size of an
121b0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
121c0 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29   int (*xRoundup)
121d0 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20  (int);          
121e0 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75  /* Round up requ
121f0 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f  est size to allo
12200 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20  cation size */. 
12210 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f   int (*xInit)(vo
12220 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20  id*);           
12230 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68  /* Initialize th
12240 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
12250 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78  or */.  void (*x
12260 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29  Shutdown)(void*)
12270 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74  ;      /* Deinit
12280 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72  ialize the memor
12290 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20  y allocator */. 
122a0 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b   void *pAppData;
122b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
122c0 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78  /* Argument to x
122d0 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75 74  Init() and xShut
122e0 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  down() */.};../*
122f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
12300 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69  nfiguration Opti
12310 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ons.** KEYWORDS:
12320 20 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20   {configuration 
12330 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68  option}.**.** Th
12340 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
12350 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20  e the available 
12360 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72  integer configur
12370 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68  ation options th
12380 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73  at.** can be pas
12390 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74  sed as the first
123a0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
123b0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
123c0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
123d0 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75  *.** New configu
123e0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
123f0 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
12400 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
12410 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69  f SQLite..** Exi
12420 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74  sting configurat
12430 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68  ion options migh
12440 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65  t be discontinue
12450 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  d.  Applications
12460 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b  .** should check
12470 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65   the return code
12480 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63   from [sqlite3_c
12490 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65  onfig()] to make
124a0 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68   sure that.** th
124b0 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20  e call worked.  
124c0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  The [sqlite3_con
124d0 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
124e0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a   will return a.*
124f0 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  * non-zero [erro
12500 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73  r code] if a dis
12510 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73  continued or uns
12520 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75  upported configu
12530 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a  ration option.**
12540 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a   is invoked..**.
12550 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c  ** <dl>.** [[SQL
12560 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
12570 45 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51  ETHREAD]] <dt>SQ
12580 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
12590 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a  LETHREAD</dt>.**
125a0 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
125b0 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
125c0 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
125d0 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
125e0 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
125f0 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65   mode] to Single
12600 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68  -thread.  In oth
12610 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73  er words, it dis
12620 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74  ables.** all mut
12630 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53  exing and puts S
12640 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64  QLite into a mod
12650 65 20 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f  e where it can o
12660 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62  nly be used.** b
12670 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61  y a single threa
12680 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20  d.   ^If SQLite 
12690 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
126a0 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
126b0 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
126c0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
126d0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
126e0 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74  ption then.** it
126f0 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65   is not possible
12700 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 5b   to change the [
12710 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
12720 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c 74  from its default
12730 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69 6e  .** value of Sin
12740 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20 73  gle-thread and s
12750 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
12760 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
12770 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52   .** [SQLITE_ERR
12780 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69  OR] if called wi
12790 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  th the SQLITE_CO
127a0 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
127b0 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  D.** configurati
127c0 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a  on option.</dd>.
127d0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
127e0 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
127f0 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
12800 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
12810 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
12820 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
12830 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
12840 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
12850 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
12860 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
12870 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e  to Multi-thread.
12880 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
12890 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a  , it disables.**
128a0 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61   mutexing on [da
128b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
128c0 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  n] and [prepared
128d0 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65   statement] obje
128e0 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  cts..** The appl
128f0 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f  ication is respo
12900 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61  nsible for seria
12910 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f  lizing access to
12920 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
12930 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b  nnections] and [
12940 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
12950 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72  nts].  But other
12960 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20   mutexes.** are 
12970 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20  enabled so that 
12980 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73  SQLite will be s
12990 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20  afe to use in a 
129a0 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a  multi-threaded.*
129b0 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73  * environment as
129c0 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20   long as no two 
129d0 74 68 72 65 61 64 73 20 61 74 74 65 6d 70 74 20  threads attempt 
129e0 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a  to use the same.
129f0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
12a00 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20  nection] at the 
12a10 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20  same time.  ^If 
12a20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
12a30 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
12a40 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
12a50 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
12a60 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
12a70 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
12a80 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70  n.** it is not p
12a90 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74  ossible to set t
12aa0 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20  he Multi-thread 
12ab0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
12ac0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
12ad0 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20  _config()] will 
12ae0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
12af0 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20  RROR] if called 
12b00 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49  with the.** SQLI
12b10 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
12b20 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74  HREAD configurat
12b30 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e  ion option.</dd>
12b40 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
12b50 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
12b60 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
12b70 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
12b80 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
12b90 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
12ba0 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
12bb0 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f  on.  ^This optio
12bc0 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74  n sets the.** [t
12bd0 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74  hreading mode] t
12be0 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e  o Serialized. In
12bf0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
12c00 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65  is option enable
12c10 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73  s.** all mutexes
12c20 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72   including the r
12c30 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65  ecursive.** mute
12c40 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  xes on [database
12c50 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
12c60 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
12c70 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  ment] objects..*
12c80 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28  * In this mode (
12c90 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65 66  which is the def
12ca0 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65  ault when SQLite
12cb0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
12cc0 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52  h.** [SQLITE_THR
12cd0 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20  EADSAFE=1]) the 
12ce0 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77  SQLite library w
12cf0 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61  ill itself seria
12d00 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74  lize access.** t
12d10 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  o [database conn
12d20 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72  ections] and [pr
12d30 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
12d40 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a  s] so that the.*
12d50 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73  * application is
12d60 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68 65   free to use the
12d70 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
12d80 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74  connection] or t
12d90 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70  he.** same [prep
12da0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
12db0 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68 72  in different thr
12dc0 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65  eads at the same
12dd0 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51   time..** ^If SQ
12de0 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
12df0 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
12e00 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
12e10 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
12e20 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
12e30 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
12e40 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
12e50 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  sible to set the
12e60 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72   Serialized [thr
12e70 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64  eading mode] and
12e80 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
12e90 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  fig()] will retu
12ea0 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
12eb0 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68  ] if called with
12ec0 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43   the.** SQLITE_C
12ed0 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
12ee0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
12ef0 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ption.</dd>.**.*
12f00 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
12f10 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53  G_MALLOC]] <dt>S
12f20 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
12f30 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOC</dt>.** <dd>
12f40 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
12f50 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69  NFIG_MALLOC opti
12f60 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
12f70 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
12f80 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65   is .** a pointe
12f90 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
12fa0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
12fb0 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
12fc0 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20  ructure..** The 
12fd0 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69  argument specifi
12fe0 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76  es.** alternativ
12ff0 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f  e low-level memo
13000 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
13010 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65  utines to be use
13020 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a  d in place of.**
13030 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
13040 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20  cation routines 
13050 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
13060 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b  e.)^ ^SQLite mak
13070 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72  es.** its own pr
13080 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
13090 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
130a0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
130b0 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
130c0 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b  .** before the [
130d0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
130e0 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c  ] call returns.<
130f0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
13100 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
13110 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  LLOC]] <dt>SQLIT
13120 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
13130 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  OC</dt>.** <dd> 
13140 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  ^(The SQLITE_CON
13150 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 6f 70  FIG_GETMALLOC op
13160 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
13170 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
13180 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74  ch.** is a point
13190 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
131a0 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
131b0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73  3_mem_methods] s
131c0 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65  tructure..** The
131d0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
131e0 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74  thods].** struct
131f0 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69  ure is filled wi
13200 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79  th the currently
13210 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20   defined memory 
13220 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
13230 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f  nes.)^.** This o
13240 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ption can be use
13250 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68  d to overload th
13260 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79  e default memory
13270 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72   allocation.** r
13280 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77  outines with a w
13290 72 61 70 70 65 72 20 74 68 61 74 20 73 69 6d 75  rapper that simu
132a0 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61  lations memory a
132b0 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72  llocation failur
132c0 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d  e or.** tracks m
132d0 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72  emory usage, for
132e0 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a   example. </dd>.
132f0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
13300 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
13310 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
13320 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64  FIG_MEMSTATUS</d
13330 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20  t>.** <dd> ^The 
13340 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
13350 4d 53 54 41 54 55 53 20 6f 70 74 69 6f 6e 20 74  MSTATUS option t
13360 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75  akes single argu
13370 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74  ment of type int
13380 2c 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 65 64  ,.** interpreted
13390 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 2c 20 77   as a boolean, w
133a0 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20  hich enables or 
133b0 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 6f 6c  disables the col
133c0 6c 65 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20 6d 65  lection of.** me
133d0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
133e0 73 74 61 74 69 73 74 69 63 73 2e 20 5e 28 57 68  statistics. ^(Wh
133f0 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  en memory alloca
13400 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20  tion statistics 
13410 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2c  are.** disabled,
13420 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53   the following S
13430 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
13440 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72   become non-oper
13450 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75  ational:.**   <u
13460 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  l>.**   <li> [sq
13470 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
13480 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  d()].**   <li> [
13490 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
134a0 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20  ighwater()].**  
134b0 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73   <li> [sqlite3_s
134c0 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34  oft_heap_limit64
134d0 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ()].**   <li> [s
134e0 71 6c 69 74 65 33 5f 73 74 61 74 75 73 36 34 28  qlite3_status64(
134f0 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a  )].**   </ul>)^.
13500 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ** ^Memory alloc
13510 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73  ation statistics
13520 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20   are enabled by 
13530 64 65 66 61 75 6c 74 20 75 6e 6c 65 73 73 20 53  default unless S
13540 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70  QLite is.** comp
13550 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54  iled with [SQLIT
13560 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41  E_DEFAULT_MEMSTA
13570 54 55 53 5d 3d 30 20 69 6e 20 77 68 69 63 68 20  TUS]=0 in which 
13580 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  case memory.** a
13590 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
135a0 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65  tics are disable
135b0 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  d by default..**
135c0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
135d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
135e0 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  ATCH]] <dt>SQLIT
135f0 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
13600 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
13610 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
13620 5f 53 43 52 41 54 43 48 20 6f 70 74 69 6f 6e 20  _SCRATCH option 
13630 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
13640 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
13650 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20  .** that SQLite 
13660 63 61 6e 20 75 73 65 20 66 6f 72 20 73 63 72 61  can use for scra
13670 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 5e 28 54  tch memory.  ^(T
13680 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
13690 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 74 6f 20 53  rguments.** to S
136a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
136b0 41 54 43 48 3a 20 20 41 20 70 6f 69 6e 74 65 72  ATCH:  A pointer
136c0 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c   an 8-byte.** al
136d0 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66  igned memory buf
136e0 66 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20 74  fer from which t
136f0 68 65 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63  he scratch alloc
13700 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a  ations will be.*
13710 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69 7a  * drawn, the siz
13720 65 20 6f 66 20 65 61 63 68 20 73 63 72 61 74 63  e of each scratc
13730 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a  h allocation (sz
13740 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61  ),.** and the ma
13750 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
13760 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69  scratch allocati
13770 6f 6e 73 20 28 4e 29 2e 29 5e 0a 2a 2a 20 54 68  ons (N).)^.** Th
13780 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
13790 20 6d 75 73 74 20 62 65 20 61 20 70 6f 69 6e 74   must be a point
137a0 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20  er to an 8-byte 
137b0 61 6c 69 67 6e 65 64 20 62 75 66 66 65 72 0a 2a  aligned buffer.*
137c0 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a  * of at least sz
137d0 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  *N bytes of memo
137e0 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  ry..** ^SQLite w
137f0 69 6c 6c 20 6e 6f 74 20 75 73 65 20 6d 6f 72 65  ill not use more
13800 20 74 68 61 6e 20 6f 6e 65 20 73 63 72 61 74 63   than one scratc
13810 68 20 62 75 66 66 65 72 73 20 70 65 72 20 74 68  h buffers per th
13820 72 65 61 64 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  read..** ^SQLite
13830 20 77 69 6c 6c 20 6e 65 76 65 72 20 72 65 71 75   will never requ
13840 65 73 74 20 61 20 73 63 72 61 74 63 68 20 62 75  est a scratch bu
13850 66 66 65 72 20 74 68 61 74 20 69 73 20 6d 6f 72  ffer that is mor
13860 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65  e than 6.** time
13870 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70  s the database p
13880 61 67 65 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66  age size..** ^If
13890 20 53 51 4c 69 74 65 20 6e 65 65 64 73 20 6e 65   SQLite needs ne
138a0 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  eds additional.*
138b0 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79  * scratch memory
138c0 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20   beyond what is 
138d0 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73  provided by this
138e0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
138f0 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20  ption, then .** 
13900 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
13910 29 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20  )] will be used 
13920 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65  to obtain the me
13930 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c 70 3e 0a  mory needed.<p>.
13940 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 61 70 70  ** ^When the app
13950 6c 69 63 61 74 69 6f 6e 20 70 72 6f 76 69 64 65  lication provide
13960 73 20 61 6e 79 20 61 6d 6f 75 6e 74 20 6f 66 20  s any amount of 
13970 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 75  scratch memory u
13980 73 69 6e 67 0a 2a 2a 20 53 51 4c 49 54 45 5f 43  sing.** SQLITE_C
13990 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 2c 20 53  ONFIG_SCRATCH, S
139a0 51 4c 69 74 65 20 61 76 6f 69 64 73 20 75 6e 6e  QLite avoids unn
139b0 65 63 65 73 73 61 72 79 20 6c 61 72 67 65 0a 2a  ecessary large.*
139c0 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
139d0 63 7c 68 65 61 70 20 61 6c 6c 6f 63 61 74 69 6f  c|heap allocatio
139e0 6e 73 5d 2e 0a 2a 2a 20 54 68 69 73 20 63 61 6e  ns]..** This can
139f0 20 68 65 6c 70 20 5b 52 6f 62 73 6f 6e 20 70 72   help [Robson pr
13a00 6f 6f 66 7c 70 72 65 76 65 6e 74 20 6d 65 6d 6f  oof|prevent memo
13a10 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
13a20 69 6c 75 72 65 73 5d 20 64 75 65 20 74 6f 20 68  ilures] due to h
13a30 65 61 70 0a 2a 2a 20 66 72 61 67 6d 65 6e 74 61  eap.** fragmenta
13a40 74 69 6f 6e 20 69 6e 20 6c 6f 77 2d 6d 65 6d 6f  tion in low-memo
13a50 72 79 20 65 6d 62 65 64 64 65 64 20 73 79 73 74  ry embedded syst
13a60 65 6d 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ems..** </dd>.**
13a70 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
13a80 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 5d 20  FIG_PAGECACHE]] 
13a90 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
13aa0 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e  G_PAGECACHE</dt>
13ab0 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51  .** <dd> ^The SQ
13ac0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
13ad0 43 41 43 48 45 20 6f 70 74 69 6f 6e 20 73 70 65  CACHE option spe
13ae0 63 69 66 69 65 73 20 61 20 6d 65 6d 6f 72 79 20  cifies a memory 
13af0 70 6f 6f 6c 0a 2a 2a 20 74 68 61 74 20 53 51 4c  pool.** that SQL
13b00 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 20  ite can use for 
13b10 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67  the database pag
13b20 65 20 63 61 63 68 65 20 77 69 74 68 20 74 68 65  e cache with the
13b30 20 64 65 66 61 75 6c 74 20 70 61 67 65 0a 2a 2a   default page.**
13b40 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74   cache implement
13b50 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73  ation.  .** This
13b60 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
13b70 70 74 69 6f 6e 20 69 73 20 61 20 6e 6f 2d 6f 70  ption is a no-op
13b80 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69   if an applicati
13b90 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67 65 0a 2a  on-define page.*
13ba0 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  * cache implemen
13bb0 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64  tation is loaded
13bc0 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49   using the [SQLI
13bd0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
13be0 32 5d 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72  2]..** ^There ar
13bf0 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
13c00 73 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46  s to SQLITE_CONF
13c10 49 47 5f 50 41 47 45 43 41 43 48 45 3a 20 41 20  IG_PAGECACHE: A 
13c20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 38 2d  pointer to.** 8-
13c30 62 79 74 65 20 61 6c 69 67 6e 65 64 20 6d 65 6d  byte aligned mem
13c40 6f 72 79 20 28 70 4d 65 6d 29 2c 20 74 68 65 20  ory (pMem), the 
13c50 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67  size of each pag
13c60 65 20 63 61 63 68 65 20 6c 69 6e 65 20 28 73 7a  e cache line (sz
13c70 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6e 75  ),.** and the nu
13c80 6d 62 65 72 20 6f 66 20 63 61 63 68 65 20 6c 69  mber of cache li
13c90 6e 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20  nes (N)..** The 
13ca0 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  sz argument shou
13cb0 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f  ld be the size o
13cc0 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 61  f the largest da
13cd0 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28  tabase page.** (
13ce0 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62  a power of two b
13cf0 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20 36  etween 512 and 6
13d00 35 35 33 36 29 20 70 6c 75 73 20 73 6f 6d 65 20  5536) plus some 
13d10 65 78 74 72 61 20 62 79 74 65 73 20 66 6f 72 20  extra bytes for 
13d20 65 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61  each.** page hea
13d30 64 65 72 2e 20 20 5e 54 68 65 20 6e 75 6d 62 65  der.  ^The numbe
13d40 72 20 6f 66 20 65 78 74 72 61 20 62 79 74 65 73  r of extra bytes
13d50 20 6e 65 65 64 65 64 20 62 79 20 74 68 65 20 70   needed by the p
13d60 61 67 65 20 68 65 61 64 65 72 0a 2a 2a 20 63 61  age header.** ca
13d70 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20  n be determined 
13d80 75 73 69 6e 67 20 5b 53 51 4c 49 54 45 5f 43 4f  using [SQLITE_CO
13d90 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53  NFIG_PCACHE_HDRS
13da0 5a 5d 2e 0a 2a 2a 20 5e 49 74 20 69 73 20 68 61  Z]..** ^It is ha
13db0 72 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 66 72  rmless, apart fr
13dc0 6f 6d 20 74 68 65 20 77 61 73 74 65 64 20 6d 65  om the wasted me
13dd0 6d 6f 72 79 2c 0a 2a 2a 20 66 6f 72 20 74 68 65  mory,.** for the
13de0 20 73 7a 20 70 61 72 61 6d 65 74 65 72 20 74 6f   sz parameter to
13df0 20 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20   be larger than 
13e00 6e 65 63 65 73 73 61 72 79 2e 20 20 54 68 65 20  necessary.  The 
13e10 70 4d 65 6d 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  pMem.** argument
13e20 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
13e30 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f  a NULL pointer o
13e40 72 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  r a pointer to a
13e50 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67  n 8-byte.** alig
13e60 6e 65 64 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d  ned block of mem
13e70 6f 72 79 20 6f 66 20 61 74 20 6c 65 61 73 74 20  ory of at least 
13e80 73 7a 2a 4e 20 62 79 74 65 73 2c 20 6f 74 68 65  sz*N bytes, othe
13e90 72 77 69 73 65 0a 2a 2a 20 73 75 62 73 65 71 75  rwise.** subsequ
13ea0 65 6e 74 20 62 65 68 61 76 69 6f 72 20 69 73 20  ent behavior is 
13eb0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 57  undefined..** ^W
13ec0 68 65 6e 20 70 4d 65 6d 20 69 73 20 6e 6f 74 20  hen pMem is not 
13ed0 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c  NULL, SQLite wil
13ee0 6c 20 73 74 72 69 76 65 20 74 6f 20 75 73 65 20  l strive to use 
13ef0 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69  the memory provi
13f00 64 65 64 0a 2a 2a 20 74 6f 20 73 61 74 69 73 66  ded.** to satisf
13f10 79 20 70 61 67 65 20 63 61 63 68 65 20 6e 65 65  y page cache nee
13f20 64 73 2c 20 66 61 6c 6c 69 6e 67 20 62 61 63 6b  ds, falling back
13f30 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   to [sqlite3_mal
13f40 6c 6f 63 28 29 5d 20 69 66 0a 2a 2a 20 61 20 70  loc()] if.** a p
13f50 61 67 65 20 63 61 63 68 65 20 6c 69 6e 65 20 69  age cache line i
13f60 73 20 6c 61 72 67 65 72 20 74 68 61 6e 20 73 7a  s larger than sz
13f70 20 62 79 74 65 73 20 6f 72 20 69 66 20 61 6c 6c   bytes or if all
13f80 20 6f 66 20 74 68 65 20 70 4d 65 6d 20 62 75 66   of the pMem buf
13f90 66 65 72 0a 2a 2a 20 69 73 20 65 78 68 61 75 73  fer.** is exhaus
13fa0 74 65 64 2e 0a 2a 2a 20 5e 49 66 20 70 4d 65 6d  ted..** ^If pMem
13fb0 20 69 73 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69   is NULL and N i
13fc0 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  s non-zero, then
13fd0 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63   each database c
13fe0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 64 6f 65  onnection.** doe
13ff0 73 20 61 6e 20 69 6e 69 74 69 61 6c 20 62 75 6c  s an initial bul
14000 6b 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72  k allocation for
14010 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f   page cache memo
14020 72 79 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  ry.** from [sqli
14030 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 73 75  te3_malloc()] su
14040 66 66 69 63 69 65 6e 74 20 66 6f 72 20 4e 20 63  fficient for N c
14050 61 63 68 65 20 6c 69 6e 65 73 20 69 66 20 4e 20  ache lines if N 
14060 69 73 20 70 6f 73 69 74 69 76 65 20 6f 72 0a 2a  is positive or.*
14070 2a 20 6f 66 20 2d 31 30 32 34 2a 4e 20 62 79 74  * of -1024*N byt
14080 65 73 20 69 66 20 4e 20 69 73 20 6e 65 67 61 74  es if N is negat
14090 69 76 65 2c 20 2e 20 5e 49 66 20 61 64 64 69 74  ive, . ^If addit
140a0 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61  ional.** page ca
140b0 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65  che memory is ne
140c0 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74  eded beyond what
140d0 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20   is provided by 
140e0 74 68 65 20 69 6e 69 74 69 61 6c 0a 2a 2a 20 61  the initial.** a
140f0 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20  llocation, then 
14100 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b  SQLite goes to [
14110 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
14120 5d 20 73 65 70 61 72 61 74 65 6c 79 20 66 6f 72  ] separately for
14130 20 65 61 63 68 0a 2a 2a 20 61 64 64 69 74 69 6f   each.** additio
14140 6e 61 6c 20 63 61 63 68 65 20 6c 69 6e 65 2e 20  nal cache line. 
14150 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
14160 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
14170 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
14180 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a  NFIG_HEAP</dt>.*
14190 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49  * <dd> ^The SQLI
141a0 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f  TE_CONFIG_HEAP o
141b0 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20  ption specifies 
141c0 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20  a static memory 
141d0 62 75 66 66 65 72 20 0a 2a 2a 20 74 68 61 74 20  buffer .** that 
141e0 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
141f0 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64  for all of its d
14200 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c  ynamic memory al
14210 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 0a 2a  location needs.*
14220 2a 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70  * beyond those p
14230 72 6f 76 69 64 65 64 20 66 6f 72 20 62 79 20 5b  rovided for by [
14240 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
14250 52 41 54 43 48 5d 20 61 6e 64 0a 2a 2a 20 5b 53  RATCH] and.** [S
14260 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
14270 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 5e 54 68 65  ECACHE]..** ^The
14280 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48   SQLITE_CONFIG_H
14290 45 41 50 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e  EAP option is on
142a0 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20  ly available if 
142b0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
142c0 65 64 0a 2a 2a 20 77 69 74 68 20 65 69 74 68 65  ed.** with eithe
142d0 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  r [SQLITE_ENABLE
142e0 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 20 5b 53 51  _MEMSYS3] or [SQ
142f0 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53  LITE_ENABLE_MEMS
14300 59 53 35 5d 20 61 6e 64 20 72 65 74 75 72 6e 73  YS5] and returns
14310 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  .** [SQLITE_ERRO
14320 52 5d 20 69 66 20 69 6e 76 6f 6b 65 64 20 6f 74  R] if invoked ot
14330 68 65 72 77 69 73 65 2e 0a 2a 2a 20 5e 54 68 65  herwise..** ^The
14340 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67  re are three arg
14350 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54 45  uments to SQLITE
14360 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3a 0a 2a 2a  _CONFIG_HEAP:.**
14370 20 41 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e   An 8-byte align
14380 65 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68  ed pointer to th
14390 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65  e memory,.** the
143a0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
143b0 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 62   in the memory b
143c0 75 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20 6d  uffer, and the m
143d0 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f  inimum allocatio
143e0 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74  n size..** ^If t
143f0 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72  he first pointer
14400 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69   (the memory poi
14410 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74  nter) is NULL, t
14420 68 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65 72  hen SQLite rever
14430 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69  ts.** to using i
14440 74 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72  ts default memor
14450 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65  y allocator (the
14460 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29   system malloc()
14470 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29   implementation)
14480 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79  ,.** undoing any
14490 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f   prior invocatio
144a0 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  n of [SQLITE_CON
144b0 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49  FIG_MALLOC].  ^I
144c0 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  f the.** memory 
144d0 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e  pointer is not N
144e0 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 61 6c 74  ULL then the alt
144f0 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a  ernative memory.
14500 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20  ** allocator is 
14510 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64 6c  engaged to handl
14520 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73  e all of SQLites
14530 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
14540 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65  on needs..** The
14550 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28   first pointer (
14560 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74  the memory point
14570 65 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69 67  er) must be alig
14580 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ned to an 8-byte
14590 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72 20  .** boundary or 
145a0 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76  subsequent behav
145b0 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77 69  ior of SQLite wi
145c0 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e  ll be undefined.
145d0 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20  .** The minimum 
145e0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20  allocation size 
145f0 69 73 20 63 61 70 70 65 64 20 61 74 20 32 2a 2a  is capped at 2**
14600 31 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20 76  12. Reasonable v
14610 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65  alues.** for the
14620 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74   minimum allocat
14630 69 6f 6e 20 73 69 7a 65 20 61 72 65 20 32 2a 2a  ion size are 2**
14640 35 20 74 68 72 6f 75 67 68 20 32 2a 2a 38 2e 3c  5 through 2**8.<
14650 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
14660 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
14670 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
14680 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a  NFIG_MUTEX</dt>.
14690 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51  ** <dd> ^(The SQ
146a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
146b0 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  X option takes a
146c0 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
146d0 20 77 68 69 63 68 20 69 73 20 61 0a 2a 2a 20 70   which is a.** p
146e0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
146f0 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
14700 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
14710 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a  ods] structure..
14720 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  ** The argument 
14730 73 70 65 63 69 66 69 65 73 20 61 6c 74 65 72 6e  specifies altern
14740 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20  ative low-level 
14750 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74  mutex routines t
14760 6f 20 62 65 20 75 73 65 64 0a 2a 2a 20 69 6e 20  o be used.** in 
14770 70 6c 61 63 65 20 74 68 65 20 6d 75 74 65 78 20  place the mutex 
14780 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69  routines built i
14790 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e  nto SQLite.)^  ^
147a0 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63  SQLite makes a c
147b0 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f  opy of.** the co
147c0 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71  ntent of the [sq
147d0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
147e0 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 20 62  ods] structure b
147f0 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74  efore the call t
14800 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
14810 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e  nfig()] returns.
14820 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
14830 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
14840 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
14850 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
14860 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
14870 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
14880 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e  n then.** the en
14890 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75  tire mutexing su
148a0 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74  bsystem is omitt
148b0 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c  ed from the buil
148c0 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c  d and hence call
148d0 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s to.** [sqlite3
148e0 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20  _config()] with 
148f0 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  the SQLITE_CONFI
14900 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72  G_MUTEX configur
14910 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c  ation option wil
14920 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  l.** return [SQL
14930 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e  ITE_ERROR].</dd>
14940 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
14950 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 5d  CONFIG_GETMUTEX]
14960 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
14970 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74  FIG_GETMUTEX</dt
14980 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20  >.** <dd> ^(The 
14990 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
149a0 54 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74 61  TMUTEX option ta
149b0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
149c0 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69  ument which.** i
149d0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
149e0 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
149f0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
14a00 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
14a10 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71  ure.  The.** [sq
14a20 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
14a30 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72  ods].** structur
14a40 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68  e is filled with
14a50 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64   the currently d
14a60 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75  efined mutex rou
14a70 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73  tines.)^.** This
14a80 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75   option can be u
14a90 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20  sed to overload 
14aa0 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65  the default mute
14ab0 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  x allocation.** 
14ac0 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20  routines with a 
14ad0 77 72 61 70 70 65 72 20 75 73 65 64 20 74 6f 20  wrapper used to 
14ae0 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67  track mutex usag
14af0 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63  e for performanc
14b00 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f  e.** profiling o
14b10 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65  r testing, for e
14b20 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53 51  xample.   ^If SQ
14b30 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
14b40 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
14b50 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
14b60 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
14b70 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
14b80 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
14b90 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75  ** the entire mu
14ba0 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d  texing subsystem
14bb0 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   is omitted from
14bc0 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68   the build and h
14bd0 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  ence calls to.**
14be0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
14bf0 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c  ()] with the SQL
14c00 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
14c10 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  TEX configuratio
14c20 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a  n option will.**
14c30 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
14c40 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a  ERROR].</dd>.**.
14c50 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
14c60 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c  IG_LOOKASIDE]] <
14c70 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
14c80 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a  _LOOKASIDE</dt>.
14c90 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51  ** <dd> ^(The SQ
14ca0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
14cb0 41 53 49 44 45 20 6f 70 74 69 6f 6e 20 74 61 6b  ASIDE option tak
14cc0 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73  es two arguments
14cd0 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 0a   that determine.
14ce0 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 20 73  ** the default s
14cf0 69 7a 65 20 6f 66 20 6c 6f 6f 6b 61 73 69 64 65  ize of lookaside
14d00 20 6d 65 6d 6f 72 79 20 6f 6e 20 65 61 63 68 20   memory on each 
14d10 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
14d20 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66 69  tion]..** The fi
14d30 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
14d40 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65  the.** size of e
14d50 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75  ach lookaside bu
14d60 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68  ffer slot and th
14d70 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20  e second is the 
14d80 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f  number of.** slo
14d90 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20  ts allocated to 
14da0 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f  each database co
14db0 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 53  nnection.)^  ^(S
14dc0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
14dd0 4b 41 53 49 44 45 0a 2a 2a 20 73 65 74 73 20 74  KASIDE.** sets t
14de0 68 65 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69  he <i>default</i
14df0 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65  > lookaside size
14e00 2e 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 42  . The [SQLITE_DB
14e10 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
14e20 5d 0a 2a 2a 20 6f 70 74 69 6f 6e 20 74 6f 20 5b  ].** option to [
14e30 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
14e40 67 28 29 5d 20 63 61 6e 20 62 65 20 75 73 65 64  g()] can be used
14e50 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c   to change the l
14e60 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66  ookaside.** conf
14e70 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64  iguration on ind
14e80 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69  ividual connecti
14e90 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a  ons.)^ </dd>.**.
14ea0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
14eb0 49 47 5f 50 43 41 43 48 45 32 5d 5d 20 3c 64 74  IG_PCACHE2]] <dt
14ec0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
14ed0 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c  CACHE2</dt>.** <
14ee0 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45  dd> ^(The SQLITE
14ef0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20  _CONFIG_PCACHE2 
14f00 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
14f10 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
14f20 68 69 63 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f  hich is .** a po
14f30 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c  inter to an [sql
14f40 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
14f50 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 54  ods2] object.  T
14f60 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63 69  his object speci
14f70 66 69 65 73 0a 2a 2a 20 74 68 65 20 69 6e 74 65  fies.** the inte
14f80 72 66 61 63 65 20 74 6f 20 61 20 63 75 73 74 6f  rface to a custo
14f90 6d 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70  m page cache imp
14fa0 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 0a 2a  lementation.)^.*
14fb0 2a 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20  * ^SQLite makes 
14fc0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73  a copy of the [s
14fd0 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
14fe0 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 3c  thods2] object.<
14ff0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
15000 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
15010 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49  ACHE2]] <dt>SQLI
15020 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
15030 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  CHE2</dt>.** <dd
15040 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43  > ^(The SQLITE_C
15050 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32  ONFIG_GETPCACHE2
15060 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
15070 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
15080 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f  which.** is a po
15090 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c  inter to an [sql
150a0 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
150b0 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 53  ods2] object.  S
150c0 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66 0a  QLite copies of.
150d0 2a 2a 20 74 68 65 20 63 75 72 72 65 6e 74 20 70  ** the current p
150e0 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  age cache implem
150f0 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68  entation into th
15100 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64  at object.)^ </d
15110 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
15120 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c  E_CONFIG_LOG]] <
15130 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
15140 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  _LOG</dt>.** <dd
15150 3e 20 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  > The SQLITE_CON
15160 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 69  FIG_LOG option i
15170 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67  s used to config
15180 75 72 65 20 74 68 65 20 53 51 4c 69 74 65 0a 2a  ure the SQLite.*
15190 2a 20 67 6c 6f 62 61 6c 20 5b 65 72 72 6f 72 20  * global [error 
151a0 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 68 65 20 53  log]..** (^The S
151b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
151c0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77   option takes tw
151d0 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 20 70  o arguments: a p
151e0 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20 66  ointer to a.** f
151f0 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 63  unction with a c
15200 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 6f 66  all signature of
15210 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 69   void(*)(void*,i
15220 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  nt,const char*),
15230 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e 74   .** and a point
15240 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66 20  er to void. ^If 
15250 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69  the function poi
15260 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  nter is not NULL
15270 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b  , it is.** invok
15280 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c  ed by [sqlite3_l
15290 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 73 73  og()] to process
152a0 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 65 76   each logging ev
152b0 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  ent.  ^If the.**
152c0 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65   function pointe
152d0 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20 5b  r is NULL, the [
152e0 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 69  sqlite3_log()] i
152f0 6e 74 65 72 66 61 63 65 20 62 65 63 6f 6d 65 73  nterface becomes
15300 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68   a no-op..** ^Th
15310 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 74  e void pointer t
15320 68 61 74 20 69 73 20 74 68 65 20 73 65 63 6f 6e  hat is the secon
15330 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 53 51  d argument to SQ
15340 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
15350 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68 72  is.** passed thr
15360 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72 73  ough as the firs
15370 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  t parameter to t
15380 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
15390 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a  efined logger.**
153a0 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65 76   function whenev
153b0 65 72 20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e  er that function
153c0 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 54   is invoked.  ^T
153d0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
153e0 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f  ter to.** the lo
153f0 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 69 73  gger function is
15400 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66   a copy of the f
15410 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
15420 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  o the correspond
15430 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
15440 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64 20  log()] call and 
15450 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 62  is intended to b
15460 65 20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  e a [result code
15470 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74 65  ] or an.** [exte
15480 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
15490 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 70  ].  ^The third p
154a0 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64 20  arameter passed 
154b0 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 69 73  to the logger is
154c0 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65 20  .** log message 
154d0 61 66 74 65 72 20 66 6f 72 6d 61 74 74 69 6e 67  after formatting
154e0 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 73 6e   via [sqlite3_sn
154f0 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54 68  printf()]..** Th
15500 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e 67  e SQLite logging
15510 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f   interface is no
15520 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 68 65  t reentrant; the
15530 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e   logger function
15540 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 79 20  .** supplied by 
15550 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
15560 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65 20  must not invoke 
15570 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72  any SQLite inter
15580 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75  face..** In a mu
15590 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61 70 70  lti-threaded app
155a0 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 61 70  lication, the ap
155b0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
155c0 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63  d logger.** func
155d0 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 68 72  tion must be thr
155e0 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a  eadsafe. </dd>.*
155f0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
15600 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e 53  NFIG_URI]] <dt>S
15610 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
15620 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 65 20 53 51  .** <dd>^(The SQ
15630 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20  LITE_CONFIG_URI 
15640 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
15650 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f  ingle argument o
15660 66 20 74 79 70 65 20 69 6e 74 2e 0a 2a 2a 20 49  f type int..** I
15670 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  f non-zero, then
15680 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73   URI handling is
15690 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65   globally enable
156a0 64 2e 20 49 66 20 74 68 65 20 70 61 72 61 6d 65  d. If the parame
156b0 74 65 72 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a 20  ter is zero,.** 
156c0 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e  then URI handlin
156d0 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69  g is globally di
156e0 73 61 62 6c 65 64 2e 29 5e 20 5e 49 66 20 55 52  sabled.)^ ^If UR
156f0 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c  I handling is gl
15700 6f 62 61 6c 6c 79 0a 2a 2a 20 65 6e 61 62 6c 65  obally.** enable
15710 64 2c 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73  d, all filenames
15720 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69   passed to [sqli
15730 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
15740 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
15750 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ,.** [sqlite3_op
15760 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70  en16()] or.** sp
15770 65 63 69 66 69 65 64 20 61 73 20 70 61 72 74 20  ecified as part 
15780 6f 66 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d  of [ATTACH] comm
15790 61 6e 64 73 20 61 72 65 20 69 6e 74 65 72 70 72  ands are interpr
157a0 65 74 65 64 20 61 73 20 55 52 49 73 2c 20 72 65  eted as URIs, re
157b0 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77  gardless.** of w
157c0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
157d0 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  e [SQLITE_OPEN_U
157e0 52 49 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20  RI] flag is set 
157f0 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  when the databas
15800 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
15810 69 73 20 6f 70 65 6e 65 64 2e 20 5e 49 66 20 69  is opened. ^If i
15820 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69  t is globally di
15830 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65  sabled, filename
15840 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e  s are.** only in
15850 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49  terpreted as URI
15860 73 20 69 66 20 74 68 65 20 53 51 4c 49 54 45 5f  s if the SQLITE_
15870 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67 20 69 73  OPEN_URI flag is
15880 20 73 65 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a   set when the.**
15890 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
158a0 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20  tion is opened. 
158b0 5e 28 42 79 20 64 65 66 61 75 6c 74 2c 20 55 52  ^(By default, UR
158c0 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c  I handling is gl
158d0 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c  obally.** disabl
158e0 65 64 2e 20 54 68 65 20 64 65 66 61 75 6c 74 20  ed. The default 
158f0 76 61 6c 75 65 20 6d 61 79 20 62 65 20 63 68 61  value may be cha
15900 6e 67 65 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e  nged by compilin
15910 67 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53  g with the.** [S
15920 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 73  QLITE_USE_URI] s
15930 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 29 5e  ymbol defined.)^
15940 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
15950 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f  CONFIG_COVERING_
15960 49 4e 44 45 58 5f 53 43 41 4e 5d 5d 20 3c 64 74  INDEX_SCAN]] <dt
15970 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43  >SQLITE_CONFIG_C
15980 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43  OVERING_INDEX_SC
15990 41 4e 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53  AN.** <dd>^The S
159a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56  QLITE_CONFIG_COV
159b0 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e  ERING_INDEX_SCAN
159c0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
159d0 73 69 6e 67 6c 65 20 69 6e 74 65 67 65 72 0a 2a  single integer.*
159e0 2a 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  * argument which
159f0 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
15a00 61 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 20  as a boolean in 
15a10 6f 72 64 65 72 20 74 6f 20 65 6e 61 62 6c 65 20  order to enable 
15a20 6f 72 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68  or disable.** th
15a30 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e  e use of coverin
15a40 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20 66 75  g indices for fu
15a50 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 20 69  ll table scans i
15a60 6e 20 74 68 65 20 71 75 65 72 79 20 6f 70 74 69  n the query opti
15a70 6d 69 7a 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 64  mizer..** ^The d
15a80 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 69  efault setting i
15a90 73 20 64 65 74 65 72 6d 69 6e 65 64 0a 2a 2a 20  s determined.** 
15aa0 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 41  by the [SQLITE_A
15ab0 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e 47 5f 49 4e  LLOW_COVERING_IN
15ac0 44 45 58 5f 53 43 41 4e 5d 20 63 6f 6d 70 69 6c  DEX_SCAN] compil
15ad0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 6f  e-time option, o
15ae0 72 20 69 73 20 22 6f 6e 22 0a 2a 2a 20 69 66 20  r is "on".** if 
15af0 74 68 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  that compile-tim
15b00 65 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6d 69 74  e option is omit
15b10 74 65 64 2e 0a 2a 2a 20 54 68 65 20 61 62 69 6c  ted..** The abil
15b20 69 74 79 20 74 6f 20 64 69 73 61 62 6c 65 20 74  ity to disable t
15b30 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69  he use of coveri
15b40 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20 66  ng indices for f
15b50 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 0a  ull table scans.
15b60 2a 2a 20 69 73 20 62 65 63 61 75 73 65 20 73 6f  ** is because so
15b70 6d 65 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 63  me incorrectly c
15b80 6f 64 65 64 20 6c 65 67 61 63 79 20 61 70 70 6c  oded legacy appl
15b90 69 63 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6d  ications might m
15ba0 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 68  alfunction.** wh
15bb0 65 6e 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74  en the optimizat
15bc0 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 20  ion is enabled. 
15bd0 20 50 72 6f 76 69 64 69 6e 67 20 74 68 65 20 61   Providing the a
15be0 62 69 6c 69 74 79 20 74 6f 0a 2a 2a 20 64 69 73  bility to.** dis
15bf0 61 62 6c 65 20 74 68 65 20 6f 70 74 69 6d 69 7a  able the optimiz
15c00 61 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 74 68 65  ation allows the
15c10 20 6f 6c 64 65 72 2c 20 62 75 67 67 79 20 61 70   older, buggy ap
15c20 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 74  plication code t
15c30 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f 75  o work.** withou
15c40 74 20 63 68 61 6e 67 65 20 65 76 65 6e 20 77 69  t change even wi
15c50 74 68 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e  th newer version
15c60 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a  s of SQLite..**.
15c70 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
15c80 49 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53 51  IG_PCACHE]] [[SQ
15c90 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
15ca0 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  CACHE]].** <dt>S
15cb0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
15cc0 43 48 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 43  CHE and SQLITE_C
15cd0 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 0a  ONFIG_GETPCACHE.
15ce0 2a 2a 20 3c 64 64 3e 20 54 68 65 73 65 20 6f 70  ** <dd> These op
15cf0 74 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c 65  tions are obsole
15d00 74 65 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f  te and should no
15d10 74 20 62 65 20 75 73 65 64 20 62 79 20 6e 65 77  t be used by new
15d20 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20 61   code..** They a
15d30 72 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20  re retained for 
15d40 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
15d50 69 62 69 6c 69 74 79 20 62 75 74 20 61 72 65 20  ibility but are 
15d60 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c  now no-ops..** <
15d70 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
15d80 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f  ITE_CONFIG_SQLLO
15d90 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  G]].** <dt>SQLIT
15da0 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 0a  E_CONFIG_SQLLOG.
15db0 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69  ** <dd>This opti
15dc0 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c  on is only avail
15dd0 61 62 6c 65 20 69 66 20 73 71 6c 69 74 65 20 69  able if sqlite i
15de0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
15df0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  the.** [SQLITE_E
15e00 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70 72  NABLE_SQLLOG] pr
15e10 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  e-processor macr
15e20 6f 20 64 65 66 69 6e 65 64 2e 20 54 68 65 20 66  o defined. The f
15e30 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 73 68  irst argument sh
15e40 6f 75 6c 64 0a 2a 2a 20 62 65 20 61 20 70 6f 69  ould.** be a poi
15e50 6e 74 65 72 20 74 6f 20 61 20 66 75 6e 63 74 69  nter to a functi
15e60 6f 6e 20 6f 66 20 74 79 70 65 20 76 6f 69 64 28  on of type void(
15e70 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
15e80 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69  *,const char*, i
15e90 6e 74 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f  nt)..** The seco
15ea0 6e 64 20 73 68 6f 75 6c 64 20 62 65 20 6f 66 20  nd should be of 
15eb0 74 79 70 65 20 28 76 6f 69 64 2a 29 2e 20 54 68  type (void*). Th
15ec0 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  e callback is in
15ed0 76 6f 6b 65 64 20 62 79 20 74 68 65 20 6c 69 62  voked by the lib
15ee0 72 61 72 79 0a 2a 2a 20 69 6e 20 74 68 72 65 65  rary.** in three
15ef0 20 73 65 70 61 72 61 74 65 20 63 69 72 63 75 6d   separate circum
15f00 73 74 61 6e 63 65 73 2c 20 69 64 65 6e 74 69 66  stances, identif
15f10 69 65 64 20 62 79 20 74 68 65 20 76 61 6c 75 65  ied by the value
15f20 20 70 61 73 73 65 64 20 61 73 20 74 68 65 0a 2a   passed as the.*
15f30 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  * fourth paramet
15f40 65 72 2e 20 49 66 20 74 68 65 20 66 6f 75 72 74  er. If the fourt
15f50 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 30  h parameter is 0
15f60 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
15f70 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
15f80 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  * passed as the 
15f90 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
15fa0 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 6f 70  has just been op
15fb0 65 6e 65 64 2e 20 54 68 65 20 74 68 69 72 64 20  ened. The third 
15fc0 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69 6e  argument.** poin
15fd0 74 73 20 74 6f 20 61 20 62 75 66 66 65 72 20 63  ts to a buffer c
15fe0 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 61  ontaining the na
15ff0 6d 65 20 6f 66 20 74 68 65 20 6d 61 69 6e 20 64  me of the main d
16000 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20 49 66  atabase file. If
16010 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70   the.** fourth p
16020 61 72 61 6d 65 74 65 72 20 69 73 20 31 2c 20 74  arameter is 1, t
16030 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74  hen the SQL stat
16040 65 6d 65 6e 74 20 74 68 61 74 20 74 68 65 20 74  ement that the t
16050 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 0a 2a  hird parameter.*
16060 2a 20 70 6f 69 6e 74 73 20 74 6f 20 68 61 73 20  * points to has 
16070 6a 75 73 74 20 62 65 65 6e 20 65 78 65 63 75 74  just been execut
16080 65 64 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 66  ed. Or, if the f
16090 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
160a0 69 73 20 32 2c 20 74 68 65 6e 0a 2a 2a 20 74 68  is 2, then.** th
160b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 69  e connection bei
160c0 6e 67 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ng passed as the
160d0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
160e0 72 20 69 73 20 62 65 69 6e 67 20 63 6c 6f 73 65  r is being close
160f0 64 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64 20  d. The.** third 
16100 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 61 73  parameter is pas
16110 73 65 64 20 4e 55 4c 4c 20 49 6e 20 74 68 69 73  sed NULL In this
16120 20 63 61 73 65 2e 20 20 41 6e 20 65 78 61 6d 70   case.  An examp
16130 6c 65 20 6f 66 20 75 73 69 6e 67 20 74 68 69 73  le of using this
16140 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  .** configuratio
16150 6e 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  n option can be 
16160 73 65 65 6e 20 69 6e 20 74 68 65 20 22 74 65 73  seen in the "tes
16170 74 5f 73 71 6c 6c 6f 67 2e 63 22 20 73 6f 75 72  t_sqllog.c" sour
16180 63 65 20 66 69 6c 65 20 69 6e 0a 2a 2a 20 74 68  ce file in.** th
16190 65 20 63 61 6e 6f 6e 69 63 61 6c 20 53 51 4c 69  e canonical SQLi
161a0 74 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e 3c  te source tree.<
161b0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
161c0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f  ITE_CONFIG_MMAP_
161d0 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  SIZE]].** <dt>SQ
161e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50  LITE_CONFIG_MMAP
161f0 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 53 51  _SIZE.** <dd>^SQ
16200 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50  LITE_CONFIG_MMAP
16210 5f 53 49 5a 45 20 74 61 6b 65 73 20 74 77 6f 20  _SIZE takes two 
16220 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 28  64-bit integer (
16230 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 20 76  sqlite3_int64) v
16240 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 61 72  alues.** that ar
16250 65 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 6d  e the default mm
16260 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 20 28 74  ap size limit (t
16270 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69  he default setti
16280 6e 67 20 66 6f 72 0a 2a 2a 20 5b 50 52 41 47 4d  ng for.** [PRAGM
16290 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 29 20 61 6e  A mmap_size]) an
162a0 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c  d the maximum al
162b0 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 20  lowed mmap size 
162c0 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20 64  limit..** ^The d
162d0 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 63  efault setting c
162e0 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e  an be overridden
162f0 20 62 79 20 65 61 63 68 20 64 61 74 61 62 61 73   by each databas
16300 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 75 73 69  e connection usi
16310 6e 67 0a 2a 2a 20 65 69 74 68 65 72 20 74 68 65  ng.** either the
16320 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69   [PRAGMA mmap_si
16330 7a 65 5d 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72 20  ze] command, or 
16340 62 79 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  by using the.** 
16350 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d  [SQLITE_FCNTL_MM
16360 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f  AP_SIZE] file co
16370 6e 74 72 6f 6c 2e 20 20 5e 28 54 68 65 20 6d 61  ntrol.  ^(The ma
16380 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d  ximum allowed mm
16390 61 70 20 73 69 7a 65 0a 2a 2a 20 77 69 6c 6c 20  ap size.** will 
163a0 62 65 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e  be silently trun
163b0 63 61 74 65 64 20 69 66 20 6e 65 63 65 73 73 61  cated if necessa
163c0 72 79 20 73 6f 20 74 68 61 74 20 69 74 20 64 6f  ry so that it do
163d0 65 73 20 6e 6f 74 20 65 78 63 65 65 64 20 74 68  es not exceed th
163e0 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  e.** compile-tim
163f0 65 20 6d 61 78 69 6d 75 6d 20 6d 6d 61 70 20 73  e maximum mmap s
16400 69 7a 65 20 73 65 74 20 62 79 20 74 68 65 0a 2a  ize set by the.*
16410 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4d 4d  * [SQLITE_MAX_MM
16420 41 50 5f 53 49 5a 45 5d 20 63 6f 6d 70 69 6c 65  AP_SIZE] compile
16430 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 29 5e 0a  -time option.)^.
16440 2a 2a 20 5e 49 66 20 65 69 74 68 65 72 20 61 72  ** ^If either ar
16450 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 6f  gument to this o
16460 70 74 69 6f 6e 20 69 73 20 6e 65 67 61 74 69 76  ption is negativ
16470 65 2c 20 74 68 65 6e 20 74 68 61 74 20 61 72 67  e, then that arg
16480 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 63 68 61 6e  ument is.** chan
16490 67 65 64 20 74 6f 20 69 74 73 20 63 6f 6d 70 69  ged to its compi
164a0 6c 65 2d 74 69 6d 65 20 64 65 66 61 75 6c 74 2e  le-time default.
164b0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
164c0 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41  CONFIG_WIN32_HEA
164d0 50 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  PSIZE]].** <dt>S
164e0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e  QLITE_CONFIG_WIN
164f0 33 32 5f 48 45 41 50 53 49 5a 45 0a 2a 2a 20 3c  32_HEAPSIZE.** <
16500 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  dd>^The SQLITE_C
16510 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50  ONFIG_WIN32_HEAP
16520 53 49 5a 45 20 6f 70 74 69 6f 6e 20 69 73 20 6f  SIZE option is o
16530 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
16540 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f   SQLite is.** co
16550 6d 70 69 6c 65 64 20 66 6f 72 20 57 69 6e 64 6f  mpiled for Windo
16560 77 73 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c  ws with the [SQL
16570 49 54 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43  ITE_WIN32_MALLOC
16580 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20  ] pre-processor 
16590 6d 61 63 72 6f 0a 2a 2a 20 64 65 66 69 6e 65 64  macro.** defined
165a0 2e 20 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  . ^SQLITE_CONFIG
165b0 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20  _WIN32_HEAPSIZE 
165c0 74 61 6b 65 73 20 61 20 33 32 2d 62 69 74 20 75  takes a 32-bit u
165d0 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20  nsigned integer 
165e0 76 61 6c 75 65 0a 2a 2a 20 74 68 61 74 20 73 70  value.** that sp
165f0 65 63 69 66 69 65 73 20 74 68 65 20 6d 61 78 69  ecifies the maxi
16600 6d 75 6d 20 73 69 7a 65 20 6f 66 20 74 68 65 20  mum size of the 
16610 63 72 65 61 74 65 64 20 68 65 61 70 2e 0a 2a 2a  created heap..**
16620 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
16630 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a  FIG_PCACHE_HDRSZ
16640 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
16650 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48  _CONFIG_PCACHE_H
16660 44 52 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65  DRSZ.** <dd>^The
16670 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
16680 43 41 43 48 45 5f 48 44 52 53 5a 20 6f 70 74 69  CACHE_HDRSZ opti
16690 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
166a0 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63  e parameter whic
166b0 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65  h.** is a pointe
166c0 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  r to an integer 
166d0 61 6e 64 20 77 72 69 74 65 73 20 69 6e 74 6f 20  and writes into 
166e0 74 68 61 74 20 69 6e 74 65 67 65 72 20 74 68 65  that integer the
166f0 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61   number of extra
16700 0a 2a 2a 20 62 79 74 65 73 20 70 65 72 20 70 61  .** bytes per pa
16710 67 65 20 72 65 71 75 69 72 65 64 20 66 6f 72 20  ge required for 
16720 65 61 63 68 20 70 61 67 65 20 69 6e 20 5b 53 51  each page in [SQ
16730 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
16740 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 20 61  CACHE]..** The a
16750 6d 6f 75 6e 74 20 6f 66 20 65 78 74 72 61 20 73  mount of extra s
16760 70 61 63 65 20 72 65 71 75 69 72 65 64 20 63 61  pace required ca
16770 6e 20 63 68 61 6e 67 65 20 64 65 70 65 6e 64 69  n change dependi
16780 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c  ng on the compil
16790 65 72 2c 0a 2a 2a 20 74 61 72 67 65 74 20 70 6c  er,.** target pl
167a0 61 74 66 6f 72 6d 2c 20 61 6e 64 20 53 51 4c 69  atform, and SQLi
167b0 74 65 20 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a  te version..**.*
167c0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
167d0 47 5f 50 4d 41 53 5a 5d 5d 0a 2a 2a 20 3c 64 74  G_PMASZ]].** <dt
167e0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
167f0 4d 41 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65  MASZ.** <dd>^The
16800 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
16810 4d 41 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65  MASZ option take
16820 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d  s a single param
16830 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73  eter which.** is
16840 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 69 6e 74   an unsigned int
16850 65 67 65 72 20 61 6e 64 20 73 65 74 73 20 74 68  eger and sets th
16860 65 20 22 4d 69 6e 69 6d 75 6d 20 50 4d 41 20 53  e "Minimum PMA S
16870 69 7a 65 22 20 66 6f 72 20 74 68 65 20 6d 75 6c  ize" for the mul
16880 74 69 74 68 72 65 61 64 65 64 0a 2a 2a 20 73 6f  tithreaded.** so
16890 72 74 65 72 20 74 6f 20 74 68 61 74 20 69 6e 74  rter to that int
168a0 65 67 65 72 2e 20 20 54 68 65 20 64 65 66 61 75  eger.  The defau
168b0 6c 74 20 6d 69 6e 69 6d 75 6d 20 50 4d 41 20 53  lt minimum PMA S
168c0 69 7a 65 20 69 73 20 73 65 74 20 62 79 20 74 68  ize is set by th
168d0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 52  e.** [SQLITE_SOR
168e0 54 45 52 5f 50 4d 41 53 5a 5d 20 63 6f 6d 70 69  TER_PMASZ] compi
168f0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 20  le-time option. 
16900 20 4e 65 77 20 74 68 72 65 61 64 73 20 61 72 65   New threads are
16910 20 6c 61 75 6e 63 68 65 64 0a 2a 2a 20 74 6f 20   launched.** to 
16920 68 65 6c 70 20 77 69 74 68 20 73 6f 72 74 20 6f  help with sort o
16930 70 65 72 61 74 69 6f 6e 73 20 77 68 65 6e 20 6d  perations when m
16940 75 6c 74 69 74 68 72 65 61 64 65 64 20 73 6f 72  ultithreaded sor
16950 74 69 6e 67 0a 2a 2a 20 69 73 20 65 6e 61 62 6c  ting.** is enabl
16960 65 64 20 28 75 73 69 6e 67 20 74 68 65 20 5b 50  ed (using the [P
16970 52 41 47 4d 41 20 74 68 72 65 61 64 73 5d 20 63  RAGMA threads] c
16980 6f 6d 6d 61 6e 64 29 20 61 6e 64 20 74 68 65 20  ommand) and the 
16990 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 74 65 6e  amount of conten
169a0 74 0a 2a 2a 20 74 6f 20 62 65 20 73 6f 72 74 65  t.** to be sorte
169b0 64 20 65 78 63 65 65 64 73 20 74 68 65 20 70 61  d exceeds the pa
169c0 67 65 20 73 69 7a 65 20 74 69 6d 65 73 20 74 68  ge size times th
169d0 65 20 6d 69 6e 69 6d 75 6d 20 6f 66 20 74 68 65  e minimum of the
169e0 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 63 61 63 68  .** [PRAGMA cach
169f0 65 5f 73 69 7a 65 5d 20 73 65 74 74 69 6e 67 20  e_size] setting 
16a00 61 6e 64 20 74 68 69 73 20 76 61 6c 75 65 2e 0a  and this value..
16a10 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
16a20 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53  ONFIG_STMTJRNL_S
16a30 50 49 4c 4c 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  PILL]].** <dt>SQ
16a40 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54  LITE_CONFIG_STMT
16a50 4a 52 4e 4c 5f 53 50 49 4c 4c 0a 2a 2a 20 3c 64  JRNL_SPILL.** <d
16a60 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  d>^The SQLITE_CO
16a70 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50  NFIG_STMTJRNL_SP
16a80 49 4c 4c 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  ILL option takes
16a90 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65   a single parame
16aa0 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 62 65 63  ter which.** bec
16ab0 6f 6d 65 73 20 74 68 65 20 5b 73 74 61 74 65 6d  omes the [statem
16ac0 65 6e 74 20 6a 6f 75 72 6e 61 6c 5d 20 73 70 69  ent journal] spi
16ad0 6c 6c 2d 74 6f 2d 64 69 73 6b 20 74 68 72 65 73  ll-to-disk thres
16ae0 68 6f 6c 64 2e 20 20 0a 2a 2a 20 5b 53 74 61 74  hold.  .** [Stat
16af0 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 5d 20  ement journals] 
16b00 61 72 65 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f  are held in memo
16b10 72 79 20 75 6e 74 69 6c 20 74 68 65 69 72 20 73  ry until their s
16b20 69 7a 65 20 28 69 6e 20 62 79 74 65 73 29 0a 2a  ize (in bytes).*
16b30 2a 20 65 78 63 65 65 64 73 20 74 68 69 73 20 74  * exceeds this t
16b40 68 72 65 73 68 6f 6c 64 2c 20 61 74 20 77 68 69  hreshold, at whi
16b50 63 68 20 70 6f 69 6e 74 20 74 68 65 79 20 61 72  ch point they ar
16b60 65 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73  e written to dis
16b70 6b 2e 0a 2a 2a 20 4f 72 20 69 66 20 74 68 65 20  k..** Or if the 
16b80 74 68 72 65 73 68 6f 6c 64 20 69 73 20 2d 31 2c  threshold is -1,
16b90 20 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e   statement journ
16ba0 61 6c 73 20 61 72 65 20 61 6c 77 61 79 73 20 68  als are always h
16bb0 65 6c 64 0a 2a 2a 20 65 78 63 6c 75 73 69 76 65  eld.** exclusive
16bc0 6c 79 20 69 6e 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  ly in memory..**
16bd0 20 53 69 6e 63 65 20 6d 61 6e 79 20 73 74 61 74   Since many stat
16be0 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 20 6e  ement journals n
16bf0 65 76 65 72 20 62 65 63 6f 6d 65 20 6c 61 72 67  ever become larg
16c00 65 2c 20 73 65 74 74 69 6e 67 20 74 68 65 20 73  e, setting the s
16c10 70 69 6c 6c 0a 2a 2a 20 74 68 72 65 73 68 6f 6c  pill.** threshol
16c20 64 20 74 6f 20 61 20 76 61 6c 75 65 20 73 75 63  d to a value suc
16c30 68 20 61 73 20 36 34 4b 69 42 20 63 61 6e 20 67  h as 64KiB can g
16c40 72 65 61 74 6c 79 20 72 65 64 75 63 65 20 74 68  reatly reduce th
16c50 65 20 61 6d 6f 75 6e 74 20 6f 66 0a 2a 2a 20 49  e amount of.** I
16c60 2f 4f 20 72 65 71 75 69 72 65 64 20 74 6f 20 73  /O required to s
16c70 75 70 70 6f 72 74 20 73 74 61 74 65 6d 65 6e 74  upport statement
16c80 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68   rollback..** Th
16c90 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20  e default value 
16ca0 66 6f 72 20 74 68 69 73 20 73 65 74 74 69 6e 67  for this setting
16cb0 20 69 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62   is controlled b
16cc0 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  y the.** [SQLITE
16cd0 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 5d  _STMTJRNL_SPILL]
16ce0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
16cf0 74 69 6f 6e 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  tion..** </dl>.*
16d00 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16d10 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
16d20 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20  READ  1  /* nil 
16d30 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16d40 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
16d50 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c  READ   2  /* nil
16d60 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16d70 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
16d80 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69  IZED    3  /* ni
16d90 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
16da0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
16db0 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73  C        4  /* s
16dc0 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
16dd0 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
16de0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
16df0 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a  MALLOC     5  /*
16e00 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
16e10 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
16e20 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
16e30 43 52 41 54 43 48 20 20 20 20 20 20 20 36 20 20  CRATCH       6  
16e40 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a  /* void*, int sz
16e50 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69  , int N */.#defi
16e60 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
16e70 5f 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37  _PAGECACHE     7
16e80 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20    /* void*, int 
16e90 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65  sz, int N */.#de
16ea0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16eb0 49 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20  IG_HEAP         
16ec0 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e   8  /* void*, in
16ed0 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e  t nByte, int min
16ee0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16ef0 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
16f00 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f  TUS     9  /* bo
16f10 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  olean */.#define
16f20 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
16f30 55 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20  UTEX        10  
16f40 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  /* sqlite3_mutex
16f50 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
16f60 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16f70 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20  IG_GETMUTEX     
16f80 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d  11  /* sqlite3_m
16f90 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  utex_methods* */
16fa0 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53  ./* previously S
16fb0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55  QLITE_CONFIG_CHU
16fc0 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68  NKALLOC 12 which
16fd0 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20   is now unused. 
16fe0 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  */ .#define SQLI
16ff0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
17000 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e  IDE    13  /* in
17010 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  t int */.#define
17020 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
17030 43 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20  CACHE       14  
17040 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66  /* no-op */.#def
17050 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
17060 47 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31  G_GETPCACHE    1
17070 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23  5  /* no-op */.#
17080 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
17090 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20  NFIG_LOG        
170a0 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20    16  /* xFunc, 
170b0 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  void* */.#define
170c0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55   SQLITE_CONFIG_U
170d0 52 49 20 20 20 20 20 20 20 20 20 20 31 37 20 20  RI          17  
170e0 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e  /* int */.#defin
170f0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
17100 50 43 41 43 48 45 32 20 20 20 20 20 20 31 38 20  PCACHE2      18 
17110 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63   /* sqlite3_pcac
17120 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a  he_methods2* */.
17130 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
17140 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32  ONFIG_GETPCACHE2
17150 20 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65     19  /* sqlite
17160 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
17170 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  2* */.#define SQ
17180 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45  LITE_CONFIG_COVE
17190 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20  RING_INDEX_SCAN 
171a0 32 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64  20  /* int */.#d
171b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
171c0 46 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20  FIG_SQLLOG      
171d0 20 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c   21  /* xSqllog,
171e0 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e   void* */.#defin
171f0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
17200 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20  MMAP_SIZE    22 
17210 20 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36   /* sqlite3_int6
17220 34 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  4, sqlite3_int64
17230 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
17240 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f  TE_CONFIG_WIN32_
17250 48 45 41 50 53 49 5a 45 20 20 20 20 20 20 32 33  HEAPSIZE      23
17260 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a    /* int nByte *
17270 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17280 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48  _CONFIG_PCACHE_H
17290 44 52 53 5a 20 20 20 20 20 20 20 20 32 34 20 20  DRSZ        24  
172a0 2f 2a 20 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a 23  /* int *psz */.#
172b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
172c0 4e 46 49 47 5f 50 4d 41 53 5a 20 20 20 20 20 20  NFIG_PMASZ      
172d0 20 20 20 20 20 20 20 20 20 32 35 20 20 2f 2a 20           25  /* 
172e0 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 73 7a 50  unsigned int szP
172f0 6d 61 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ma */.#define SQ
17300 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54  LITE_CONFIG_STMT
17310 4a 52 4e 4c 5f 53 50 49 4c 4c 20 20 20 20 20 20  JRNL_SPILL      
17320 32 36 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65  26  /* int nByte
17330 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
17340 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f  REF: Database Co
17350 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75  nnection Configu
17360 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a  ration Options.*
17370 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
17380 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61  ants are the ava
17390 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63  ilable integer c
173a0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
173b0 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e  ions that.** can
173c0 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
173d0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
173e0 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  t to the [sqlite
173f0 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69  3_db_config()] i
17400 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
17410 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  New configuratio
17420 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65  n options may be
17430 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
17440 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
17450 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67  ite..** Existing
17460 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
17470 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20  ptions might be 
17480 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41  discontinued.  A
17490 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
174a0 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20  hould check the 
174b0 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d  return code from
174c0 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
174d0 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73  fig()] to make s
174e0 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ure that.** the 
174f0 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54  call worked.  ^T
17500 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  he [sqlite3_db_c
17510 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
17520 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61  ce will return a
17530 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72  .** non-zero [er
17540 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64  ror code] if a d
17550 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75  iscontinued or u
17560 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69  nsupported confi
17570 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a  guration option.
17580 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a  ** is invoked..*
17590 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74  *.** <dl>.** <dt
175a0 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
175b0 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a  _LOOKASIDE</dt>.
175c0 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
175d0 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65  tion takes three
175e0 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   additional argu
175f0 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72  ments that deter
17600 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f  mine the .** [lo
17610 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61  okaside memory a
17620 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67  llocator] config
17630 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20  uration for the 
17640 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
17650 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66  tion]..** ^The f
17660 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74  irst argument (t
17670 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
17680 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64  er to [sqlite3_d
17690 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61  b_config()] is a
176a0 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  .** pointer to a
176b0 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74   memory buffer t
176c0 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73  o use for lookas
176d0 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e  ide memory..** ^
176e0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
176f0 6e 74 20 61 66 74 65 72 20 74 68 65 20 53 51 4c  nt after the SQL
17700 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
17710 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d  KASIDE verb.** m
17720 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68  ay be NULL in wh
17730 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 65 20  ich case SQLite 
17740 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68  will allocate th
17750 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62  e.** lookaside b
17760 75 66 66 65 72 20 69 74 73 65 6c 66 20 75 73 69  uffer itself usi
17770 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ng [sqlite3_mall
17780 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f  oc()]. ^The seco
17790 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
177a0 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61  he.** size of ea
177b0 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ch lookaside buf
177c0 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20  fer slot.  ^The 
177d0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
177e0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  s the number of.
177f0 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73  ** slots.  The s
17800 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65  ize of the buffe
17810 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  r in the first a
17820 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20  rgument must be 
17830 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20  greater than.** 
17840 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20  or equal to the 
17850 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73  product of the s
17860 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20  econd and third 
17870 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20  arguments.  The 
17880 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62  buffer.** must b
17890 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
178a0 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e  8-byte boundary.
178b0 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64    ^If the second
178c0 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
178d0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
178e0 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74  LOOKASIDE is not
178f0 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38   a multiple of 8
17900 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c  , it is internal
17910 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f  ly.** rounded do
17920 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73  wn to the next s
17930 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20  maller multiple 
17940 6f 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f  of 8.  ^(The loo
17950 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a  kaside memory.**
17960 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66   configuration f
17970 6f 72 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  or a database co
17980 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c  nnection can onl
17990 79 20 62 65 20 63 68 61 6e 67 65 64 20 77 68 65  y be changed whe
179a0 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63  n that.** connec
179b0 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72  tion is not curr
179c0 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b  ently using look
179d0 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72  aside memory, or
179e0 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a   in other words.
179f0 2a 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75 72  ** when the "cur
17a00 72 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75  rent value" retu
17a10 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
17a20 74 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44  te3_db_status](D
17a30 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ,[SQLITE_CONFIG_
17a40 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20  LOOKASIDE],...) 
17a50 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20  is zero..** Any 
17a60 61 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67  attempt to chang
17a70 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20  e the lookaside 
17a80 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61  memory configura
17a90 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73  tion when lookas
17aa0 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73  ide.** memory is
17ab0 20 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74   in use leaves t
17ac0 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
17ad0 20 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72   unchanged and r
17ae0 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49  eturns .** [SQLI
17af0 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e  TE_BUSY].)^</dd>
17b00 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
17b10 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
17b20 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c  E_FKEY</dt>.** <
17b30 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
17b40 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62   is used to enab
17b50 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68  le or disable th
17b60 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66  e enforcement of
17b70 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79  .** [foreign key
17b80 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20   constraints].  
17b90 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20  There should be 
17ba0 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61  two additional a
17bb0 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65  rguments..** The
17bc0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
17bd0 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  is an integer wh
17be0 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61  ich is 0 to disa
17bf0 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  ble FK enforceme
17c00 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20  nt,.** positive 
17c10 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66  to enable FK enf
17c20 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61  orcement or nega
17c30 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b  tive to leave FK
17c40 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20   enforcement.** 
17c50 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20  unchanged.  The 
17c60 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
17c70 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
17c80 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f   an integer into
17c90 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69   which.** is wri
17ca0 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69  tten 0 or 1 to i
17cb0 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20  ndicate whether 
17cc0 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69  FK enforcement i
17cd0 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66  s off or on.** f
17ce0 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61  ollowing this ca
17cf0 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ll.  The second 
17d00 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
17d10 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
17d20 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73   in.** which cas
17d30 65 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65  e the FK enforce
17d40 6d 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20  ment setting is 
17d50 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63  not reported bac
17d60 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  k. </dd>.**.** <
17d70 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
17d80 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45  IG_ENABLE_TRIGGE
17d90 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  R</dt>.** <dd> ^
17da0 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75  This option is u
17db0 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72  sed to enable or
17dc0 20 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45   disable [CREATE
17dd0 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67   TRIGGER | trigg
17de0 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73  ers]..** There s
17df0 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64  hould be two add
17e00 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74  itional argument
17e10 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  s..** The first 
17e20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69  argument is an i
17e30 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20  nteger which is 
17e40 30 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69  0 to disable tri
17e50 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69  ggers,.** positi
17e60 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69  ve to enable tri
17e70 67 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76  ggers or negativ
17e80 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73  e to leave the s
17e90 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64  etting unchanged
17ea0 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
17eb0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70  parameter is a p
17ec0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
17ed0 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a  eger into which.
17ee0 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20  ** is written 0 
17ef0 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65  or 1 to indicate
17f00 20 77 68 65 74 68 65 72 20 74 72 69 67 67 65 72   whether trigger
17f10 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f  s are disabled o
17f20 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c  r enabled.** fol
17f30 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c  lowing this call
17f40 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  .  The second pa
17f50 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61  rameter may be a
17f60 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69   NULL pointer, i
17f70 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20  n.** which case 
17f80 74 68 65 20 74 72 69 67 67 65 72 20 73 65 74 74  the trigger sett
17f90 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72  ing is not repor
17fa0 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a  ted back. </dd>.
17fb0 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
17fc0 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
17fd0 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a 45 52 3c  _FTS3_TOKENIZER<
17fe0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
17ff0 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  is option is use
18000 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64  d to enable or d
18010 69 73 61 62 6c 65 20 74 68 65 20 74 77 6f 2d 61  isable the two-a
18020 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 65 72 73 69  rgument.** versi
18030 6f 6e 20 6f 66 20 74 68 65 20 5b 66 74 73 33 5f  on of the [fts3_
18040 74 6f 6b 65 6e 69 7a 65 72 28 29 5d 20 66 75 6e  tokenizer()] fun
18050 63 74 69 6f 6e 20 77 68 69 63 68 20 69 73 20 70  ction which is p
18060 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 46  art of the.** [F
18070 54 53 33 5d 20 66 75 6c 6c 2d 74 65 78 74 20 73  TS3] full-text s
18080 65 61 72 63 68 20 65 6e 67 69 6e 65 20 65 78 74  earch engine ext
18090 65 6e 73 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65  ension..** There
180a0 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61   should be two a
180b0 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
180c0 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  nts..** The firs
180d0 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  t argument is an
180e0 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69   integer which i
180f0 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 66  s 0 to disable f
18100 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28 29 20  ts3_tokenizer() 
18110 6f 72 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74  or.** positive t
18120 6f 20 65 6e 61 62 6c 65 20 66 74 73 33 5f 74 6f  o enable fts3_to
18130 6b 65 6e 69 7a 65 72 28 29 20 6f 72 20 6e 65 67  kenizer() or neg
18140 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74  ative to leave t
18150 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 75 6e  he setting.** un
18160 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20  changed..** The 
18170 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
18180 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
18190 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f   an integer into
181a0 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69   which.** is wri
181b0 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69  tten 0 or 1 to i
181c0 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20  ndicate whether 
181d0 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 20 69  fts3_tokenizer i
181e0 73 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e  s disabled or en
181f0 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  abled.** followi
18200 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54  ng this call.  T
18210 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
18220 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c  ter may be a NUL
18230 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a  L pointer, in.**
18240 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20   which case the 
18250 6e 65 77 20 73 65 74 74 69 6e 67 20 69 73 20 6e  new setting is n
18260 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  ot reported back
18270 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  . </dd>.**.** <d
18280 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
18290 47 5f 45 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45 58  G_ENABLE_LOAD_EX
182a0 54 45 4e 53 49 4f 4e 3c 2f 64 74 3e 0a 2a 2a 20  TENSION</dt>.** 
182b0 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
182c0 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61  n is used to ena
182d0 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74  ble or disable t
182e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64  he [sqlite3_load
182f0 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 0a 2a 2a  _extension()].**
18300 20 69 6e 74 65 72 66 61 63 65 20 69 6e 64 65 70   interface indep
18310 65 6e 64 65 6e 74 6c 79 20 6f 66 20 74 68 65 20  endently of the 
18320 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  [load_extension(
18330 29 5d 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e  )] SQL function.
18340 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
18350 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74  _enable_load_ext
18360 65 6e 73 69 6f 6e 28 29 5d 20 41 50 49 20 65 6e  ension()] API en
18370 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
18380 73 20 62 6f 74 68 20 74 68 65 0a 2a 2a 20 43 2d  s both the.** C-
18390 41 50 49 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61  API [sqlite3_loa
183a0 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 61  d_extension()] a
183b0 6e 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nd the SQL funct
183c0 69 6f 6e 20 5b 6c 6f 61 64 5f 65 78 74 65 6e 73  ion [load_extens
183d0 69 6f 6e 28 29 5d 2e 0a 2a 2a 20 54 68 65 72 65  ion()]..** There
183e0 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61   should be two a
183f0 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
18400 6e 74 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 65  nts..** When the
18410 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
18420 74 6f 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  to this interfac
18430 65 20 69 73 20 31 2c 20 74 68 65 6e 20 6f 6e 6c  e is 1, then onl
18440 79 20 74 68 65 20 43 2d 41 50 49 20 69 73 0a 2a  y the C-API is.*
18450 2a 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 74 68  * enabled and th
18460 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72  e SQL function r
18470 65 6d 61 69 6e 73 20 64 69 73 61 62 6c 65 64 2e  emains disabled.
18480 20 20 49 66 20 74 68 65 20 66 69 72 73 74 20 61    If the first a
18490 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68  rgument to.** th
184a0 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  is interface is 
184b0 30 2c 20 74 68 65 6e 20 62 6f 74 68 20 74 68 65  0, then both the
184c0 20 43 2d 41 50 49 20 61 6e 64 20 74 68 65 20 53   C-API and the S
184d0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20  QL function are 
184e0 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 20 49 66 20  disabled..** If 
184f0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
18500 6e 74 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 6e  nt is -1, then n
18510 6f 20 63 68 61 6e 67 65 73 20 61 72 65 20 6d 61  o changes are ma
18520 64 65 20 74 6f 20 73 74 61 74 65 20 6f 66 20 65  de to state of e
18530 69 74 68 65 72 20 74 68 65 0a 2a 2a 20 43 2d 41  ither the.** C-A
18540 50 49 20 6f 72 20 74 68 65 20 53 51 4c 20 66 75  PI or the SQL fu
18550 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20 73  nction..** The s
18560 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
18570 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
18580 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20  an integer into 
18590 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74  which.** is writ
185a0 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e  ten 0 or 1 to in
185b0 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 5b  dicate whether [
185c0 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74  sqlite3_load_ext
185d0 65 6e 73 69 6f 6e 28 29 5d 20 69 6e 74 65 72 66  ension()] interf
185e0 61 63 65 0a 2a 2a 20 69 73 20 64 69 73 61 62 6c  ace.** is disabl
185f0 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 20 66 6f  ed or enabled fo
18600 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c  llowing this cal
18610 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70  l.  The second p
18620 61 72 61 6d 65 74 65 72 20 6d 61 79 0a 2a 2a 20  arameter may.** 
18630 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  be a NULL pointe
18640 72 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65  r, in which case
18650 20 74 68 65 20 6e 65 77 20 73 65 74 74 69 6e 67   the new setting
18660 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64   is not reported
18670 20 62 61 63 6b 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a   back..** </dd>.
18680 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
18690 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 49 4e 44 42  _DBCONFIG_MAINDB
186a0 4e 41 4d 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NAME</dt>.** <dd
186b0 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69  > ^This option i
186c0 73 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65  s used to change
186d0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
186e0 20 22 6d 61 69 6e 22 20 64 61 74 61 62 61 73 65   "main" database
186f0 0a 2a 2a 20 73 63 68 65 6d 61 2e 20 20 5e 54 68  .** schema.  ^Th
18700 65 20 73 6f 6c 65 20 61 72 67 75 6d 65 6e 74 20  e sole argument 
18710 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
18720 61 20 63 6f 6e 73 74 61 6e 74 20 55 54 46 38 20  a constant UTF8 
18730 73 74 72 69 6e 67 0a 2a 2a 20 77 68 69 63 68 20  string.** which 
18740 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 20  will become the 
18750 6e 65 77 20 73 63 68 65 6d 61 20 6e 61 6d 65 20  new schema name 
18760 69 6e 20 70 6c 61 63 65 20 6f 66 20 22 6d 61 69  in place of "mai
18770 6e 22 2e 20 20 5e 53 51 4c 69 74 65 0a 2a 2a 20  n".  ^SQLite.** 
18780 64 6f 65 73 20 6e 6f 74 20 6d 61 6b 65 20 61 20  does not make a 
18790 63 6f 70 79 20 6f 66 20 74 68 65 20 6e 65 77 20  copy of the new 
187a0 6d 61 69 6e 20 73 63 68 65 6d 61 20 6e 61 6d 65  main schema name
187b0 20 73 74 72 69 6e 67 2c 20 73 6f 20 74 68 65 20   string, so the 
187c0 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d  application.** m
187d0 75 73 74 20 65 6e 73 75 72 65 20 74 68 61 74 20  ust ensure that 
187e0 74 68 65 20 61 72 67 75 6d 65 6e 74 20 70 61 73  the argument pas
187f0 73 65 64 20 69 6e 74 6f 20 74 68 69 73 20 44 42  sed into this DB
18800 43 4f 4e 46 49 47 20 6f 70 74 69 6f 6e 20 69 73  CONFIG option is
18810 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 75 6e   unchanged.** un
18820 74 69 6c 20 61 66 74 65 72 20 74 68 65 20 64 61  til after the da
18830 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
18840 6e 20 63 6c 6f 73 65 73 2e 0a 2a 2a 20 3c 2f 64  n closes..** </d
18850 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
18860 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4e 4f 5f  ITE_DBCONFIG_NO_
18870 43 4b 50 54 5f 4f 4e 5f 43 4c 4f 53 45 3c 2f 64  CKPT_ON_CLOSE</d
18880 74 3e 0a 2a 2a 20 3c 64 64 3e 20 55 73 75 61 6c  t>.** <dd> Usual
18890 6c 79 2c 20 77 68 65 6e 20 61 20 64 61 74 61 62  ly, when a datab
188a0 61 73 65 20 69 6e 20 77 61 6c 20 6d 6f 64 65 20  ase in wal mode 
188b0 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 64 65 74  is closed or det
188c0 61 63 68 65 64 20 66 72 6f 6d 20 61 20 0a 2a 2a  ached from a .**
188d0 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   database handle
188e0 2c 20 53 51 4c 69 74 65 20 63 68 65 63 6b 73 20  , SQLite checks 
188f0 69 66 20 74 68 69 73 20 77 69 6c 6c 20 6d 65 61  if this will mea
18900 6e 20 74 68 61 74 20 74 68 65 72 65 20 61 72 65  n that there are
18910 20 6e 6f 77 20 6e 6f 20 0a 2a 2a 20 63 6f 6e 6e   now no .** conn
18920 65 63 74 69 6f 6e 73 20 61 74 20 61 6c 6c 20 74  ections at all t
18930 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20  o the database. 
18940 49 66 20 73 6f 2c 20 69 74 20 70 65 72 66 6f 72  If so, it perfor
18950 6d 73 20 61 20 63 68 65 63 6b 70 6f 69 6e 74 20  ms a checkpoint 
18960 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 62 65  .** operation be
18970 66 6f 72 65 20 63 6c 6f 73 69 6e 67 20 74 68 65  fore closing the
18980 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 54 68 69   connection. Thi
18990 73 20 6f 70 74 69 6f 6e 20 6d 61 79 20 62 65 20  s option may be 
189a0 75 73 65 64 20 74 6f 0a 2a 2a 20 6f 76 65 72 72  used to.** overr
189b0 69 64 65 20 74 68 69 73 20 62 65 68 61 76 69 6f  ide this behavio
189c0 75 72 2e 20 54 68 65 20 66 69 72 73 74 20 70 61  ur. The first pa
189d0 72 61 6d 65 74 65 72 20 70 61 73 73 65 64 20 74  rameter passed t
189e0 6f 20 74 68 69 73 20 6f 70 65 72 61 74 69 6f 6e  o this operation
189f0 0a 2a 2a 20 69 73 20 61 6e 20 69 6e 74 65 67 65  .** is an intege
18a00 72 20 2d 20 6e 6f 6e 2d 7a 65 72 6f 20 74 6f 20  r - non-zero to 
18a10 64 69 73 61 62 6c 65 20 63 68 65 63 6b 70 6f 69  disable checkpoi
18a20 6e 74 73 2d 6f 6e 2d 63 6c 6f 73 65 2c 20 6f 72  nts-on-close, or
18a30 20 7a 65 72 6f 20 28 74 68 65 0a 2a 2a 20 64 65   zero (the.** de
18a40 66 61 75 6c 74 29 20 74 6f 20 65 6e 61 62 6c 65  fault) to enable
18a50 20 74 68 65 6d 2e 20 54 68 65 20 73 65 63 6f 6e   them. The secon
18a60 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
18a70 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
18a80 6e 74 65 67 65 72 0a 2a 2a 20 69 6e 74 6f 20 77  nteger.** into w
18a90 68 69 63 68 20 69 73 20 77 72 69 74 74 65 6e 20  hich is written 
18aa0 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61  0 or 1 to indica
18ab0 74 65 20 77 68 65 74 68 65 72 20 63 68 65 63 6b  te whether check
18ac0 70 6f 69 6e 74 73 2d 6f 6e 2d 63 6c 6f 73 65 0a  points-on-close.
18ad0 2a 2a 20 68 61 76 65 20 62 65 65 6e 20 64 69 73  ** have been dis
18ae0 61 62 6c 65 64 20 2d 20 30 20 69 66 20 74 68 65  abled - 0 if the
18af0 79 20 61 72 65 20 6e 6f 74 20 64 69 73 61 62 6c  y are not disabl
18b00 65 64 2c 20 31 20 69 66 20 74 68 65 79 20 61 72  ed, 1 if they ar
18b10 65 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  e..** </dd>.**.*
18b20 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </dl>.*/.#defi
18b30 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
18b40 49 47 5f 4d 41 49 4e 44 42 4e 41 4d 45 20 20 20  IG_MAINDBNAME   
18b50 20 20 20 20 20 20 20 20 20 31 30 30 30 20 2f 2a           1000 /*
18b60 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 2a 2f 0a   const char* */.
18b70 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
18b80 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
18b90 45 20 20 20 20 20 20 20 20 20 20 20 20 20 31 30  E             10
18ba0 30 31 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20  01 /* void* int 
18bb0 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  int */.#define S
18bc0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
18bd0 4e 41 42 4c 45 5f 46 4b 45 59 20 20 20 20 20 20  NABLE_FKEY      
18be0 20 20 20 20 20 31 30 30 32 20 2f 2a 20 69 6e 74       1002 /* int
18bf0 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65   int* */.#define
18c00 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
18c10 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 20  _ENABLE_TRIGGER 
18c20 20 20 20 20 20 20 20 31 30 30 33 20 2f 2a 20 69         1003 /* i
18c30 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69  nt int* */.#defi
18c40 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
18c50 49 47 5f 45 4e 41 42 4c 45 5f 46 54 53 33 5f 54  IG_ENABLE_FTS3_T
18c60 4f 4b 45 4e 49 5a 45 52 20 31 30 30 34 20 2f 2a  OKENIZER 1004 /*
18c70 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65   int int* */.#de
18c80 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
18c90 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 4c 4f 41 44  NFIG_ENABLE_LOAD
18ca0 5f 45 58 54 45 4e 53 49 4f 4e 20 31 30 30 35 20  _EXTENSION 1005 
18cb0 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23  /* int int* */.#
18cc0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
18cd0 43 4f 4e 46 49 47 5f 4e 4f 5f 43 4b 50 54 5f 4f  CONFIG_NO_CKPT_O
18ce0 4e 5f 43 4c 4f 53 45 20 20 20 20 20 20 31 30 30  N_CLOSE      100
18cf0 36 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f  6 /* int int* */
18d00 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
18d10 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73  F: Enable Or Dis
18d20 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65  able Extended Re
18d30 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4d 45  sult Codes.** ME
18d40 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
18d50 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
18d60 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
18d70 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65  _codes() routine
18d80 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61   enables or disa
18d90 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74  bles the.** [ext
18da0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
18db0 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53  es] feature of S
18dc0 51 4c 69 74 65 2e 20 5e 54 68 65 20 65 78 74 65  QLite. ^The exte
18dd0 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63  nded result.** c
18de0 6f 64 65 73 20 61 72 65 20 64 69 73 61 62 6c 65  odes are disable
18df0 64 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72  d by default for
18e00 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70   historical comp
18e10 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 53 51  atibility..*/.SQ
18e20 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
18e30 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
18e40 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74  sult_codes(sqlit
18e50 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b  e3*, int onoff);
18e60 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
18e70 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f  : Last Insert Ro
18e80 77 69 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  wid.** METHOD: s
18e90 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 45 61  qlite3.**.** ^Ea
18ea0 63 68 20 65 6e 74 72 79 20 69 6e 20 6d 6f 73 74  ch entry in most
18eb0 20 53 51 4c 69 74 65 20 74 61 62 6c 65 73 20 28   SQLite tables (
18ec0 65 78 63 65 70 74 20 66 6f 72 20 5b 57 49 54 48  except for [WITH
18ed0 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65  OUT ROWID] table
18ee0 73 29 0a 2a 2a 20 68 61 73 20 61 20 75 6e 69 71  s).** has a uniq
18ef0 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  ue 64-bit signed
18f00 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20  .** integer key 
18f10 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49  called the [ROWI
18f20 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54  D | "rowid"]. ^T
18f30 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61  he rowid is alwa
18f40 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20  ys available.** 
18f50 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64  as an undeclared
18f60 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f   column named RO
18f70 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f  WID, OID, or _RO
18f80 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20  WID_ as long as 
18f90 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61  those.** names a
18fa0 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64  re not also used
18fb0 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64   by explicitly d
18fc0 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e  eclared columns.
18fd0 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c   ^If.** the tabl
18fe0 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f  e has a column o
18ff0 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20  f type [INTEGER 
19000 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65  PRIMARY KEY] the
19010 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a  n that column.**
19020 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61   is another alia
19030 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e  s for the rowid.
19040 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
19050 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
19060 72 6f 77 69 64 28 44 29 20 69 6e 74 65 72 66 61  rowid(D) interfa
19070 63 65 20 75 73 75 61 6c 6c 79 20 72 65 74 75 72  ce usually retur
19080 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f  ns the [rowid] o
19090 66 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20 72 65  f.** the most re
190a0 63 65 6e 74 20 73 75 63 63 65 73 73 66 75 6c 20  cent successful 
190b0 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 61 20  [INSERT] into a 
190c0 72 6f 77 69 64 20 74 61 62 6c 65 20 6f 72 20 5b  rowid table or [
190d0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a  virtual table].*
190e0 2a 20 6f 6e 20 64 61 74 61 62 61 73 65 20 63 6f  * on database co
190f0 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 5e 49 6e 73  nnection D. ^Ins
19100 65 72 74 73 20 69 6e 74 6f 20 5b 57 49 54 48 4f  erts into [WITHO
19110 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73  UT ROWID] tables
19120 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f   are not.** reco
19130 72 64 65 64 2e 20 5e 49 66 20 6e 6f 20 73 75 63  rded. ^If no suc
19140 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d  cessful [INSERT]
19150 73 20 69 6e 74 6f 20 72 6f 77 69 64 20 74 61 62  s into rowid tab
19160 6c 65 73 20 68 61 76 65 20 65 76 65 72 20 6f 63  les have ever oc
19170 63 75 72 72 65 64 20 0a 2a 2a 20 6f 6e 20 74 68  curred .** on th
19180 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
19190 63 74 69 6f 6e 20 44 2c 20 74 68 65 6e 20 73 71  ction D, then sq
191a0 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
191b0 74 5f 72 6f 77 69 64 28 44 29 20 72 65 74 75 72  t_rowid(D) retur
191c0 6e 73 20 0a 2a 2a 20 7a 65 72 6f 2e 0a 2a 2a 0a  ns .** zero..**.
191d0 2a 2a 20 41 73 20 77 65 6c 6c 20 61 73 20 62 65  ** As well as be
191e0 69 6e 67 20 73 65 74 20 61 75 74 6f 6d 61 74 69  ing set automati
191f0 63 61 6c 6c 79 20 61 73 20 72 6f 77 73 20 61 72  cally as rows ar
19200 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 20  e inserted into 
19210 64 61 74 61 62 61 73 65 0a 2a 2a 20 74 61 62 6c  database.** tabl
19220 65 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65  es, the value re
19230 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 66  turned by this f
19240 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 73  unction may be s
19250 65 74 20 65 78 70 6c 69 63 69 74 6c 79 20 62 79  et explicitly by
19260 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  .** [sqlite3_set
19270 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
19280 69 64 28 29 5d 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65  id()].**.** Some
19290 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69   virtual table i
192a0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d  mplementations m
192b0 61 79 20 49 4e 53 45 52 54 20 72 6f 77 73 20 69  ay INSERT rows i
192c0 6e 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 73  nto rowid tables
192d0 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 63   as.** part of c
192e0 6f 6d 6d 69 74 74 69 6e 67 20 61 20 74 72 61 6e  ommitting a tran
192f0 73 61 63 74 69 6f 6e 20 28 65 2e 67 2e 20 74 6f  saction (e.g. to
19300 20 66 6c 75 73 68 20 64 61 74 61 20 61 63 63 75   flush data accu
19310 6d 75 6c 61 74 65 64 20 69 6e 20 6d 65 6d 6f 72  mulated in memor
19320 79 0a 2a 2a 20 74 6f 20 64 69 73 6b 29 2e 20 49  y.** to disk). I
19330 6e 20 74 68 69 73 20 63 61 73 65 20 73 75 62 73  n this case subs
19340 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
19350 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  this function re
19360 74 75 72 6e 20 74 68 65 20 72 6f 77 69 64 0a 2a  turn the rowid.*
19370 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
19380 68 20 74 68 65 73 65 20 69 6e 74 65 72 6e 61 6c  h these internal
19390 20 49 4e 53 45 52 54 20 6f 70 65 72 61 74 69 6f   INSERT operatio
193a0 6e 73 2c 20 77 68 69 63 68 20 6c 65 61 64 73 20  ns, which leads 
193b0 74 6f 20 0a 2a 2a 20 75 6e 69 6e 74 75 69 74 69  to .** unintuiti
193c0 76 65 20 72 65 73 75 6c 74 73 2e 20 56 69 72 74  ve results. Virt
193d0 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d  ual table implem
193e0 65 6e 74 61 74 69 6f 6e 73 20 74 68 61 74 20 64  entations that d
193f0 6f 20 77 72 69 74 65 20 74 6f 20 72 6f 77 69 64  o write to rowid
19400 0a 2a 2a 20 74 61 62 6c 65 73 20 69 6e 20 74 68  .** tables in th
19410 69 73 20 77 61 79 20 63 61 6e 20 61 76 6f 69 64  is way can avoid
19420 20 74 68 69 73 20 70 72 6f 62 6c 65 6d 20 62 79   this problem by
19430 20 72 65 73 74 6f 72 69 6e 67 20 74 68 65 20 6f   restoring the o
19440 72 69 67 69 6e 61 6c 20 0a 2a 2a 20 72 6f 77 69  riginal .** rowi
19450 64 20 76 61 6c 75 65 20 75 73 69 6e 67 20 5b 73  d value using [s
19460 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f  qlite3_set_last_
19470 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20  insert_rowid()] 
19480 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67  before returning
19490 20 0a 2a 2a 20 63 6f 6e 74 72 6f 6c 20 74 6f 20   .** control to 
194a0 74 68 65 20 75 73 65 72 2e 0a 2a 2a 0a 2a 2a 20  the user..**.** 
194b0 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d  ^(If an [INSERT]
194c0 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61   occurs within a
194d0 20 74 72 69 67 67 65 72 20 74 68 65 6e 20 74 68   trigger then th
194e0 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20  is routine will 
194f0 0a 2a 2a 20 72 65 74 75 72 6e 20 74 68 65 20 5b  .** return the [
19500 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e  rowid] of the in
19510 73 65 72 74 65 64 20 72 6f 77 20 61 73 20 6c 6f  serted row as lo
19520 6e 67 20 61 73 20 74 68 65 20 74 72 69 67 67 65  ng as the trigge
19530 72 20 69 73 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67  r is .** running
19540 2e 20 4f 6e 63 65 20 74 68 65 20 74 72 69 67 67  . Once the trigg
19550 65 72 20 70 72 6f 67 72 61 6d 20 65 6e 64 73 2c  er program ends,
19560 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
19570 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20  ned .** by this 
19580 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73 20  routine reverts 
19590 74 6f 20 77 68 61 74 20 69 74 20 77 61 73 20 62  to what it was b
195a0 65 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65  efore the trigge
195b0 72 20 77 61 73 20 66 69 72 65 64 2e 29 5e 0a 2a  r was fired.)^.*
195c0 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54  *.** ^An [INSERT
195d0 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 65  ] that fails due
195e0 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74   to a constraint
195f0 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f   violation is no
19600 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  t a.** successfu
19610 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64  l [INSERT] and d
19620 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  oes not change t
19630 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
19640 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75  d by this.** rou
19650 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53  tine.  ^Thus INS
19660 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53  ERT OR FAIL, INS
19670 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49  ERT OR IGNORE, I
19680 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43  NSERT OR ROLLBAC
19690 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54  K,.** and INSERT
196a0 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e   OR ABORT make n
196b0 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  o changes to the
196c0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
196d0 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65   this.** routine
196e0 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65   when their inse
196f0 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28  rtion fails.  ^(
19700 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52  When INSERT OR R
19710 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e  EPLACE.** encoun
19720 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e  ters a constrain
19730 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20  t violation, it 
19740 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20  does not fail.  
19750 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f  The.** INSERT co
19760 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c  ntinues to compl
19770 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65  etion after dele
19780 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63  ting rows that c
19790 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e  aused.** the con
197a0 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20  straint problem 
197b0 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50  so INSERT OR REP
197c0 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73  LACE will always
197d0 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72   change.** the r
197e0 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
197f0 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e  his interface.)^
19800 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20  .**.** ^For the 
19810 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73  purposes of this
19820 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e   routine, an [IN
19830 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65  SERT] is conside
19840 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63  red to.** be suc
19850 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20  cessful even if 
19860 69 74 20 69 73 20 73 75 62 73 65 71 75 65 6e 74  it is subsequent
19870 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a  ly rolled back..
19880 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  **.** This funct
19890 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c  ion is accessibl
198a0 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65  e to SQL stateme
198b0 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b  nts via the.** [
198c0 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
198d0 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  d() SQL function
198e0 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65  ]..**.** If a se
198f0 70 61 72 61 74 65 20 74 68 72 65 61 64 20 70 65  parate thread pe
19900 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e  rforms a new [IN
19910 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d  SERT] on the sam
19920 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
19930 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74  nnection while t
19940 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74  he [sqlite3_last
19950 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
19960 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  .** function is 
19970 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73  running and thus
19980 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73   changes the las
19990 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d  t insert [rowid]
199a0 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61  ,.** then the va
199b0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
199c0 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e  [sqlite3_last_in
199d0 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73  sert_rowid()] is
199e0 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c  .** unpredictabl
199f0 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20  e and might not 
19a00 65 71 75 61 6c 20 65 69 74 68 65 72 20 74 68 65  equal either the
19a10 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a   old or the new.
19a20 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b  ** last insert [
19a30 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 53 51 4c 49 54  rowid]..*/.SQLIT
19a40 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e  E_API sqlite3_in
19a50 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74  t64 sqlite3_last
19a60 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71  _insert_rowid(sq
19a70 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
19a80 43 41 50 49 33 52 45 46 3a 20 53 65 74 20 74 68  CAPI3REF: Set th
19a90 65 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f  e Last Insert Ro
19aa0 77 69 64 20 76 61 6c 75 65 2e 0a 2a 2a 20 4d 45  wid value..** ME
19ab0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
19ac0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
19ad0 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  set_last_insert_
19ae0 72 6f 77 69 64 28 44 2c 20 52 29 20 6d 65 74 68  rowid(D, R) meth
19af0 6f 64 20 61 6c 6c 6f 77 73 20 74 68 65 20 61 70  od allows the ap
19b00 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20  plication to.** 
19b10 73 65 74 20 74 68 65 20 76 61 6c 75 65 20 72 65  set the value re
19b20 74 75 72 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e  turned by callin
19b30 67 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69  g sqlite3_last_i
19b40 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20 74  nsert_rowid(D) t
19b50 6f 20 52 20 0a 2a 2a 20 77 69 74 68 6f 75 74 20  o R .** without 
19b60 69 6e 73 65 72 74 69 6e 67 20 61 20 72 6f 77 20  inserting a row 
19b70 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  into the databas
19b80 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  e..*/.SQLITE_API
19b90 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65   void sqlite3_se
19ba0 74 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  t_last_insert_ro
19bb0 77 69 64 28 73 71 6c 69 74 65 33 2a 2c 73 71 6c  wid(sqlite3*,sql
19bc0 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 2f 2a  ite3_int64);../*
19bd0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
19be0 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f  unt The Number O
19bf0 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a  f Rows Modified.
19c00 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
19c10 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  e3.**.** ^This f
19c20 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
19c30 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
19c40 77 73 20 6d 6f 64 69 66 69 65 64 2c 20 69 6e 73  ws modified, ins
19c50 65 72 74 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65  erted or.** dele
19c60 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20  ted by the most 
19c70 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74  recently complet
19c80 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  ed INSERT, UPDAT
19c90 45 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73  E or DELETE.** s
19ca0 74 61 74 65 6d 65 6e 74 20 6f 6e 20 74 68 65 20  tatement on the 
19cb0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
19cc0 69 6f 6e 20 73 70 65 63 69 66 69 65 64 20 62 79  ion specified by
19cd0 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65   the only parame
19ce0 74 65 72 2e 0a 2a 2a 20 5e 45 78 65 63 75 74 69  ter..** ^Executi
19cf0 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70  ng any other typ
19d00 65 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65  e of SQL stateme
19d10 6e 74 20 64 6f 65 73 20 6e 6f 74 20 6d 6f 64 69  nt does not modi
19d20 66 79 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20  fy the value.** 
19d30 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73  returned by this
19d40 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
19d50 20 5e 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d   ^Only changes m
19d60 61 64 65 20 64 69 72 65 63 74 6c 79 20 62 79 20  ade directly by 
19d70 74 68 65 20 49 4e 53 45 52 54 2c 20 55 50 44 41  the INSERT, UPDA
19d80 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61  TE or DELETE sta
19d90 74 65 6d 65 6e 74 20 61 72 65 0a 2a 2a 20 63 6f  tement are.** co
19da0 6e 73 69 64 65 72 65 64 20 2d 20 61 75 78 69 6c  nsidered - auxil
19db0 69 61 72 79 20 63 68 61 6e 67 65 73 20 63 61 75  iary changes cau
19dc0 73 65 64 20 62 79 20 5b 43 52 45 41 54 45 20 54  sed by [CREATE T
19dd0 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72  RIGGER | trigger
19de0 73 5d 2c 20 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e  s], .** [foreign
19df0 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 6f 72   key actions] or
19e00 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74   [REPLACE] const
19e10 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e  raint resolution
19e20 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64   are not counted
19e30 2e 0a 2a 2a 20 0a 2a 2a 20 43 68 61 6e 67 65 73  ..** .** Changes
19e40 20 74 6f 20 61 20 76 69 65 77 20 74 68 61 74 20   to a view that 
19e50 61 72 65 20 69 6e 74 65 72 63 65 70 74 65 64 20  are intercepted 
19e60 62 79 20 0a 2a 2a 20 5b 49 4e 53 54 45 41 44 20  by .** [INSTEAD 
19e70 4f 46 20 74 72 69 67 67 65 72 20 7c 20 49 4e 53  OF trigger | INS
19e80 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 73  TEAD OF triggers
19e90 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65  ] are not counte
19ea0 64 2e 20 5e 54 68 65 20 76 61 6c 75 65 20 0a 2a  d. ^The value .*
19eb0 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  * returned by sq
19ec0 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20  lite3_changes() 
19ed0 69 6d 6d 65 64 69 61 74 65 6c 79 20 61 66 74 65  immediately afte
19ee0 72 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44  r an INSERT, UPD
19ef0 41 54 45 20 6f 72 20 0a 2a 2a 20 44 45 4c 45 54  ATE or .** DELET
19f00 45 20 73 74 61 74 65 6d 65 6e 74 20 72 75 6e 20  E statement run 
19f10 6f 6e 20 61 20 76 69 65 77 20 69 73 20 61 6c 77  on a view is alw
19f20 61 79 73 20 7a 65 72 6f 2e 20 4f 6e 6c 79 20 63  ays zero. Only c
19f30 68 61 6e 67 65 73 20 6d 61 64 65 20 74 6f 20 72  hanges made to r
19f40 65 61 6c 20 0a 2a 2a 20 74 61 62 6c 65 73 20 61  eal .** tables a
19f50 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a  re counted..**.*
19f60 2a 20 54 68 69 6e 67 73 20 61 72 65 20 6d 6f 72  * Things are mor
19f70 65 20 63 6f 6d 70 6c 69 63 61 74 65 64 20 69 66  e complicated if
19f80 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61   the sqlite3_cha
19f90 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20  nges() function 
19fa0 69 73 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 77  is.** executed w
19fb0 68 69 6c 65 20 61 20 74 72 69 67 67 65 72 20 70  hile a trigger p
19fc0 72 6f 67 72 61 6d 20 69 73 20 72 75 6e 6e 69 6e  rogram is runnin
19fd0 67 2e 20 54 68 69 73 20 6d 61 79 20 68 61 70 70  g. This may happ
19fe0 65 6e 20 69 66 20 74 68 65 0a 2a 2a 20 70 72 6f  en if the.** pro
19ff0 67 72 61 6d 20 75 73 65 73 20 74 68 65 20 5b 63  gram uses the [c
1a000 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e  hanges() SQL fun
1a010 63 74 69 6f 6e 5d 2c 20 6f 72 20 69 66 20 73 6f  ction], or if so
1a020 6d 65 20 6f 74 68 65 72 20 63 61 6c 6c 62 61 63  me other callbac
1a030 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 6e  k.** function in
1a040 76 6f 6b 65 73 20 73 71 6c 69 74 65 33 5f 63 68  vokes sqlite3_ch
1a050 61 6e 67 65 73 28 29 20 64 69 72 65 63 74 6c 79  anges() directly
1a060 2e 20 45 73 73 65 6e 74 69 61 6c 6c 79 3a 0a 2a  . Essentially:.*
1a070 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20  * .** <ul>.**   
1a080 3c 6c 69 3e 20 5e 28 42 65 66 6f 72 65 20 65 6e  <li> ^(Before en
1a090 74 65 72 69 6e 67 20 61 20 74 72 69 67 67 65 72  tering a trigger
1a0a0 20 70 72 6f 67 72 61 6d 20 74 68 65 20 76 61 6c   program the val
1a0b0 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  ue returned by.*
1a0c0 2a 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33  *        sqlite3
1a0d0 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74  _changes() funct
1a0e0 69 6f 6e 20 69 73 20 73 61 76 65 64 2e 20 41 66  ion is saved. Af
1a0f0 74 65 72 20 74 68 65 20 74 72 69 67 67 65 72 20  ter the trigger 
1a100 70 72 6f 67 72 61 6d 20 0a 2a 2a 20 20 20 20 20  program .**     
1a110 20 20 20 68 61 73 20 66 69 6e 69 73 68 65 64 2c     has finished,
1a120 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 76 61   the original va
1a130 6c 75 65 20 69 73 20 72 65 73 74 6f 72 65 64 2e  lue is restored.
1a140 29 5e 0a 2a 2a 20 0a 2a 2a 20 20 20 3c 6c 69 3e  )^.** .**   <li>
1a150 20 5e 28 57 69 74 68 69 6e 20 61 20 74 72 69 67   ^(Within a trig
1a160 67 65 72 20 70 72 6f 67 72 61 6d 20 65 61 63 68  ger program each
1a170 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20   INSERT, UPDATE 
1a180 61 6e 64 20 44 45 4c 45 54 45 20 0a 2a 2a 20 20  and DELETE .**  
1a190 20 20 20 20 20 20 73 74 61 74 65 6d 65 6e 74 20        statement 
1a1a0 73 65 74 73 20 74 68 65 20 76 61 6c 75 65 20 72  sets the value r
1a1b0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
1a1c0 65 33 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a  e3_changes() .**
1a1d0 20 20 20 20 20 20 20 20 75 70 6f 6e 20 63 6f 6d          upon com
1a1e0 70 6c 65 74 69 6f 6e 20 61 73 20 6e 6f 72 6d 61  pletion as norma
1a1f0 6c 2e 20 4f 66 20 63 6f 75 72 73 65 2c 20 74 68  l. Of course, th
1a200 69 73 20 76 61 6c 75 65 20 77 69 6c 6c 20 6e 6f  is value will no
1a210 74 20 69 6e 63 6c 75 64 65 20 0a 2a 2a 20 20 20  t include .**   
1a220 20 20 20 20 20 61 6e 79 20 63 68 61 6e 67 65 73       any changes
1a230 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 73 75   performed by su
1a240 62 2d 74 72 69 67 67 65 72 73 2c 20 61 73 20 74  b-triggers, as t
1a250 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  he sqlite3_chang
1a260 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20  es() .**        
1a270 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 73 61  value will be sa
1a280 76 65 64 20 61 6e 64 20 72 65 73 74 6f 72 65 64  ved and restored
1a290 20 61 66 74 65 72 20 65 61 63 68 20 73 75 62 2d   after each sub-
1a2a0 74 72 69 67 67 65 72 20 68 61 73 20 72 75 6e 2e  trigger has run.
1a2b0 29 5e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 0a  )^.** </ul>.** .
1a2c0 2a 2a 20 5e 54 68 69 73 20 6d 65 61 6e 73 20 74  ** ^This means t
1a2d0 68 61 74 20 69 66 20 74 68 65 20 63 68 61 6e 67  hat if the chang
1a2e0 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  es() SQL functio
1a2f0 6e 20 28 6f 72 20 73 69 6d 69 6c 61 72 29 20 69  n (or similar) i
1a300 73 20 75 73 65 64 0a 2a 2a 20 62 79 20 74 68 65  s used.** by the
1a310 20 66 69 72 73 74 20 49 4e 53 45 52 54 2c 20 55   first INSERT, U
1a320 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20  PDATE or DELETE 
1a330 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e  statement within
1a340 20 61 20 74 72 69 67 67 65 72 2c 20 69 74 20 0a   a trigger, it .
1a350 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 76  ** returns the v
1a360 61 6c 75 65 20 61 73 20 73 65 74 20 77 68 65 6e  alue as set when
1a370 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 73 74 61   the calling sta
1a380 74 65 6d 65 6e 74 20 62 65 67 61 6e 20 65 78 65  tement began exe
1a390 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 69  cuting..** ^If i
1a3a0 74 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65  t is used by the
1a3b0 20 73 65 63 6f 6e 64 20 6f 72 20 73 75 62 73 65   second or subse
1a3c0 71 75 65 6e 74 20 73 75 63 68 20 73 74 61 74 65  quent such state
1a3d0 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20 74 72  ment within a tr
1a3e0 69 67 67 65 72 20 0a 2a 2a 20 70 72 6f 67 72 61  igger .** progra
1a3f0 6d 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  m, the value ret
1a400 75 72 6e 65 64 20 72 65 66 6c 65 63 74 73 20 74  urned reflects t
1a410 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  he number of row
1a420 73 20 6d 6f 64 69 66 69 65 64 20 62 79 20 74 68  s modified by th
1a430 65 20 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 49  e .** previous I
1a440 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72  NSERT, UPDATE or
1a450 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e   DELETE statemen
1a460 74 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d  t within the sam
1a470 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a  e trigger..**.**
1a480 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73   See also the [s
1a490 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
1a4a0 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63  nges()] interfac
1a4b0 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74  e, the.** [count
1a4c0 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d  _changes pragma]
1a4d0 2c 20 61 6e 64 20 74 68 65 20 5b 63 68 61 6e 67  , and the [chang
1a4e0 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  es() SQL functio
1a4f0 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73  n]..**.** If a s
1a500 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d  eparate thread m
1a510 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20  akes changes on 
1a520 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
1a530 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
1a540 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63  while [sqlite3_c
1a550 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e  hanges()] is run
1a560 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61  ning then the va
1a570 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  lue returned.** 
1a580 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  is unpredictable
1a590 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67   and not meaning
1a5a0 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ful..*/.SQLITE_A
1a5b0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
1a5c0 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29  hanges(sqlite3*)
1a5d0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1a5e0 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20  F: Total Number 
1a5f0 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64  Of Rows Modified
1a600 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
1a610 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  te3.**.** ^This 
1a620 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1a630 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65   the total numbe
1a640 72 20 6f 66 20 72 6f 77 73 20 69 6e 73 65 72 74  r of rows insert
1a650 65 64 2c 20 6d 6f 64 69 66 69 65 64 20 6f 72 0a  ed, modified or.
1a660 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20 61 6c  ** deleted by al
1a670 6c 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44  l [INSERT], [UPD
1a680 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d  ATE] or [DELETE]
1a690 20 73 74 61 74 65 6d 65 6e 74 73 20 63 6f 6d 70   statements comp
1a6a0 6c 65 74 65 64 0a 2a 2a 20 73 69 6e 63 65 20 74  leted.** since t
1a6b0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1a6c0 65 63 74 69 6f 6e 20 77 61 73 20 6f 70 65 6e 65  ection was opene
1a6d0 64 2c 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 6f  d, including tho
1a6e0 73 65 20 65 78 65 63 75 74 65 64 20 61 73 0a 2a  se executed as.*
1a6f0 2a 20 70 61 72 74 20 6f 66 20 74 72 69 67 67 65  * part of trigge
1a700 72 20 70 72 6f 67 72 61 6d 73 2e 20 5e 45 78 65  r programs. ^Exe
1a710 63 75 74 69 6e 67 20 61 6e 79 20 6f 74 68 65 72  cuting any other
1a720 20 74 79 70 65 20 6f 66 20 53 51 4c 20 73 74 61   type of SQL sta
1a730 74 65 6d 65 6e 74 0a 2a 2a 20 64 6f 65 73 20 6e  tement.** does n
1a740 6f 74 20 61 66 66 65 63 74 20 74 68 65 20 76 61  ot affect the va
1a750 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
1a760 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
1a770 61 6e 67 65 73 28 29 2e 0a 2a 2a 20 0a 2a 2a 20  anges()..** .** 
1a780 5e 43 68 61 6e 67 65 73 20 6d 61 64 65 20 61 73  ^Changes made as
1a790 20 70 61 72 74 20 6f 66 20 5b 66 6f 72 65 69 67   part of [foreig
1a7a0 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 61  n key actions] a
1a7b0 72 65 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74  re included in t
1a7c0 68 65 0a 2a 2a 20 63 6f 75 6e 74 2c 20 62 75 74  he.** count, but
1a7d0 20 74 68 6f 73 65 20 6d 61 64 65 20 61 73 20 70   those made as p
1a7e0 61 72 74 20 6f 66 20 52 45 50 4c 41 43 45 20 63  art of REPLACE c
1a7f0 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75  onstraint resolu
1a800 74 69 6f 6e 20 61 72 65 0a 2a 2a 20 6e 6f 74 2e  tion are.** not.
1a810 20 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76   ^Changes to a v
1a820 69 65 77 20 74 68 61 74 20 61 72 65 20 69 6e 74  iew that are int
1a830 65 72 63 65 70 74 65 64 20 62 79 20 49 4e 53 54  ercepted by INST
1a840 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 73 20  EAD OF triggers 
1a850 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e  .** are not coun
1a860 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 53 65 65 20  ted..** .** See 
1a870 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  also the [sqlite
1a880 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74  3_changes()] int
1a890 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b  erface, the.** [
1a8a0 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72  count_changes pr
1a8b0 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b  agma], and the [
1a8c0 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20  total_changes() 
1a8d0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a  SQL function]..*
1a8e0 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61  *.** If a separa
1a8f0 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20  te thread makes 
1a900 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73  changes on the s
1a910 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
1a920 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65  nection.** while
1a930 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f   [sqlite3_total_
1a940 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75  changes()] is ru
1a950 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76  nning then the v
1a960 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64  alue.** returned
1a970 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c   is unpredictabl
1a980 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e  e and not meanin
1a990 67 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  gful..*/.SQLITE_
1a9a0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
1a9b0 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71  total_changes(sq
1a9c0 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
1a9d0 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72  CAPI3REF: Interr
1a9e0 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69  upt A Long-Runni
1a9f0 6e 67 20 51 75 65 72 79 0a 2a 2a 20 4d 45 54 48  ng Query.** METH
1aa00 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
1aa10 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
1aa20 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64   causes any pend
1aa30 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 65  ing database ope
1aa40 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20  ration to abort 
1aa50 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74  and.** return at
1aa60 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70   its earliest op
1aa70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20  portunity. This 
1aa80 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 63  routine is typic
1aa90 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69  ally.** called i
1aaa0 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20  n response to a 
1aab0 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68  user action such
1aac0 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 61   as pressing "Ca
1aad0 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c  ncel".** or Ctrl
1aae0 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73 65  -C where the use
1aaf0 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71  r wants a long q
1ab00 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74  uery operation t
1ab10 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69  o halt.** immedi
1ab20 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74  ately..**.** ^It
1ab30 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c   is safe to call
1ab40 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72   this routine fr
1ab50 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66  om a thread diff
1ab60 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a  erent from the.*
1ab70 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73  * thread that is
1ab80 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69   currently runni
1ab90 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ng the database 
1aba0 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20  operation.  But 
1abb0 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66  it.** is not saf
1abc0 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72  e to call this r
1abd0 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64  outine with a [d
1abe0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1abf0 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63  on] that.** is c
1ac00 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63  losed or might c
1ac10 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69  lose before sqli
1ac20 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
1ac30 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  returns..**.** ^
1ac40 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74  If an SQL operat
1ac50 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72  ion is very near
1ac60 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 20 74  ly finished at t
1ac70 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20  he time when.** 
1ac80 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1ac90 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74  t() is called, t
1aca0 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74  hen it might not
1acb0 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75   have an opportu
1acc0 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e  nity.** to be in
1acd0 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69  terrupted and mi
1ace0 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20  ght continue to 
1acf0 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a  completion..**.*
1ad00 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 74  * ^An SQL operat
1ad10 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65  ion that is inte
1ad20 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74  rrupted will ret
1ad30 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  urn [SQLITE_INTE
1ad40 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74  RRUPT]..** ^If t
1ad50 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 53  he interrupted S
1ad60 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  QL operation is 
1ad70 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  an INSERT, UPDAT
1ad80 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  E, or DELETE.** 
1ad90 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61  that is inside a
1ada0 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  n explicit trans
1adb0 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  action, then the
1adc0 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74   entire transact
1add0 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72  ion.** will be r
1ade0 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d  olled back autom
1adf0 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20  atically..**.** 
1ae00 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  ^The sqlite3_int
1ae10 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69  errupt(D) call i
1ae20 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69  s in effect unti
1ae30 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20  l all currently 
1ae40 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73  running.** SQL s
1ae50 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61  tatements on [da
1ae60 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1ae70 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20  n] D complete.  
1ae80 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61  ^Any new SQL sta
1ae90 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20  tements.** that 
1aea0 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65  are started afte
1aeb0 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  r the sqlite3_in
1aec0 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61  terrupt() call a
1aed0 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a  nd before the .*
1aee0 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d  * running statem
1aef0 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65 72  ents reaches zer
1af00 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70 74 65  o are interrupte
1af10 64 20 61 73 20 69 66 20 74 68 65 79 20 68 61 64  d as if they had
1af20 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67   been.** running
1af30 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71   prior to the sq
1af40 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1af50 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51  ) call.  ^New SQ
1af60 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
1af70 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64  that are started
1af80 20 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69   after the runni
1af90 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75  ng statement cou
1afa0 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20  nt reaches zero 
1afb0 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63  are.** not effec
1afc0 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74  ted by the sqlit
1afd0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a  e3_interrupt()..
1afe0 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71  ** ^A call to sq
1aff0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1b000 44 29 20 74 68 61 74 20 6f 63 63 75 72 73 20 77  D) that occurs w
1b010 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f  hen there are no
1b020 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20   running.** SQL 
1b030 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20  statements is a 
1b040 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f  no-op and has no
1b050 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73   effect on SQL s
1b060 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
1b070 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
1b080 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ter the sqlite3_
1b090 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c  interrupt() call
1b0a0 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
1b0b0 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
1b0c0 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65  connection close
1b0d0 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33  s while [sqlite3
1b0e0 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a  _interrupt()].**
1b0f0 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
1b100 20 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c   bad things will
1b110 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a   likely happen..
1b120 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  */.SQLITE_API vo
1b130 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  id sqlite3_inter
1b140 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a  rupt(sqlite3*);.
1b150 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1b160 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e   Determine If An
1b170 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49   SQL Statement I
1b180 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a  s Complete.**.**
1b190 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
1b1a0 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 69 6e  are useful durin
1b1b0 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69  g command-line i
1b1c0 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e  nput to determin
1b1d0 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72  e if the.** curr
1b1e0 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65  ently entered te
1b1f0 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d  xt seems to form
1b200 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20   a complete SQL 
1b210 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20  statement or.** 
1b220 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  if additional in
1b230 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62 65  put is needed be
1b240 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65  fore sending the
1b250 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51   text into.** SQ
1b260 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67  Lite for parsing
1b270 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  .  ^These routin
1b280 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 20 74  es return 1 if t
1b290 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a  he input string.
1b2a0 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62 65  ** appears to be
1b2b0 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20   a complete SQL 
1b2c0 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73  statement.  ^A s
1b2d0 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67  tatement is judg
1b2e0 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70  ed to be.** comp
1b2f0 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 73 20  lete if it ends 
1b300 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e  with a semicolon
1b310 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f   token and is no
1b320 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 61 0a  t a prefix of a.
1b330 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43  ** well-formed C
1b340 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73 74  REATE TRIGGER st
1b350 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63  atement.  ^Semic
1b360 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65  olons that are e
1b370 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a  mbedded within.*
1b380 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  * string literal
1b390 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e  s or quoted iden
1b3a0 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20  tifier names or 
1b3b0 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74  comments are not
1b3c0 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20  .** independent 
1b3d0 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65  tokens (they are
1b3e0 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b   part of the tok
1b3f0 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65 79  en in which they
1b400 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64   are.** embedded
1b410 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f  ) and thus do no
1b420 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61  t count as a sta
1b430 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f  tement terminato
1b440 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65 0a  r.  ^Whitespace.
1b450 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20  ** and comments 
1b460 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20  that follow the 
1b470 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20  final semicolon 
1b480 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a  are ignored..**.
1b490 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
1b4a0 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 20 74  es return 0 if t
1b4b0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
1b4c0 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66  incomplete.  ^If
1b4d0 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c   a.** memory all
1b4e0 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74  ocation fails, t
1b4f0 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  hen SQLITE_NOMEM
1b500 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
1b510 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
1b520 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65  nes do not parse
1b530 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
1b540 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c  nts thus.** will
1b550 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74   not detect synt
1b560 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72  actically incorr
1b570 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  ect SQL..**.** ^
1b580 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e  (If SQLite has n
1b590 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69  ot been initiali
1b5a0 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  zed using [sqlit
1b5b0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d  e3_initialize()]
1b5c0 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e   prior .** to in
1b5d0 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  voking sqlite3_c
1b5e0 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e  omplete16() then
1b5f0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
1b600 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
1b610 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
1b620 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d  y by sqlite3_com
1b630 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20 74  plete16().  If t
1b640 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  hat initializati
1b650 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65  on fails,.** the
1b660 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  n the return val
1b670 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
1b680 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c  complete16() wil
1b690 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a  l be non-zero.**
1b6a0 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   regardless of w
1b6b0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
1b6c0 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63  e input SQL is c
1b6d0 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a  omplete.)^.**.**
1b6e0 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73   The input to [s
1b6f0 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28  qlite3_complete(
1b700 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72  )] must be a zer
1b710 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
1b720 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a  UTF-8 string..**
1b730 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f  .** The input to
1b740 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65   [sqlite3_comple
1b750 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20  te16()] must be 
1b760 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
1b770 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69  d.** UTF-16 stri
1b780 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74  ng in native byt
1b790 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 53 51 4c 49  e order..*/.SQLI
1b7a0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
1b7b0 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73  e3_complete(cons
1b7c0 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 53 51  t char *sql);.SQ
1b7d0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
1b7e0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
1b7f0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29  const void *sql)
1b800 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1b810 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 43 61  F: Register A Ca
1b820 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65  llback To Handle
1b830 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72   SQLITE_BUSY Err
1b840 6f 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ors.** KEYWORDS:
1b850 20 7b 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63   {busy-handler c
1b860 61 6c 6c 62 61 63 6b 7d 20 7b 62 75 73 79 20 68  allback} {busy h
1b870 61 6e 64 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f  andler}.** METHO
1b880 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
1b890 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 75   ^The sqlite3_bu
1b8a0 73 79 5f 68 61 6e 64 6c 65 72 28 44 2c 58 2c 50  sy_handler(D,X,P
1b8b0 29 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61  ) routine sets a
1b8c0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1b8d0 6f 6e 20 58 0a 2a 2a 20 74 68 61 74 20 6d 69 67  on X.** that mig
1b8e0 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69  ht be invoked wi
1b8f0 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77 68  th argument P wh
1b900 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74  enever.** an att
1b910 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20  empt is made to 
1b920 61 63 63 65 73 73 20 61 20 64 61 74 61 62 61 73  access a databas
1b930 65 20 74 61 62 6c 65 20 61 73 73 6f 63 69 61 74  e table associat
1b940 65 64 20 77 69 74 68 0a 2a 2a 20 5b 64 61 74 61  ed with.** [data
1b950 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1b960 20 44 20 77 68 65 6e 20 61 6e 6f 74 68 65 72 20   D when another 
1b970 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f  thread.** or pro
1b980 63 65 73 73 20 68 61 73 20 74 68 65 20 74 61 62  cess has the tab
1b990 6c 65 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20 54 68  le locked..** Th
1b9a0 65 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  e sqlite3_busy_h
1b9b0 61 6e 64 6c 65 72 28 29 20 69 6e 74 65 72 66 61  andler() interfa
1b9c0 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 69 6d  ce is used to im
1b9d0 70 6c 65 6d 65 6e 74 0a 2a 2a 20 5b 73 71 6c 69  plement.** [sqli
1b9e0 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
1b9f0 28 29 5d 20 61 6e 64 20 5b 50 52 41 47 4d 41 20  ()] and [PRAGMA 
1ba00 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 2e 0a 2a  busy_timeout]..*
1ba10 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73  *.** ^If the bus
1ba20 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55  y callback is NU
1ba30 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45  LL, then [SQLITE
1ba40 5f 42 55 53 59 5d 0a 2a 2a 20 69 73 20 72 65 74  _BUSY].** is ret
1ba50 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  urned immediatel
1ba60 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72  y upon encounter
1ba70 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e  ing the lock.  ^
1ba80 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c  If the busy call
1ba90 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e  back.** is not N
1baa0 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61  ULL, then the ca
1bab0 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62 65 20  llback might be 
1bac0 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f  invoked with two
1bad0 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a   arguments..**.*
1bae0 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
1baf0 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62 75 73  ument to the bus
1bb00 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63  y handler is a c
1bb10 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a  opy of the void*
1bb20 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a   pointer which.*
1bb30 2a 20 69 73 20 74 68 65 20 74 68 69 72 64 20 61  * is the third a
1bb40 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
1bb50 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
1bb60 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  ).  ^The second 
1bb70 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74  argument to.** t
1bb80 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
1bb90 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20  callback is the 
1bba0 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20  number of times 
1bbb0 74 68 61 74 20 74 68 65 20 62 75 73 79 20 68 61  that the busy ha
1bbc0 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65  ndler has.** bee
1bbd0 6e 20 69 6e 76 6f 6b 65 64 20 70 72 65 76 69 6f  n invoked previo
1bbe0 75 73 6c 79 20 66 6f 72 20 74 68 65 20 73 61 6d  usly for the sam
1bbf0 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e  e locking event.
1bc00 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 73    ^If the.** bus
1bc10 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  y callback retur
1bc20 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64  ns 0, then no ad
1bc30 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74  ditional attempt
1bc40 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a  s are made to.**
1bc50 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61   access the data
1bc60 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45  base and [SQLITE
1bc70 5f 42 55 53 59 5d 20 69 73 20 72 65 74 75 72 6e  _BUSY] is return
1bc80 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 70  ed.** to the app
1bc90 6c 69 63 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66  lication..** ^If
1bca0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
1bcb0 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
1bcc0 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74  then another att
1bcd0 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20  empt.** is made 
1bce0 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 61  to access the da
1bcf0 74 61 62 61 73 65 20 61 6e 64 20 74 68 65 20 63  tabase and the c
1bd00 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a  ycle repeats..**
1bd10 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65  .** The presence
1bd20 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c   of a busy handl
1bd30 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72  er does not guar
1bd40 61 6e 74 65 65 20 74 68 61 74 20 69 74 20 77 69  antee that it wi
1bd50 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a  ll be invoked.**
1bd60 20 77 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c   when there is l
1bd70 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20  ock contention. 
1bd80 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74 65 72  ^If SQLite deter
1bd90 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b  mines that invok
1bda0 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20  ing the busy.** 
1bdb0 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65  handler could re
1bdc0 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f  sult in a deadlo
1bdd0 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61  ck, it will go a
1bde0 68 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20  head and return 
1bdf0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a  [SQLITE_BUSY].**
1be00 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
1be10 69 6f 6e 20 69 6e 73 74 65 61 64 20 6f 66 20 69  ion instead of i
1be20 6e 76 6f 6b 69 6e 67 20 74 68 65 20 0a 2a 2a 20  nvoking the .** 
1be30 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  busy handler..**
1be40 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e   Consider a scen
1be50 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70  ario where one p
1be60 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e  rocess is holdin
1be70 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68  g a read lock th
1be80 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69  at.** it is tryi
1be90 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f  ng to promote to
1bea0 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b   a reserved lock
1beb0 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64   and.** a second
1bec0 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64   process is hold
1bed0 69 6e 67 20 61 20 72 65 73 65 72 76 65 64 20 6c  ing a reserved l
1bee0 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73 20 74  ock that it is t
1bef0 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d  rying.** to prom
1bf00 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73  ote to an exclus
1bf10 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66  ive lock.  The f
1bf20 69 72 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e  irst process can
1bf30 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62  not proceed.** b
1bf40 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f  ecause it is blo
1bf50 63 6b 65 64 20 62 79 20 74 68 65 20 73 65 63 6f  cked by the seco
1bf60 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  nd and the secon
1bf70 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74  d process cannot
1bf80 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61  .** proceed beca
1bf90 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65  use it is blocke
1bfa0 64 20 62 79 20 74 68 65 20 66 69 72 73 74 2e 20  d by the first. 
1bfb0 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73   If both process
1bfc0 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65  es.** invoke the
1bfd0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20   busy handlers, 
1bfe0 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b  neither will mak
1bff0 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20  e any progress. 
1c000 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53   Therefore,.** S
1c010 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53  QLite returns [S
1c020 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20  QLITE_BUSY] for 
1c030 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  the first proces
1c040 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74  s, hoping that t
1c050 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75  his.** will indu
1c060 63 65 20 74 68 65 20 66 69 72 73 74 20 70 72 6f  ce the first pro
1c070 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20  cess to release 
1c080 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e  its read lock an
1c090 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73  d allow.** the s
1c0a0 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f  econd process to
1c0b0 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20   proceed..**.** 
1c0c0 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 75 73  ^The default bus
1c0d0 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55  y callback is NU
1c0e0 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72  LL..**.** ^(Ther
1c0f0 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20  e can only be a 
1c100 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64  single busy hand
1c110 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20  ler defined for 
1c120 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73  each.** [databas
1c130 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20  e connection].  
1c140 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75  Setting a new bu
1c150 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72  sy handler clear
1c160 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75  s any.** previou
1c170 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e  sly set handler.
1c180 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 63  )^  ^Note that c
1c190 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
1c1a0 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a  busy_timeout()].
1c1b0 2a 2a 20 6f 72 20 65 76 61 6c 75 61 74 69 6e 67  ** or evaluating
1c1c0 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69   [PRAGMA busy_ti
1c1d0 6d 65 6f 75 74 3d 4e 5d 20 77 69 6c 6c 20 63 68  meout=N] will ch
1c1e0 61 6e 67 65 20 74 68 65 0a 2a 2a 20 62 75 73 79  ange the.** busy
1c1f0 20 68 61 6e 64 6c 65 72 20 61 6e 64 20 74 68 75   handler and thu
1c200 73 20 63 6c 65 61 72 20 61 6e 79 20 70 72 65 76  s clear any prev
1c210 69 6f 75 73 6c 79 20 73 65 74 20 62 75 73 79 20  iously set busy 
1c220 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  handler..**.** T
1c230 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  he busy callback
1c240 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65   should not take
1c250 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69   any actions whi
1c260 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a  ch modify the.**
1c270 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1c280 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
1c290 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  d the busy handl
1c2a0 65 72 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  er.  In other wo
1c2b0 72 64 73 2c 0a 2a 2a 20 74 68 65 20 62 75 73 79  rds,.** the busy
1c2c0 20 68 61 6e 64 6c 65 72 20 69 73 20 6e 6f 74 20   handler is not 
1c2d0 72 65 65 6e 74 72 61 6e 74 2e 20 20 41 6e 79 20  reentrant.  Any 
1c2e0 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20  such actions.** 
1c2f0 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69  result in undefi
1c300 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  ned behavior..**
1c310 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64   .** A busy hand
1c320 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f  ler must not clo
1c330 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
1c340 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72  connection.** or
1c350 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1c360 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b  ment] that invok
1c370 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ed the busy hand
1c380 6c 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ler..*/.SQLITE_A
1c390 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  PI int sqlite3_b
1c3a0 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69  usy_handler(sqli
1c3b0 74 65 33 2a 2c 69 6e 74 28 2a 29 28 76 6f 69 64  te3*,int(*)(void
1c3c0 2a 2c 69 6e 74 29 2c 76 6f 69 64 2a 29 3b 0a 0a  *,int),void*);..
1c3d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1c3e0 53 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f  Set A Busy Timeo
1c3f0 75 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ut.** METHOD: sq
1c400 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  lite3.**.** ^Thi
1c410 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61  s routine sets a
1c420 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68   [sqlite3_busy_h
1c430 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61  andler | busy ha
1c440 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65  ndler] that slee
1c450 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63  ps.** for a spec
1c460 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20  ified amount of 
1c470 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c  time when a tabl
1c480 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54  e is locked.  ^T
1c490 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69  he handler.** wi
1c4a0 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c  ll sleep multipl
1c4b0 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74  e times until at
1c4c0 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c   least "ms" mill
1c4d0 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
1c4e0 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63  ping.** have acc
1c4f0 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65  umulated.  ^Afte
1c500 72 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20  r at least "ms" 
1c510 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
1c520 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65  sleeping,.** the
1c530 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73   handler returns
1c540 20 30 20 77 68 69 63 68 20 63 61 75 73 65 73 20   0 which causes 
1c550 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1c560 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53   to return.** [S
1c570 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a  QLITE_BUSY]..**.
1c580 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73  ** ^Calling this
1c590 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e   routine with an
1c5a0 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74   argument less t
1c5b0 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20  han or equal to 
1c5c0 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66  zero.** turns of
1c5d0 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c  f all busy handl
1c5e0 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ers..**.** ^(The
1c5f0 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61  re can only be a
1c600 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e   single busy han
1c610 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 69  dler for a parti
1c620 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61  cular.** [databa
1c630 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
1c640 74 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65  t any given mome
1c650 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20  nt.  If another 
1c660 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20  busy handler.** 
1c670 77 61 73 20 64 65 66 69 6e 65 64 20 20 28 75 73  was defined  (us
1c680 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  ing [sqlite3_bus
1c690 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72  y_handler()]) pr
1c6a0 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a  ior to calling.*
1c6b0 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20  * this routine, 
1c6c0 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 20  that other busy 
1c6d0 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72  handler is clear
1c6e0 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  ed.)^.**.** See 
1c6f0 61 6c 73 6f 3a 20 20 5b 50 52 41 47 4d 41 20 62  also:  [PRAGMA b
1c700 75 73 79 5f 74 69 6d 65 6f 75 74 5d 0a 2a 2f 0a  usy_timeout].*/.
1c710 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
1c720 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
1c730 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  out(sqlite3*, in
1c740 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  t ms);../*.** CA
1c750 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65  PI3REF: Convenie
1c760 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72  nce Routines For
1c770 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73   Running Queries
1c780 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
1c790 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  te3.**.** This i
1c7a0 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74 65 72  s a legacy inter
1c7b0 66 61 63 65 20 74 68 61 74 20 69 73 20 70 72 65  face that is pre
1c7c0 73 65 72 76 65 64 20 66 6f 72 20 62 61 63 6b 77  served for backw
1c7d0 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
1c7e0 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68  ty..** Use of th
1c7f0 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  is interface is 
1c800 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e  not recommended.
1c810 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f  .**.** Definitio
1c820 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74  n: A <b>result t
1c830 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f  able</b> is memo
1c840 72 79 20 64 61 74 61 20 73 74 72 75 63 74 75 72  ry data structur
1c850 65 20 63 72 65 61 74 65 64 20 62 79 20 74 68 65  e created by the
1c860 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  .** [sqlite3_get
1c870 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66  _table()] interf
1c880 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74  ace.  A result t
1c890 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65  able records the
1c8a0 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65  .** complete que
1c8b0 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20  ry results from 
1c8c0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72  one or more quer
1c8d0 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ies..**.** The t
1c8e0 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c  able conceptuall
1c8f0 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f  y has a number o
1c900 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d  f rows and colum
1c910 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73  ns.  But.** thes
1c920 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f  e numbers are no
1c930 74 20 70 61 72 74 20 6f 66 20 74 68 65 20 72 65  t part of the re
1c940 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c  sult table itsel
1c950 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d  f.  These.** num
1c960 62 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65  bers are obtaine
1c970 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c  d separately.  L
1c980 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62  et N be the numb
1c990 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e  er of rows.** an
1c9a0 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65  d M be the numbe
1c9b0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a  r of columns..**
1c9c0 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
1c9d0 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  le is an array o
1c9e0 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65  f pointers to ze
1c9f0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
1ca00 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20  F-8 strings..** 
1ca10 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a  There are (N+1)*
1ca20 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68  M elements in th
1ca30 65 20 61 72 72 61 79 2e 20 20 54 68 65 20 66 69  e array.  The fi
1ca40 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70  rst M pointers p
1ca50 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d  oint.** to zero-
1ca60 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
1ca70 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e  gs that  contain
1ca80 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68   the names of th
1ca90 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68  e columns..** Th
1caa0 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72  e remaining entr
1cab0 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f  ies all point to
1cac0 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20   query results. 
1cad0 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73   NULL values res
1cae0 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70  ult.** in NULL p
1caf0 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74  ointers.  All ot
1cb00 68 65 72 20 76 61 6c 75 65 73 20 61 72 65 20 69  her values are i
1cb10 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65  n their UTF-8 ze
1cb20 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
1cb30 20 73 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e   string represen
1cb40 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e  tation as return
1cb50 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
1cb60 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a  olumn_text()]..*
1cb70 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61  *.** A result ta
1cb80 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73  ble might consis
1cb90 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  t of one or more
1cba0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1cbb0 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f  ons..** It is no
1cbc0 74 20 73 61 66 65 20 74 6f 20 70 61 73 73 20 61  t safe to pass a
1cbd0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69   result table di
1cbe0 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74  rectly to [sqlit
1cbf0 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41  e3_free()]..** A
1cc00 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68   result table sh
1cc10 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61  ould be dealloca
1cc20 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
1cc30 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d  e3_free_table()]
1cc40 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20  ..**.** ^(As an 
1cc50 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72  example of the r
1cc60 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d  esult table form
1cc70 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75  at, suppose a qu
1cc80 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73  ery result.** is
1cc90 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
1cca0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1ccb0 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e  pre>.**        N
1ccc0 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67 65  ame        | Age
1ccd0 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d  .**        -----
1cce0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1ccf0 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69  --.**        Ali
1cd00 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a  ce       | 43.**
1cd10 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20 20          Bob     
1cd20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20      | 28.**     
1cd30 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c     Cindy       |
1cd40 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62   21.** </pre></b
1cd50 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1cd60 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20 63   There are two c
1cd70 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64  olumn (M==2) and
1cd80 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d   three rows (N==
1cd90 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a  3).  Thus the.**
1cda0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61   result table ha
1cdb0 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75  s 8 entries.  Su
1cdc0 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74  ppose the result
1cdd0 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64   table is stored
1cde0 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20  .** in an array 
1cdf0 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20  names azResult. 
1ce00 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68   Then azResult h
1ce10 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e  olds this conten
1ce20 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  t:.**.** <blockq
1ce30 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
1ce40 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1ce50 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a  1;0] = "Name";.*
1ce60 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1ce70 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22  t&#91;1] = "Age"
1ce80 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1ce90 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41  sult&#91;2] = "A
1cea0 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  lice";.**       
1ceb0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d   azResult&#91;3]
1cec0 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20   = "43";.**     
1ced0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1cee0 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20  4] = "Bob";.**  
1cef0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1cf00 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a  91;5] = "28";.**
1cf10 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1cf20 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79  &#91;6] = "Cindy
1cf30 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1cf40 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22  esult&#91;7] = "
1cf50 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  21";.** </pre></
1cf60 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
1cf70 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1cf80 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e  _get_table() fun
1cf90 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20  ction evaluates 
1cfa0 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73  one or more.** s
1cfb0 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74  emicolon-separat
1cfc0 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
1cfd0 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65  s in the zero-te
1cfe0 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a  rminated UTF-8.*
1cff0 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20  * string of its 
1d000 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e  2nd parameter an
1d010 64 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 75  d returns a resu
1d020 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a  lt table to the.
1d030 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e  ** pointer given
1d040 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 72 61   in its 3rd para
1d050 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74  meter..**.** Aft
1d060 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  er the applicati
1d070 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  on has finished 
1d080 77 69 74 68 20 74 68 65 20 72 65 73 75 6c 74 20  with the result 
1d090 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65 74  from sqlite3_get
1d0a0 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20  _table(),.** it 
1d0b0 6d 75 73 74 20 70 61 73 73 20 74 68 65 20 72 65  must pass the re
1d0c0 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e 74  sult table point
1d0d0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72  er to sqlite3_fr
1d0e0 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72  ee_table() in or
1d0f0 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73  der to.** releas
1d100 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61  e the memory tha
1d110 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20  t was malloced. 
1d120 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20   Because of the 
1d130 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  way the.** [sqli
1d140 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61  te3_malloc()] ha
1d150 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c  ppens within sql
1d160 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1d170 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a  , the calling.**
1d180 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e   function must n
1d190 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b  ot try to call [
1d1a0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
1d1b0 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a  directly.  Only.
1d1c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ** [sqlite3_free
1d1d0 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c  _table()] is abl
1d1e0 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65  e to release the
1d1f0 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79   memory properly
1d200 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a   and safely..**.
1d210 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67  ** The sqlite3_g
1d220 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72  et_table() inter
1d230 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e  face is implemen
1d240 74 65 64 20 61 73 20 61 20 77 72 61 70 70 65 72  ted as a wrapper
1d250 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69   around.** [sqli
1d260 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68  te3_exec()].  Th
1d270 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  e sqlite3_get_ta
1d280 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f  ble() routine do
1d290 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65  es not have acce
1d2a0 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74  ss.** to any int
1d2b0 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63  ernal data struc
1d2c0 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  tures of SQLite.
1d2d0 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74    It uses only t
1d2e0 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74  he public.** int
1d2f0 65 72 66 61 63 65 20 64 65 66 69 6e 65 64 20 68  erface defined h
1d300 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65  ere.  As a conse
1d310 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74  quence, errors t
1d320 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65  hat occur in the
1d330 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65  .** wrapper laye
1d340 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65  r outside of the
1d350 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74   internal [sqlit
1d360 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20  e3_exec()] call 
1d370 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65  are not.** refle
1d380 63 74 65 64 20 69 6e 20 73 75 62 73 65 71 75 65  cted in subseque
1d390 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  nt calls to [sql
1d3a0 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20  ite3_errcode()] 
1d3b0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  or.** [sqlite3_e
1d3c0 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  rrmsg()]..*/.SQL
1d3d0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
1d3e0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20  te3_get_table(. 
1d3f0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
1d400 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65         /* An ope
1d410 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20  n database */.  
1d420 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
1d430 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20  ,     /* SQL to 
1d440 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a  be evaluated */.
1d450 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73    char ***pazRes
1d460 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c  ult,    /* Resul
1d470 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20  ts of the query 
1d480 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c  */.  int *pnRow,
1d490 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75             /* Nu
1d4a0 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72  mber of result r
1d4b0 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65  ows written here
1d4c0 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c   */.  int *pnCol
1d4d0 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e  umn,        /* N
1d4e0 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20  umber of result 
1d4f0 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20  columns written 
1d500 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a  here */.  char *
1d510 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20  *pzErrmsg       
1d520 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69  /* Error msg wri
1d530 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a  tten here */.);.
1d540 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
1d550 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
1d560 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74  le(char **result
1d570 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1d580 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74  EF: Formatted St
1d590 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75  ring Printing Fu
1d5a0 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  nctions.**.** Th
1d5b0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
1d5c0 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20   work-alikes of 
1d5d0 74 68 65 20 22 70 72 69 6e 74 66 28 29 22 20 66  the "printf()" f
1d5e0 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f  amily of functio
1d5f0 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73  ns.** from the s
1d600 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
1d610 79 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  y..** These rout
1d620 69 6e 65 73 20 75 6e 64 65 72 73 74 61 6e 64 20  ines understand 
1d630 6d 6f 73 74 20 6f 66 20 74 68 65 20 63 6f 6d 6d  most of the comm
1d640 6f 6e 20 4b 26 52 20 66 6f 72 6d 61 74 74 69 6e  on K&R formattin
1d650 67 20 6f 70 74 69 6f 6e 73 2c 0a 2a 2a 20 70 6c  g options,.** pl
1d660 75 73 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e  us some addition
1d670 61 6c 20 6e 6f 6e 2d 73 74 61 6e 64 61 72 64 20  al non-standard 
1d680 66 6f 72 6d 61 74 73 2c 20 64 65 74 61 69 6c 65  formats, detaile
1d690 64 20 62 65 6c 6f 77 2e 0a 2a 2a 20 4e 6f 74 65  d below..** Note
1d6a0 20 74 68 61 74 20 73 6f 6d 65 20 6f 66 20 74 68   that some of th
1d6b0 65 20 6d 6f 72 65 20 6f 62 73 63 75 72 65 20 66  e more obscure f
1d6c0 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e  ormatting option
1d6d0 73 20 66 72 6f 6d 20 72 65 63 65 6e 74 0a 2a 2a  s from recent.**
1d6e0 20 43 2d 6c 69 62 72 61 72 79 20 73 74 61 6e 64   C-library stand
1d6f0 61 72 64 73 20 61 72 65 20 6f 6d 69 74 74 65 64  ards are omitted
1d700 20 66 72 6f 6d 20 74 68 69 73 20 69 6d 70 6c 65   from this imple
1d710 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  mentation..**.**
1d720 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70   ^The sqlite3_mp
1d730 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69  rintf() and sqli
1d740 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72  te3_vmprintf() r
1d750 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20 74 68  outines write th
1d760 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69  eir.** results i
1d770 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69  nto memory obtai
1d780 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
1d790 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20  3_malloc()]..** 
1d7a0 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75  The strings retu
1d7b0 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 74 77  rned by these tw
1d7c0 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c  o routines shoul
1d7d0 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64  d be.** released
1d7e0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   by [sqlite3_fre
1d7f0 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75  e()].  ^Both rou
1d800 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a  tines return a.*
1d810 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  * NULL pointer i
1d820 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  f [sqlite3_mallo
1d830 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74  c()] is unable t
1d840 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67  o allocate enoug
1d850 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68  h.** memory to h
1d860 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e  old the resultin
1d870 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  g string..**.** 
1d880 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6e  ^(The sqlite3_sn
1d890 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65  printf() routine
1d8a0 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22   is similar to "
1d8b0 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d  snprintf()" from
1d8c0 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64  .** the standard
1d8d0 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65   C library.  The
1d8e0 20 72 65 73 75 6c 74 20 69 73 20 77 72 69 74 74   result is writt
1d8f0 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62  en into the.** b
1d900 75 66 66 65 72 20 73 75 70 70 6c 69 65 64 20 61  uffer supplied a
1d910 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
1d920 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a  ameter whose siz
1d930 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a  e is given by.**
1d940 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
1d950 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20  eter. Note that 
1d960 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65  the order of the
1d970 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61  .** first two pa
1d980 72 61 6d 65 74 65 72 73 20 69 73 20 72 65 76 65  rameters is reve
1d990 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e  rsed from snprin
1d9a0 74 66 28 29 2e 29 5e 20 20 54 68 69 73 20 69 73  tf().)^  This is
1d9b0 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61   an.** historica
1d9c0 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61 74 20  l accident that 
1d9d0 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20  cannot be fixed 
1d9e0 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67  without breaking
1d9f0 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f  .** backwards co
1da00 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20 5e 28  mpatibility.  ^(
1da10 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73  Note also that s
1da20 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1da30 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70  ).** returns a p
1da40 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75  ointer to its bu
1da50 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20  ffer instead of 
1da60 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
1da70 20 63 68 61 72 61 63 74 65 72 73 20 61 63 74 75   characters actu
1da80 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74  ally written int
1da90 6f 20 74 68 65 20 62 75 66 66 65 72 2e 29 5e 20  o the buffer.)^ 
1daa0 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a   We admit that.*
1dab0 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
1dac0 63 68 61 72 61 63 74 65 72 73 20 77 72 69 74 74  characters writt
1dad0 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f  en would be a mo
1dae0 72 65 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e  re useful return
1daf0 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65  .** value but we
1db00 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74   cannot change t
1db10 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
1db20 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70  n of sqlite3_snp
1db30 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77  rintf().** now w
1db40 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20  ithout breaking 
1db50 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
1db60 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73  *.** ^As long as
1db70 20 74 68 65 20 62 75 66 66 65 72 20 73 69 7a 65   the buffer size
1db80 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e   is greater than
1db90 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73   zero, sqlite3_s
1dba0 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61  nprintf().** gua
1dbb0 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65  rantees that the
1dbc0 20 62 75 66 66 65 72 20 69 73 20 61 6c 77 61 79   buffer is alway
1dbd0 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  s zero-terminate
1dbe0 64 2e 20 20 5e 54 68 65 20 66 69 72 73 74 0a 2a  d.  ^The first.*
1dbf0 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20  * parameter "n" 
1dc00 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a  is the total siz
1dc10 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c  e of the buffer,
1dc20 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65   including space
1dc30 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f   for.** the zero
1dc40 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f   terminator.  So
1dc50 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72   the longest str
1dc60 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65 20  ing that can be 
1dc70 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72  completely.** wr
1dc80 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d  itten will be n-
1dc90 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  1 characters..**
1dca0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1dcb0 5f 76 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75  _vsnprintf() rou
1dcc0 74 69 6e 65 20 69 73 20 61 20 76 61 72 61 72 67  tine is a vararg
1dcd0 73 20 76 65 72 73 69 6f 6e 20 6f 66 20 73 71 6c  s version of sql
1dce0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 2e  ite3_snprintf().
1dcf0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
1dd00 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d  tines all implem
1dd10 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f  ent some additio
1dd20 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a  nal formatting.*
1dd30 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61  * options that a
1dd40 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f  re useful for co
1dd50 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73  nstructing SQL s
1dd60 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c  tatements..** Al
1dd70 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70  l of the usual p
1dd80 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69  rintf() formatti
1dd90 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79  ng options apply
1dda0 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20  .  In addition, 
1ddb0 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20  there.** is are 
1ddc0 22 25 71 22 2c 20 22 25 51 22 2c 20 22 25 77 22  "%q", "%Q", "%w"
1ddd0 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e   and "%z" option
1dde0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25  s..**.** ^(The %
1ddf0 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c  q option works l
1de00 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20 69  ike %s in that i
1de10 74 20 73 75 62 73 74 69 74 75 74 65 73 20 61 20  t substitutes a 
1de20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  nul-terminated.*
1de30 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68  * string from th
1de40 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e  e argument list.
1de50 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f    But %q also do
1de60 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27  ubles every '\''
1de70 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25   character..** %
1de80 71 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f  q is designed fo
1de90 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 73  r use inside a s
1dea0 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e  tring literal.)^
1deb0 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61    By doubling ea
1dec0 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61  ch '\''.** chara
1ded0 63 74 65 72 20 69 74 20 65 73 63 61 70 65 73 20  cter it escapes 
1dee0 74 68 61 74 20 63 68 61 72 61 63 74 65 72 20 61  that character a
1def0 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20  nd allows it to 
1df00 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f  be inserted into
1df10 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a  .** the string..
1df20 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c  **.** For exampl
1df30 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73 74  e, assume the st
1df40 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54  ring variable zT
1df50 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78  ext contains tex
1df60 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  t as follows:.**
1df70 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1df80 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a  <pre>.**  char *
1df90 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20 61 20  zText = "It's a 
1dfa0 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20  happy day!";.** 
1dfb0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1dfc0 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61  te>.**.** One ca
1dfd0 6e 20 75 73 65 20 74 68 69 73 20 74 65 78 74 20  n use this text 
1dfe0 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  in an SQL statem
1dff0 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  ent as follows:.
1e000 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1e010 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72  e><pre>.**  char
1e020 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33   *zSQL = sqlite3
1e030 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54  _mprintf("INSERT
1e040 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55   INTO table VALU
1e050 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74  ES('%q')", zText
1e060 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65  );.**  sqlite3_e
1e070 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c  xec(db, zSQL, 0,
1e080 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69   0, 0);.**  sqli
1e090 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a  te3_free(zSQL);.
1e0a0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1e0b0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63  quote>.**.** Bec
1e0c0 61 75 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d  ause the %q form
1e0d0 61 74 20 73 74 72 69 6e 67 20 69 73 20 75 73 65  at string is use
1e0e0 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61 72  d, the '\'' char
1e0f0 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a  acter in zText.*
1e100 2a 20 69 73 20 65 73 63 61 70 65 64 20 61 6e 64  * is escaped and
1e110 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74   the SQL generat
1e120 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73  ed is as follows
1e130 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1e140 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e  ote><pre>.**  IN
1e150 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31  SERT INTO table1
1e160 20 56 41 4c 55 45 53 28 27 49 74 27 27 73 20 61   VALUES('It''s a
1e170 20 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a   happy day!').**
1e180 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1e190 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ote>.**.** This 
1e1a0 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64  is correct.  Had
1e1b0 20 77 65 20 75 73 65 64 20 25 73 20 69 6e 73 74   we used %s inst
1e1c0 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67  ead of %q, the g
1e1d0 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20  enerated SQL.** 
1e1e0 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65  would have looke
1e1f0 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a  d like this:.**.
1e200 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1e210 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20  pre>.**  INSERT 
1e220 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55  INTO table1 VALU
1e230 45 53 28 27 49 74 27 73 20 61 20 68 61 70 70 79  ES('It's a happy
1e240 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72   day!');.** </pr
1e250 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
1e260 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e  **.** This secon
1e270 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20  d example is an 
1e280 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72  SQL syntax error
1e290 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20  .  As a general 
1e2a0 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a  rule you should.
1e2b0 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25 71  ** always use %q
1e2c0 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77   instead of %s w
1e2d0 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65  hen inserting te
1e2e0 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67  xt into a string
1e2f0 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20   literal..**.** 
1e300 5e 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20  ^(The %Q option 
1e310 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78  works like %q ex
1e320 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64  cept it also add
1e330 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20  s single quotes 
1e340 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75  around.** the ou
1e350 74 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74  tside of the tot
1e360 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69  al string.  Addi
1e370 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65  tionally, if the
1e380 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68   parameter in th
1e390 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69  e.** argument li
1e3a0 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  st is a NULL poi
1e3b0 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 74  nter, %Q substit
1e3c0 75 74 65 73 20 74 68 65 20 74 65 78 74 20 22 4e  utes the text "N
1e3d0 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a  ULL" (without.**
1e3e0 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e   single quotes).
1e3f0 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d  )^  So, for exam
1e400 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73  ple, one could s
1e410 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ay:.**.** <block
1e420 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1e430 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c  char *zSQL = sql
1e440 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e  ite3_mprintf("IN
1e450 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20  SERT INTO table 
1e460 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65  VALUES(%Q)", zTe
1e470 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33  xt);.**  sqlite3
1e480 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20  _exec(db, zSQL, 
1e490 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71  0, 0, 0);.**  sq
1e4a0 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29  lite3_free(zSQL)
1e4b0 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
1e4c0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
1e4d0 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69  he code above wi
1e4e0 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72  ll render a corr
1e4f0 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ect SQL statemen
1e500 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a  t in the zSQL.**
1e510 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69   variable even i
1e520 66 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 69  f the zText vari
1e530 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70  able is a NULL p
1e540 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ointer..**.** ^(
1e550 54 68 65 20 22 25 77 22 20 66 6f 72 6d 61 74 74  The "%w" formatt
1e560 69 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20 6c 69  ing option is li
1e570 6b 65 20 22 25 71 22 20 65 78 63 65 70 74 20 74  ke "%q" except t
1e580 68 61 74 20 69 74 20 65 78 70 65 63 74 73 20 74  hat it expects t
1e590 6f 0a 2a 2a 20 62 65 20 63 6f 6e 74 61 69 6e 65  o.** be containe
1e5a0 64 20 77 69 74 68 69 6e 20 64 6f 75 62 6c 65 2d  d within double-
1e5b0 71 75 6f 74 65 73 20 69 6e 73 74 65 61 64 20 6f  quotes instead o
1e5c0 66 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 2c  f single quotes,
1e5d0 20 61 6e 64 20 69 74 0a 2a 2a 20 65 73 63 61 70   and it.** escap
1e5e0 65 73 20 74 68 65 20 64 6f 75 62 6c 65 2d 71 75  es the double-qu
1e5f0 6f 74 65 20 63 68 61 72 61 63 74 65 72 20 69 6e  ote character in
1e600 73 74 65 61 64 20 6f 66 20 74 68 65 20 73 69 6e  stead of the sin
1e610 67 6c 65 2d 71 75 6f 74 65 0a 2a 2a 20 63 68 61  gle-quote.** cha
1e620 72 61 63 74 65 72 2e 29 5e 20 20 54 68 65 20 22  racter.)^  The "
1e630 25 77 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f  %w" formatting o
1e640 70 74 69 6f 6e 20 69 73 20 69 6e 74 65 6e 64 65  ption is intende
1e650 64 20 66 6f 72 20 73 61 66 65 6c 79 20 69 6e 73  d for safely ins
1e660 65 72 74 69 6e 67 0a 2a 2a 20 74 61 62 6c 65 20  erting.** table 
1e670 61 6e 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 73  and column names
1e680 20 69 6e 74 6f 20 61 20 63 6f 6e 73 74 72 75 63   into a construc
1e690 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ted SQL statemen
1e6a0 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22  t..**.** ^(The "
1e6b0 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f  %z" formatting o
1e6c0 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
1e6d0 20 22 25 73 22 20 62 75 74 20 77 69 74 68 20 74   "%s" but with t
1e6e0 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74  he.** addition t
1e6f0 68 61 74 20 61 66 74 65 72 20 74 68 65 20 73 74  hat after the st
1e700 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65  ring has been re
1e710 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e  ad and copied in
1e720 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74  to.** the result
1e730 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  , [sqlite3_free(
1e740 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20  )] is called on 
1e750 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
1e760 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  .)^.*/.SQLITE_AP
1e770 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  I char *sqlite3_
1e780 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68  mprintf(const ch
1e790 61 72 2a 2c 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45  ar*,...);.SQLITE
1e7a0 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74  _API char *sqlit
1e7b0 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73  e3_vmprintf(cons
1e7c0 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74  t char*, va_list
1e7d0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68  );.SQLITE_API ch
1e7e0 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72  ar *sqlite3_snpr
1e7f0 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63  intf(int,char*,c
1e800 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29  onst char*, ...)
1e810 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61  ;.SQLITE_API cha
1e820 72 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e 70 72  r *sqlite3_vsnpr
1e830 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63  intf(int,char*,c
1e840 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c  onst char*, va_l
1e850 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ist);../*.** CAP
1e860 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c  I3REF: Memory Al
1e870 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74  location Subsyst
1e880 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  em.**.** The SQL
1e890 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 74 68  ite core uses th
1e8a0 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e  ese three routin
1e8b0 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  es for all of it
1e8c0 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61  s own.** interna
1e8d0 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
1e8e0 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65  ion needs. "Core
1e8f0 22 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75  " in the previou
1e900 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f  s sentence.** do
1e910 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f  es not include o
1e920 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20  perating-system 
1e930 73 70 65 63 69 66 69 63 20 56 46 53 20 69 6d 70  specific VFS imp
1e940 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68  lementation.  Th
1e950 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53  e.** Windows VFS
1e960 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c   uses native mal
1e970 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29  loc() and free()
1e980 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74   for some operat
1e990 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ions..**.** ^The
1e9a0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1e9b0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
1e9c0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
1e9d0 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d   block.** of mem
1e9e0 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62  ory at least N b
1e9f0 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20  ytes in length, 
1ea00 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 70  where N is the p
1ea10 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66  arameter..** ^If
1ea20 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1ea30 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f  ) is unable to o
1ea40 62 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74  btain sufficient
1ea50 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c   free.** memory,
1ea60 20 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55   it returns a NU
1ea70 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66  LL pointer.  ^If
1ea80 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e   the parameter N
1ea90 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d   to.** sqlite3_m
1eaa0 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20  alloc() is zero 
1eab0 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  or negative then
1eac0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1ead0 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e  ) returns.** a N
1eae0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
1eaf0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1eb00 6d 61 6c 6c 6f 63 36 34 28 4e 29 20 72 6f 75 74  malloc64(N) rout
1eb10 69 6e 65 20 77 6f 72 6b 73 20 6a 75 73 74 20 6c  ine works just l
1eb20 69 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d  ike.** sqlite3_m
1eb30 61 6c 6c 6f 63 28 4e 29 20 65 78 63 65 70 74 20  alloc(N) except 
1eb40 74 68 61 74 20 4e 20 69 73 20 61 6e 20 75 6e 73  that N is an uns
1eb50 69 67 6e 65 64 20 36 34 2d 62 69 74 20 69 6e 74  igned 64-bit int
1eb60 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20  eger instead.** 
1eb70 6f 66 20 61 20 73 69 67 6e 65 64 20 33 32 2d 62  of a signed 32-b
1eb80 69 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a  it integer..**.*
1eb90 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74  * ^Calling sqlit
1eba0 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20 61  e3_free() with a
1ebb0 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75   pointer previou
1ebc0 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  sly returned.** 
1ebd0 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  by sqlite3_mallo
1ebe0 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  c() or sqlite3_r
1ebf0 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65  ealloc() release
1ec00 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f  s that memory so
1ec10 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68  .** that it migh
1ec20 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e 54  t be reused.  ^T
1ec30 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  he sqlite3_free(
1ec40 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20  ) routine is.** 
1ec50 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61  a no-op if is ca
1ec60 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c  lled with a NULL
1ec70 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69   pointer.  Passi
1ec80 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ng a NULL pointe
1ec90 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  r.** to sqlite3_
1eca0 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65  free() is harmle
1ecb0 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67  ss.  After being
1ecc0 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a   freed, memory.*
1ecd0 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72  * should neither
1ece0 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69   be read nor wri
1ecf0 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64  tten.  Even read
1ed00 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66  ing previously f
1ed10 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d  reed.** memory m
1ed20 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61  ight result in a
1ed30 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61   segmentation fa
1ed40 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76  ult or other sev
1ed50 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65  ere error..** Me
1ed60 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c  mory corruption,
1ed70 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20   a segmentation 
1ed80 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20  fault, or other 
1ed90 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20  severe error.** 
1eda0 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20  might result if 
1edb0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69  sqlite3_free() i
1edc0 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  s called with a 
1edd0 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  non-NULL pointer
1ede0 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74   that.** was not
1edf0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73   obtained from s
1ee00 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1ee10 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  or sqlite3_reall
1ee20 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  oc()..**.** ^The
1ee30 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1ee40 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20  (X,N) interface 
1ee50 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69  attempts to resi
1ee60 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65  ze a.** prior me
1ee70 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1ee80 58 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74  X to be at least
1ee90 20 4e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66   N bytes..** ^If
1eea0 20 74 68 65 20 58 20 70 61 72 61 6d 65 74 65 72   the X parameter
1eeb0 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
1eec0 6c 6f 63 28 58 2c 4e 29 0a 2a 2a 20 69 73 20 61  loc(X,N).** is a
1eed0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
1eee0 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72 20  en its behavior 
1eef0 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20  is identical to 
1ef00 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74  calling.** sqlit
1ef10 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 2e 0a 2a 2a  e3_malloc(N)..**
1ef20 20 5e 49 66 20 74 68 65 20 4e 20 70 61 72 61 6d   ^If the N param
1ef30 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
1ef40 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 73 20  realloc(X,N) is 
1ef50 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74  zero or.** negat
1ef60 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 65 68  ive then the beh
1ef70 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79  avior is exactly
1ef80 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c   the same as cal
1ef90 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ling.** sqlite3_
1efa0 66 72 65 65 28 58 29 2e 0a 2a 2a 20 5e 73 71 6c  free(X)..** ^sql
1efb0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e  ite3_realloc(X,N
1efc0 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  ) returns a poin
1efd0 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20  ter to a memory 
1efe0 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66  allocation.** of
1eff0 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
1f000 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c  s in size or NUL
1f010 4c 20 69 66 20 69 6e 73 75 66 66 69 63 69 65 6e  L if insufficien
1f020 74 20 6d 65 6d 6f 72 79 20 69 73 20 61 76 61 69  t memory is avai
1f030 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20  lable..** ^If M 
1f040 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  is the size of t
1f050 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
1f060 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c  ion, then min(N,
1f070 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74  M) bytes.** of t
1f080 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
1f090 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69  ion are copied i
1f0a0 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e  nto the beginnin
1f0b0 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 74 75  g of buffer retu
1f0c0 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74  rned.** by sqlit
1f0d0 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20  e3_realloc(X,N) 
1f0e0 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c  and the prior al
1f0f0 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65  location is free
1f100 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  d..** ^If sqlite
1f110 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72  3_realloc(X,N) r
1f120 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 20  eturns NULL and 
1f130 4e 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20 74  N is positive, t
1f140 68 65 6e 20 74 68 65 0a 2a 2a 20 70 72 69 6f 72  hen the.** prior
1f150 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 6e   allocation is n
1f160 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20  ot freed..**.** 
1f170 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61  ^The sqlite3_rea
1f180 6c 6c 6f 63 36 34 28 58 2c 4e 29 20 69 6e 74 65  lloc64(X,N) inte
1f190 72 66 61 63 65 73 20 77 6f 72 6b 73 20 74 68 65  rfaces works the
1f1a0 20 73 61 6d 65 20 61 73 0a 2a 2a 20 73 71 6c 69   same as.** sqli
1f1b0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
1f1c0 20 65 78 63 65 70 74 20 74 68 61 74 20 4e 20 69   except that N i
1f1d0 73 20 61 20 36 34 2d 62 69 74 20 75 6e 73 69 67  s a 64-bit unsig
1f1e0 6e 65 64 20 69 6e 74 65 67 65 72 20 69 6e 73 74  ned integer inst
1f1f0 65 61 64 0a 2a 2a 20 6f 66 20 61 20 33 32 2d 62  ead.** of a 32-b
1f200 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
1f210 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 58 20 69  r..**.** ^If X i
1f220 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  s a memory alloc
1f230 61 74 69 6f 6e 20 70 72 65 76 69 6f 75 73 6c 79  ation previously
1f240 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73   obtained from s
1f250 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c  qlite3_malloc(),
1f260 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
1f270 6f 63 36 34 28 29 2c 20 73 71 6c 69 74 65 33 5f  oc64(), sqlite3_
1f280 72 65 61 6c 6c 6f 63 28 29 2c 20 6f 72 20 73 71  realloc(), or sq
1f290 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28  lite3_realloc64(
1f2a0 29 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  ), then.** sqlit
1f2b0 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 75  e3_msize(X) retu
1f2c0 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20  rns the size of 
1f2d0 74 68 61 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  that memory allo
1f2e0 63 61 74 69 6f 6e 20 69 6e 20 62 79 74 65 73 2e  cation in bytes.
1f2f0 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 20 72  .** ^The value r
1f300 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
1f310 65 33 5f 6d 73 69 7a 65 28 58 29 20 6d 69 67 68  e3_msize(X) migh
1f320 74 20 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e  t be larger than
1f330 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f   the number.** o
1f340 66 20 62 79 74 65 73 20 72 65 71 75 65 73 74 65  f bytes requeste
1f350 64 20 77 68 65 6e 20 58 20 77 61 73 20 61 6c 6c  d when X was all
1f360 6f 63 61 74 65 64 2e 20 20 5e 49 66 20 58 20 69  ocated.  ^If X i
1f370 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
1f380 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   then.** sqlite3
1f390 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 75 72 6e  _msize(X) return
1f3a0 73 20 7a 65 72 6f 2e 20 20 49 66 20 58 20 70 6f  s zero.  If X po
1f3b0 69 6e 74 73 20 74 6f 20 73 6f 6d 65 74 68 69 6e  ints to somethin
1f3c0 67 20 74 68 61 74 20 69 73 20 6e 6f 74 0a 2a 2a  g that is not.**
1f3d0 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
1f3e0 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  f memory allocat
1f3f0 69 6f 6e 2c 20 6f 72 20 69 66 20 69 74 20 70 6f  ion, or if it po
1f400 69 6e 74 73 20 74 6f 20 61 20 66 6f 72 6d 65 72  ints to a former
1f410 6c 79 0a 2a 2a 20 76 61 6c 69 64 20 6d 65 6d 6f  ly.** valid memo
1f420 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 68  ry allocation th
1f430 61 74 20 68 61 73 20 6e 6f 77 20 62 65 65 6e 20  at has now been 
1f440 66 72 65 65 64 2c 20 74 68 65 6e 20 74 68 65 20  freed, then the 
1f450 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 73  behavior.** of s
1f460 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20  qlite3_msize(X) 
1f470 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  is undefined and
1f480 20 70 6f 73 73 69 62 6c 79 20 68 61 72 6d 66 75   possibly harmfu
1f490 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65  l..**.** ^The me
1f4a0 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 79  mory returned by
1f4b0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1f4c0 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  ), sqlite3_reall
1f4d0 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  oc(),.** sqlite3
1f4e0 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 61 6e 64  _malloc64(), and
1f4f0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1f500 36 34 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79  64().** is alway
1f510 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20  s aligned to at 
1f520 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74 65 20  least an 8 byte 
1f530 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f 20  boundary, or to 
1f540 61 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f 75 6e  a.** 4 byte boun
1f550 64 61 72 79 20 69 66 20 74 68 65 20 5b 53 51 4c  dary if the [SQL
1f560 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47 4e  ITE_4_BYTE_ALIGN
1f570 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69  ED_MALLOC] compi
1f580 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f  le-time.** optio
1f590 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  n is used..**.**
1f5a0 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69   In SQLite versi
1f5b0 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35  on 3.5.0 and 3.5
1f5c0 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69  .1, it was possi
1f5d0 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a  ble to define.**
1f5e0 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54   the SQLITE_OMIT
1f5f0 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49  _MEMORY_ALLOCATI
1f600 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63  ON which would c
1f610 61 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69  ause the built-i
1f620 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  n.** implementat
1f630 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75  ion of these rou
1f640 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74  tines to be omit
1f650 74 65 64 2e 20 20 54 68 61 74 20 63 61 70 61 62  ted.  That capab
1f660 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c  ility.** is no l
1f670 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20  onger provided. 
1f680 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d   Only built-in m
1f690 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73  emory allocators
1f6a0 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a   can be used..**
1f6b0 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51 4c  .** Prior to SQL
1f6c0 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e  ite version 3.7.
1f6d0 31 30 2c 20 74 68 65 20 57 69 6e 64 6f 77 73 20  10, the Windows 
1f6e0 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79  OS interface lay
1f6f0 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 68 65  er called.** the
1f700 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29   system malloc()
1f710 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72 65   and free() dire
1f720 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72  ctly when conver
1f730 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65  ting.** filename
1f740 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55 54  s between the UT
1f750 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65  F-8 encoding use
1f760 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61  d by SQLite.** a
1f770 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c 65  nd whatever file
1f780 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73  name encoding is
1f790 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61 72   used by the par
1f7a0 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a  ticular Windows.
1f7b0 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e  ** installation.
1f7c0 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74    Memory allocat
1f7d0 69 6f 6e 20 65 72 72 6f 72 73 20 77 65 72 65 20  ion errors were 
1f7e0 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a  detected, but.**
1f7f0 20 74 68 65 79 20 77 65 72 65 20 72 65 70 6f 72   they were repor
1f800 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c  ted back as [SQL
1f810 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72  ITE_CANTOPEN] or
1f820 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  .** [SQLITE_IOER
1f830 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b  R] rather than [
1f840 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a  SQLITE_NOMEM]..*
1f850 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72  *.** The pointer
1f860 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73   arguments to [s
1f870 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61  qlite3_free()] a
1f880 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  nd [sqlite3_real
1f890 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62  loc()].** must b
1f8a0 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72  e either NULL or
1f8b0 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f   else pointers o
1f8c0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70  btained from a p
1f8d0 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69  rior.** invocati
1f8e0 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  on of [sqlite3_m
1f8f0 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c  alloc()] or [sql
1f900 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20  ite3_realloc()] 
1f910 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74  that have.** not
1f920 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73   yet been releas
1f930 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70  ed..**.** The ap
1f940 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
1f950 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 74 65  ot read or write
1f960 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20   any part of.** 
1f970 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72  a block of memor
1f980 79 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62  y after it has b
1f990 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69  een released usi
1f9a0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  ng.** [sqlite3_f
1f9b0 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  ree()] or [sqlit
1f9c0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  e3_realloc()]..*
1f9d0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  /.SQLITE_API voi
1f9e0 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  d *sqlite3_mallo
1f9f0 63 28 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  c(int);.SQLITE_A
1fa00 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  PI void *sqlite3
1fa10 5f 6d 61 6c 6c 6f 63 36 34 28 73 71 6c 69 74 65  _malloc64(sqlite
1fa20 33 5f 75 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54  3_uint64);.SQLIT
1fa30 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69  E_API void *sqli
1fa40 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64  te3_realloc(void
1fa50 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  *, int);.SQLITE_
1fa60 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  API void *sqlite
1fa70 33 5f 72 65 61 6c 6c 6f 63 36 34 28 76 6f 69 64  3_realloc64(void
1fa80 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  *, sqlite3_uint6
1fa90 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  4);.SQLITE_API v
1faa0 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65  oid sqlite3_free
1fab0 28 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f  (void*);.SQLITE_
1fac0 41 50 49 20 73 71 6c 69 74 65 33 5f 75 69 6e 74  API sqlite3_uint
1fad0 36 34 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65  64 sqlite3_msize
1fae0 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  (void*);../*.** 
1faf0 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
1fb00 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69   Allocator Stati
1fb10 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  stics.**.** SQLi
1fb20 74 65 20 70 72 6f 76 69 64 65 73 20 74 68 65 73  te provides thes
1fb30 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73  e two interfaces
1fb40 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f   for reporting o
1fb50 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20  n the status.** 
1fb60 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
1fb70 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69  malloc()], [sqli
1fb80 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64  te3_free()], and
1fb90 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
1fba0 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  c()].** routines
1fbb0 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65  , which form the
1fbc0 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79   built-in memory
1fbd0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73   allocation subs
1fbe0 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ystem..**.** ^Th
1fbf0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  e [sqlite3_memor
1fc00 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e  y_used()] routin
1fc10 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
1fc20 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a  mber of bytes.**
1fc30 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65   of memory curre
1fc40 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67  ntly outstanding
1fc50 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e   (malloced but n
1fc60 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54  ot freed)..** ^T
1fc70 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  he [sqlite3_memo
1fc80 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
1fc90 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
1fca0 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76  the maximum.** v
1fcb0 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33  alue of [sqlite3
1fcc0 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
1fcd0 73 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77  since the high-w
1fce0 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73  ater mark.** was
1fcf0 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e 54   last reset.  ^T
1fd00 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
1fd10 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d  ed by [sqlite3_m
1fd20 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e  emory_used()] an
1fd30 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65  d.** [sqlite3_me
1fd40 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
1fd50 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76  ] include any ov
1fd60 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 20  erhead.** added 
1fd70 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73  by SQLite in its
1fd80 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
1fd90 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  of [sqlite3_mall
1fda0 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f  oc()],.** but no
1fdb0 74 20 6f 76 65 72 68 65 61 64 20 61 64 64 65 64  t overhead added
1fdc0 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65   by the any unde
1fdd0 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69  rlying system li
1fde0 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65  brary.** routine
1fdf0 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  s that [sqlite3_
1fe00 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61  malloc()] may ca
1fe10 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d  ll..**.** ^The m
1fe20 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72  emory high-water
1fe30 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20 74   mark is reset t
1fe40 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61  o the current va
1fe50 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74  lue of.** [sqlit
1fe60 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
1fe70 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  ] if and only if
1fe80 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 74   the parameter t
1fe90 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65  o.** [sqlite3_me
1fea0 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
1feb0 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68 65  ] is true.  ^The
1fec0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a   value returned.
1fed0 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d  ** by [sqlite3_m
1fee0 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
1fef0 31 29 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d  1)] is the high-
1ff00 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72  water mark.** pr
1ff10 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65 74  ior to the reset
1ff20 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
1ff30 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
1ff40 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
1ff50 64 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  d(void);.SQLITE_
1ff60 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  API sqlite3_int6
1ff70 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  4 sqlite3_memory
1ff80 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 20 72  _highwater(int r
1ff90 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a  esetFlag);../*.*
1ffa0 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 65 75  * CAPI3REF: Pseu
1ffb0 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72  do-Random Number
1ffc0 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a   Generator.**.**
1ffd0 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73   SQLite contains
1ffe0 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20   a high-quality 
1fff0 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75  pseudo-random nu
20000 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28  mber generator (
20010 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a  PRNG) used to.**
20020 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b   select random [
20030 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20  ROWID | ROWIDs] 
20040 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e  when inserting n
20050 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20  ew records into 
20060 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20  a table that.** 
20070 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 65  already uses the
20080 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c   largest possibl
20090 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20  e [ROWID].  The 
200a0 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65  PRNG is also use
200b0 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69  d for.** the bui
200c0 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61  ld-in random() a
200d0 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20  nd randomblob() 
200e0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20  SQL functions.  
200f0 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61  This interface a
20100 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61  llows.** applica
20110 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20  tions to access 
20120 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f  the same PRNG fo
20130 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73  r other purposes
20140 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20  ..**.** ^A call 
20150 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  to this routine 
20160 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f  stores N bytes o
20170 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74  f randomness int
20180 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 20 5e  o buffer P..** ^
20190 54 68 65 20 50 20 70 61 72 61 6d 65 74 65 72 20  The P parameter 
201a0 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f  can be a NULL po
201b0 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  inter..**.** ^If
201c0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68 61   this routine ha
201d0 73 20 6e 6f 74 20 62 65 65 6e 20 70 72 65 76 69  s not been previ
201e0 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20 6f 72 20  ously called or 
201f0 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 0a  if the previous.
20200 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e 20 6c 65  ** call had N le
20210 73 73 20 74 68 61 6e 20 6f 6e 65 20 6f 72 20 61  ss than one or a
20220 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f   NULL pointer fo
20230 72 20 50 2c 20 74 68 65 6e 20 74 68 65 20 50 52  r P, then the PR
20240 4e 47 20 69 73 0a 2a 2a 20 73 65 65 64 65 64 20  NG is.** seeded 
20250 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73  using randomness
20260 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 74   obtained from t
20270 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d  he xRandomness m
20280 65 74 68 6f 64 20 6f 66 0a 2a 2a 20 74 68 65 20  ethod of.** the 
20290 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
202a0 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  _vfs] object..**
202b0 20 5e 49 66 20 74 68 65 20 70 72 65 76 69 6f 75   ^If the previou
202c0 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72  s call to this r
202d0 6f 75 74 69 6e 65 20 68 61 64 20 61 6e 20 4e 20  outine had an N 
202e0 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20 61 6e 64  of 1 or more and
202f0 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c 20 50   a.** non-NULL P
20300 20 74 68 65 6e 20 74 68 65 20 70 73 65 75 64 6f   then the pseudo
20310 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67  -randomness is g
20320 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65  enerated.** inte
20330 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f  rnally and witho
20340 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74  ut recourse to t
20350 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  he [sqlite3_vfs]
20360 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20   xRandomness.** 
20370 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 53 51 4c 49 54  method..*/.SQLIT
20380 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
20390 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e  e3_randomness(in
203a0 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a  t N, void *P);..
203b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
203c0 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74  Compile-Time Aut
203d0 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62  horization Callb
203e0 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  acks.** METHOD: 
203f0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
20400 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69  his routine regi
20410 73 74 65 72 73 20 61 6e 20 61 75 74 68 6f 72 69  sters an authori
20420 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74  zer callback wit
20430 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a  h a particular.*
20440 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
20450 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65  ection], supplie
20460 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  d in the first a
20470 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  rgument..** ^The
20480 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
20490 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
204a0 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  as SQL statement
204b0 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70  s are being comp
204c0 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69  iled.** by [sqli
204d0 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
204e0 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b  r its variants [
204f0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
20500 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  v2()],.** [sqlit
20510 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20  e3_prepare16()] 
20520 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
20530 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e  pare16_v2()].  ^
20540 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f  At various.** po
20550 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 20  ints during the 
20560 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63  compilation proc
20570 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73  ess, as logic is
20580 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a   being created.*
20590 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72  * to perform var
205a0 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68  ious actions, th
205b0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
205c0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
205d0 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68   to.** see if th
205e0 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20  ose actions are 
205f0 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61  allowed.  ^The a
20600 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
20610 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74  ck should.** ret
20620 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
20630 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74  to allow the act
20640 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e  ion, [SQLITE_IGN
20650 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77  ORE] to disallow
20660 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63   the.** specific
20670 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f   action but allo
20680 77 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  w the SQL statem
20690 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20  ent to continue 
206a0 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65  to be.** compile
206b0 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45  d, or [SQLITE_DE
206c0 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65  NY] to cause the
206d0 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74   entire SQL stat
206e0 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72  ement to be.** r
206f0 65 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e 20  ejected with an 
20700 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20  error.  ^If the 
20710 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
20720 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  ack returns.** a
20730 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74  ny value other t
20740 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  han [SQLITE_IGNO
20750 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  RE], [SQLITE_OK]
20760 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e  , or [SQLITE_DEN
20770 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b  Y].** then the [
20780 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
20790 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c  v2()] or equival
207a0 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72  ent call that tr
207b0 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61  iggered.** the a
207c0 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66  uthorizer will f
207d0 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ail with an erro
207e0 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a  r message..**.**
207f0 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61   When the callba
20800 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
20810 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61  TE_OK], that mea
20820 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  ns the operation
20830 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69 73  .** requested is
20840 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20   ok.  ^When the 
20850 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
20860 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20   [SQLITE_DENY], 
20870 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
20880 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
20890 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c   equivalent call
208a0 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20   that triggered 
208b0 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65  the.** authorize
208c0 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68  r will fail with
208d0 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
208e0 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61  e explaining tha
208f0 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64  t.** access is d
20900 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54  enied. .**.** ^T
20910 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
20920 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  er to the author
20930 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
20940 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74   a copy of the t
20950 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65  hird.** paramete
20960 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
20970 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
20980 29 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68  ) interface. ^Th
20990 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
209a0 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c  er.** to the cal
209b0 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65  lback is an inte
209c0 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59  ger [SQLITE_COPY
209d0 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20   | action code] 
209e0 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a  that specifies.*
209f0 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72  * the particular
20a00 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75   action to be au
20a10 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74  thorized. ^The t
20a20 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78  hird through six
20a30 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a  th parameters.**
20a40 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
20a50 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   are zero-termin
20a60 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61  ated strings tha
20a70 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69  t contain additi
20a80 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20  onal.** details 
20a90 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e  about the action
20aa0 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65   to be authorize
20ab0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
20ac0 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20   action code is 
20ad0 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a  [SQLITE_READ].**
20ae0 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63   and the callbac
20af0 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
20b00 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74  E_IGNORE] then t
20b10 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
20b20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65  statement] state
20b30 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63  ment is construc
20b40 74 65 64 20 74 6f 20 73 75 62 73 74 69 74 75 74  ted to substitut
20b50 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75  e.** a NULL valu
20b60 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68  e in place of th
20b70 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74  e table column t
20b80 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a  hat would have.*
20b90 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b  * been read if [
20ba0 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62  SQLITE_OK] had b
20bb0 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54  een returned.  T
20bc0 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  he [SQLITE_IGNOR
20bd0 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e  E].** return can
20be0 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79   be used to deny
20bf0 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73   an untrusted us
20c00 65 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64  er access to ind
20c10 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d  ividual.** colum
20c20 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a  ns of a table..*
20c30 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e  * ^If the action
20c40 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45   code is [SQLITE
20c50 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65  _DELETE] and the
20c60 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
20c70 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e  s.** [SQLITE_IGN
20c80 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44  ORE] then the [D
20c90 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e  ELETE] operation
20ca0 20 70 72 6f 63 65 65 64 73 20 62 75 74 20 74 68   proceeds but th
20cb0 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f  e.** [truncate o
20cc0 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20  ptimization] is 
20cd0 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c  disabled and all
20ce0 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65   rows are delete
20cf0 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a  d individually..
20d00 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69  **.** An authori
20d10 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 65 6e  zer is used when
20d20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
20d30 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a  e | preparing].*
20d40 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
20d50 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74   from an untrust
20d60 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e  ed source, to en
20d70 73 75 72 65 20 74 68 61 74 20 74 68 65 20 53 51  sure that the SQ
20d80 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
20d90 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63  do not try to ac
20da0 63 65 73 73 20 64 61 74 61 20 74 68 65 79 20 61  cess data they a
20db0 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74  re not allowed t
20dc0 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74  o see, or that t
20dd0 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72  hey do not.** tr
20de0 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c  y to execute mal
20df0 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74  icious statement
20e00 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 68  s that damage th
20e10 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72  e database.  For
20e20 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20  .** example, an 
20e30 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20  application may 
20e40 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20  allow a user to 
20e50 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 0a  enter arbitrary.
20e60 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 66  ** SQL queries f
20e70 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79  or evaluation by
20e80 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 75   a database.  Bu
20e90 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
20ea0 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61  n does.** not wa
20eb0 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 62  nt the user to b
20ec0 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61  e able to make a
20ed0 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 73  rbitrary changes
20ee0 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62   to the.** datab
20ef0 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69  ase.  An authori
20f00 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62  zer could then b
20f10 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77  e put in place w
20f20 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72  hile the.** user
20f30 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20  -entered SQL is 
20f40 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  being [sqlite3_p
20f50 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 65  repare | prepare
20f60 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c  d] that.** disal
20f70 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67 20  lows everything 
20f80 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20  except [SELECT] 
20f90 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
20fa0 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * Applications t
20fb0 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63  hat need to proc
20fc0 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74  ess SQL from unt
20fd0 72 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a  rusted sources.*
20fe0 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e  * might also con
20ff0 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72  sider lowering r
21000 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75  esource limits u
21010 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69  sing [sqlite3_li
21020 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69  mit()].** and li
21030 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73 65 20  miting database 
21040 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b  size using the [
21050 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20  max_page_count] 
21060 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61  [PRAGMA].** in a
21070 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67  ddition to using
21080 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a   an authorizer..
21090 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73  **.** ^(Only a s
210a0 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72  ingle authorizer
210b0 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65   can be in place
210c0 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 63   on a database c
210d0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20  onnection.** at 
210e0 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61  a time.  Each ca
210f0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65  ll to sqlite3_se
21100 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65  t_authorizer ove
21110 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72  rrides the.** pr
21120 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20  evious call.)^  
21130 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61 75 74  ^Disable the aut
21140 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61  horizer by insta
21150 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c  lling a NULL cal
21160 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75  lback..** The au
21170 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61  thorizer is disa
21180 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e  bled by default.
21190 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  .**.** The autho
211a0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d  rizer callback m
211b0 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68  ust not do anyth
211c0 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f  ing that will mo
211d0 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61  dify.** the data
211e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
211f0 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
21200 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
21210 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  back..** Note th
21220 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  at [sqlite3_prep
21230 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
21240 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62  qlite3_step()] b
21250 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72  oth modify their
21260 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
21270 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  nections for the
21280 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64   meaning of "mod
21290 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72  ify" in this par
212a0 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57  agraph..**.** ^W
212b0 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hen [sqlite3_pre
212c0 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73  pare_v2()] is us
212d0 65 64 20 74 6f 20 70 72 65 70 61 72 65 20 61 20  ed to prepare a 
212e0 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a  statement, the.*
212f0 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68  * statement migh
21300 74 20 62 65 20 72 65 2d 70 72 65 70 61 72 65 64  t be re-prepared
21310 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33   during [sqlite3
21320 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20  _step()] due to 
21330 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61  a .** schema cha
21340 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65  nge.  Hence, the
21350 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
21360 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74 20  uld ensure that 
21370 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61  the.** correct a
21380 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
21390 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c  ck remains in pl
213a0 61 63 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b  ace during the [
213b0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
213c0 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61  .**.** ^Note tha
213d0 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  t the authorizer
213e0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
213f0 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67  oked only during
21400 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
21410 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76  pare()] or its v
21420 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72  ariants.  Author
21430 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a  ization is not.*
21440 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69  * performed duri
21450 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61  ng statement eva
21460 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69  luation in [sqli
21470 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c  te3_step()], unl
21480 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64  ess.** as stated
21490 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73   in the previous
214a0 20 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69   paragraph, sqli
214b0 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b  te3_step() invok
214c0 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72  es.** sqlite3_pr
214d0 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65  epare_v2() to re
214e0 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d  prepare a statem
214f0 65 6e 74 20 61 66 74 65 72 20 61 20 73 63 68 65  ent after a sche
21500 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 53 51  ma change..*/.SQ
21510 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
21520 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
21530 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  zer(.  sqlite3*,
21540 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28  .  int (*xAuth)(
21550 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
21560 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
21570 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  *,const char*,co
21580 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f  nst char*),.  vo
21590 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b  id *pUserData.);
215a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
215b0 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74  : Authorizer Ret
215c0 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20  urn Codes.**.** 
215d0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  The [sqlite3_set
215e0 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
215f0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
21600 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74  k function] must
21610 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65  .** return eithe
21620 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72  r [SQLITE_OK] or
21630 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77   one of these tw
21640 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f  o constants in o
21650 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61  rder.** to signa
21660 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68 65 72  l SQLite whether
21670 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69   or not the acti
21680 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e  on is permitted.
21690 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71    See the.** [sq
216a0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
216b0 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65  izer | authorize
216c0 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d  r documentation]
216d0 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a   for additional.
216e0 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  ** information..
216f0 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
21700 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 69 73  SQLITE_IGNORE is
21710 20 61 6c 73 6f 20 75 73 65 64 20 61 73 20 61 20   also used as a 
21720 5b 63 6f 6e 66 6c 69 63 74 20 72 65 73 6f 6c 75  [conflict resolu
21730 74 69 6f 6e 20 6d 6f 64 65 5d 0a 2a 2a 20 72 65  tion mode].** re
21740 74 75 72 6e 65 64 20 66 72 6f 6d 20 74 68 65 20  turned from the 
21750 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e  [sqlite3_vtab_on
21760 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69 6e 74  _conflict()] int
21770 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69  erface..*/.#defi
21780 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20  ne SQLITE_DENY  
21790 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68   1   /* Abort th
217a0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
217b0 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f  with an error */
217c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
217d0 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f  IGNORE 2   /* Do
217e0 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73  n't allow access
217f0 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65  , but don't gene
21800 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f  rate an error */
21810 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
21820 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74  : Authorizer Act
21830 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20  ion Codes.**.** 
21840 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  The [sqlite3_set
21850 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69  _authorizer()] i
21860 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
21870 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  rs a callback fu
21880 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69  nction.** that i
21890 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74  s invoked to aut
218a0 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20 53  horize certain S
218b0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74  QL statement act
218c0 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65  ions.  The.** se
218d0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
218e0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
218f0 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64  s an integer cod
21900 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73  e that specifies
21910 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20  .** what action 
21920 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69  is being authori
21930 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65 20  zed.  These are 
21940 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74 69  the integer acti
21950 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a  on codes that.**
21960 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
21970 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20  callback may be 
21980 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  passed..**.** Th
21990 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20  ese action code 
219a0 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77  values signify w
219b0 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72  hat kind of oper
219c0 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a  ation is to be.*
219d0 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54  * authorized.  T
219e0 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 70  he 3rd and 4th p
219f0 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65  arameters to the
21a00 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a   authorization.*
21a10 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  * callback funct
21a20 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61  ion will be para
21a30 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64  meters or NULL d
21a40 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63  epending on whic
21a50 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f  h of these.** co
21a60 64 65 73 20 69 73 20 75 73 65 64 20 61 73 20 74  des is used as t
21a70 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
21a80 74 65 72 2e 20 20 5e 28 54 68 65 20 35 74 68 20  ter.  ^(The 5th 
21a90 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
21aa0 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63  .** authorizer c
21ab0 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e  allback is the n
21ac0 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
21ad0 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65  ase ("main", "te
21ae0 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66  mp",.** etc.) if
21af0 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20 20   applicable.)^  
21b00 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d 65 74  ^The 6th paramet
21b10 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  er to the author
21b20 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  izer callback.**
21b30 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
21b40 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74  the inner-most t
21b50 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 20 74  rigger or view t
21b60 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62  hat is responsib
21b70 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63  le for.** the ac
21b80 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20  cess attempt or 
21b90 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63  NULL if this acc
21ba0 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 20 64  ess attempt is d
21bb0 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20  irectly from.** 
21bc0 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f  top-level SQL co
21bd0 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a  de..*/./********
21be0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
21bf0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
21c00 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a  *** 3rd ********
21c10 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a  **** 4th *******
21c20 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ****/.#define SQ
21c30 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45  LITE_CREATE_INDE
21c40 58 20 20 20 20 20 20 20 20 20 20 31 20 20 20 2f  X          1   /
21c50 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
21c60 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
21c70 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
21c80 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45  ITE_CREATE_TABLE
21c90 20 20 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a            2   /*
21ca0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
21cb0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
21cc0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
21cd0 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49  TE_CREATE_TEMP_I
21ce0 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20  NDEX     3   /* 
21cf0 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
21d00 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
21d10 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
21d20 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41  E_CREATE_TEMP_TA
21d30 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54  BLE     4   /* T
21d40 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
21d50 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
21d60 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
21d70 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49  _CREATE_TEMP_TRI
21d80 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72  GGER   5   /* Tr
21d90 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
21da0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
21db0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
21dc0 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57  CREATE_TEMP_VIEW
21dd0 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65        6   /* Vie
21de0 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
21df0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
21e00 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
21e10 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 20 20  REATE_TRIGGER   
21e20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67       7   /* Trig
21e30 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
21e40 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
21e50 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
21e60 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 20 20  EATE_VIEW       
21e70 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20      8   /* View 
21e80 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
21e90 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
21ea0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c  efine SQLITE_DEL
21eb0 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ETE             
21ec0 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20     9   /* Table 
21ed0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
21ee0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
21ef0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
21f00 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  _INDEX          
21f10 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   10   /* Index N
21f20 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
21f30 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
21f40 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
21f50 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20  TABLE           
21f60 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  11   /* Table Na
21f70 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
21f80 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
21f90 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
21fa0 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31  EMP_INDEX      1
21fb0 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  2   /* Index Nam
21fc0 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
21fd0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
21fe0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
21ff0 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33  MP_TABLE      13
22000 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
22010 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
22020 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
22030 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
22040 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 34 20  P_TRIGGER    14 
22050 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
22060 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
22070 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
22080 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
22090 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 20 20  _VIEW       15  
220a0 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
220b0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
220c0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
220d0 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47  QLITE_DROP_TRIGG
220e0 45 52 20 20 20 20 20 20 20 20 20 31 36 20 20 20  ER         16   
220f0 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
22100 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
22110 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
22120 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20  LITE_DROP_VIEW  
22130 20 20 20 20 20 20 20 20 20 20 31 37 20 20 20 2f            17   /
22140 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
22150 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
22160 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22170 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20  ITE_INSERT      
22180 20 20 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a           18   /*
22190 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
221a0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
221b0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
221c0 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20  TE_PRAGMA       
221d0 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20          19   /* 
221e0 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20  Pragma Name     
221f0 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20  1st arg or NULL 
22200 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22210 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20  E_READ          
22220 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54         20   /* T
22230 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43  able Name      C
22240 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a  olumn Name     *
22250 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22260 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20  _SELECT         
22270 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55        21   /* NU
22280 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55  LL            NU
22290 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
222a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
222b0 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20  TRANSACTION     
222c0 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 65       22   /* Ope
222d0 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c  ration       NUL
222e0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
222f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
22300 50 44 41 54 45 20 20 20 20 20 20 20 20 20 20 20  PDATE           
22310 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c      23   /* Tabl
22320 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75  e Name      Colu
22330 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  mn Name     */.#
22340 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54  define SQLITE_AT
22350 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20  TACH            
22360 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e     24   /* Filen
22370 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20  ame        NULL 
22380 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
22390 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54  efine SQLITE_DET
223a0 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20  ACH             
223b0 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61    25   /* Databa
223c0 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20  se Name   NULL  
223d0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
223e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45  fine SQLITE_ALTE
223f0 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  R_TABLE         
22400 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73   26   /* Databas
22410 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e  e Name   Table N
22420 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
22430 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44  ine SQLITE_REIND
22440 45 58 20 20 20 20 20 20 20 20 20 20 20 20 20 20  EX              
22450 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  27   /* Index Na
22460 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
22470 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
22480 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a  ne SQLITE_ANALYZ
22490 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32  E              2
224a0 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  8   /* Table Nam
224b0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
224c0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
224d0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
224e0 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 32 39  VTABLE        29
224f0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
22500 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d        Module Nam
22510 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
22520 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41   SQLITE_DROP_VTA
22530 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 30 20  BLE          30 
22540 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
22550 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65       Module Name
22560 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
22570 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20  SQLITE_FUNCTION 
22580 20 20 20 20 20 20 20 20 20 20 20 20 33 31 20 20              31  
22590 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20   /* NULL        
225a0 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d      Function Nam
225b0 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  e   */.#define S
225c0 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 20  QLITE_SAVEPOINT 
225d0 20 20 20 20 20 20 20 20 20 20 20 33 32 20 20 20             32   
225e0 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20  /* Operation    
225f0 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d     Savepoint Nam
22600 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e  */.#define SQ
22610 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20  LITE_COPY       
22620 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f             0   /
22630 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64  * No longer used
22640 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
22650 54 45 5f 52 45 43 55 52 53 49 56 45 20 20 20 20  TE_RECURSIVE    
22660 20 20 20 20 20 20 20 20 33 33 20 20 20 2f 2a 20          33   /* 
22670 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
22680 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
22690 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
226a0 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20  EF: Tracing And 
226b0 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69  Profiling Functi
226c0 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ons.** METHOD: s
226d0 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65  qlite3.**.** The
226e0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
226f0 64 65 70 72 65 63 61 74 65 64 2e 20 55 73 65 20  deprecated. Use 
22700 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 72 61  the [sqlite3_tra
22710 63 65 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61  ce_v2()] interfa
22720 63 65 0a 2a 2a 20 69 6e 73 74 65 61 64 20 6f 66  ce.** instead of
22730 20 74 68 65 20 72 6f 75 74 69 6e 65 73 20 64 65   the routines de
22740 73 63 72 69 62 65 64 20 68 65 72 65 2e 0a 2a 2a  scribed here..**
22750 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
22760 65 73 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c  es register call
22770 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74  back functions t
22780 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 64 20  hat can be used 
22790 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61  for.** tracing a
227a0 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65  nd profiling the
227b0 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51   execution of SQ
227c0 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
227d0 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63  .** ^The callbac
227e0 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73  k function regis
227f0 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33  tered by sqlite3
22800 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f  _trace() is invo
22810 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75  ked at.** variou
22820 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20  s times when an 
22830 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73  SQL statement is
22840 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73   being run by [s
22850 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a  qlite3_step()]..
22860 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
22870 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b  trace() callback
22880 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   is invoked with
22890 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69   a UTF-8 renderi
228a0 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c  ng of the.** SQL
228b0 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
228c0 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  as the statement
228d0 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 65 78   first begins ex
228e0 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64  ecuting..** ^(Ad
228f0 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33  ditional sqlite3
22900 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63  _trace() callbac
22910 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a  ks might occur.*
22920 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 67 65  * as each trigge
22930 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69  red subprogram i
22940 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20  s entered.  The 
22950 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72  callbacks for tr
22960 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69  iggers.** contai
22970 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f  n a UTF-8 SQL co
22980 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74  mment that ident
22990 69 66 69 65 73 20 74 68 65 20 74 72 69 67 67 65  ifies the trigge
229a0 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  r.)^.**.** The [
229b0 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 49 5a  SQLITE_TRACE_SIZ
229c0 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65  E_LIMIT] compile
229d0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 63 61 6e  -time option can
229e0 20 62 65 20 75 73 65 64 20 74 6f 20 6c 69 6d 69   be used to limi
229f0 74 0a 2a 2a 20 74 68 65 20 6c 65 6e 67 74 68 20  t.** the length 
22a00 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65  of [bound parame
22a10 74 65 72 5d 20 65 78 70 61 6e 73 69 6f 6e 20 69  ter] expansion i
22a20 6e 20 74 68 65 20 6f 75 74 70 75 74 20 6f 66 20  n the output of 
22a30 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 2e  sqlite3_trace().
22a40 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c  .**.** ^The call
22a50 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65  back function re
22a60 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69  gistered by sqli
22a70 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73  te3_profile() is
22a80 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65   invoked.** as e
22a90 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ach SQL statemen
22aa0 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 68  t finishes.  ^Th
22ab0 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61  e profile callba
22ac0 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74  ck contains.** t
22ad0 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74  he original stat
22ae0 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61  ement text and a
22af0 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61  n estimate of wa
22b00 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a  ll-clock time.**
22b10 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61   of how long tha
22b20 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b  t statement took
22b30 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20 70   to run.  ^The p
22b40 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a  rofile callback.
22b50 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e 20 75 6e  ** time is in un
22b60 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e  its of nanosecon
22b70 64 73 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20  ds, however the 
22b80 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e  current implemen
22b90 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c  tation.** is onl
22ba0 79 20 63 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c  y capable of mil
22bb0 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74  lisecond resolut
22bc0 69 6f 6e 20 73 6f 20 74 68 65 20 73 69 78 20 6c  ion so the six l
22bd0 65 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74  east significant
22be0 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e 20 74 68  .** digits in th
22bf0 65 20 74 69 6d 65 20 61 72 65 20 6d 65 61 6e 69  e time are meani
22c00 6e 67 6c 65 73 73 2e 20 20 46 75 74 75 72 65 20  ngless.  Future 
22c10 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
22c20 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76  te.** might prov
22c30 69 64 65 20 67 72 65 61 74 65 72 20 72 65 73 6f  ide greater reso
22c40 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72  lution on the pr
22c50 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e  ofiler callback.
22c60 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33    The.** sqlite3
22c70 5f 70 72 6f 66 69 6c 65 28 29 20 66 75 6e 63 74  _profile() funct
22c80 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 72 65  ion is considere
22c90 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61  d experimental a
22ca0 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74  nd is.** subject
22cb0 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66 75   to change in fu
22cc0 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
22cd0 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49   SQLite..*/.SQLI
22ce0 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45  TE_API SQLITE_DE
22cf0 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 2a 73  PRECATED void *s
22d00 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c  qlite3_trace(sql
22d10 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a  ite3*,.   void(*
22d20 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f  xTrace)(void*,co
22d30 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64  nst char*), void
22d40 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53  *);.SQLITE_API S
22d50 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
22d60 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70   void *sqlite3_p
22d70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c  rofile(sqlite3*,
22d80 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69  .   void(*xProfi
22d90 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20  le)(void*,const 
22da0 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69  char*,sqlite3_ui
22db0 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  nt64), void*);..
22dc0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
22dd0 53 51 4c 20 54 72 61 63 65 20 45 76 65 6e 74 20  SQL Trace Event 
22de0 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  Codes.** KEYWORD
22df0 53 3a 20 53 51 4c 49 54 45 5f 54 52 41 43 45 0a  S: SQLITE_TRACE.
22e00 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
22e10 74 61 6e 74 73 20 69 64 65 6e 74 69 66 79 20 63  tants identify c
22e20 6c 61 73 73 65 73 20 6f 66 20 65 76 65 6e 74 73  lasses of events
22e30 20 74 68 61 74 20 63 61 6e 20 62 65 20 6d 6f 6e   that can be mon
22e40 69 74 6f 72 65 64 0a 2a 2a 20 75 73 69 6e 67 20  itored.** using 
22e50 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 72 61  the [sqlite3_tra
22e60 63 65 5f 76 32 28 29 5d 20 74 72 61 63 69 6e 67  ce_v2()] tracing
22e70 20 6c 6f 67 69 63 2e 20 20 54 68 65 20 74 68 69   logic.  The thi
22e80 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74  rd argument.** t
22e90 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65  o [sqlite3_trace
22ea0 5f 76 32 28 29 5d 20 69 73 20 61 6e 20 4f 52 2d  _v2()] is an OR-
22eb0 65 64 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f  ed combination o
22ec0 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66  f one or more of
22ed0 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  .** the followin
22ee0 67 20 63 6f 6e 73 74 61 6e 74 73 2e 20 20 5e 54  g constants.  ^T
22ef0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
22f00 74 20 74 6f 20 74 68 65 20 74 72 61 63 65 20 63  t to the trace c
22f10 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6f 6e  allback.** is on
22f20 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
22f30 6e 67 20 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a  ng constants..**
22f40 0a 2a 2a 20 4e 65 77 20 74 72 61 63 69 6e 67 20  .** New tracing 
22f50 63 6f 6e 73 74 61 6e 74 73 20 6d 61 79 20 62 65  constants may be
22f60 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
22f70 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a   releases..**.**
22f80 20 5e 41 20 74 72 61 63 65 20 63 61 6c 6c 62 61   ^A trace callba
22f90 63 6b 20 68 61 73 20 66 6f 75 72 20 61 72 67 75  ck has four argu
22fa0 6d 65 6e 74 73 3a 20 78 43 61 6c 6c 62 61 63 6b  ments: xCallback
22fb0 28 54 2c 43 2c 50 2c 58 29 2e 0a 2a 2a 20 5e 54  (T,C,P,X)..** ^T
22fc0 68 65 20 54 20 61 72 67 75 6d 65 6e 74 20 69 73  he T argument is
22fd0 20 6f 6e 65 20 6f 66 20 74 68 65 20 69 6e 74 65   one of the inte
22fe0 67 65 72 20 74 79 70 65 20 63 6f 64 65 73 20 61  ger type codes a
22ff0 62 6f 76 65 2e 0a 2a 2a 20 5e 54 68 65 20 43 20  bove..** ^The C 
23000 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 63 6f  argument is a co
23010 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 78  py of the contex
23020 74 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64  t pointer passed
23030 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f   in as the.** fo
23040 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  urth argument to
23050 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f   [sqlite3_trace_
23060 76 32 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 50 20  v2()]..** The P 
23070 61 6e 64 20 58 20 61 72 67 75 6d 65 6e 74 73 20  and X arguments 
23080 61 72 65 20 70 6f 69 6e 74 65 72 73 20 77 68 6f  are pointers who
23090 73 65 20 6d 65 61 6e 69 6e 67 73 20 64 65 70 65  se meanings depe
230a0 6e 64 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20 3c  nd on T..**.** <
230b0 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  dl>.** [[SQLITE_
230c0 54 52 41 43 45 5f 53 54 4d 54 5d 5d 20 3c 64 74  TRACE_STMT]] <dt
230d0 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 54  >SQLITE_TRACE_ST
230e0 4d 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e  MT</dt>.** <dd>^
230f0 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  An SQLITE_TRACE_
23100 53 54 4d 54 20 63 61 6c 6c 62 61 63 6b 20 69 73  STMT callback is
23110 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61 20   invoked when a 
23120 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
23130 6e 74 0a 2a 2a 20 66 69 72 73 74 20 62 65 67 69  nt.** first begi
23140 6e 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 70  ns running and p
23150 6f 73 73 69 62 6c 79 20 61 74 20 6f 74 68 65 72  ossibly at other
23160 20 74 69 6d 65 73 20 64 75 72 69 6e 67 20 74 68   times during th
23170 65 0a 2a 2a 20 65 78 65 63 75 74 69 6f 6e 20 6f  e.** execution o
23180 66 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  f the prepared s
23190 74 61 74 65 6d 65 6e 74 2c 20 73 75 63 68 20 61  tatement, such a
231a0 73 20 61 74 20 74 68 65 20 73 74 61 72 74 20 6f  s at the start o
231b0 66 20 65 61 63 68 0a 2a 2a 20 74 72 69 67 67 65  f each.** trigge
231c0 72 20 73 75 62 70 72 6f 67 72 61 6d 2e 20 5e 54  r subprogram. ^T
231d0 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73  he P argument is
231e0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
231f0 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
23200 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 65 20  tatement]. ^The 
23210 58 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  X argument is a 
23220 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74 72  pointer to a str
23230 69 6e 67 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ing which.** is 
23240 74 68 65 20 75 6e 65 78 70 61 6e 64 65 64 20 53  the unexpanded S
23250 51 4c 20 74 65 78 74 20 6f 66 20 74 68 65 20 70  QL text of the p
23260 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
23270 74 20 6f 72 20 61 6e 20 53 51 4c 20 63 6f 6d 6d  t or an SQL comm
23280 65 6e 74 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64  ent .** that ind
23290 69 63 61 74 65 73 20 74 68 65 20 69 6e 76 6f 63  icates the invoc
232a0 61 74 69 6f 6e 20 6f 66 20 61 20 74 72 69 67 67  ation of a trigg
232b0 65 72 2e 20 20 5e 54 68 65 20 63 61 6c 6c 62 61  er.  ^The callba
232c0 63 6b 20 63 61 6e 20 63 6f 6d 70 75 74 65 0a 2a  ck can compute.*
232d0 2a 20 74 68 65 20 73 61 6d 65 20 74 65 78 74 20  * the same text 
232e0 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 20  that would have 
232f0 62 65 65 6e 20 72 65 74 75 72 6e 65 64 20 62 79  been returned by
23300 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c   the legacy [sql
23310 69 74 65 33 5f 74 72 61 63 65 28 29 5d 0a 2a 2a  ite3_trace()].**
23320 20 69 6e 74 65 72 66 61 63 65 20 62 79 20 75 73   interface by us
23330 69 6e 67 20 74 68 65 20 58 20 61 72 67 75 6d 65  ing the X argume
23340 6e 74 20 77 68 65 6e 20 58 20 62 65 67 69 6e 73  nt when X begins
23350 20 77 69 74 68 20 22 2d 2d 22 20 61 6e 64 20 69   with "--" and i
23360 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  nvoking.** [sqli
23370 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c  te3_expanded_sql
23380 28 50 29 5d 20 6f 74 68 65 72 77 69 73 65 2e 0a  (P)] otherwise..
23390 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54  **.** [[SQLITE_T
233a0 52 41 43 45 5f 50 52 4f 46 49 4c 45 5d 5d 20 3c  RACE_PROFILE]] <
233b0 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  dt>SQLITE_TRACE_
233c0 50 52 4f 46 49 4c 45 3c 2f 64 74 3e 0a 2a 2a 20  PROFILE</dt>.** 
233d0 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54  <dd>^An SQLITE_T
233e0 52 41 43 45 5f 50 52 4f 46 49 4c 45 20 63 61 6c  RACE_PROFILE cal
233f0 6c 62 61 63 6b 20 70 72 6f 76 69 64 65 73 20 61  lback provides a
23400 70 70 72 6f 78 69 6d 61 74 65 6c 79 20 74 68 65  pproximately the
23410 20 73 61 6d 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61   same.** informa
23420 74 69 6f 6e 20 61 73 20 69 73 20 70 72 6f 76 69  tion as is provi
23430 64 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  ded by the [sqli
23440 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 20 63  te3_profile()] c
23450 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65  allback..** ^The
23460 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61   P argument is a
23470 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
23480 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
23490 65 6e 74 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20  ent] and the.** 
234a0 58 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74  X argument point
234b0 73 20 74 6f 20 61 20 36 34 2d 62 69 74 20 69 6e  s to a 64-bit in
234c0 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 74  teger which is t
234d0 68 65 20 65 73 74 69 6d 61 74 65 64 20 6f 66 0a  he estimated of.
234e0 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
234f0 20 6e 61 6e 6f 73 65 63 6f 6e 64 20 74 68 61 74   nanosecond that
23500 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
23510 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20  atement took to 
23520 72 75 6e 2e 0a 2a 2a 20 5e 54 68 65 20 53 51 4c  run..** ^The SQL
23530 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c  ITE_TRACE_PROFIL
23540 45 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  E callback is in
23550 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20 73  voked when the s
23560 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65  tatement finishe
23570 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  s..**.** [[SQLIT
23580 45 5f 54 52 41 43 45 5f 52 4f 57 5d 5d 20 3c 64  E_TRACE_ROW]] <d
23590 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52  t>SQLITE_TRACE_R
235a0 4f 57 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e  OW</dt>.** <dd>^
235b0 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  An SQLITE_TRACE_
235c0 52 4f 57 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ROW callback is 
235d0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
235e0 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73   a prepared.** s
235f0 74 61 74 65 6d 65 6e 74 20 67 65 6e 65 72 61 74  tatement generat
23600 65 73 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20  es a single row 
23610 6f 66 20 72 65 73 75 6c 74 2e 20 20 0a 2a 2a 20  of result.  .** 
23620 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20  ^The P argument 
23630 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
23640 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
23650 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 74 68 65  atement] and the
23660 0a 2a 2a 20 58 20 61 72 67 75 6d 65 6e 74 20 69  .** X argument i
23670 73 20 75 6e 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  s unused..**.** 
23680 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43  [[SQLITE_TRACE_C
23690 4c 4f 53 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  LOSE]] <dt>SQLIT
236a0 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 3c 2f 64  E_TRACE_CLOSE</d
236b0 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51  t>.** <dd>^An SQ
236c0 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45  LITE_TRACE_CLOSE
236d0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
236e0 6f 6b 65 64 20 77 68 65 6e 20 61 20 64 61 74 61  oked when a data
236f0 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
23700 6f 6e 20 63 6c 6f 73 65 73 2e 0a 2a 2a 20 5e 54  on closes..** ^T
23710 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73  he P argument is
23720 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
23730 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
23740 65 63 74 69 6f 6e 5d 20 6f 62 6a 65 63 74 0a 2a  ection] object.*
23750 2a 20 61 6e 64 20 74 68 65 20 58 20 61 72 67 75  * and the X argu
23760 6d 65 6e 74 20 69 73 20 75 6e 75 73 65 64 2e 0a  ment is unused..
23770 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
23780 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45  ine SQLITE_TRACE
23790 5f 53 54 4d 54 20 20 20 20 20 20 20 30 78 30 31  _STMT       0x01
237a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
237b0 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 20 20 20  TRACE_PROFILE   
237c0 20 30 78 30 32 0a 23 64 65 66 69 6e 65 20 53 51   0x02.#define SQ
237d0 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 20 20  LITE_TRACE_ROW  
237e0 20 20 20 20 20 20 30 78 30 34 0a 23 64 65 66 69        0x04.#defi
237f0 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  ne SQLITE_TRACE_
23800 43 4c 4f 53 45 20 20 20 20 20 20 30 78 30 38 0a  CLOSE      0x08.
23810 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
23820 20 53 51 4c 20 54 72 61 63 65 20 48 6f 6f 6b 0a   SQL Trace Hook.
23830 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
23840 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  e3.**.** ^The sq
23850 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 44  lite3_trace_v2(D
23860 2c 4d 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63  ,M,X,P) interfac
23870 65 20 72 65 67 69 73 74 65 72 73 20 61 20 74 72  e registers a tr
23880 61 63 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  ace callback.** 
23890 66 75 6e 63 74 69 6f 6e 20 58 20 61 67 61 69 6e  function X again
238a0 73 74 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  st [database con
238b0 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 75 73 69 6e  nection] D, usin
238c0 67 20 70 72 6f 70 65 72 74 79 20 6d 61 73 6b 20  g property mask 
238d0 4d 0a 2a 2a 20 61 6e 64 20 63 6f 6e 74 65 78 74  M.** and context
238e0 20 70 6f 69 6e 74 65 72 20 50 2e 20 20 5e 49 66   pointer P.  ^If
238f0 20 74 68 65 20 58 20 63 61 6c 6c 62 61 63 6b 20   the X callback 
23900 69 73 0a 2a 2a 20 4e 55 4c 4c 20 6f 72 20 69 66  is.** NULL or if
23910 20 74 68 65 20 4d 20 6d 61 73 6b 20 69 73 20 7a   the M mask is z
23920 65 72 6f 2c 20 74 68 65 6e 20 74 72 61 63 69 6e  ero, then tracin
23930 67 20 69 73 20 64 69 73 61 62 6c 65 64 2e 20 20  g is disabled.  
23940 54 68 65 0a 2a 2a 20 4d 20 61 72 67 75 6d 65 6e  The.** M argumen
23950 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20  t should be the 
23960 62 69 74 77 69 73 65 20 4f 52 2d 65 64 20 63 6f  bitwise OR-ed co
23970 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20  mbination of.** 
23980 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 5b 53 51  zero or more [SQ
23990 4c 49 54 45 5f 54 52 41 43 45 5d 20 63 6f 6e 73  LITE_TRACE] cons
239a0 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 45 61  tants..**.** ^Ea
239b0 63 68 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65  ch call to eithe
239c0 72 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  r sqlite3_trace(
239d0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 74 72 61  ) or sqlite3_tra
239e0 63 65 5f 76 32 28 29 20 6f 76 65 72 72 69 64 65  ce_v2() override
239f0 73 20 0a 2a 2a 20 28 63 61 6e 63 65 6c 73 29 20  s .** (cancels) 
23a00 61 6e 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 20  any prior calls 
23a10 74 6f 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  to sqlite3_trace
23a20 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 74 72  () or sqlite3_tr
23a30 61 63 65 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20  ace_v2()..**.** 
23a40 5e 54 68 65 20 58 20 63 61 6c 6c 62 61 63 6b 20  ^The X callback 
23a50 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  is invoked whene
23a60 76 65 72 20 61 6e 79 20 6f 66 20 74 68 65 20 65  ver any of the e
23a70 76 65 6e 74 73 20 69 64 65 6e 74 69 66 69 65 64  vents identified
23a80 20 62 79 20 0a 2a 2a 20 6d 61 73 6b 20 4d 20 6f   by .** mask M o
23a90 63 63 75 72 2e 20 20 5e 54 68 65 20 69 6e 74 65  ccur.  ^The inte
23aa0 67 65 72 20 72 65 74 75 72 6e 20 76 61 6c 75 65  ger return value
23ab0 20 66 72 6f 6d 20 74 68 65 20 63 61 6c 6c 62 61   from the callba
23ac0 63 6b 20 69 73 20 63 75 72 72 65 6e 74 6c 79 0a  ck is currently.
23ad0 2a 2a 20 69 67 6e 6f 72 65 64 2c 20 74 68 6f 75  ** ignored, thou
23ae0 67 68 20 74 68 69 73 20 6d 61 79 20 63 68 61 6e  gh this may chan
23af0 67 65 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ge in future rel
23b00 65 61 73 65 73 2e 20 20 43 61 6c 6c 62 61 63 6b  eases.  Callback
23b10 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
23b20 6f 6e 73 20 73 68 6f 75 6c 64 20 72 65 74 75 72  ons should retur
23b30 6e 20 7a 65 72 6f 20 74 6f 20 65 6e 73 75 72 65  n zero to ensure
23b40 20 66 75 74 75 72 65 20 63 6f 6d 70 61 74 69 62   future compatib
23b50 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20  ility..**.** ^A 
23b60 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 69  trace callback i
23b70 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 66  s invoked with f
23b80 6f 75 72 20 61 72 67 75 6d 65 6e 74 73 3a 20 63  our arguments: c
23b90 61 6c 6c 62 61 63 6b 28 54 2c 43 2c 50 2c 58 29  allback(T,C,P,X)
23ba0 2e 0a 2a 2a 20 5e 54 68 65 20 54 20 61 72 67 75  ..** ^The T argu
23bb0 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 74  ment is one of t
23bc0 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45  he [SQLITE_TRACE
23bd0 5d 0a 2a 2a 20 63 6f 6e 73 74 61 6e 74 73 20 74  ].** constants t
23be0 6f 20 69 6e 64 69 63 61 74 65 20 77 68 79 20 74  o indicate why t
23bf0 68 65 20 63 61 6c 6c 62 61 63 6b 20 77 61 73 20  he callback was 
23c00 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e 54 68 65  invoked..** ^The
23c10 20 43 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61   C argument is a
23c20 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e   copy of the con
23c30 74 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  text pointer..**
23c40 20 54 68 65 20 50 20 61 6e 64 20 58 20 61 72 67   The P and X arg
23c50 75 6d 65 6e 74 73 20 61 72 65 20 70 6f 69 6e 74  uments are point
23c60 65 72 73 20 77 68 6f 73 65 20 6d 65 61 6e 69 6e  ers whose meanin
23c70 67 73 20 64 65 70 65 6e 64 20 6f 6e 20 54 2e 0a  gs depend on T..
23c80 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
23c90 33 5f 74 72 61 63 65 5f 76 32 28 29 20 69 6e 74  3_trace_v2() int
23ca0 65 72 66 61 63 65 20 69 73 20 69 6e 74 65 6e 64  erface is intend
23cb0 65 64 20 74 6f 20 72 65 70 6c 61 63 65 20 74 68  ed to replace th
23cc0 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  e legacy.** inte
23cd0 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f  rfaces [sqlite3_
23ce0 74 72 61 63 65 28 29 5d 20 61 6e 64 20 5b 73 71  trace()] and [sq
23cf0 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d  lite3_profile()]
23d00 2c 20 62 6f 74 68 20 6f 66 20 77 68 69 63 68 0a  , both of which.
23d10 2a 2a 20 61 72 65 20 64 65 70 72 65 63 61 74 65  ** are deprecate
23d20 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  d..*/.SQLITE_API
23d30 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61   int sqlite3_tra
23d40 63 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  ce_v2(.  sqlite3
23d50 2a 2c 0a 20 20 75 6e 73 69 67 6e 65 64 20 75 4d  *,.  unsigned uM
23d60 61 73 6b 2c 0a 20 20 69 6e 74 28 2a 78 43 61 6c  ask,.  int(*xCal
23d70 6c 62 61 63 6b 29 28 75 6e 73 69 67 6e 65 64 2c  lback)(unsigned,
23d80 76 6f 69 64 2a 2c 76 6f 69 64 2a 2c 76 6f 69 64  void*,void*,void
23d90 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 43 74 78  *),.  void *pCtx
23da0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
23db0 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72  REF: Query Progr
23dc0 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ess Callbacks.**
23dd0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
23de0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
23df0 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
23e00 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e  dler(D,N,X,P) in
23e10 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 74  terface causes t
23e20 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66  he callback.** f
23e30 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 20  unction X to be 
23e40 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63  invoked periodic
23e50 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67  ally during long
23e60 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74   running calls t
23e70 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  o.** [sqlite3_ex
23e80 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ec()], [sqlite3_
23e90 73 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c  step()] and [sql
23ea0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
23eb0 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73  ] for.** databas
23ec0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20  e connection D. 
23ed0 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20   An example use 
23ee0 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65  for this.** inte
23ef0 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70  rface is to keep
23f00 20 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64   a GUI updated d
23f10 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75  uring a large qu
23f20 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ery..**.** ^The 
23f30 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 70  parameter P is p
23f40 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73  assed through as
23f50 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65   the only parame
23f60 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63  ter to the .** c
23f70 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
23f80 20 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65   X.  ^The parame
23f90 74 65 72 20 4e 20 69 73 20 74 68 65 20 61 70 70  ter N is the app
23fa0 72 6f 78 69 6d 61 74 65 20 6e 75 6d 62 65 72 20  roximate number 
23fb0 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20  of .** [virtual 
23fc0 6d 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63 74  machine instruct
23fd0 69 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 20 65  ions] that are e
23fe0 76 61 6c 75 61 74 65 64 20 62 65 74 77 65 65 6e  valuated between
23ff0 20 73 75 63 63 65 73 73 69 76 65 0a 2a 2a 20 69   successive.** i
24000 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
24010 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e 20 20 5e  e callback X.  ^
24020 49 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61  If N is less tha
24030 6e 20 6f 6e 65 20 74 68 65 6e 20 74 68 65 20 70  n one then the p
24040 72 6f 67 72 65 73 73 0a 2a 2a 20 68 61 6e 64 6c  rogress.** handl
24050 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 2e 0a  er is disabled..
24060 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69  **.** ^Only a si
24070 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68 61  ngle progress ha
24080 6e 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65 66  ndler may be def
24090 69 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d 65  ined at one time
240a0 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73   per.** [databas
240b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73  e connection]; s
240c0 65 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72 6f  etting a new pro
240d0 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61  gress handler ca
240e0 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64  ncels the.** old
240f0 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67 20   one.  ^Setting 
24100 70 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20 4e  parameter X to N
24110 55 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68 65  ULL disables the
24120 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
24130 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72  r..** ^The progr
24140 65 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20 61  ess handler is a
24150 6c 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79 20  lso disabled by 
24160 73 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20 76  setting N to a v
24170 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61  alue less.** tha
24180 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  n 1..**.** ^If t
24190 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c  he progress call
241a0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e  back returns non
241b0 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61  -zero, the opera
241c0 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72  tion is.** inter
241d0 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65  rupted.  This fe
241e0 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65  ature can be use
241f0 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61  d to implement a
24200 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74  .** "Cancel" but
24210 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f  ton on a GUI pro
24220 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78  gress dialog box
24230 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67  ..**.** The prog
24240 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c  ress handler cal
24250 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64  lback must not d
24260 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20  o anything that 
24270 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74  will modify.** t
24280 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
24290 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
242a0 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65 73 73  ked the progress
242b0 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74   handler..** Not
242c0 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  e that [sqlite3_
242d0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
242e0 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  d [sqlite3_step(
242f0 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74  )] both modify t
24300 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65  heir.** database
24310 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72   connections for
24320 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20   the meaning of 
24330 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73  "modify" in this
24340 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a   paragraph..**.*
24350 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  /.SQLITE_API voi
24360 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65  d sqlite3_progre
24370 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74  ss_handler(sqlit
24380 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29  e3*, int, int(*)
24390 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b  (void*), void*);
243a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
243b0 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20  : Opening A New 
243c0 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
243d0 69 6f 6e 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54  ion.** CONSTRUCT
243e0 4f 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OR: sqlite3.**.*
243f0 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
24400 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65  s open an SQLite
24410 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 61   database file a
24420 73 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  s specified by t
24430 68 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20  he .** filename 
24440 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66  argument. ^The f
24450 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
24460 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
24470 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20  as UTF-8 for.** 
24480 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
24490 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nd sqlite3_open_
244a0 76 32 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d  v2() and as UTF-
244b0 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  16 in the native
244c0 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66   byte.** order f
244d0 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  or sqlite3_open1
244e0 36 28 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61  6(). ^(A [databa
244f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68  se connection] h
24500 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79  andle is usually
24510 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20  .** returned in 
24520 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61  *ppDb, even if a
24530 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20  n error occurs. 
24540 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74   The only except
24550 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69  ion is that.** i
24560 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62  f SQLite is unab
24570 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  le to allocate m
24580 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
24590 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
245a0 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69  ct,.** a NULL wi
245b0 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e  ll be written in
245c0 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64  to *ppDb instead
245d0 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   of a pointer to
245e0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a   the [sqlite3].*
245f0 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66  * object.)^ ^(If
24600 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
24610 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20   opened (and/or 
24620 63 72 65 61 74 65 64 29 20 73 75 63 63 65 73 73  created) success
24630 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b  fully, then.** [
24640 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65  SQLITE_OK] is re
24650 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69  turned.  Otherwi
24660 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  se an [error cod
24670 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29  e] is returned.)
24680 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ^ ^The.** [sqlit
24690 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20  e3_errmsg()] or 
246a0 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  [sqlite3_errmsg1
246b0 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61  6()] routines ca
246c0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74  n be used to obt
246d0 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73  ain.** an Englis
246e0 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72  h language descr
246f0 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72  iption of the er
24700 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  ror following a 
24710 66 61 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a  failure of any.*
24720 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  * of the sqlite3
24730 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73  _open() routines
24740 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66  ..**.** ^The def
24750 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 77 69  ault encoding wi
24760 6c 6c 20 62 65 20 55 54 46 2d 38 20 66 6f 72 20  ll be UTF-8 for 
24770 64 61 74 61 62 61 73 65 73 20 63 72 65 61 74 65  databases create
24780 64 20 75 73 69 6e 67 0a 2a 2a 20 73 71 6c 69 74  d using.** sqlit
24790 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c  e3_open() or sql
247a0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20  ite3_open_v2(). 
247b0 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e   ^The default en
247c0 63 6f 64 69 6e 67 20 66 6f 72 20 64 61 74 61 62  coding for datab
247d0 61 73 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20  ases.** created 
247e0 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70  using sqlite3_op
247f0 65 6e 31 36 28 29 20 77 69 6c 6c 20 62 65 20 55  en16() will be U
24800 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74  TF-16 in the nat
24810 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
24820 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72  **.** Whether or
24830 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63   not an error oc
24840 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 20  curs when it is 
24850 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65  opened, resource
24860 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  s.** associated 
24870 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61  with the [databa
24880 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68  se connection] h
24890 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20  andle should be 
248a0 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70  released by.** p
248b0 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71  assing it to [sq
248c0 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77  lite3_close()] w
248d0 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e  hen it is no lon
248e0 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a  ger required..**
248f0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
24900 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66  open_v2() interf
24910 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73  ace works like s
24920 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a  qlite3_open().**
24930 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20   except that it 
24940 61 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 69  accepts two addi
24950 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72  tional parameter
24960 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  s for additional
24970 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72   control.** over
24980 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73   the new databas
24990 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e  e connection.  ^
249a0 28 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d  (The flags param
249b0 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  eter to.** sqlit
249c0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e  e3_open_v2() can
249d0 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20   take one of.** 
249e0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  the following th
249f0 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69  ree values, opti
24a00 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20  onally combined 
24a10 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51  with the .** [SQ
24a20 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
24a30 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  X], [SQLITE_OPEN
24a40 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51  _FULLMUTEX], [SQ
24a50 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
24a60 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  CACHE],.** [SQLI
24a70 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
24a80 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53  ACHE], and/or [S
24a90 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20  QLITE_OPEN_URI] 
24aa0 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c  flags:)^.**.** <
24ab0 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  dl>.** ^(<dt>[SQ
24ac0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
24ad0 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LY]</dt>.** <dd>
24ae0 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
24af0 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f  opened in read-o
24b00 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68  nly mode.  If th
24b10 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20  e database does 
24b20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65  not.** already e
24b30 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69  xist, an error i
24b40 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e  s returned.</dd>
24b50 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b  )^.**.** ^(<dt>[
24b60 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
24b70 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  WRITE]</dt>.** <
24b80 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
24b90 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
24ba0 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e  ading and writin
24bb0 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f  g if possible, o
24bc0 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c  r reading.** onl
24bd0 79 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73  y if the file is
24be0 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64   write protected
24bf0 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e   by the operatin
24c00 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69  g system.  In ei
24c10 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65  ther.** case the
24c20 20 64 61 74 61 62 61 73 65 20 6d 75 73 74 20 61   database must a
24c30 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74  lready exist, ot
24c40 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72  herwise an error
24c50 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64   is returned.</d
24c60 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74  d>)^.**.** ^(<dt
24c70 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  >[SQLITE_OPEN_RE
24c80 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49  ADWRITE] | [SQLI
24c90 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c  TE_OPEN_CREATE]<
24ca0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
24cb0 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
24cc0 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61  ed for reading a
24cd0 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20  nd writing, and 
24ce0 69 73 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a  is created if.**
24cf0 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72   it does not alr
24d00 65 61 64 79 20 65 78 69 73 74 2e 20 54 68 69 73  eady exist. This
24d10 20 69 73 20 74 68 65 20 62 65 68 61 76 69 6f 72   is the behavior
24d20 20 74 68 61 74 20 69 73 20 61 6c 77 61 79 73 20   that is always 
24d30 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69  used for.** sqli
24d40 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
24d50 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e  qlite3_open16().
24d60 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e  </dd>)^.** </dl>
24d70 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72  .**.** If the 3r
24d80 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
24d90 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
24da0 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74   is not one of t
24db0 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f  he.** combinatio
24dc0 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f  ns shown above o
24dd0 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e  ptionally combin
24de0 65 64 20 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a  ed with other.**
24df0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
24e00 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f  ADONLY | SQLITE_
24e10 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20  OPEN_* bits].** 
24e20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
24e30 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
24e40 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53  **.** ^If the [S
24e50 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
24e60 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c  EX] flag is set,
24e70 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
24e80 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
24e90 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75   opens in the mu
24ea0 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65  lti-thread [thre
24eb0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c  ading mode] as l
24ec0 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c  ong as the singl
24ed0 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65  e-thread.** mode
24ee0 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65   has not been se
24ef0 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  t at compile-tim
24f00 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e  e or start-time.
24f10 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51    ^If the.** [SQ
24f20 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55  LITE_OPEN_FULLMU
24f30 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74  TEX] flag is set
24f40 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
24f50 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70  se connection op
24f60 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65  ens.** in the se
24f70 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64  rialized [thread
24f80 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73  ing mode] unless
24f90 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77   single-thread w
24fa0 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  as.** previously
24fb0 20 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d   selected at com
24fc0 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61  pile-time or sta
24fd0 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65  rt-time..** ^The
24fe0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48   [SQLITE_OPEN_SH
24ff0 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20  AREDCACHE] flag 
25000 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62  causes the datab
25010 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
25020 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65  o be.** eligible
25030 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20   to use [shared 
25040 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67  cache mode], reg
25050 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
25060 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64  er or not shared
25070 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61  .** cache is ena
25080 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  bled using [sqli
25090 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65  te3_enable_share
250a0 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68  d_cache()].  ^Th
250b0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  e.** [SQLITE_OPE
250c0 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 20  N_PRIVATECACHE] 
250d0 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20  flag causes the 
250e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
250f0 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61  ion to not.** pa
25100 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68  rticipate in [sh
25110 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d  ared cache mode]
25120 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 65   even if it is e
25130 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  nabled..**.** ^T
25140 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
25150 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
25160 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20  pen_v2() is the 
25170 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  name of the.** [
25180 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
25190 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73  ect that defines
251a0 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
251b0 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20  ystem interface 
251c0 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20  that.** the new 
251d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
251e0 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20  ion should use. 
251f0 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20   ^If the fourth 
25200 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
25210 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
25220 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20  hen the default 
25230 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
25240 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a  ject is used..**
25250 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65  .** ^If the file
25260 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79  name is ":memory
25270 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61  :", then a priva
25280 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e  te, temporary in
25290 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
252a0 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20 66  .** is created f
252b0 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  or the connectio
252c0 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d  n.  ^This in-mem
252d0 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 69 6c  ory database wil
252e0 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a  l vanish when.**
252f0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
25300 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73  nnection is clos
25310 65 64 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  ed.  Future vers
25320 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
25330 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65  ight.** make use
25340 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73   of additional s
25350 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73  pecial filenames
25360 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 68   that begin with
25370 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 74   the ":" charact
25380 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63  er..** It is rec
25390 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68  ommended that wh
253a0 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69  en a database fi
253b0 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20  lename actually 
253c0 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a  does begin with.
253d0 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63 74  ** a ":" charact
253e0 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72  er you should pr
253f0 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d  efix the filenam
25400 65 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d  e with a pathnam
25410 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f  e such as.** "./
25420 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67  " to avoid ambig
25430 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  uity..**.** ^If 
25440 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20  the filename is 
25450 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c  an empty string,
25460 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c   then a private,
25470 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e   temporary.** on
25480 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77  -disk database w
25490 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20  ill be created. 
254a0 20 5e 54 68 69 73 20 70 72 69 76 61 74 65 20 64   ^This private d
254b0 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a  atabase will be.
254c0 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ** automatically
254d0 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e   deleted as soon
254e0 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73 65   as the database
254f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63   connection is c
25500 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55  losed..**.** [[U
25510 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20  RI filenames in 
25520 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d  sqlite3_open()]]
25530 20 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d   <h3>URI Filenam
25540 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49  es</h3>.**.** ^I
25550 66 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d  f [URI filename]
25560 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20   interpretation 
25570 69 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20  is enabled, and 
25580 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  the filename arg
25590 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20  ument.** begins 
255a0 77 69 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 68  with "file:", th
255b0 65 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  en the filename 
255c0 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
255d0 73 20 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a  s a URI. ^URI.**
255e0 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70   filename interp
255f0 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62  retation is enab
25600 6c 65 64 20 69 66 20 74 68 65 20 5b 53 51 4c 49  led if the [SQLI
25610 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61  TE_OPEN_URI] fla
25620 67 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74  g is.** set in t
25630 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
25640 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  nt to sqlite3_op
25650 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66 20 69  en_v2(), or if i
25660 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e  t has.** been en
25670 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75  abled globally u
25680 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45  sing the [SQLITE
25690 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74  _CONFIG_URI] opt
256a0 69 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  ion with the.** 
256b0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
256c0 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62 79 20  )] method or by 
256d0 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f  the [SQLITE_USE_
256e0 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  URI] compile-tim
256f0 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20  e option..** As 
25700 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  of SQLite versio
25710 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c  n 3.7.7, URI fil
25720 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61  ename interpreta
25730 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f  tion is turned o
25740 66 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74  ff.** by default
25750 2c 20 62 75 74 20 66 75 74 75 72 65 20 72 65 6c  , but future rel
25760 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20  eases of SQLite 
25770 6d 69 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49  might enable URI
25780 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74   filename.** int
25790 65 72 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64  erpretation by d
257a0 65 66 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55  efault.  See "[U
257b0 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66  RI filenames]" f
257c0 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  or additional.**
257d0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
257e0 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  .** URI filename
257f0 73 20 61 72 65 20 70 61 72 73 65 64 20 61 63 63  s are parsed acc
25800 6f 72 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39  ording to RFC 39
25810 38 36 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20  86. ^If the URI 
25820 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61  contains an.** a
25830 75 74 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69  uthority, then i
25840 74 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72  t must be either
25850 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
25860 20 6f 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a   or the string .
25870 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20  ** "localhost". 
25880 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 74  ^If the authorit
25890 79 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74  y is not an empt
258a0 79 20 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63  y string or "loc
258b0 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20  alhost", an .** 
258c0 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
258d0 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e  d to the caller.
258e0 20 5e 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63   ^The fragment c
258f0 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52  omponent of a UR
25900 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e  I, if .** presen
25910 74 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a  t, is ignored..*
25920 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65  *.** ^SQLite use
25930 73 20 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f  s the path compo
25940 6e 65 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20  nent of the URI 
25950 61 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  as the name of t
25960 68 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20  he disk file.** 
25970 77 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74  which contains t
25980 68 65 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66  he database. ^If
25990 20 74 68 65 20 70 61 74 68 20 62 65 67 69 6e 73   the path begins
259a0 20 77 69 74 68 20 61 20 27 2f 27 20 63 68 61 72   with a '/' char
259b0 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20  acter, .** then 
259c0 69 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  it is interprete
259d0 64 20 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65  d as an absolute
259e0 20 70 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70   path. ^If the p
259f0 61 74 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67  ath does not beg
25a00 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f  in .** with a '/
25a10 27 20 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20  ' (meaning that 
25a20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 73 65  the authority se
25a30 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64  ction is omitted
25a40 20 66 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a   from the URI).*
25a50 2a 20 74 68 65 6e 20 74 68 65 20 70 61 74 68 20  * then the path 
25a60 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
25a70 73 20 61 20 72 65 6c 61 74 69 76 65 20 70 61 74  s a relative pat
25a80 68 2e 20 0a 2a 2a 20 5e 28 4f 6e 20 77 69 6e 64  h. .** ^(On wind
25a90 6f 77 73 2c 20 74 68 65 20 66 69 72 73 74 20 63  ows, the first c
25aa0 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61  omponent of an a
25ab0 62 73 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a  bsolute path .**
25ac0 20 69 73 20 61 20 64 72 69 76 65 20 73 70 65 63   is a drive spec
25ad0 69 66 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20  ification (e.g. 
25ae0 22 43 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  "C:").)^.**.** [
25af0 5b 63 6f 72 65 20 55 52 49 20 71 75 65 72 79 20  [core URI query 
25b00 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20  parameters]].** 
25b10 54 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e  The query compon
25b20 65 6e 74 20 6f 66 20 61 20 55 52 49 20 6d 61 79  ent of a URI may
25b30 20 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 74   contain paramet
25b40 65 72 73 20 74 68 61 74 20 61 72 65 20 69 6e 74  ers that are int
25b50 65 72 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 68  erpreted.** eith
25b60 65 72 20 62 79 20 53 51 4c 69 74 65 20 69 74 73  er by SQLite its
25b70 65 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 46  elf, or by a [VF
25b80 53 20 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 69  S | custom VFS i
25b90 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a  mplementation]..
25ba0 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64 20 69 74  ** SQLite and it
25bb0 73 20 62 75 69 6c 74 2d 69 6e 20 5b 56 46 53 65  s built-in [VFSe
25bc0 73 5d 20 69 6e 74 65 72 70 72 65 74 20 74 68 65  s] interpret the
25bd0 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 71 75  .** following qu
25be0 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 3a 0a  ery parameters:.
25bf0 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20  **.** <ul>.**   
25c00 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a  <li> <b>vfs</b>:
25c10 20 5e 54 68 65 20 22 76 66 73 22 20 70 61 72 61   ^The "vfs" para
25c20 6d 65 74 65 72 20 6d 61 79 20 62 65 20 75 73 65  meter may be use
25c30 64 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65  d to specify the
25c40 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20   name of.**     
25c50 61 20 56 46 53 20 6f 62 6a 65 63 74 20 74 68 61  a VFS object tha
25c60 74 20 70 72 6f 76 69 64 65 73 20 74 68 65 20 6f  t provides the o
25c70 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
25c80 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 73  interface that s
25c90 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20  hould.**     be 
25ca0 75 73 65 64 20 74 6f 20 61 63 63 65 73 73 20 74  used to access t
25cb0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
25cc0 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74 68   on disk. ^If th
25cd0 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74  is option is set
25ce0 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d   to.**     an em
25cf0 70 74 79 20 73 74 72 69 6e 67 20 74 68 65 20 64  pty string the d
25d00 65 66 61 75 6c 74 20 56 46 53 20 6f 62 6a 65 63  efault VFS objec
25d10 74 20 69 73 20 75 73 65 64 2e 20 5e 53 70 65 63  t is used. ^Spec
25d20 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77  ifying an unknow
25d30 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20 69 73 20  n.**     VFS is 
25d40 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20 73 71  an error. ^If sq
25d50 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
25d60 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20  is used and the 
25d70 76 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a  vfs option is.**
25d80 20 20 20 20 20 70 72 65 73 65 6e 74 2c 20 74 68       present, th
25d90 65 6e 20 74 68 65 20 56 46 53 20 73 70 65 63 69  en the VFS speci
25da0 66 69 65 64 20 62 79 20 74 68 65 20 6f 70 74 69  fied by the opti
25db0 6f 6e 20 74 61 6b 65 73 20 70 72 65 63 65 64 65  on takes precede
25dc0 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20  nce over.**     
25dd0 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64  the value passed
25de0 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 70   as the fourth p
25df0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
25e00 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a  te3_open_v2()..*
25e10 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d  *.**   <li> <b>m
25e20 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d  ode</b>: ^(The m
25e30 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61  ode parameter ma
25e40 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68  y be set to eith
25e50 65 72 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a 2a  er "ro", "rw",.*
25e60 2a 20 20 20 20 20 22 72 77 63 22 2c 20 6f 72 20  *     "rwc", or 
25e70 22 6d 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d 70  "memory". Attemp
25e80 74 69 6e 67 20 74 6f 20 73 65 74 20 69 74 20 74  ting to set it t
25e90 6f 20 61 6e 79 20 6f 74 68 65 72 20 76 61 6c 75  o any other valu
25ea0 65 20 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20 65  e is.**     an e
25eb0 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20  rror)^. .**     
25ec0 5e 49 66 20 22 72 6f 22 20 69 73 20 73 70 65 63  ^If "ro" is spec
25ed0 69 66 69 65 64 2c 20 74 68 65 6e 20 74 68 65 20  ified, then the 
25ee0 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
25ef0 65 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79  ed for read-only
25f00 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c   .**     access,
25f10 20 6a 75 73 74 20 61 73 20 69 66 20 74 68 65 20   just as if the 
25f20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
25f30 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64 20  DONLY] flag had 
25f40 62 65 65 6e 20 73 65 74 20 69 6e 20 74 68 65 20  been set in the 
25f50 0a 2a 2a 20 20 20 20 20 74 68 69 72 64 20 61 72  .**     third ar
25f60 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
25f70 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 49 66  3_open_v2(). ^If
25f80 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e   the mode option
25f90 20 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20   is set to .**  
25fa0 20 20 20 22 72 77 22 2c 20 74 68 65 6e 20 74 68     "rw", then th
25fb0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
25fc0 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 77 72  ened for read-wr
25fd0 69 74 65 20 28 62 75 74 20 6e 6f 74 20 63 72 65  ite (but not cre
25fe0 61 74 65 29 20 0a 2a 2a 20 20 20 20 20 61 63 63  ate) .**     acc
25ff0 65 73 73 2c 20 61 73 20 69 66 20 53 51 4c 49 54  ess, as if SQLIT
26000 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
26010 20 28 62 75 74 20 6e 6f 74 20 53 51 4c 49 54 45   (but not SQLITE
26020 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29 20 68 61  _OPEN_CREATE) ha
26030 64 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20 73  d .**     been s
26040 65 74 2e 20 5e 56 61 6c 75 65 20 22 72 77 63 22  et. ^Value "rwc"
26050 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74   is equivalent t
26060 6f 20 73 65 74 74 69 6e 67 20 62 6f 74 68 20 0a  o setting both .
26070 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50  **     SQLITE_OP
26080 45 4e 5f 52 45 41 44 57 52 49 54 45 20 61 6e 64  EN_READWRITE and
26090 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
260a0 41 54 45 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f  ATE.  ^If the mo
260b0 64 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20  de option is.** 
260c0 20 20 20 20 73 65 74 20 74 6f 20 22 6d 65 6d 6f      set to "memo
260d0 72 79 22 20 74 68 65 6e 20 61 20 70 75 72 65 20  ry" then a pure 
260e0 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62  [in-memory datab
260f0 61 73 65 5d 20 74 68 61 74 20 6e 65 76 65 72 20  ase] that never 
26100 72 65 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72 20  reads.**     or 
26110 77 72 69 74 65 73 20 66 72 6f 6d 20 64 69 73 6b  writes from disk
26120 20 69 73 20 75 73 65 64 2e 20 5e 49 74 20 69 73   is used. ^It is
26130 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70 65   an error to spe
26140 63 69 66 79 20 61 20 76 61 6c 75 65 20 66 6f 72  cify a value for
26150 0a 2a 2a 20 20 20 20 20 74 68 65 20 6d 6f 64 65  .**     the mode
26160 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 20   parameter that 
26170 69 73 20 6c 65 73 73 20 72 65 73 74 72 69 63 74  is less restrict
26180 69 76 65 20 74 68 61 6e 20 74 68 61 74 20 73 70  ive than that sp
26190 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20  ecified by.**   
261a0 20 20 74 68 65 20 66 6c 61 67 73 20 70 61 73 73    the flags pass
261b0 65 64 20 69 6e 20 74 68 65 20 74 68 69 72 64 20  ed in the third 
261c0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
261d0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a  ite3_open_v2()..
261e0 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e  **.**   <li> <b>
261f0 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20  cache</b>: ^The 
26200 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20  cache parameter 
26210 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69  may be set to ei
26220 74 68 65 72 20 22 73 68 61 72 65 64 22 20 6f 72  ther "shared" or
26230 0a 2a 2a 20 20 20 20 20 22 70 72 69 76 61 74 65  .**     "private
26240 22 2e 20 5e 53 65 74 74 69 6e 67 20 69 74 20 74  ". ^Setting it t
26250 6f 20 22 73 68 61 72 65 64 22 20 69 73 20 65 71  o "shared" is eq
26260 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74  uivalent to sett
26270 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 53  ing the.**     S
26280 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
26290 44 43 41 43 48 45 20 62 69 74 20 69 6e 20 74 68  DCACHE bit in th
262a0 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
262b0 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20   passed to.**   
262c0 20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76    sqlite3_open_v
262d0 32 28 29 2e 20 5e 53 65 74 74 69 6e 67 20 74 68  2(). ^Setting th
262e0 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65  e cache paramete
262f0 72 20 74 6f 20 22 70 72 69 76 61 74 65 22 20 69  r to "private" i
26300 73 20 0a 2a 2a 20 20 20 20 20 65 71 75 69 76 61  s .**     equiva
26310 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20  lent to setting 
26320 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  the SQLITE_OPEN_
26330 50 52 49 56 41 54 45 43 41 43 48 45 20 62 69 74  PRIVATECACHE bit
26340 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73 71 6c  ..**     ^If sql
26350 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
26360 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 22  s used and the "
26370 63 61 63 68 65 22 20 70 61 72 61 6d 65 74 65 72  cache" parameter
26380 20 69 73 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a   is present in.*
26390 2a 20 20 20 20 20 61 20 55 52 49 20 66 69 6c 65  *     a URI file
263a0 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c 75 65 20  name, its value 
263b0 6f 76 65 72 72 69 64 65 73 20 61 6e 79 20 62 65  overrides any be
263c0 68 61 76 69 6f 72 20 72 65 71 75 65 73 74 65 64  havior requested
263d0 20 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20   by setting.**  
263e0 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50     SQLITE_OPEN_P
263f0 52 49 56 41 54 45 43 41 43 48 45 20 6f 72 20 53  RIVATECACHE or S
26400 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
26410 44 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 0a  DCACHE flag..**.
26420 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 70 73 6f 77  **  <li> <b>psow
26430 3c 2f 62 3e 3a 20 5e 54 68 65 20 70 73 6f 77 20  </b>: ^The psow 
26440 70 61 72 61 6d 65 74 65 72 20 69 6e 64 69 63 61  parameter indica
26450 74 65 73 20 77 68 65 74 68 65 72 20 6f 72 20 6e  tes whether or n
26460 6f 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 5b 70  ot the.**     [p
26470 6f 77 65 72 73 61 66 65 20 6f 76 65 72 77 72 69  owersafe overwri
26480 74 65 5d 20 70 72 6f 70 65 72 74 79 20 64 6f 65  te] property doe
26490 73 20 6f 72 20 64 6f 65 73 20 6e 6f 74 20 61 70  s or does not ap
264a0 70 6c 79 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20  ply to the.**   
264b0 20 20 73 74 6f 72 61 67 65 20 6d 65 64 69 61 20    storage media 
264c0 6f 6e 20 77 68 69 63 68 20 74 68 65 20 64 61 74  on which the dat
264d0 61 62 61 73 65 20 66 69 6c 65 20 72 65 73 69 64  abase file resid
264e0 65 73 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20  es..**.**  <li> 
264f0 3c 62 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e  <b>nolock</b>: ^
26500 54 68 65 20 6e 6f 6c 6f 63 6b 20 70 61 72 61 6d  The nolock param
26510 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 61  eter is a boolea
26520 6e 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  n query paramete
26530 72 0a 2a 2a 20 20 20 20 20 77 68 69 63 68 20 69  r.**     which i
26540 66 20 73 65 74 20 64 69 73 61 62 6c 65 73 20 66  f set disables f
26550 69 6c 65 20 6c 6f 63 6b 69 6e 67 20 69 6e 20 72  ile locking in r
26560 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 20  ollback journal 
26570 6d 6f 64 65 73 2e 20 20 54 68 69 73 0a 2a 2a 20  modes.  This.** 
26580 20 20 20 20 69 73 20 75 73 65 66 75 6c 20 66 6f      is useful fo
26590 72 20 61 63 63 65 73 73 69 6e 67 20 61 20 64 61  r accessing a da
265a0 74 61 62 61 73 65 20 6f 6e 20 61 20 66 69 6c 65  tabase on a file
265b0 73 79 73 74 65 6d 20 74 68 61 74 20 64 6f 65 73  system that does
265c0 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 73 75 70 70   not.**     supp
265d0 6f 72 74 20 6c 6f 63 6b 69 6e 67 2e 20 20 43 61  ort locking.  Ca
265e0 75 74 69 6f 6e 3a 20 20 44 61 74 61 62 61 73 65  ution:  Database
265f0 20 63 6f 72 72 75 70 74 69 6f 6e 20 6d 69 67 68   corruption migh
26600 74 20 72 65 73 75 6c 74 20 69 66 20 74 77 6f 0a  t result if two.
26610 2a 2a 20 20 20 20 20 6f 72 20 6d 6f 72 65 20 70  **     or more p
26620 72 6f 63 65 73 73 65 73 20 77 72 69 74 65 20 74  rocesses write t
26630 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  o the same datab
26640 61 73 65 20 61 6e 64 20 61 6e 79 20 6f 6e 65 20  ase and any one 
26650 6f 66 20 74 68 6f 73 65 0a 2a 2a 20 20 20 20 20  of those.**     
26660 70 72 6f 63 65 73 73 65 73 20 75 73 65 73 20 6e  processes uses n
26670 6f 6c 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20  olock=1..**.**  
26680 3c 6c 69 3e 20 3c 62 3e 69 6d 6d 75 74 61 62 6c  <li> <b>immutabl
26690 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 69 6d 6d 75  e</b>: ^The immu
266a0 74 61 62 6c 65 20 70 61 72 61 6d 65 74 65 72 20  table parameter 
266b0 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65  is a boolean que
266c0 72 79 0a 2a 2a 20 20 20 20 20 70 61 72 61 6d 65  ry.**     parame
266d0 74 65 72 20 74 68 61 74 20 69 6e 64 69 63 61 74  ter that indicat
266e0 65 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61  es that the data
266f0 62 61 73 65 20 66 69 6c 65 20 69 73 20 73 74 6f  base file is sto
26700 72 65 64 20 6f 6e 0a 2a 2a 20 20 20 20 20 72 65  red on.**     re
26710 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 2e 20 20  ad-only media.  
26720 5e 57 68 65 6e 20 69 6d 6d 75 74 61 62 6c 65 20  ^When immutable 
26730 69 73 20 73 65 74 2c 20 53 51 4c 69 74 65 20 61  is set, SQLite a
26740 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a  ssumes that the.
26750 2a 2a 20 20 20 20 20 64 61 74 61 62 61 73 65 20  **     database 
26760 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 63  file cannot be c
26770 68 61 6e 67 65 64 2c 20 65 76 65 6e 20 62 79 20  hanged, even by 
26780 61 20 70 72 6f 63 65 73 73 20 77 69 74 68 20 68  a process with h
26790 69 67 68 65 72 0a 2a 2a 20 20 20 20 20 70 72 69  igher.**     pri
267a0 76 69 6c 65 67 65 2c 20 61 6e 64 20 73 6f 20 74  vilege, and so t
267b0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
267c0 70 65 6e 65 64 20 72 65 61 64 2d 6f 6e 6c 79 20  pened read-only 
267d0 61 6e 64 20 61 6c 6c 20 6c 6f 63 6b 69 6e 67 0a  and all locking.
267e0 2a 2a 20 20 20 20 20 61 6e 64 20 63 68 61 6e 67  **     and chang
267f0 65 20 64 65 74 65 63 74 69 6f 6e 20 69 73 20 64  e detection is d
26800 69 73 61 62 6c 65 64 2e 20 20 43 61 75 74 69 6f  isabled.  Cautio
26810 6e 3a 20 53 65 74 74 69 6e 67 20 74 68 65 20 69  n: Setting the i
26820 6d 6d 75 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20  mmutable.**     
26830 70 72 6f 70 65 72 74 79 20 6f 6e 20 61 20 64 61  property on a da
26840 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 61 74  tabase file that
26850 20 64 6f 65 73 20 69 6e 20 66 61 63 74 20 63 68   does in fact ch
26860 61 6e 67 65 20 63 61 6e 20 72 65 73 75 6c 74 0a  ange can result.
26870 2a 2a 20 20 20 20 20 69 6e 20 69 6e 63 6f 72 72  **     in incorr
26880 65 63 74 20 71 75 65 72 79 20 72 65 73 75 6c 74  ect query result
26890 73 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45  s and/or [SQLITE
268a0 5f 43 4f 52 52 55 50 54 5d 20 65 72 72 6f 72 73  _CORRUPT] errors
268b0 2e 0a 2a 2a 20 20 20 20 20 53 65 65 20 61 6c 73  ..**     See als
268c0 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  o: [SQLITE_IOCAP
268d0 5f 49 4d 4d 55 54 41 42 4c 45 5d 2e 0a 2a 2a 20  _IMMUTABLE]..** 
268e0 20 20 20 20 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a        .** </ul>.
268f0 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e  **.** ^Specifyin
26900 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72  g an unknown par
26910 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20 71 75  ameter in the qu
26920 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  ery component of
26930 20 61 20 55 52 49 20 69 73 20 6e 6f 74 20 61 6e   a URI is not an
26940 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75 74 75  .** error.  Futu
26950 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
26960 51 4c 69 74 65 20 6d 69 67 68 74 20 75 6e 64 65  QLite might unde
26970 72 73 74 61 6e 64 20 61 64 64 69 74 69 6f 6e 61  rstand additiona
26980 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d  l query.** param
26990 65 74 65 72 73 2e 20 20 53 65 65 20 22 5b 71 75  eters.  See "[qu
269a0 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 20 77  ery parameters w
269b0 69 74 68 20 73 70 65 63 69 61 6c 20 6d 65 61 6e  ith special mean
269c0 69 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d 22 20  ing to SQLite]" 
269d0 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61  for.** additiona
269e0 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
269f0 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e  *.** [[URI filen
26a00 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c  ame examples]] <
26a10 68 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65 20  h3>URI filename 
26a20 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a  examples</h3>.**
26a30 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65  .** <table borde
26a40 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74  r="1" align=cent
26a50 65 72 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35  er cellpadding=5
26a60 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52  >.** <tr><th> UR
26a70 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e  I filenames <th>
26a80 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e   Results.** <tr>
26a90 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64  <td> file:data.d
26aa0 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  b <td> .**      
26ab0 20 20 20 20 4f 70 65 6e 20 74 68 65 20 66 69 6c      Open the fil
26ac0 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74  e "data.db" in t
26ad0 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63  he current direc
26ae0 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  tory..** <tr><td
26af0 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65  > file:/home/fre
26b00 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a  d/data.db<br>.**
26b10 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f            file:/
26b20 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  //home/fred/data
26b30 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20  .db <br> .**    
26b40 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63        file://loc
26b50 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64  alhost/home/fred
26b60 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74  /data.db <br> <t
26b70 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
26b80 4f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  Open the databas
26b90 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72  e file "/home/fr
26ba0 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20  ed/data.db"..** 
26bb0 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f  <tr><td> file://
26bc0 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72  darkstar/home/fr
26bd0 65 64 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e 20  ed/data.db <td> 
26be0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20  .**          An 
26bf0 65 72 72 6f 72 2e 20 22 64 61 72 6b 73 74 61 72  error. "darkstar
26c00 22 20 69 73 20 6e 6f 74 20 61 20 72 65 63 6f 67  " is not a recog
26c10 6e 69 7a 65 64 20 61 75 74 68 6f 72 69 74 79 2e  nized authority.
26c20 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c  .** <tr><td styl
26c30 65 3d 22 77 68 69 74 65 2d 73 70 61 63 65 3a 6e  e="white-space:n
26c40 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20  owrap"> .**     
26c50 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f       file:///C:/
26c60 44 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e 64 25  Documents%20and%
26c70 32 30 53 65 74 74 69 6e 67 73 2f 66 72 65 64 2f  20Settings/fred/
26c80 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a  Desktop/data.db.
26c90 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57 69 6e 64  **     <td> Wind
26ca0 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74  ows only: Open t
26cb0 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62  he file "data.db
26cc0 22 20 6f 6e 20 66 72 65 64 27 73 20 64 65 73 6b  " on fred's desk
26cd0 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20  top on drive.** 
26ce0 20 20 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74           C:. Not
26cf0 65 20 74 68 61 74 20 74 68 65 20 25 32 30 20 65  e that the %20 e
26d00 73 63 61 70 69 6e 67 20 69 6e 20 74 68 69 73 20  scaping in this 
26d10 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73  example is not s
26d20 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20  trictly .**     
26d30 20 20 20 20 20 6e 65 63 65 73 73 61 72 79 20 2d       necessary -
26d40 20 73 70 61 63 65 20 63 68 61 72 61 63 74 65 72   space character
26d50 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 6c 69  s can be used li
26d60 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20  terally.**      
26d70 20 20 20 20 69 6e 20 55 52 49 20 66 69 6c 65 6e      in URI filen
26d80 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  ames..** <tr><td
26d90 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d  > file:data.db?m
26da0 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d 70 72 69  ode=ro&cache=pri
26db0 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  vate <td> .**   
26dc0 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65         Open file
26dd0 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68   "data.db" in th
26de0 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74  e current direct
26df0 6f 72 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c  ory for read-onl
26e00 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20  y access..**    
26e10 20 20 20 20 20 20 52 65 67 61 72 64 6c 65 73 73        Regardless
26e20 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
26e30 6f 74 20 73 68 61 72 65 64 2d 63 61 63 68 65 20  ot shared-cache 
26e40 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20  mode is enabled 
26e50 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64  by.**          d
26e60 65 66 61 75 6c 74 2c 20 75 73 65 20 61 20 70 72  efault, use a pr
26e70 69 76 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20  ivate cache..** 
26e80 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68  <tr><td> file:/h
26e90 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
26ea0 3f 76 66 73 3d 75 6e 69 78 2d 64 6f 74 66 69 6c  ?vfs=unix-dotfil
26eb0 65 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20  e <td>.**       
26ec0 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68     Open file "/h
26ed0 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
26ee0 22 2e 20 55 73 65 20 74 68 65 20 73 70 65 63 69  ". Use the speci
26ef0 61 6c 20 56 46 53 20 22 75 6e 69 78 2d 64 6f 74  al VFS "unix-dot
26f00 66 69 6c 65 22 0a 2a 2a 20 20 20 20 20 20 20 20  file".**        
26f10 20 20 74 68 61 74 20 75 73 65 73 20 64 6f 74 2d    that uses dot-
26f20 66 69 6c 65 73 20 69 6e 20 70 6c 61 63 65 20 6f  files in place o
26f30 66 20 70 6f 73 69 78 20 61 64 76 69 73 6f 72 79  f posix advisory
26f40 20 6c 6f 63 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 72   locking..** <tr
26f50 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e  ><td> file:data.
26f60 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79  db?mode=readonly
26f70 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
26f80 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 72 65     An error. "re
26f90 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61  adonly" is not a
26fa0 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f   valid option fo
26fb0 72 20 74 68 65 20 22 6d 6f 64 65 22 20 70 61 72  r the "mode" par
26fc0 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62  ameter..** </tab
26fd0 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68  le>.**.** ^URI h
26fe0 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70  exadecimal escap
26ff0 65 20 73 65 71 75 65 6e 63 65 73 20 28 25 48 48  e sequences (%HH
27000 29 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20  ) are supported 
27010 77 69 74 68 69 6e 20 74 68 65 20 70 61 74 68 20  within the path 
27020 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d  and.** query com
27030 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55 52 49  ponents of a URI
27040 2e 20 41 20 68 65 78 61 64 65 63 69 6d 61 6c 20  . A hexadecimal 
27050 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 20  escape sequence 
27060 63 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a  consists of a.**
27070 20 70 65 72 63 65 6e 74 20 73 69 67 6e 20 2d 20   percent sign - 
27080 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62  "%" - followed b
27090 79 20 65 78 61 63 74 6c 79 20 74 77 6f 20 68 65  y exactly two he
270a0 78 61 64 65 63 69 6d 61 6c 20 64 69 67 69 74 73  xadecimal digits
270b0 20 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e 67 20   .** specifying 
270c0 61 6e 20 6f 63 74 65 74 20 76 61 6c 75 65 2e 20  an octet value. 
270d0 5e 42 65 66 6f 72 65 20 74 68 65 20 70 61 74 68  ^Before the path
270e0 20 6f 72 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e   or query compon
270f0 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49  ents of a.** URI
27100 20 66 69 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e   filename are in
27110 74 65 72 70 72 65 74 65 64 2c 20 74 68 65 79 20  terpreted, they 
27120 61 72 65 20 65 6e 63 6f 64 65 64 20 75 73 69 6e  are encoded usin
27130 67 20 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20  g UTF-8 and all 
27140 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d 61 6c 20  .** hexadecimal 
27150 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73  escape sequences
27160 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 73   replaced by a s
27170 69 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e 74 61  ingle byte conta
27180 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72  ining the.** cor
27190 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74  responding octet
271a0 2e 20 49 66 20 74 68 69 73 20 70 72 6f 63 65 73  . If this proces
271b0 73 20 67 65 6e 65 72 61 74 65 73 20 61 6e 20 69  s generates an i
271c0 6e 76 61 6c 69 64 20 55 54 46 2d 38 20 65 6e 63  nvalid UTF-8 enc
271d0 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65  oding,.** the re
271e0 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
271f0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f  ned..**.** <b>No
27200 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73  te to Windows us
27210 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e  ers:</b>  The en
27220 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20  coding used for 
27230 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  the filename arg
27240 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69  ument.** of sqli
27250 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
27260 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
27270 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20   must be UTF-8, 
27280 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20  not whatever.** 
27290 63 6f 64 65 70 61 67 65 20 69 73 20 63 75 72 72  codepage is curr
272a0 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20  ently defined.  
272b0 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69  Filenames contai
272c0 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e  ning internation
272d0 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73  al.** characters
272e0 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
272f0 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f  ed to UTF-8 prio
27300 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65  r to passing the
27310 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  m into.** sqlite
27320 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69  3_open() or sqli
27330 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a  te3_open_v2()..*
27340 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20  *.** <b>Note to 
27350 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 20  Windows Runtime 
27360 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20  users:</b>  The 
27370 74 65 6d 70 6f 72 61 72 79 20 64 69 72 65 63 74  temporary direct
27380 6f 72 79 20 6d 75 73 74 20 62 65 20 73 65 74 0a  ory must be set.
27390 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c  ** prior to call
273a0 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ing sqlite3_open
273b0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  () or sqlite3_op
273c0 65 6e 5f 76 32 28 29 2e 20 20 4f 74 68 65 72 77  en_v2().  Otherw
273d0 69 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20  ise, various.** 
273e0 66 65 61 74 75 72 65 73 20 74 68 61 74 20 72 65  features that re
273f0 71 75 69 72 65 20 74 68 65 20 75 73 65 20 6f 66  quire the use of
27400 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73   temporary files
27410 20 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a   may fail..**.**
27420 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
27430 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f  te3_temp_directo
27440 72 79 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ry].*/.SQLITE_AP
27450 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  I int sqlite3_op
27460 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  en(.  const char
27470 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
27480 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
27490 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20  me (UTF-8) */.  
274a0 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20  sqlite3 **ppDb  
274b0 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
274c0 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
274d0 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50   */.);.SQLITE_AP
274e0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  I int sqlite3_op
274f0 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f  en16(.  const vo
27500 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20  id *filename,   
27510 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65  /* Database file
27520 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f  name (UTF-16) */
27530 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
27540 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b          /* OU
27550 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
27560 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45  dle */.);.SQLITE
27570 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
27580 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73  _open_v2(.  cons
27590 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65  t char *filename
275a0 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
275b0 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29  filename (UTF-8)
275c0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
275d0 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a  ppDb,         /*
275e0 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
275f0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20  handle */.  int 
27600 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20  flags,          
27610 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a      /* Flags */.
27620 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56    const char *zV
27630 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  fs        /* Nam
27640 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20  e of VFS module 
27650 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a  to use */.);../*
27660 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62  .** CAPI3REF: Ob
27670 74 61 69 6e 20 56 61 6c 75 65 73 20 46 6f 72 20  tain Values For 
27680 55 52 49 20 50 61 72 61 6d 65 74 65 72 73 0a 2a  URI Parameters.*
27690 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 75  *.** These are u
276a0 74 69 6c 69 74 79 20 72 6f 75 74 69 6e 65 73 2c  tility routines,
276b0 20 75 73 65 66 75 6c 20 74 6f 20 56 46 53 20 69   useful to VFS i
276c0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20  mplementations, 
276d0 74 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f  that check.** to
276e0 20 73 65 65 20 69 66 20 61 20 64 61 74 61 62 61   see if a databa
276f0 73 65 20 66 69 6c 65 20 77 61 73 20 61 20 55 52  se file was a UR
27700 49 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 65 64  I that contained
27710 20 61 20 73 70 65 63 69 66 69 63 20 71 75 65 72   a specific quer
27720 79 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c  y .** parameter,
27730 20 61 6e 64 20 69 66 20 73 6f 20 6f 62 74 61 69   and if so obtai
27740 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ns the value of 
27750 74 68 61 74 20 71 75 65 72 79 20 70 61 72 61 6d  that query param
27760 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46  eter..**.** If F
27770 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65   is the database
27780 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65   filename pointe
27790 72 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68  r passed into th
277a0 65 20 78 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64  e xOpen() method
277b0 20 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d   of .** a VFS im
277c0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65  plementation whe
277d0 6e 20 74 68 65 20 66 6c 61 67 73 20 70 61 72 61  n the flags para
277e0 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 28 29  meter to xOpen()
277f0 20 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20   has one or .** 
27800 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b 53 51 4c  more of the [SQL
27810 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72  ITE_OPEN_URI] or
27820 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
27830 49 4e 5f 44 42 5d 20 62 69 74 73 20 73 65 74 20  IN_DB] bits set 
27840 61 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68 65 20  and.** P is the 
27850 6e 61 6d 65 20 6f 66 20 74 68 65 20 71 75 65 72  name of the quer
27860 79 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65  y parameter, the
27870 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69  n.** sqlite3_uri
27880 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20  _parameter(F,P) 
27890 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75  returns the valu
278a0 65 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20 70 61  e of the P.** pa
278b0 72 61 6d 65 74 65 72 20 69 66 20 69 74 20 65 78  rameter if it ex
278c0 69 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70  ists or a NULL p
278d0 6f 69 6e 74 65 72 20 69 66 20 50 20 64 6f 65 73  ointer if P does
278e0 20 6e 6f 74 20 61 70 70 65 61 72 20 61 73 20 61   not appear as a
278f0 20 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d   .** query param
27900 65 74 65 72 20 6f 6e 20 46 2e 20 20 49 66 20 50  eter on F.  If P
27910 20 69 73 20 61 20 71 75 65 72 79 20 70 61 72 61   is a query para
27920 6d 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61  meter of F.** ha
27930 73 20 6e 6f 20 65 78 70 6c 69 63 69 74 20 76 61  s no explicit va
27940 6c 75 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  lue, then sqlite
27950 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28  3_uri_parameter(
27960 46 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20  F,P) returns.** 
27970 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
27980 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a  empty string..**
27990 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
279a0 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
279b0 42 29 20 72 6f 75 74 69 6e 65 20 61 73 73 75 6d  B) routine assum
279c0 65 73 20 74 68 61 74 20 50 20 69 73 20 61 20 62  es that P is a b
279d0 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65  oolean.** parame
279e0 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ter and returns 
279f0 74 72 75 65 20 28 31 29 20 6f 72 20 66 61 6c 73  true (1) or fals
27a00 65 20 28 30 29 20 61 63 63 6f 72 64 69 6e 67 20  e (0) according 
27a10 74 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20  to the value.** 
27a20 6f 66 20 50 2e 20 20 54 68 65 20 73 71 6c 69 74  of P.  The sqlit
27a30 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
27a40 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 72 65  ,P,B) routine re
27a50 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 69  turns true (1) i
27a60 66 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f  f the.** value o
27a70 66 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  f query paramete
27a80 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 79  r P is one of "y
27a90 65 73 22 2c 20 22 74 72 75 65 22 2c 20 6f 72 20  es", "true", or 
27aa0 22 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63  "on" in any.** c
27ab0 61 73 65 20 6f 72 20 69 66 20 74 68 65 20 76 61  ase or if the va
27ac0 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20  lue begins with 
27ad0 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65  a non-zero numbe
27ae0 72 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69  r.  The .** sqli
27af0 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
27b00 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 73 20  F,P,B) routines 
27b10 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 28 30  returns false (0
27b20 29 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f  ) if the value o
27b30 66 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d  f.** query param
27b40 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66  eter P is one of
27b50 20 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20   "no", "false", 
27b60 6f 72 20 22 6f 66 66 22 20 69 6e 20 61 6e 79 20  or "off" in any 
27b70 63 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68  case or.** if th
27b80 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77  e value begins w
27b90 69 74 68 20 61 20 6e 75 6d 65 72 69 63 20 7a 65  ith a numeric ze
27ba0 72 6f 2e 20 20 49 66 20 50 20 69 73 20 6e 6f 74  ro.  If P is not
27bb0 20 61 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61   a query.** para
27bc0 6d 65 74 65 72 20 6f 6e 20 46 20 6f 72 20 69 66  meter on F or if
27bd0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20   the value of P 
27be0 69 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63  is does not matc
27bf0 68 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20  h any of the.** 
27c00 61 62 6f 76 65 2c 20 74 68 65 6e 20 73 71 6c 69  above, then sqli
27c10 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
27c20 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 28  F,P,B) returns (
27c30 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  B!=0)..**.** The
27c40 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74   sqlite3_uri_int
27c50 36 34 28 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e  64(F,P,D) routin
27c60 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 20 76  e converts the v
27c70 61 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f 20 61  alue of P into a
27c80 0a 2a 2a 20 36 34 2d 62 69 74 20 73 69 67 6e 65  .** 64-bit signe
27c90 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 72 65  d integer and re
27ca0 74 75 72 6e 73 20 74 68 61 74 20 69 6e 74 65 67  turns that integ
27cb0 65 72 2c 20 6f 72 20 44 20 69 66 20 50 20 64 6f  er, or D if P do
27cc0 65 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e  es not.** exist.
27cd0 20 20 49 66 20 74 68 65 20 76 61 6c 75 65 20 6f    If the value o
27ce0 66 20 50 20 69 73 20 73 6f 6d 65 74 68 69 6e 67  f P is something
27cf0 20 6f 74 68 65 72 20 74 68 61 6e 20 61 6e 20 69   other than an i
27d00 6e 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20  nteger, then.** 
27d10 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64  zero is returned
27d20 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73  ..** .** If F is
27d30 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
27d40 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72   then sqlite3_ur
27d50 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29  i_parameter(F,P)
27d60 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e   returns NULL an
27d70 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69  d.** sqlite3_uri
27d80 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20  _boolean(F,P,B) 
27d90 72 65 74 75 72 6e 73 20 42 2e 20 20 49 66 20 46  returns B.  If F
27da0 20 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70   is not a NULL p
27db0 6f 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73  ointer and.** is
27dc0 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20   not a database 
27dd0 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 70 6f  file pathname po
27de0 69 6e 74 65 72 20 74 68 61 74 20 53 51 4c 69 74  inter that SQLit
27df0 65 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68  e passed into th
27e00 65 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d  e xOpen.** VFS m
27e10 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 65 20  ethod, then the 
27e20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69 73  behavior of this
27e30 20 72 6f 75 74 69 6e 65 20 69 73 20 75 6e 64 65   routine is unde
27e40 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
27e50 6c 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c  ly.** undesirabl
27e60 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  e..*/.SQLITE_API
27e70 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
27e80 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
27e90 65 72 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  er(const char *z
27ea0 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20  Filename, const 
27eb0 63 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 53  char *zParam);.S
27ec0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
27ed0 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
27ee0 6e 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46  n(const char *zF
27ef0 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  ile, const char 
27f00 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62 44 65  *zParam, int bDe
27f10 66 61 75 6c 74 29 3b 0a 53 51 4c 49 54 45 5f 41  fault);.SQLITE_A
27f20 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  PI sqlite3_int64
27f30 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74   sqlite3_uri_int
27f40 36 34 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  64(const char*, 
27f50 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c  const char*, sql
27f60 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f  ite3_int64);.../
27f70 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
27f80 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d  rror Codes And M
27f90 65 73 73 61 67 65 73 0a 2a 2a 20 4d 45 54 48 4f  essages.** METHO
27fa0 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
27fb0 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
27fc0 63 65 6e 74 20 73 71 6c 69 74 65 33 5f 2a 20 41  cent sqlite3_* A
27fd0 50 49 20 63 61 6c 6c 20 61 73 73 6f 63 69 61 74  PI call associat
27fe0 65 64 20 77 69 74 68 20 0a 2a 2a 20 5b 64 61 74  ed with .** [dat
27ff0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
28000 5d 20 44 20 66 61 69 6c 65 64 2c 20 74 68 65 6e  ] D failed, then
28010 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72   the sqlite3_err
28020 63 6f 64 65 28 44 29 20 69 6e 74 65 72 66 61 63  code(D) interfac
28030 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65  e.** returns the
28040 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74   numeric [result
28050 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e   code] or [exten
28060 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
28070 20 66 6f 72 20 74 68 61 74 0a 2a 2a 20 41 50 49   for that.** API
28080 20 63 61 6c 6c 2e 0a 2a 2a 20 49 66 20 74 68 65   call..** If the
28090 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49   most recent API
280a0 20 63 61 6c 6c 20 77 61 73 20 73 75 63 63 65 73   call was succes
280b0 73 66 75 6c 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  sful,.** then th
280c0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
280d0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 65 72 72 63  rom sqlite3_errc
280e0 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e  ode() is undefin
280f0 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  ed..** ^The sqli
28100 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72  te3_extended_err
28110 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66  code().** interf
28120 61 63 65 20 69 73 20 74 68 65 20 73 61 6d 65 20  ace is the same 
28130 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61  except that it a
28140 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 74 68  lways returns th
28150 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  e .** [extended 
28160 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65  result code] eve
28170 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20  n when extended 
28180 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
28190 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a  .** disabled..**
281a0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
281b0 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71  _errmsg() and sq
281c0 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
281d0 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d   return English-
281e0 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74  language.** text
281f0 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20   that describes 
28200 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69  the error, as ei
28210 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54  ther UTF-8 or UT
28220 46 2d 31 36 20 72 65 73 70 65 63 74 69 76 65 6c  F-16 respectivel
28230 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74  y..** ^(Memory t
28240 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72  o hold the error
28250 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
28260 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72  is managed inter
28270 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70  nally..** The ap
28280 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e  plication does n
28290 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79  ot need to worry
282a0 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74   about freeing t
282b0 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f  he result..** Ho
282c0 77 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72  wever, the error
282d0 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65   string might be
282e0 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20   overwritten or 
282f0 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a  deallocated by.*
28300 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  * subsequent cal
28310 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69  ls to other SQLi
28320 74 65 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e  te interface fun
28330 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  ctions.)^.**.** 
28340 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72  ^The sqlite3_err
28350 73 74 72 28 29 20 69 6e 74 65 72 66 61 63 65 20  str() interface 
28360 72 65 74 75 72 6e 73 20 74 68 65 20 45 6e 67 6c  returns the Engl
28370 69 73 68 2d 6c 61 6e 67 75 61 67 65 20 74 65 78  ish-language tex
28380 74 0a 2a 2a 20 74 68 61 74 20 64 65 73 63 72 69  t.** that descri
28390 62 65 73 20 74 68 65 20 5b 72 65 73 75 6c 74 20  bes the [result 
283a0 63 6f 64 65 5d 2c 20 61 73 20 55 54 46 2d 38 2e  code], as UTF-8.
283b0 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20  .** ^(Memory to 
283c0 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d  hold the error m
283d0 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73  essage string is
283e0 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61   managed interna
283f0 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75 73 74 20  lly.** and must 
28400 6e 6f 74 20 62 65 20 66 72 65 65 64 20 62 79 20  not be freed by 
28410 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29  the application)
28420 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  ^..**.** When th
28430 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e serialized [th
28440 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73  reading mode] is
28450 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68   in use, it migh
28460 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65  t be the.** case
28470 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65   that a second e
28480 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61  rror occurs on a
28490 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
284a0 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74   in between.** t
284b0 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66  he time of the f
284c0 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74  irst error and t
284d0 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65  he call to these
284e0 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
284f0 57 68 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e  When that happen
28500 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72  s, the second er
28510 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f  ror will be repo
28520 72 74 65 64 20 73 69 6e 63 65 20 74 68 65 73 65  rted since these
28530 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61  .** interfaces a
28540 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74 68 65  lways report the
28550 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73   most recent res
28560 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a  ult.  To avoid.*
28570 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74 68 72  * this, each thr
28580 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65  ead can obtain e
28590 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20  xclusive use of 
285a0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
285b0 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62  nnection] D.** b
285c0 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69  y invoking [sqli
285d0 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d  te3_mutex_enter]
285e0 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74  ([sqlite3_db_mut
285f0 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62  ex](D)) before b
28600 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75  eginning.** to u
28610 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e  se D and invokin
28620 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  g [sqlite3_mutex
28630 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33  _leave]([sqlite3
28640 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61  _db_mutex](D)) a
28650 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c  fter.** all call
28660 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61  s to the interfa
28670 63 65 73 20 6c 69 73 74 65 64 20 68 65 72 65 20  ces listed here 
28680 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a  are completed..*
28690 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72  *.** If an inter
286a0 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20  face fails with 
286b0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74  SQLITE_MISUSE, t
286c0 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e  hat means the in
286d0 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69  terface.** was i
286e0 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74  nvoked incorrect
286f0 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ly by the applic
28700 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20  ation.  In that 
28710 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72  case, the.** err
28720 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73  or code and mess
28730 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e  age may or may n
28740 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 53 51  ot be set..*/.SQ
28750 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
28760 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c  ite3_errcode(sql
28770 69 74 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54  ite3 *db);.SQLIT
28780 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
28790 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f  3_extended_errco
287a0 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b  de(sqlite3 *db);
287b0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
287c0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
287d0 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29  errmsg(sqlite3*)
287e0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
287f0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
28800 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65  _errmsg16(sqlite
28810 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  3*);.SQLITE_API 
28820 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
28830 74 65 33 5f 65 72 72 73 74 72 28 69 6e 74 29 3b  te3_errstr(int);
28840 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
28850 3a 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  : Prepared State
28860 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b  ment Object.** K
28870 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72  EYWORDS: {prepar
28880 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70  ed statement} {p
28890 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
288a0 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  ts}.**.** An ins
288b0 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
288c0 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20  ject represents 
288d0 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61  a single SQL sta
288e0 74 65 6d 65 6e 74 20 74 68 61 74 0a 2a 2a 20 68  tement that.** h
288f0 61 73 20 62 65 65 6e 20 63 6f 6d 70 69 6c 65 64  as been compiled
28900 20 69 6e 74 6f 20 62 69 6e 61 72 79 20 66 6f 72   into binary for
28910 6d 20 61 6e 64 20 69 73 20 72 65 61 64 79 20 74  m and is ready t
28920 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 2e 0a  o be evaluated..
28930 2a 2a 0a 2a 2a 20 54 68 69 6e 6b 20 6f 66 20 65  **.** Think of e
28940 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ach SQL statemen
28950 74 20 61 73 20 61 20 73 65 70 61 72 61 74 65 20  t as a separate 
28960 63 6f 6d 70 75 74 65 72 20 70 72 6f 67 72 61 6d  computer program
28970 2e 20 20 54 68 65 0a 2a 2a 20 6f 72 69 67 69 6e  .  The.** origin
28980 61 6c 20 53 51 4c 20 74 65 78 74 20 69 73 20 73  al SQL text is s
28990 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 41 20 70  ource code.  A p
289a0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
289b0 74 20 6f 62 6a 65 63 74 20 0a 2a 2a 20 69 73 20  t object .** is 
289c0 74 68 65 20 63 6f 6d 70 69 6c 65 64 20 6f 62 6a  the compiled obj
289d0 65 63 74 20 63 6f 64 65 2e 20 20 41 6c 6c 20 53  ect code.  All S
289e0 51 4c 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  QL must be conve
289f0 72 74 65 64 20 69 6e 74 6f 20 61 0a 2a 2a 20 70  rted into a.** p
28a00 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
28a10 74 20 62 65 66 6f 72 65 20 69 74 20 63 61 6e 20  t before it can 
28a20 62 65 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  be run..**.** Th
28a30 65 20 6c 69 66 65 2d 63 79 63 6c 65 20 6f 66 20  e life-cycle of 
28a40 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  a prepared state
28a50 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75 73 75 61  ment object usua
28a60 6c 6c 79 20 67 6f 65 73 20 6c 69 6b 65 20 74 68  lly goes like th
28a70 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a  is:.**.** <ol>.*
28a80 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68  * <li> Create th
28a90 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
28aa0 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75 73 69 6e  ment object usin
28ab0 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
28ac0 72 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 3c 6c 69  re_v2()]..** <li
28ad0 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f  > Bind values to
28ae0 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73   [parameters] us
28af0 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
28b00 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20  bind_*().**     
28b10 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
28b20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c  <li> Run the SQL
28b30 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
28b40 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65  ite3_step()] one
28b50 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a   or more times..
28b60 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68  ** <li> Reset th
28b70 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
28b80 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ment using [sqli
28b90 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65  te3_reset()] the
28ba0 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20  n go back.**    
28bb0 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f    to step 2.  Do
28bc0 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f   this zero or mo
28bd0 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69  re times..** <li
28be0 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62  > Destroy the ob
28bf0 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ject using [sqli
28c00 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e  te3_finalize()].
28c10 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 74 79 70  .** </ol>.*/.typ
28c20 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
28c30 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33  te3_stmt sqlite3
28c40 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  _stmt;../*.** CA
28c50 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65  PI3REF: Run-time
28c60 20 4c 69 6d 69 74 73 0a 2a 2a 20 4d 45 54 48 4f   Limits.** METHO
28c70 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
28c80 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61 63   ^(This interfac
28c90 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a  e allows the siz
28ca0 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e  e of various con
28cb0 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69  structs to be li
28cc0 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f  mited.** on a co
28cd0 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e  nnection by conn
28ce0 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54  ection basis.  T
28cf0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
28d00 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61  er is the.** [da
28d10 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
28d20 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69  n] whose limit i
28d30 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71  s to be set or q
28d40 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20  ueried.  The.** 
28d50 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
28d60 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b   is one of the [
28d70 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
28d80 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a  ] that define a.
28d90 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73  ** class of cons
28da0 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a  tructs to be siz
28db0 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20  e limited.  The 
28dc0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
28dd0 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69  is the.** new li
28de0 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e  mit for that con
28df0 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  struct.)^.**.** 
28e00 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69  ^If the new limi
28e10 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20  t is a negative 
28e20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69  number, the limi
28e30 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a  t is unchanged..
28e40 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69  ** ^(For each li
28e50 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c  mit category SQL
28e60 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d  ITE_LIMIT_<i>NAM
28e70 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61  E</i> there is a
28e80 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68   .** [limits | h
28e90 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d  ard upper bound]
28ea0 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69  .** set at compi
28eb0 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70  le-time by a C p
28ec0 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
28ed0 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d  o called.** [lim
28ee0 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58  its | SQLITE_MAX
28ef0 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a  _<i>NAME</i>]..*
28f00 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22  * (The "_LIMIT_"
28f10 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20   in the name is 
28f20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58  changed to "_MAX
28f30 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d  _".))^.** ^Attem
28f40 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20  pts to increase 
28f50 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74  a limit above it
28f60 73 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  s hard upper bou
28f70 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74  nd are.** silent
28f80 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20  ly truncated to 
28f90 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20 62  the hard upper b
28fa0 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67  ound..**.** ^Reg
28fb0 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
28fc0 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69  er or not the li
28fd0 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c  mit was changed,
28fe0 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   the .** [sqlite
28ff0 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72  3_limit()] inter
29000 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
29010 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20   prior value of 
29020 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48  the limit..** ^H
29030 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68  ence, to find th
29040 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20  e current value 
29050 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f  of a limit witho
29060 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a  ut changing it,.
29070 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65  ** simply invoke
29080 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
29090 77 69 74 68 20 74 68 65 20 74 68 69 72 64 20 70  with the third p
290a0 61 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20  arameter set to 
290b0 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69  -1..**.** Run-ti
290c0 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e  me limits are in
290d0 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69  tended for use i
290e0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  n applications t
290f0 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f  hat manage.** bo
29100 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74  th their own int
29110 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61  ernal database a
29120 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65  nd also database
29130 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72  s that are contr
29140 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72  olled.** by untr
29150 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73  usted external s
29160 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d  ources.  An exam
29170 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  ple application 
29180 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65  might be a.** we
29190 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 20 68  b browser that h
291a0 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62  as its own datab
291b0 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67  ases for storing
291c0 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20   history and.** 
291d0 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61 73  separate databas
291e0 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79  es controlled by
291f0 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 6c   JavaScript appl
29200 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61  ications downloa
29210 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49  ded.** off the I
29220 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e  nternet.  The in
29230 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73  ternal databases
29240 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68   can be given th
29250 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61  e.** large, defa
29260 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74  ult limits.  Dat
29270 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62  abases managed b
29280 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63  y external sourc
29290 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76  es can.** be giv
292a0 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20  en much smaller 
292b0 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20  limits designed 
292c0 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e  to prevent a den
292d0 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a  ial of service.*
292e0 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c  * attack.  Devel
292f0 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f  opers might also
29300 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65   want to use the
29310 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
29320 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69  thorizer()].** i
29330 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 74  nterface to furt
29340 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72  her control untr
29350 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20  usted SQL.  The 
29360 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61  size of the data
29370 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20  base.** created 
29380 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  by an untrusted 
29390 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f  script can be co
293a0 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68  ntained using th
293b0 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63  e.** [max_page_c
293c0 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a  ount] [PRAGMA]..
293d0 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69  **.** New run-ti
293e0 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  me limit categor
293f0 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ies may be added
29400 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
29410 73 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ses..*/.SQLITE_A
29420 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c  PI int sqlite3_l
29430 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69  imit(sqlite3*, i
29440 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61  nt id, int newVa
29450 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
29460 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69  REF: Run-Time Li
29470 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a 2a  mit Categories.*
29480 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d  * KEYWORDS: {lim
29490 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c  it category} {*l
294a0 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d  imit categories}
294b0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
294c0 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61  stants define va
294d0 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e 63  rious performanc
294e0 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74  e limits.** that
294f0 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 20   can be lowered 
29500 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e  at run-time usin
29510 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  g [sqlite3_limit
29520 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f  ()]..** The syno
29530 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61 6e  psis of the mean
29540 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72 69  ings of the vari
29550 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73 68  ous limits is sh
29560 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64  own below..** Ad
29570 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
29580 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c  tion is availabl
29590 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c  e at [limits | L
295a0 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65 5d  imits in SQLite]
295b0 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ..**.** <dl>.** 
295c0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  [[SQLITE_LIMIT_L
295d0 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  ENGTH]] ^(<dt>SQ
295e0 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
295f0 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
29600 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f  e maximum size o
29610 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20  f any string or 
29620 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f  BLOB or table ro
29630 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e  w, in bytes.<dd>
29640 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
29650 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
29660 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  TH]] ^(<dt>SQLIT
29670 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
29680 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
29690 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
296a0 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74  h of an SQL stat
296b0 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e  ement, in bytes.
296c0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
296d0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
296e0 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  UMN]] ^(<dt>SQLI
296f0 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c  TE_LIMIT_COLUMN<
29700 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
29710 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
29720 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74  f columns in a t
29730 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20  able definition 
29740 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73  or in the.** res
29750 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45  ult set of a [SE
29760 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78  LECT] or the max
29770 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63  imum number of c
29780 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64  olumns in an ind
29790 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f  ex.** or in an O
297a0 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50  RDER BY or GROUP
297b0 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e   BY clause.</dd>
297c0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
297d0 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
297e0 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  TH]] ^(<dt>SQLIT
297f0 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
29800 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
29810 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68  he maximum depth
29820 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 74 72   of the parse tr
29830 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73  ee on any expres
29840 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  sion.</dd>)^.**.
29850 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
29860 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
29870 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  T]] ^(<dt>SQLITE
29880 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
29890 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c  SELECT</dt>.** <
298a0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
298b0 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69  umber of terms i
298c0 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c  n a compound SEL
298d0 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f  ECT statement.</
298e0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
298f0 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
29900 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  OP]] ^(<dt>SQLIT
29910 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c  E_LIMIT_VDBE_OP<
29920 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
29930 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
29940 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69  f instructions i
29950 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68  n a virtual mach
29960 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75  ine program.** u
29970 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
29980 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
29990 74 2e 20 20 49 66 20 5b 73 71 6c 69 74 65 33 5f  t.  If [sqlite3_
299a0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
299b0 0a 2a 2a 20 74 68 65 20 65 71 75 69 76 61 6c 65  .** the equivale
299c0 6e 74 20 74 72 69 65 73 20 74 6f 20 61 6c 6c 6f  nt tries to allo
299d0 63 61 74 65 20 73 70 61 63 65 20 66 6f 72 20 6d  cate space for m
299e0 6f 72 65 20 74 68 61 6e 20 74 68 69 73 20 6d 61  ore than this ma
299f0 6e 79 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 69 6e  ny opcodes.** in
29a00 20 61 20 73 69 6e 67 6c 65 20 70 72 65 70 61 72   a single prepar
29a10 65 64 20 73 74 61 74 65 6d 65 6e 74 2c 20 61 6e  ed statement, an
29a20 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 65 72   SQLITE_NOMEM er
29a30 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ror is returned.
29a40 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
29a50 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
29a60 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64  CTION_ARG]] ^(<d
29a70 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  t>SQLITE_LIMIT_F
29a80 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e  UNCTION_ARG</dt>
29a90 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
29aa0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  mum number of ar
29ab0 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e  guments on a fun
29ac0 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ction.</dd>)^.**
29ad0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
29ae0 49 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e 28  IT_ATTACHED]] ^(
29af0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
29b00 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a  _ATTACHED</dt>.*
29b10 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
29b20 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54  m number of [ATT
29b30 41 43 48 20 7c 20 61 74 74 61 63 68 65 64 20 64  ACH | attached d
29b40 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64  atabases].)^</dd
29b50 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
29b60 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
29b70 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20  ERN_LENGTH]].** 
29b80 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
29b90 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
29ba0 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
29bb0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c  dd>The maximum l
29bc0 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74  ength of the pat
29bd0 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f  tern argument to
29be0 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a   the [LIKE] or.*
29bf0 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f  * [GLOB] operato
29c00 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  rs.</dd>)^.**.**
29c10 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
29c20 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d  VARIABLE_NUMBER]
29c30 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  ].** ^(<dt>SQLIT
29c40 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
29c50 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20  _NUMBER</dt>.** 
29c60 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
29c70 69 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20  index number of 
29c80 61 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20  any [parameter] 
29c90 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  in an SQL statem
29ca0 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  ent.)^.**.** [[S
29cb0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47  QLITE_LIMIT_TRIG
29cc0 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64  GER_DEPTH]] ^(<d
29cd0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54  t>SQLITE_LIMIT_T
29ce0 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74  RIGGER_DEPTH</dt
29cf0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
29d00 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65  imum depth of re
29d10 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67  cursion for trig
29d20 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  gers.</dd>)^.**.
29d30 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
29d40 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53  T_WORKER_THREADS
29d50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
29d60 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52  LIMIT_WORKER_THR
29d70 45 41 44 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  EADS</dt>.** <dd
29d80 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
29d90 62 65 72 20 6f 66 20 61 75 78 69 6c 69 61 72 79  ber of auxiliary
29da0 20 77 6f 72 6b 65 72 20 74 68 72 65 61 64 73 20   worker threads 
29db0 74 68 61 74 20 61 20 73 69 6e 67 6c 65 0a 2a 2a  that a single.**
29dc0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
29dd0 6d 65 6e 74 5d 20 6d 61 79 20 73 74 61 72 74 2e  ment] may start.
29de0 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e  </dd>)^.** </dl>
29df0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
29e00 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20  TE_LIMIT_LENGTH 
29e10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
29e20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
29e30 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
29e40 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20  NGTH            
29e50 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
29e60 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
29e70 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  N               
29e80 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
29e90 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
29ea0 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20  _DEPTH          
29eb0 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
29ec0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d  SQLITE_LIMIT_COM
29ed0 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20  POUND_SELECT    
29ee0 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65         4.#define
29ef0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44   SQLITE_LIMIT_VD
29f00 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20  BE_OP           
29f10 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e          5.#defin
29f20 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  e SQLITE_LIMIT_F
29f30 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20  UNCTION_ARG     
29f40 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69           6.#defi
29f50 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
29f60 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20 20  ATTACHED        
29f70 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66            7.#def
29f80 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
29f90 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45  _LIKE_PATTERN_LE
29fa0 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 65  NGTH       8.#de
29fb0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
29fc0 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
29fd0 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 23 64  R           9.#d
29fe0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
29ff0 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48  IT_TRIGGER_DEPTH
2a000 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23              10.#
2a010 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
2a020 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41  MIT_WORKER_THREA
2a030 44 53 20 20 20 20 20 20 20 20 20 20 20 31 31 0a  DS           11.
2a040 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2a050 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53  : Compiling An S
2a060 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  QL Statement.** 
2a070 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73  KEYWORDS: {SQL s
2a080 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65  tatement compile
2a090 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  r}.** METHOD: sq
2a0a0 6c 69 74 65 33 0a 2a 2a 20 43 4f 4e 53 54 52 55  lite3.** CONSTRU
2a0b0 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73 74  CTOR: sqlite3_st
2a0c0 6d 74 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63  mt.**.** To exec
2a0d0 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79  ute an SQL query
2a0e0 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20  , it must first 
2a0f0 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f  be compiled into
2a100 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20   a byte-code.** 
2a110 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e  program using on
2a120 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  e of these routi
2a130 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  nes..**.** The f
2a140 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22  irst argument, "
2a150 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62  db", is a [datab
2a160 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
2a170 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a  obtained from a.
2a180 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 73  ** prior success
2a190 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
2a1a0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
2a1b0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
2a1c0 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
2a1d0 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65  _open16()].  The
2a1e0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2a1f0 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61  tion must not ha
2a200 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a  ve been closed..
2a210 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
2a220 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c   argument, "zSql
2a230 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d  ", is the statem
2a240 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c  ent to be compil
2a250 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61  ed, encoded.** a
2a260 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f  s either UTF-8 o
2a270 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73  r UTF-16.  The s
2a280 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
2a290 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
2a2a0 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74  pare_v2().** int
2a2b0 65 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d  erfaces use UTF-
2a2c0 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  8, and sqlite3_p
2a2d0 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 73  repare16() and s
2a2e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2a2f0 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46  _v2().** use UTF
2a300 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  -16..**.** ^If t
2a310 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e  he nByte argumen
2a320 74 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  t is negative, t
2a330 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64  hen zSql is read
2a340 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69   up to the.** fi
2a350 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  rst zero termina
2a360 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65 20 69  tor. ^If nByte i
2a370 73 20 70 6f 73 69 74 69 76 65 2c 20 74 68 65 6e  s positive, then
2a380 20 69 74 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75   it is the.** nu
2a390 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 72 65  mber of bytes re
2a3a0 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e  ad from zSql.  ^
2a3b0 49 66 20 6e 42 79 74 65 20 69 73 20 7a 65 72 6f  If nByte is zero
2a3c0 2c 20 74 68 65 6e 20 6e 6f 20 70 72 65 70 61 72  , then no prepar
2a3d0 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  ed.** statement 
2a3e0 69 73 20 67 65 6e 65 72 61 74 65 64 2e 0a 2a 2a  is generated..**
2a3f0 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b   If the caller k
2a400 6e 6f 77 73 20 74 68 61 74 20 74 68 65 20 73 75  nows that the su
2a410 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73  pplied string is
2a420 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c   nul-terminated,
2a430 20 74 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20 69   then.** there i
2a440 73 20 61 20 73 6d 61 6c 6c 20 70 65 72 66 6f 72  s a small perfor
2a450 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20  mance advantage 
2a460 74 6f 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42  to passing an nB
2a470 79 74 65 20 70 61 72 61 6d 65 74 65 72 20 74 68  yte parameter th
2a480 61 74 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d  at.** is the num
2a490 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
2a4a0 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
2a4b0 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69   <i>including</i
2a4c0 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72  >.** the nul-ter
2a4d0 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e  minator..**.** ^
2a4e0 49 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74  If pzTail is not
2a4f0 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61   NULL then *pzTa
2a500 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f  il is made to po
2a510 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74  int to the first
2a520 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68   byte.** past th
2a530 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72  e end of the fir
2a540 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  st SQL statement
2a550 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65   in zSql.  These
2a560 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a   routines only.*
2a570 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69  * compile the fi
2a580 72 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  rst statement in
2a590 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69   zSql, so *pzTai
2a5a0 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69  l is left pointi
2a5b0 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65  ng to.** what re
2a5c0 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64  mains uncompiled
2a5d0 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74  ..**.** ^*ppStmt
2a5e0 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e   is left pointin
2a5f0 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20  g to a compiled 
2a600 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2a610 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65  ent] that can be
2a620 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69  .** executed usi
2a630 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
2a640 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20  ()].  ^If there 
2a650 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70  is an error, *pp
2a660 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74  Stmt is set.** t
2a670 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65  o NULL.  ^If the
2a680 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74   input text cont
2a690 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20  ains no SQL (if 
2a6a0 74 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20  the input is an 
2a6b0 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20  empty.** string 
2a6c0 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68  or a comment) th
2a6d0 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65  en *ppStmt is se
2a6e0 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68  t to NULL..** Th
2a6f0 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64  e calling proced
2a700 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62  ure is responsib
2a710 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20  le for deleting 
2a720 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20  the compiled.** 
2a730 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73  SQL statement us
2a740 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
2a750 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69  alize()] after i
2a760 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  t has finished w
2a770 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d  ith it..** ppStm
2a780 74 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c  t may not be NUL
2a790 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63  L..**.** ^On suc
2a7a0 63 65 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65  cess, the sqlite
2a7b0 33 5f 70 72 65 70 61 72 65 28 29 20 66 61 6d 69  3_prepare() fami
2a7c0 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72  ly of routines r
2a7d0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
2a7e0 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20  ];.** otherwise 
2a7f0 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
2a800 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
2a810 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70  ** The sqlite3_p
2a820 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20  repare_v2() and 
2a830 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2a840 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65  6_v2() interface
2a850 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65  s are.** recomme
2a860 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77  nded for all new
2a870 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74   programs. The t
2a880 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61  wo older interfa
2a890 63 65 73 20 61 72 65 20 72 65 74 61 69 6e 65 64  ces are retained
2a8a0 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64  .** for backward
2a8b0 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c  s compatibility,
2a8c0 20 62 75 74 20 74 68 65 69 72 20 75 73 65 20 69   but their use i
2a8d0 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a  s discouraged..*
2a8e0 2a 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69  * ^In the "v2" i
2a8f0 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 70  nterfaces, the p
2a900 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2a910 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74  t.** that is ret
2a920 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69  urned (the [sqli
2a930 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74  te3_stmt] object
2a940 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70  ) contains a cop
2a950 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67  y of the.** orig
2a960 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54  inal SQL text. T
2a970 68 69 73 20 63 61 75 73 65 73 20 74 68 65 20 5b  his causes the [
2a980 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2a990 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20  interface to.** 
2a9a0 62 65 68 61 76 65 20 64 69 66 66 65 72 65 6e 74  behave different
2a9b0 6c 79 20 69 6e 20 74 68 72 65 65 20 77 61 79 73  ly in three ways
2a9c0 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20  :.**.** <ol>.** 
2a9d0 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  <li>.** ^If the 
2a9e0 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20  database schema 
2a9f0 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64  changes, instead
2aa00 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53   of returning [S
2aa10 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73  QLITE_SCHEMA] as
2aa20 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73   it.** always us
2aa30 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74  ed to do, [sqlit
2aa40 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20  e3_step()] will 
2aa50 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65  automatically re
2aa60 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a  compile the SQL.
2aa70 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  ** statement and
2aa80 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61   try to run it a
2aa90 67 61 69 6e 2e 20 41 73 20 6d 61 6e 79 20 61 73  gain. As many as
2aaa0 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 53 43 48   [SQLITE_MAX_SCH
2aab0 45 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a 20 72 65  EMA_RETRY].** re
2aac0 74 72 69 65 73 20 77 69 6c 6c 20 6f 63 63 75 72  tries will occur
2aad0 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f   before sqlite3_
2aae0 73 74 65 70 28 29 20 67 69 76 65 73 20 75 70 20  step() gives up 
2aaf0 61 6e 64 20 72 65 74 75 72 6e 73 20 61 6e 20 65  and returns an e
2ab00 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a  rror..** </li>.*
2ab10 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68  *.** <li>.** ^Wh
2ab20 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  en an error occu
2ab30 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  rs, [sqlite3_ste
2ab40 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  p()] will return
2ab50 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61   one of the deta
2ab60 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63  iled.** [error c
2ab70 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64  odes] or [extend
2ab80 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e  ed error codes].
2ab90 20 20 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65    ^The legacy be
2aba0 68 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a  havior was that.
2abb0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
2abc0 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72  ()] would only r
2abd0 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20  eturn a generic 
2abe0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72  [SQLITE_ERROR] r
2abf0 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e  esult code.** an
2ac00 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  d the applicatio
2ac10 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20  n would have to 
2ac20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61  make a second ca
2ac30 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ll to [sqlite3_r
2ac40 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72  eset()].** in or
2ac50 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20  der to find the 
2ac60 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65  underlying cause
2ac70 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e   of the problem.
2ac80 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20 70   With the "v2" p
2ac90 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66  repare.** interf
2aca0 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c  aces, the underl
2acb0 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20  ying reason for 
2acc0 74 68 65 20 65 72 72 6f 72 20 69 73 20 72 65 74  the error is ret
2acd0 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  urned immediatel
2ace0 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a  y..** </li>.**.*
2acf0 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68  * <li>.** ^If th
2ad00 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65  e specific value
2ad10 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d   bound to [param
2ad20 65 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61  eter | host para
2ad30 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a  meter] in the .*
2ad40 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d  * WHERE clause m
2ad50 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74  ight influence t
2ad60 68 65 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65  he choice of que
2ad70 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74  ry plan for a st
2ad80 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e  atement,.** then
2ad90 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77   the statement w
2ada0 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63  ill be automatic
2adb0 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c  ally recompiled,
2adc0 20 61 73 20 69 66 20 74 68 65 72 65 20 68 61 64   as if there had
2add0 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65   been .** a sche
2ade0 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68  ma change, on th
2adf0 65 20 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65  e first  [sqlite
2ae00 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66  3_step()] call f
2ae10 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61  ollowing any cha
2ae20 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73  nge.** to the [s
2ae30 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2ae40 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20   | bindings] of 
2ae50 74 68 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d  that [parameter]
2ae60 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69  . .** ^The speci
2ae70 66 69 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45  fic value of WHE
2ae80 52 45 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d  RE-clause [param
2ae90 65 74 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c  eter] might infl
2aea0 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68  uence the .** ch
2aeb0 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c  oice of query pl
2aec0 61 6e 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  an if the parame
2aed0 74 65 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d  ter is the left-
2aee0 68 61 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b  hand side of a [
2aef0 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f  LIKE].** or [GLO
2af00 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69  B] operator or i
2af10 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
2af20 69 73 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61  is compared to a
2af30 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e  n indexed column
2af40 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c  .** and the [SQL
2af50 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33  ITE_ENABLE_STAT3
2af60 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
2af70 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64  ption is enabled
2af80 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  ..** </li>.** </
2af90 6f 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ol>.*/.SQLITE_AP
2afa0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  I int sqlite3_pr
2afb0 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33  epare(.  sqlite3
2afc0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
2afd0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
2afe0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
2aff0 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  har *zSql,      
2b000 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
2b010 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  t, UTF-8 encoded
2b020 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
2b030 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2b040 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
2b050 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
2b060 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
2b070 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
2b080 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
2b090 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2b0a0 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c  st char **pzTail
2b0b0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
2b0c0 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
2b0d0 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
2b0e0 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  /.);.SQLITE_API 
2b0f0 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
2b100 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  are_v2(.  sqlite
2b110 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
2b120 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
2b130 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2b140 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
2b150 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
2b160 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  nt, UTF-8 encode
2b170 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
2b180 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
2b190 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
2b1a0 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
2b1b0 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
2b1c0 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
2b1d0 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
2b1e0 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
2b1f0 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69  nst char **pzTai
2b200 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
2b210 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
2b220 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
2b230 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  */.);.SQLITE_API
2b240 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65   int sqlite3_pre
2b250 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65  pare16(.  sqlite
2b260 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
2b270 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database 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 7a 53 71 6c 2c 20 20 20 20 20  void *zSql,     
2b2a0 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
2b2b0 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  nt, UTF-16 encod
2b2c0 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
2b2d0 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
2b2e0 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
2b2f0 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
2b300 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
2b310 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
2b320 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
2b330 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
2b340 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61  onst void **pzTa
2b350 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
2b360 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
2b370 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
2b380 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50   */.);.SQLITE_AP
2b390 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  I int sqlite3_pr
2b3a0 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71  epare16_v2(.  sq
2b3b0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
2b3c0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
2b3d0 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
2b3e0 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
2b3f0 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
2b400 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
2b410 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
2b420 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
2b430 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
2b440 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
2b450 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
2b460 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
2b470 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
2b480 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
2b490 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
2b4a0 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
2b4b0 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
2b4c0 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
2b4d0 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  zSql */.);../*.*
2b4e0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 72  * CAPI3REF: Retr
2b4f0 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74  ieving Statement
2b500 20 53 51 4c 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20   SQL.** METHOD: 
2b510 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2b520 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2b530 73 71 6c 28 50 29 20 69 6e 74 65 72 66 61 63 65  sql(P) interface
2b540 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
2b550 65 72 20 74 6f 20 61 20 63 6f 70 79 20 6f 66 20  er to a copy of 
2b560 74 68 65 20 55 54 46 2d 38 0a 2a 2a 20 53 51 4c  the UTF-8.** SQL
2b570 20 74 65 78 74 20 75 73 65 64 20 74 6f 20 63 72   text used to cr
2b580 65 61 74 65 20 5b 70 72 65 70 61 72 65 64 20 73  eate [prepared s
2b590 74 61 74 65 6d 65 6e 74 5d 20 50 20 69 66 20 50  tatement] P if P
2b5a0 20 77 61 73 0a 2a 2a 20 63 72 65 61 74 65 64 20   was.** created 
2b5b0 62 79 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74  by either [sqlit
2b5c0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2b5d0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
2b5e0 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a  pare16_v2()]..**
2b5f0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
2b600 70 61 6e 64 65 64 5f 73 71 6c 28 50 29 20 69 6e  panded_sql(P) in
2b610 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2b620 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 55  a pointer to a U
2b630 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 63  TF-8.** string c
2b640 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 53 51  ontaining the SQ
2b650 4c 20 74 65 78 74 20 6f 66 20 70 72 65 70 61 72  L text of prepar
2b660 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20 77  ed statement P w
2b670 69 74 68 0a 2a 2a 20 5b 62 6f 75 6e 64 20 70 61  ith.** [bound pa
2b680 72 61 6d 65 74 65 72 73 5d 20 65 78 70 61 6e 64  rameters] expand
2b690 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20  ed..**.** ^(For 
2b6a0 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 20 70 72  example, if a pr
2b6b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2b6c0 20 69 73 20 63 72 65 61 74 65 64 20 75 73 69 6e   is created usin
2b6d0 67 20 74 68 65 20 53 51 4c 0a 2a 2a 20 74 65 78  g the SQL.** tex
2b6e0 74 20 22 53 45 4c 45 43 54 20 24 61 62 63 2c 3a  t "SELECT $abc,:
2b6f0 78 79 7a 22 20 61 6e 64 20 69 66 20 70 61 72 61  xyz" and if para
2b700 6d 65 74 65 72 20 24 61 62 63 20 69 73 20 62 6f  meter $abc is bo
2b710 75 6e 64 20 74 6f 20 69 6e 74 65 67 65 72 20 32  und to integer 2
2b720 33 34 35 0a 2a 2a 20 61 6e 64 20 70 61 72 61 6d  345.** and param
2b730 65 74 65 72 20 3a 78 79 7a 20 69 73 20 75 6e 62  eter :xyz is unb
2b740 6f 75 6e 64 2c 20 74 68 65 6e 20 73 71 6c 69 74  ound, then sqlit
2b750 65 33 5f 73 71 6c 28 29 20 77 69 6c 6c 20 72 65  e3_sql() will re
2b760 74 75 72 6e 0a 2a 2a 20 74 68 65 20 6f 72 69 67  turn.** the orig
2b770 69 6e 61 6c 20 73 74 72 69 6e 67 2c 20 22 53 45  inal string, "SE
2b780 4c 45 43 54 20 24 61 62 63 2c 3a 78 79 7a 22 20  LECT $abc,:xyz" 
2b790 62 75 74 20 73 71 6c 69 74 65 33 5f 65 78 70 61  but sqlite3_expa
2b7a0 6e 64 65 64 5f 73 71 6c 28 29 0a 2a 2a 20 77 69  nded_sql().** wi
2b7b0 6c 6c 20 72 65 74 75 72 6e 20 22 53 45 4c 45 43  ll return "SELEC
2b7c0 54 20 32 33 34 35 2c 4e 55 4c 4c 22 2e 29 5e 0a  T 2345,NULL".)^.
2b7d0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2b7e0 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28  e3_expanded_sql(
2b7f0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2b800 72 6e 73 20 4e 55 4c 4c 20 69 66 20 69 6e 73 75  rns NULL if insu
2b810 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 0a  fficient memory.
2b820 2a 2a 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20  ** is available 
2b830 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75  to hold the resu
2b840 6c 74 2c 20 6f 72 20 69 66 20 74 68 65 20 72 65  lt, or if the re
2b850 73 75 6c 74 20 77 6f 75 6c 64 20 65 78 63 65 65  sult would excee
2b860 64 20 74 68 65 0a 2a 2a 20 74 68 65 20 6d 61 78  d the.** the max
2b870 69 6d 75 6d 20 73 74 72 69 6e 67 20 6c 65 6e 67  imum string leng
2b880 74 68 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79  th determined by
2b890 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4c 49 4d   the [SQLITE_LIM
2b8a0 49 54 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 0a 2a  IT_LENGTH]..**.*
2b8b0 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 54  * ^The [SQLITE_T
2b8c0 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d  RACE_SIZE_LIMIT]
2b8d0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
2b8e0 74 69 6f 6e 20 6c 69 6d 69 74 73 20 74 68 65 20  tion limits the 
2b8f0 73 69 7a 65 20 6f 66 0a 2a 2a 20 62 6f 75 6e 64  size of.** bound
2b900 20 70 61 72 61 6d 65 74 65 72 20 65 78 70 61 6e   parameter expan
2b910 73 69 6f 6e 73 2e 20 20 5e 54 68 65 20 5b 53 51  sions.  ^The [SQ
2b920 4c 49 54 45 5f 4f 4d 49 54 5f 54 52 41 43 45 5d  LITE_OMIT_TRACE]
2b930 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a   compile-time.**
2b940 20 6f 70 74 69 6f 6e 20 63 61 75 73 65 73 20 73   option causes s
2b950 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f  qlite3_expanded_
2b960 73 71 6c 28 29 20 74 6f 20 61 6c 77 61 79 73 20  sql() to always 
2b970 72 65 74 75 72 6e 20 4e 55 4c 4c 2e 0a 2a 2a 0a  return NULL..**.
2b980 2a 2a 20 5e 54 68 65 20 73 74 72 69 6e 67 20 72  ** ^The string r
2b990 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
2b9a0 65 33 5f 73 71 6c 28 50 29 20 69 73 20 6d 61 6e  e3_sql(P) is man
2b9b0 61 67 65 64 20 62 79 20 53 51 4c 69 74 65 20 61  aged by SQLite a
2b9c0 6e 64 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74  nd is.** automat
2b9d0 69 63 61 6c 6c 79 20 66 72 65 65 64 20 77 68 65  ically freed whe
2b9e0 6e 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  n the prepared s
2b9f0 74 61 74 65 6d 65 6e 74 20 69 73 20 66 69 6e 61  tatement is fina
2ba00 6c 69 7a 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73  lized..** ^The s
2ba10 74 72 69 6e 67 20 72 65 74 75 72 6e 65 64 20 62  tring returned b
2ba20 79 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64  y sqlite3_expand
2ba30 65 64 5f 73 71 6c 28 50 29 2c 20 6f 6e 20 74 68  ed_sql(P), on th
2ba40 65 20 6f 74 68 65 72 20 68 61 6e 64 2c 0a 2a 2a  e other hand,.**
2ba50 20 69 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f   is obtained fro
2ba60 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
2ba70 63 28 29 5d 20 61 6e 64 20 6d 75 73 74 20 62 65  c()] and must be
2ba80 20 66 72 65 65 20 62 79 20 74 68 65 20 61 70 70   free by the app
2ba90 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 62 79 20 70  lication.** by p
2baa0 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71  assing it to [sq
2bab0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a  lite3_free()]..*
2bac0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  /.SQLITE_API con
2bad0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
2bae0 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d  _sql(sqlite3_stm
2baf0 74 20 2a 70 53 74 6d 74 29 3b 0a 53 51 4c 49 54  t *pStmt);.SQLIT
2bb00 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69  E_API char *sqli
2bb10 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c  te3_expanded_sql
2bb20 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
2bb30 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
2bb40 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e  PI3REF: Determin
2bb50 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74  e If An SQL Stat
2bb60 65 6d 65 6e 74 20 57 72 69 74 65 73 20 54 68 65  ement Writes The
2bb70 20 44 61 74 61 62 61 73 65 0a 2a 2a 20 4d 45 54   Database.** MET
2bb80 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
2bb90 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
2bba0 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
2bbb0 6c 79 28 58 29 20 69 6e 74 65 72 66 61 63 65 20  ly(X) interface 
2bbc0 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f  returns true (no
2bbd0 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e  n-zero) if.** an
2bbe0 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70  d only if the [p
2bbf0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2bc00 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69  t] X makes no di
2bc10 72 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a  rect changes to.
2bc20 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  ** the content o
2bc30 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  f the database f
2bc40 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  ile..**.** Note 
2bc50 74 68 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f  that [applicatio
2bc60 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
2bc70 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b  nctions] or.** [
2bc80 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20  virtual tables] 
2bc90 6d 69 67 68 74 20 63 68 61 6e 67 65 20 74 68 65  might change the
2bca0 20 64 61 74 61 62 61 73 65 20 69 6e 64 69 72 65   database indire
2bcb0 63 74 6c 79 20 61 73 20 61 20 73 69 64 65 20 65  ctly as a side e
2bcc0 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f  ffect.  .** ^(Fo
2bcd0 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e  r example, if an
2bce0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
2bcf0 69 6e 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20  ines a function 
2bd00 22 65 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a  "eval()" that .*
2bd10 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33  * calls [sqlite3
2bd20 5f 65 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74  _exec()], then t
2bd30 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c  he following SQL
2bd40 20 73 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64   statement would
2bd50 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64  .** change the d
2bd60 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 72  atabase file thr
2bd70 6f 75 67 68 20 73 69 64 65 2d 65 66 66 65 63 74  ough side-effect
2bd80 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
2bd90 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
2bda0 20 53 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45   SELECT eval('DE
2bdb0 4c 45 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46  LETE FROM t1') F
2bdc0 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65  ROM t2;.** </pre
2bdd0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
2bde0 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65  *.** But because
2bdf0 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74   the [SELECT] st
2be00 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74  atement does not
2be10 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61   change the data
2be20 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72  base file.** dir
2be30 65 63 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73  ectly, sqlite3_s
2be40 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77  tmt_readonly() w
2be50 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72  ould still retur
2be60 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  n true.)^.**.** 
2be70 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e  ^Transaction con
2be80 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20  trol statements 
2be90 73 75 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c  such as [BEGIN],
2bea0 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c   [COMMIT], [ROLL
2beb0 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50  BACK],.** [SAVEP
2bec0 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45  OINT], and [RELE
2bed0 41 53 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74  ASE] cause sqlit
2bee0 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
2bef0 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75  () to return tru
2bf00 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20  e,.** since the 
2bf10 73 74 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73  statements thems
2bf20 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74  elves do not act
2bf30 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65  ually modify the
2bf40 20 64 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a   database but.**
2bf50 20 72 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e   rather they con
2bf60 74 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20  trol the timing 
2bf70 6f 66 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74  of when other st
2bf80 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20  atements modify 
2bf90 74 68 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65  the .** database
2bfa0 2e 20 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d  .  ^The [ATTACH]
2bfb0 20 61 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74   and [DETACH] st
2bfc0 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61  atements also ca
2bfd0 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  use.** sqlite3_s
2bfe0 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74  tmt_readonly() t
2bff0 6f 20 72 65 74 75 72 6e 20 74 72 75 65 20 73 69  o return true si
2c000 6e 63 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65  nce, while those
2c010 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63   statements.** c
2c020 68 61 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67  hange the config
2c030 75 72 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74  uration of a dat
2c040 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2c050 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61  , they do not ma
2c060 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74  ke .** changes t
2c070 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  o the content of
2c080 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
2c090 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2a 20  les on disk..** 
2c0a0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d  ^The sqlite3_stm
2c0b0 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 69 6e 74  t_readonly() int
2c0c0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
2c0d0 72 75 65 20 66 6f 72 20 5b 42 45 47 49 4e 5d 20  rue for [BEGIN] 
2c0e0 73 69 6e 63 65 0a 2a 2a 20 5b 42 45 47 49 4e 5d  since.** [BEGIN]
2c0f0 20 6d 65 72 65 6c 79 20 73 65 74 73 20 69 6e 74   merely sets int
2c100 65 72 6e 61 6c 20 66 6c 61 67 73 2c 20 62 75 74  ernal flags, but
2c110 20 74 68 65 20 5b 42 45 47 49 4e 7c 42 45 47 49   the [BEGIN|BEGI
2c120 4e 20 49 4d 4d 45 44 49 41 54 45 5d 20 61 6e 64  N IMMEDIATE] and
2c130 0a 2a 2a 20 5b 42 45 47 49 4e 7c 42 45 47 49 4e  .** [BEGIN|BEGIN
2c140 20 45 58 43 4c 55 53 49 56 45 5d 20 63 6f 6d 6d   EXCLUSIVE] comm
2c150 61 6e 64 73 20 64 6f 20 74 6f 75 63 68 20 74 68  ands do touch th
2c160 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 73  e database and s
2c170 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d  o.** sqlite3_stm
2c180 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 72 65 74  t_readonly() ret
2c190 75 72 6e 73 20 66 61 6c 73 65 20 66 6f 72 20 74  urns false for t
2c1a0 68 6f 73 65 20 63 6f 6d 6d 61 6e 64 73 2e 0a 2a  hose commands..*
2c1b0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
2c1c0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
2c1d0 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73  adonly(sqlite3_s
2c1e0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
2c1f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
2c200 74 65 72 6d 69 6e 65 20 49 66 20 41 20 50 72 65  termine If A Pre
2c210 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
2c220 48 61 73 20 42 65 65 6e 20 52 65 73 65 74 0a 2a  Has Been Reset.*
2c230 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2c240 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  3_stmt.**.** ^Th
2c250 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62  e sqlite3_stmt_b
2c260 75 73 79 28 53 29 20 69 6e 74 65 72 66 61 63 65  usy(S) interface
2c270 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e   returns true (n
2c280 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68 65 0a  on-zero) if the.
2c290 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
2c2a0 74 65 6d 65 6e 74 5d 20 53 20 68 61 73 20 62 65  tement] S has be
2c2b0 65 6e 20 73 74 65 70 70 65 64 20 61 74 20 6c 65  en stepped at le
2c2c0 61 73 74 20 6f 6e 63 65 20 75 73 69 6e 67 20 0a  ast once using .
2c2d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
2c2e0 28 53 29 5d 20 62 75 74 20 68 61 73 20 6e 65 69  (S)] but has nei
2c2f0 74 68 65 72 20 72 75 6e 20 74 6f 20 63 6f 6d 70  ther run to comp
2c300 6c 65 74 69 6f 6e 20 28 72 65 74 75 72 6e 65 64  letion (returned
2c310 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  .** [SQLITE_DONE
2c320 5d 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  ] from [sqlite3_
2c330 73 74 65 70 28 53 29 5d 29 20 6e 6f 72 0a 2a 2a  step(S)]) nor.**
2c340 20 62 65 65 6e 20 72 65 73 65 74 20 75 73 69 6e   been reset usin
2c350 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
2c360 28 53 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69  (S)].  ^The sqli
2c370 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29  te3_stmt_busy(S)
2c380 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65  .** interface re
2c390 74 75 72 6e 73 20 66 61 6c 73 65 20 69 66 20 53  turns false if S
2c3a0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
2c3b0 65 72 2e 20 20 49 66 20 53 20 69 73 20 6e 6f 74  er.  If S is not
2c3c0 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e   a .** NULL poin
2c3d0 74 65 72 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ter and is not a
2c3e0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61   pointer to a va
2c3f0 6c 69 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  lid [prepared st
2c400 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65  atement].** obje
2c410 63 74 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  ct, then the beh
2c420 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
2c430 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20  ed and probably 
2c440 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a  undesirable..**.
2c450 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
2c460 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e  e can be used in
2c470 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71   combination [sq
2c480 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28  lite3_next_stmt(
2c490 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20  )].** to locate 
2c4a0 61 6c 6c 20 70 72 65 70 61 72 65 64 20 73 74 61  all prepared sta
2c4b0 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74  tements associat
2c4c0 65 64 20 77 69 74 68 20 61 20 64 61 74 61 62 61  ed with a databa
2c4d0 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  se .** connectio
2c4e0 6e 20 74 68 61 74 20 61 72 65 20 69 6e 20 6e 65  n that are in ne
2c4f0 65 64 20 6f 66 20 62 65 69 6e 67 20 72 65 73 65  ed of being rese
2c500 74 2e 20 20 54 68 69 73 20 63 61 6e 20 62 65 20  t.  This can be 
2c510 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61  used,.** for exa
2c520 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73  mple, in diagnos
2c530 74 69 63 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  tic routines to 
2c540 73 65 61 72 63 68 20 66 6f 72 20 70 72 65 70 61  search for prepa
2c550 72 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  red .** statemen
2c560 74 73 20 74 68 61 74 20 61 72 65 20 68 6f 6c 64  ts that are hold
2c570 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ing a transactio
2c580 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54  n open..*/.SQLIT
2c590 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
2c5a0 33 5f 73 74 6d 74 5f 62 75 73 79 28 73 71 6c 69  3_stmt_busy(sqli
2c5b0 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
2c5c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e  ** CAPI3REF: Dyn
2c5d0 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56  amically Typed V
2c5e0 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b  alue Object.** K
2c5f0 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63  EYWORDS: {protec
2c600 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2c610 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20  e} {unprotected 
2c620 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a  sqlite3_value}.*
2c630 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  *.** SQLite uses
2c640 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c   the sqlite3_val
2c650 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70  ue object to rep
2c660 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65  resent all value
2c670 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65  s.** that can be
2c680 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74   stored in a dat
2c690 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c  abase table. SQL
2c6a0 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63  ite uses dynamic
2c6b0 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74   typing.** for t
2c6c0 68 65 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f  he values it sto
2c6d0 72 65 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 74  res.  ^Values st
2c6e0 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f  ored in sqlite3_
2c6f0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a  value objects.**
2c700 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73   can be integers
2c710 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  , floating point
2c720 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73   values, strings
2c730 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c  , BLOBs, or NULL
2c740 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74  ..**.** An sqlit
2c750 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
2c760 6d 61 79 20 62 65 20 65 69 74 68 65 72 20 22 70  may be either "p
2c770 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e  rotected" or "un
2c780 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53  protected"..** S
2c790 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20 72  ome interfaces r
2c7a0 65 71 75 69 72 65 20 61 20 70 72 6f 74 65 63 74  equire a protect
2c7b0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2c7c0 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61  .  Other interfa
2c7d0 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65  ces.** will acce
2c7e0 70 74 20 65 69 74 68 65 72 20 61 20 70 72 6f 74  pt either a prot
2c7f0 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72  ected or an unpr
2c800 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2c810 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20  value..** Every 
2c820 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61  interface that a
2c830 63 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76  ccepts sqlite3_v
2c840 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73  alue arguments s
2c850 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74  pecifies.** whet
2c860 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65  her or not it re
2c870 71 75 69 72 65 73 20 61 20 70 72 6f 74 65 63 74  quires a protect
2c880 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2c890 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  .  The.** [sqlit
2c8a0 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 29 5d 20  e3_value_dup()] 
2c8b0 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65  interface can be
2c8c0 20 75 73 65 64 20 74 6f 20 63 6f 6e 73 74 72 75   used to constru
2c8d0 63 74 20 61 20 6e 65 77 20 0a 2a 2a 20 70 72 6f  ct a new .** pro
2c8e0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2c8f0 61 6c 75 65 20 66 72 6f 6d 20 61 6e 20 75 6e 70  alue from an unp
2c900 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2c910 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  _value..**.** Th
2c920 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74  e terms "protect
2c930 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65  ed" and "unprote
2c940 63 74 65 64 22 20 72 65 66 65 72 20 74 6f 20 77  cted" refer to w
2c950 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a  hether or not.**
2c960 20 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64   a mutex is held
2c970 2e 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d  .  An internal m
2c980 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72  utex is held for
2c990 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   a protected.** 
2c9a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2c9b0 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65  ject but no mute
2c9c0 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e  x is held for an
2c9d0 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
2c9e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2c9f0 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65  ject.  If SQLite
2ca00 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20   is compiled to 
2ca10 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  be single-thread
2ca20 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c  ed.** (with [SQL
2ca30 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
2ca40 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69  ] and with [sqli
2ca50 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29  te3_threadsafe()
2ca60 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a  ] returning 0).*
2ca70 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69  * or if SQLite i
2ca80 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20  s run in one of 
2ca90 72 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f  reduced mutex mo
2caa0 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  des .** [SQLITE_
2cab0 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
2cac0 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  EAD] or [SQLITE_
2cad0 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
2cae0 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72  AD].** then ther
2caf0 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74  e is no distinct
2cb00 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74  ion between prot
2cb10 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74  ected and unprot
2cb20 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
2cb30 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61  _value objects a
2cb40 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65 20 75  nd they can be u
2cb50 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61  sed interchangea
2cb60 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a  bly.  However,.*
2cb70 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f  * for maximum co
2cb80 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69  de portability i
2cb90 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
2cba0 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f   that applicatio
2cbb0 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65  ns.** still make
2cbc0 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e   the distinction
2cbd0 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74   between protect
2cbe0 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74  ed and unprotect
2cbf0 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
2cc00 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e  lue objects even
2cc10 20 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74   when not strict
2cc20 6c 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a  ly required..**.
2cc30 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2cc40 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68  value objects th
2cc50 61 74 20 61 72 65 20 70 61 73 73 65 64 20 61 73  at are passed as
2cc60 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f   parameters into
2cc70 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   the.** implemen
2cc80 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69  tation of [appli
2cc90 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
2cca0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72  QL functions] ar
2ccb0 65 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20  e protected..** 
2ccc0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  ^The sqlite3_val
2ccd0 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  ue object return
2cce0 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
2ccf0 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
2cd00 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64  ] is unprotected
2cd10 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64  ..** Unprotected
2cd20 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2cd30 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20  bjects may only 
2cd40 62 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20  be used with.** 
2cd50 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
2cd60 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71  value()] and [sq
2cd70 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
2cd80 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  ()]..** The [sql
2cd90 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20  ite3_value_blob 
2cda0 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  | sqlite3_value_
2cdb0 74 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f  type()] family o
2cdc0 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  f.** interfaces 
2cdd0 72 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 65  require protecte
2cde0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
2cdf0 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65  objects..*/.type
2ce00 64 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73  def struct Mem s
2ce10 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f  qlite3_value;../
2ce20 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
2ce30 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74  QL Function Cont
2ce40 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ext Object.**.**
2ce50 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20   The context in 
2ce60 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e  which an SQL fun
2ce70 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69  ction executes i
2ce80 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a  s stored in an.*
2ce90 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  * sqlite3_contex
2cea0 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f  t object.  ^A po
2ceb0 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69  inter to an sqli
2cec0 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65  te3_context obje
2ced0 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20  ct.** is always 
2cee0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
2cef0 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  to [application-
2cf00 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
2cf10 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61  tions]..** The a
2cf20 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2cf30 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ed SQL function 
2cf40 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
2cf50 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a  ill pass this.**
2cf60 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68   pointer through
2cf70 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b   into calls to [
2cf80 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
2cf90 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73  nt | sqlite3_res
2cfa0 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ult()],.** [sqli
2cfb0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
2cfc0 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74  ntext()], [sqlit
2cfd0 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c  e3_user_data()],
2cfe0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
2cff0 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29  text_db_handle()
2d000 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  ], [sqlite3_get_
2d010 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61  auxdata()],.** a
2d020 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73  nd/or [sqlite3_s
2d030 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a  et_auxdata()]..*
2d040 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
2d050 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
2d060 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
2d070 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2d080 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65  F: Binding Value
2d090 73 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 74  s To Prepared St
2d0a0 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57  atements.** KEYW
2d0b0 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61  ORDS: {host para
2d0c0 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72  meter} {host par
2d0d0 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70  ameters} {host p
2d0e0 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a  arameter name}.*
2d0f0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c  * KEYWORDS: {SQL
2d100 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c   parameter} {SQL
2d110 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61   parameters} {pa
2d120 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d  rameter binding}
2d130 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2d140 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
2d150 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74  (In the SQL stat
2d160 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75 74  ement text input
2d170 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   to [sqlite3_pre
2d180 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69  pare_v2()] and i
2d190 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20  ts variants,.** 
2d1a0 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20  literals may be 
2d1b0 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70  replaced by a [p
2d1c0 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20 6d  arameter] that m
2d1d0 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f  atches one of fo
2d1e0 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c  llowing.** templ
2d1f0 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ates:.**.** <ul>
2d200 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c  .** <li>  ?.** <
2d210 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69  li>  ?NNN.** <li
2d220 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20  >  :VVV.** <li> 
2d230 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24   @VVV.** <li>  $
2d240 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  VVV.** </ul>.**.
2d250 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c 61  ** In the templa
2d260 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72  tes above, NNN r
2d270 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e 74  epresents an int
2d280 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a  eger literal,.**
2d290 20 61 6e 64 20 56 56 56 20 72 65 70 72 65 73 65   and VVV represe
2d2a0 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65  nts an alphanume
2d2b0 72 69 63 20 69 64 65 6e 74 69 66 69 65 72 2e 29  ric identifier.)
2d2c0 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 6f  ^  ^The values o
2d2d0 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d  f these.** param
2d2e0 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c  eters (also call
2d2f0 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74  ed "host paramet
2d300 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51  er names" or "SQ
2d310 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a  L parameters").*
2d320 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75 73 69  * can be set usi
2d330 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ng the sqlite3_b
2d340 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
2d350 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a   defined here..*
2d360 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
2d370 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
2d380 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
2d390 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77   routines is alw
2d3a0 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72  ays.** a pointer
2d3b0 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
2d3c0 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65  _stmt] object re
2d3d0 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b  turned from.** [
2d3e0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2d3f0 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  v2()] or its var
2d400 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  iants..**.** ^Th
2d410 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
2d420 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f  t is the index o
2d430 66 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65  f the SQL parame
2d440 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a  ter to be set..*
2d450 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20  * ^The leftmost 
2d460 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61  SQL parameter ha
2d470 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e  s an index of 1.
2d480 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d 65    ^When the same
2d490 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61   named.** SQL pa
2d4a0 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 64 20  rameter is used 
2d4b0 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20  more than once, 
2d4c0 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65  second and subse
2d4d0 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65  quent.** occurre
2d4e0 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 73 61  nces have the sa
2d4f0 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 65 20  me index as the 
2d500 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65  first occurrence
2d510 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 20  ..** ^The index 
2d520 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65  for named parame
2d530 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b  ters can be look
2d540 65 64 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a  ed up using the.
2d550 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
2d560 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
2d570 28 29 5d 20 41 50 49 20 69 66 20 64 65 73 69 72  ()] API if desir
2d580 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 0a  ed.  ^The index.
2d590 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61  ** for "?NNN" pa
2d5a0 72 61 6d 65 74 65 72 73 20 69 73 20 74 68 65 20  rameters is the 
2d5b0 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a  value of NNN..**
2d5c0 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20   ^The NNN value 
2d5d0 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e 20  must be between 
2d5e0 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74  1 and the [sqlit
2d5f0 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70  e3_limit()].** p
2d600 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45  arameter [SQLITE
2d610 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
2d620 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74  NUMBER] (default
2d630 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a   value: 999)..**
2d640 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61  .** ^The third a
2d650 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76  rgument is the v
2d660 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20  alue to bind to 
2d670 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  the parameter..*
2d680 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20  * ^If the third 
2d690 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
2d6a0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29  ite3_bind_text()
2d6b0 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   or sqlite3_bind
2d6c0 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 6f 72 20  _text16().** or 
2d6d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2d6e0 62 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  b() is a NULL po
2d6f0 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 66  inter then the f
2d700 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 0a  ourth parameter.
2d710 2a 2a 20 69 73 20 69 67 6e 6f 72 65 64 20 61 6e  ** is ignored an
2d720 64 20 74 68 65 20 65 6e 64 20 72 65 73 75 6c 74  d the end result
2d730 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20   is the same as 
2d740 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c  sqlite3_bind_nul
2d750 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20  l()..**.** ^(In 
2d760 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74  those routines t
2d770 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 74  hat have a fourt
2d780 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20  h argument, its 
2d790 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20  value is the.** 
2d7a0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
2d7b0 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  in the parameter
2d7c0 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20  .  To be clear: 
2d7d0 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 65  the value is the
2d7e0 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75  .** number of <u
2d7f0 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68  >bytes</u> in th
2d800 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65  e value, not the
2d810 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
2d820 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20  cters.)^.** ^If 
2d830 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
2d840 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
2d850 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73  bind_text() or s
2d860 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2d870 31 36 28 29 0a 2a 2a 20 69 73 20 6e 65 67 61 74  16().** is negat
2d880 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 6c 65  ive, then the le
2d890 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69  ngth of the stri
2d8a0 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d  ng is.** the num
2d8b0 62 65 72 20 6f 66 20 62 79 74 65 73 20 75 70 20  ber of bytes up 
2d8c0 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  to the first zer
2d8d0 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a  o terminator..**
2d8e0 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   If the fourth p
2d8f0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
2d900 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20  te3_bind_blob() 
2d910 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
2d920 6e 0a 2a 2a 20 74 68 65 20 62 65 68 61 76 69 6f  n.** the behavio
2d930 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
2d940 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 67 61  ** If a non-nega
2d950 74 69 76 65 20 66 6f 75 72 74 68 20 70 61 72 61  tive fourth para
2d960 6d 65 74 65 72 20 69 73 20 70 72 6f 76 69 64 65  meter is provide
2d970 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  d to sqlite3_bin
2d980 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72 20 73  d_text().** or s
2d990 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2d9a0 31 36 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  16() or sqlite3_
2d9b0 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20 74 68  bind_text64() th
2d9c0 65 6e 0a 2a 2a 20 74 68 61 74 20 70 61 72 61 6d  en.** that param
2d9d0 65 74 65 72 20 6d 75 73 74 20 62 65 20 74 68 65  eter must be the
2d9e0 20 62 79 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20   byte offset.** 
2d9f0 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65  where the NUL te
2da00 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f  rminator would o
2da10 63 63 75 72 20 61 73 73 75 6d 69 6e 67 20 74 68  ccur assuming th
2da20 65 20 73 74 72 69 6e 67 20 77 65 72 65 20 4e 55  e string were NU
2da30 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e  L.** terminated.
2da40 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61    If any NUL cha
2da50 72 61 63 74 65 72 73 20 6f 63 63 75 72 20 61 74  racters occur at
2da60 20 62 79 74 65 20 6f 66 66 73 65 74 73 20 6c 65   byte offsets le
2da70 73 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20  ss than .** the 
2da80 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66 6f 75  value of the fou
2da90 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 68  rth parameter th
2daa0 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67  en the resulting
2dab0 20 73 74 72 69 6e 67 20 76 61 6c 75 65 20 77 69   string value wi
2dac0 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d  ll.** contain em
2dad0 62 65 64 64 65 64 20 4e 55 4c 73 2e 20 20 54 68  bedded NULs.  Th
2dae0 65 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72  e result of expr
2daf0 65 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e  essions involvin
2db00 67 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74  g strings.** wit
2db10 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20  h embedded NULs 
2db20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
2db30 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61  .** ^The fifth a
2db40 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 42  rgument to the B
2db50 4c 4f 42 20 61 6e 64 20 73 74 72 69 6e 67 20 62  LOB and string b
2db60 69 6e 64 69 6e 67 20 69 6e 74 65 72 66 61 63 65  inding interface
2db70 73 0a 2a 2a 20 69 73 20 61 20 64 65 73 74 72 75  s.** is a destru
2db80 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73  ctor used to dis
2db90 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42  pose of the BLOB
2dba0 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66   or.** string af
2dbb0 74 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66  ter SQLite has f
2dbc0 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e  inished with it.
2dbd0 20 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f    ^The destructo
2dbe0 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74  r is called.** t
2dbf0 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65  o dispose of the
2dc00 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20   BLOB or string 
2dc10 65 76 65 6e 20 69 66 20 74 68 65 20 63 61 6c 6c  even if the call
2dc20 20 74 6f 20 62 69 6e 64 20 41 50 49 20 66 61 69   to bind API fai
2dc30 6c 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  ls..** ^If the f
2dc40 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73  ifth argument is
2dc50 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20  .** the special 
2dc60 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54  value [SQLITE_ST
2dc70 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69  ATIC], then SQLi
2dc80 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  te assumes that 
2dc90 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  the.** informati
2dca0 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c  on is in static,
2dcb0 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65   unmanaged space
2dcc0 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65   and does not ne
2dcd0 65 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a  ed to be freed..
2dce0 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68  ** ^If the fifth
2dcf0 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68   argument has th
2dd00 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f  e value [SQLITE_
2dd10 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e  TRANSIENT], then
2dd20 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73  .** SQLite makes
2dd30 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65   its own private
2dd40 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74   copy of the dat
2dd50 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62  a immediately, b
2dd60 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c  efore.** the sql
2dd70 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
2dd80 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a  utine returns..*
2dd90 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 20  *.** ^The sixth 
2dda0 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
2ddb0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28  te3_bind_text64(
2ddc0 29 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f 66  ) must be one of
2ddd0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38  .** [SQLITE_UTF8
2dde0 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  ], [SQLITE_UTF16
2ddf0 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  ], [SQLITE_UTF16
2de00 42 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  BE], or [SQLITE_
2de10 55 54 46 31 36 4c 45 5d 0a 2a 2a 20 74 6f 20 73  UTF16LE].** to s
2de20 70 65 63 69 66 79 20 74 68 65 20 65 6e 63 6f 64  pecify the encod
2de30 69 6e 67 20 6f 66 20 74 68 65 20 74 65 78 74 20  ing of the text 
2de40 69 6e 20 74 68 65 20 74 68 69 72 64 20 70 61 72  in the third par
2de50 61 6d 65 74 65 72 2e 20 20 49 66 0a 2a 2a 20 74  ameter.  If.** t
2de60 68 65 20 73 69 78 74 68 20 61 72 67 75 6d 65 6e  he sixth argumen
2de70 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  t to sqlite3_bin
2de80 64 5f 74 65 78 74 36 34 28 29 20 69 73 20 6e 6f  d_text64() is no
2de90 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20  t one of the.** 
2dea0 61 6c 6c 6f 77 65 64 20 76 61 6c 75 65 73 20 73  allowed values s
2deb0 68 6f 77 6e 20 61 62 6f 76 65 2c 20 6f 72 20 69  hown above, or i
2dec0 66 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64  f the text encod
2ded0 69 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e 74  ing is different
2dee0 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 65 6e 63  .** from the enc
2def0 6f 64 69 6e 67 20 73 70 65 63 69 66 69 65 64 20  oding specified 
2df00 62 79 20 74 68 65 20 73 69 78 74 68 20 70 61 72  by the sixth par
2df10 61 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65  ameter, then the
2df20 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20   behavior.** is 
2df30 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
2df40 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69   ^The sqlite3_bi
2df50 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f  nd_zeroblob() ro
2df60 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c  utine binds a BL
2df70 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74  OB of length N t
2df80 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64  hat.** is filled
2df90 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e   with zeroes.  ^
2dfa0 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20  A zeroblob uses 
2dfb0 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f  a fixed amount o
2dfc0 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73  f memory.** (jus
2dfd0 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20  t an integer to 
2dfe0 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77  hold its size) w
2dff0 68 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67  hile it is being
2e000 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a   processed..** Z
2e010 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74  eroblobs are int
2e020 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20 61  ended to serve a
2e030 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66  s placeholders f
2e040 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a  or BLOBs whose.*
2e050 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74  * content is lat
2e060 65 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67  er written using
2e070 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  .** [sqlite3_blo
2e080 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65  b_open | increme
2e090 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72  ntal BLOB I/O] r
2e0a0 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e  outines..** ^A n
2e0b0 65 67 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f  egative value fo
2e0c0 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72  r the zeroblob r
2e0d0 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f  esults in a zero
2e0e0 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a  -length BLOB..**
2e0f0 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20 74  .** ^If any of t
2e100 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
2e110 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65  *() routines are
2e120 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e   called with a N
2e130 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66  ULL pointer.** f
2e140 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  or the [prepared
2e150 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77   statement] or w
2e160 69 74 68 20 61 20 70 72 65 70 61 72 65 64 20 73  ith a prepared s
2e170 74 61 74 65 6d 65 6e 74 20 66 6f 72 20 77 68 69  tatement for whi
2e180 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  ch.** [sqlite3_s
2e190 74 65 70 28 29 5d 20 68 61 73 20 62 65 65 6e 20  tep()] has been 
2e1a0 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63 65  called more rece
2e1b0 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69 74  ntly than [sqlit
2e1c0 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20  e3_reset()],.** 
2e1d0 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 20 77 69  then the call wi
2e1e0 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
2e1f0 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66 20 61  E_MISUSE].  If a
2e200 6e 79 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  ny sqlite3_bind_
2e210 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73  ().** routine is
2e220 20 70 61 73 73 65 64 20 61 20 5b 70 72 65 70 61   passed a [prepa
2e230 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
2e240 68 61 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e  hat has been fin
2e250 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72  alized, the.** r
2e260 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e  esult is undefin
2e270 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20  ed and probably 
2e280 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  harmful..**.** ^
2e290 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74  Bindings are not
2e2a0 20 63 6c 65 61 72 65 64 20 62 79 20 74 68 65 20   cleared by the 
2e2b0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2e2c0 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55  ] routine..** ^U
2e2d0 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72  nbound parameter
2e2e0 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  s are interprete
2e2f0 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  d as NULL..**.**
2e300 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69   ^The sqlite3_bi
2e310 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72 65  nd_* routines re
2e320 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
2e330 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61   on success or a
2e340 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65  n.** [error code
2e350 5d 20 69 66 20 61 6e 79 74 68 69 6e 67 20 67 6f  ] if anything go
2e360 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53  es wrong..** ^[S
2e370 51 4c 49 54 45 5f 54 4f 4f 42 49 47 5d 20 6d 69  QLITE_TOOBIG] mi
2e380 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20  ght be returned 
2e390 69 66 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61  if the size of a
2e3a0 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 0a   string or BLOB.
2e3b0 2a 2a 20 65 78 63 65 65 64 73 20 6c 69 6d 69 74  ** exceeds limit
2e3c0 73 20 69 6d 70 6f 73 65 64 20 62 79 20 5b 73 71  s imposed by [sq
2e3d0 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51  lite3_limit]([SQ
2e3e0 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
2e3f0 48 5d 29 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  H]) or.** [SQLIT
2e400 45 5f 4d 41 58 5f 4c 45 4e 47 54 48 5d 2e 0a 2a  E_MAX_LENGTH]..*
2e410 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45  * ^[SQLITE_RANGE
2e420 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  ] is returned if
2e430 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a   the parameter.*
2e440 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f  * index is out o
2e450 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49  f range.  ^[SQLI
2e460 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74  TE_NOMEM] is ret
2e470 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28  urned if malloc(
2e480 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53  ) fails..**.** S
2e490 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
2e4a0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2e4b0 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73  _count()],.** [s
2e4c0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2e4d0 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61  meter_name()], a
2e4e0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  nd [sqlite3_bind
2e4f0 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
2e500 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ()]..*/.SQLITE_A
2e510 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  PI int sqlite3_b
2e520 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  ind_blob(sqlite3
2e530 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
2e540 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c  st void*, int n,
2e550 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
2e560 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
2e570 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
2e580 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  ob64(sqlite3_stm
2e590 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76  t*, int, const v
2e5a0 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69  oid*, sqlite3_ui
2e5b0 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20  nt64,.          
2e5c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f                vo
2e5d0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53  id(*)(void*));.S
2e5e0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
2e5f0 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c  lite3_bind_doubl
2e600 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2e610 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 53   int, double);.S
2e620 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
2e630 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73  lite3_bind_int(s
2e640 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2e650 74 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  t, int);.SQLITE_
2e660 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
2e670 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74  bind_int64(sqlit
2e680 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73  e3_stmt*, int, s
2e690 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 53  qlite3_int64);.S
2e6a0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
2e6b0 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28  lite3_bind_null(
2e6c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2e6d0 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
2e6e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2e6f0 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74  _text(sqlite3_st
2e700 6d 74 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68  mt*,int,const ch
2e710 61 72 2a 2c 69 6e 74 2c 76 6f 69 64 28 2a 29 28  ar*,int,void(*)(
2e720 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f  void*));.SQLITE_
2e730 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
2e740 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69  bind_text16(sqli
2e750 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
2e760 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
2e770 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
2e780 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
2e790 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  t sqlite3_bind_t
2e7a0 65 78 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  ext64(sqlite3_st
2e7b0 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
2e7c0 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 75  char*, sqlite3_u
2e7d0 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20  int64,.         
2e7e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2e7f0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 2c 20  void(*)(void*), 
2e800 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 65 6e  unsigned char en
2e810 63 6f 64 69 6e 67 29 3b 0a 53 51 4c 49 54 45 5f  coding);.SQLITE_
2e820 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
2e830 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74  bind_value(sqlit
2e840 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
2e850 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  onst sqlite3_val
2e860 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ue*);.SQLITE_API
2e870 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e   int sqlite3_bin
2e880 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74  d_zeroblob(sqlit
2e890 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69  e3_stmt*, int, i
2e8a0 6e 74 20 6e 29 3b 0a 53 51 4c 49 54 45 5f 41 50  nt n);.SQLITE_AP
2e8b0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  I int sqlite3_bi
2e8c0 6e 64 5f 7a 65 72 6f 62 6c 6f 62 36 34 28 73 71  nd_zeroblob64(sq
2e8d0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2e8e0 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  , sqlite3_uint64
2e8f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2e900 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51  EF: Number Of SQ
2e910 4c 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  L Parameters.** 
2e920 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
2e930 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  stmt.**.** ^This
2e940 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20   routine can be 
2e950 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65  used to find the
2e960 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20   number of [SQL 
2e970 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69  parameters].** i
2e980 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
2e990 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70  atement].  SQL p
2e9a0 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f  arameters are to
2e9b0 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66  kens of the.** f
2e9c0 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c  orm "?", "?NNN",
2e9d0 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c   ":AAA", "$AAA",
2e9e0 20 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 20   or "@AAA" that 
2e9f0 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63  serve as.** plac
2ea00 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c  eholders for val
2ea10 75 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 71  ues that are [sq
2ea20 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
2ea30 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74  | bound].** to t
2ea40 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 74  he parameters at
2ea50 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a   a later time..*
2ea60 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74  *.** ^(This rout
2ea70 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74  ine actually ret
2ea80 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f  urns the index o
2ea90 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 28 72  f the largest (r
2eaa0 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72  ightmost).** par
2eab0 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20  ameter. For all 
2eac0 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e  forms except ?NN
2ead0 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72  N, this will cor
2eae0 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a  respond to the.*
2eaf0 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71  * number of uniq
2eb00 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ue parameters.  
2eb10 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66  If parameters of
2eb20 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61   the ?NNN form a
2eb30 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72  re used,.** ther
2eb40 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e  e may be gaps in
2eb50 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a   the list.)^.**.
2eb60 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
2eb70 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
2eb80 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
2eb90 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
2eba0 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
2ebb0 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
2ebc0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2ebd0 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
2ebe0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2ebf0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2ec00 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c  ameter_count(sql
2ec10 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
2ec20 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61  .** CAPI3REF: Na
2ec30 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72  me Of A Host Par
2ec40 61 6d 65 74 65 72 0a 2a 2a 20 4d 45 54 48 4f 44  ameter.** METHOD
2ec50 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2ec60 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2ec70 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2ec80 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72  _name(P,N) inter
2ec90 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20  face returns.** 
2eca0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
2ecb0 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 6d 65  N-th [SQL parame
2ecc0 74 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 72 65  ter] in the [pre
2ecd0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2ece0 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72   P..** ^(SQL par
2ecf0 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66  ameters of the f
2ed00 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a  orm "?NNN" or ":
2ed10 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f  AAA" or "@AAA" o
2ed20 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65  r "$AAA".** have
2ed30 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73   a name which is
2ed40 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e   the string "?NN
2ed50 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20  N" or ":AAA" or 
2ed60 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22  "@AAA" or "$AAA"
2ed70 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79  .** respectively
2ed80 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f  ..** In other wo
2ed90 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c  rds, the initial
2eda0 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22   ":" or "$" or "
2edb0 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20  @" or "?".** is 
2edc0 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 74  included as part
2edd0 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a   of the name.)^.
2ede0 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 20 6f  ** ^Parameters o
2edf0 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77  f the form "?" w
2ee00 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69  ithout a followi
2ee10 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76 65 20  ng integer have 
2ee20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61  no name.** and a
2ee30 72 65 20 72 65 66 65 72 72 65 64 20 74 6f 20 61  re referred to a
2ee40 73 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20  s "nameless" or 
2ee50 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d  "anonymous param
2ee60 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54  eters"..**.** ^T
2ee70 68 65 20 66 69 72 73 74 20 68 6f 73 74 20 70 61  he first host pa
2ee80 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69  rameter has an i
2ee90 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30  ndex of 1, not 0
2eea0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
2eeb0 76 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 6f  value N is out o
2eec0 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68  f range or if th
2eed0 65 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 72  e N-th parameter
2eee0 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c   is.** nameless,
2eef0 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65   then NULL is re
2ef00 74 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 65  turned.  ^The re
2ef10 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
2ef20 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54  .** always in UT
2ef30 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65  F-8 encoding eve
2ef40 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70  n if the named p
2ef50 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20  arameter was.** 
2ef60 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69  originally speci
2ef70 66 69 65 64 20 61 73 20 55 54 46 2d 31 36 20 69  fied as UTF-16 i
2ef80 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  n [sqlite3_prepa
2ef90 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  re16()] or.** [s
2efa0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2efb0 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65  _v2()]..**.** Se
2efc0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
2efd0 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
2efe0 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b  e3_bind()],.** [
2eff0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2f000 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
2f010 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
2f020 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2f030 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  index()]..*/.SQL
2f040 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
2f050 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64  ar *sqlite3_bind
2f060 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
2f070 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2f080 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
2f090 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41  3REF: Index Of A
2f0a0 20 50 61 72 61 6d 65 74 65 72 20 57 69 74 68 20   Parameter With 
2f0b0 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 20  A Given Name.** 
2f0c0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
2f0d0 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75  stmt.**.** ^Retu
2f0e0 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  rn the index of 
2f0f0 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  an SQL parameter
2f100 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e   given its name.
2f110 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20    ^The.** index 
2f120 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69  value returned i
2f130 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75  s suitable for u
2f140 73 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  se as the second
2f150 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f  .** parameter to
2f160 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2f170 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
2f180 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a  ()].  ^A zero.**
2f190 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
2f1a0 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61  no matching para
2f1b0 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20  meter is found. 
2f1c0 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a   ^The parameter.
2f1d0 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20  ** name must be 
2f1e0 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65  given in UTF-8 e
2f1f0 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69  ven if the origi
2f200 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  nal statement.**
2f210 20 77 61 73 20 70 72 65 70 61 72 65 64 20 66 72   was prepared fr
2f220 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20 75  om UTF-16 text u
2f230 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  sing [sqlite3_pr
2f240 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a  epare16_v2()]..*
2f250 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
2f260 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2f270 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
2f280 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
2f290 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
2f2a0 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  unt()], and.** [
2f2b0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2f2c0 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2e 0a  ameter_name()]..
2f2d0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
2f2e0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  t sqlite3_bind_p
2f2f0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73  arameter_index(s
2f300 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f  qlite3_stmt*, co
2f310 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29  nst char *zName)
2f320 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2f330 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e  F: Reset All Bin
2f340 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61  dings On A Prepa
2f350 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a  red Statement.**
2f360 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2f370 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e  _stmt.**.** ^Con
2f380 74 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74  trary to the int
2f390 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20  uition of many, 
2f3a0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2f3b0 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74  ] does not reset
2f3c0 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
2f3d0 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e  _bind_blob | bin
2f3e0 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65  dings] on a [pre
2f3f0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2f400 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73 20 72  ..** ^Use this r
2f410 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20  outine to reset 
2f420 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74  all host paramet
2f430 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a  ers to NULL..*/.
2f440 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
2f450 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e  qlite3_clear_bin
2f460 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74  dings(sqlite3_st
2f470 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
2f480 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66  I3REF: Number Of
2f490 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65   Columns In A Re
2f4a0 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48  sult Set.** METH
2f4b0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2f4c0 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74  .**.** ^Return t
2f4d0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
2f4e0 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75  umns in the resu
2f4f0 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65 64 20  lt set returned 
2f500 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  by the.** [prepa
2f510 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
2f520 5e 49 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ^If this routine
2f530 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 61 74   returns 0, that
2f540 20 6d 65 61 6e 73 20 74 68 65 20 0a 2a 2a 20 5b   means the .** [
2f550 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2f560 6e 74 5d 20 72 65 74 75 72 6e 73 20 6e 6f 20 64  nt] returns no d
2f570 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  ata (for example
2f580 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a   an [UPDATE])..*
2f590 2a 20 5e 48 6f 77 65 76 65 72 2c 20 6a 75 73 74  * ^However, just
2f5a0 20 62 65 63 61 75 73 65 20 74 68 69 73 20 72 6f   because this ro
2f5b0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20  utine returns a 
2f5c0 70 6f 73 69 74 69 76 65 20 6e 75 6d 62 65 72 20  positive number 
2f5d0 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 6d 65 61 6e  does not.** mean
2f5e0 20 74 68 61 74 20 6f 6e 65 20 6f 72 20 6d 6f 72   that one or mor
2f5f0 65 20 72 6f 77 73 20 6f 66 20 64 61 74 61 20 77  e rows of data w
2f600 69 6c 6c 20 62 65 20 72 65 74 75 72 6e 65 64 2e  ill be returned.
2f610 20 20 5e 41 20 53 45 4c 45 43 54 20 73 74 61 74    ^A SELECT stat
2f620 65 6d 65 6e 74 0a 2a 2a 20 77 69 6c 6c 20 61 6c  ement.** will al
2f630 77 61 79 73 20 68 61 76 65 20 61 20 70 6f 73 69  ways have a posi
2f640 74 69 76 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  tive sqlite3_col
2f650 75 6d 6e 5f 63 6f 75 6e 74 28 29 20 62 75 74 20  umn_count() but 
2f660 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
2f670 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65  .** WHERE clause
2f680 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 61 6e 64   constraints and
2f690 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6e 74 65   the table conte
2f6a0 6e 74 2c 20 69 74 20 6d 69 67 68 74 20 72 65 74  nt, it might ret
2f6b0 75 72 6e 20 6e 6f 20 72 6f 77 73 2e 0a 2a 2a 0a  urn no rows..**.
2f6c0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
2f6d0 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
2f6e0 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ()].*/.SQLITE_AP
2f6f0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  I int sqlite3_co
2f700 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74  lumn_count(sqlit
2f710 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
2f720 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2f730 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49  : Column Names I
2f740 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a  n A Result Set.*
2f750 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2f760 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  3_stmt.**.** ^Th
2f770 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
2f780 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73  urn the name ass
2f790 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69  igned to a parti
2f7a0 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  cular column.** 
2f7b0 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  in the result se
2f7c0 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20  t of a [SELECT] 
2f7d0 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65  statement.  ^The
2f7e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2f7f0 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66  name().** interf
2f800 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
2f810 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d  inter to a zero-
2f820 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
2f830 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73   string.** and s
2f840 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
2f850 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73 20 61  me16() returns a
2f860 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65   pointer to a ze
2f870 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
2f880 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20   UTF-16 string. 
2f890 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61   ^The first para
2f8a0 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 70 72  meter is the [pr
2f8b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2f8c0 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d  ].** that implem
2f8d0 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43 54  ents the [SELECT
2f8e0 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68  ] statement. ^Th
2f8f0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
2f900 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c  er is the.** col
2f910 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68  umn number.  ^Th
2f920 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d  e leftmost colum
2f930 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a  n is number 0..*
2f940 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e  *.** ^The return
2f950 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65  ed string pointe
2f960 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c  r is valid until
2f970 20 65 69 74 68 65 72 20 74 68 65 20 5b 70 72 65   either the [pre
2f980 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2f990 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64  .** is destroyed
2f9a0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   by [sqlite3_fin
2f9b0 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69  alize()] or unti
2f9c0 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  l the statement 
2f9d0 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  is automatically
2f9e0 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62  .** reprepared b
2f9f0 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c  y the first call
2fa00 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
2fa10 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69  p()] for a parti
2fa20 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20  cular run.** or 
2fa30 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63  until the next c
2fa40 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  all to.** sqlite
2fa50 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20  3_column_name() 
2fa60 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
2fa70 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68  n_name16() on th
2fa80 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a  e same column..*
2fa90 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  *.** ^If sqlite3
2faa0 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20  _malloc() fails 
2fab0 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65  during the proce
2fac0 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20  ssing of either 
2fad0 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20  routine.** (for 
2fae0 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61  example during a
2faf0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d   conversion from
2fb00 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36   UTF-8 to UTF-16
2fb10 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c  ) then a.** NULL
2fb20 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75   pointer is retu
2fb30 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rned..**.** ^The
2fb40 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c   name of a resul
2fb50 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20  t column is the 
2fb60 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53  value of the "AS
2fb70 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20  " clause for.** 
2fb80 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20  that column, if 
2fb90 74 68 65 72 65 20 69 73 20 61 6e 20 41 53 20 63  there is an AS c
2fba0 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65 72 65  lause.  If there
2fbb0 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65   is no AS clause
2fbc0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d  .** then the nam
2fbd0 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  e of the column 
2fbe0 69 73 20 75 6e 73 70 65 63 69 66 69 65 64 20 61  is unspecified a
2fbf0 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72  nd may change fr
2fc00 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73  om.** one releas
2fc10 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74  e of SQLite to t
2fc20 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 53 51 4c 49  he next..*/.SQLI
2fc30 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
2fc40 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
2fc50 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  n_name(sqlite3_s
2fc60 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 53 51  tmt*, int N);.SQ
2fc70 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
2fc80 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
2fc90 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  umn_name16(sqlit
2fca0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29  e3_stmt*, int N)
2fcb0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2fcc0 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74  F: Source Of Dat
2fcd0 61 20 49 6e 20 41 20 51 75 65 72 79 20 52 65 73  a In A Query Res
2fce0 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ult.** METHOD: s
2fcf0 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
2fd00 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
2fd10 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e  s provide a mean
2fd20 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74  s to determine t
2fd30 68 65 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  he database, tab
2fd40 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65  le, and.** table
2fd50 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20   column that is 
2fd60 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 61 20  the origin of a 
2fd70 70 61 72 74 69 63 75 6c 61 72 20 72 65 73 75 6c  particular resul
2fd80 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b  t column in.** [
2fd90 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
2fda0 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20  t..** ^The name 
2fdb0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
2fdc0 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75  or table or colu
2fdd0 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e  mn can be return
2fde0 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20  ed as.** either 
2fdf0 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  a UTF-8 or UTF-1
2fe00 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20  6 string.  ^The 
2fe10 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69  _database_ routi
2fe20 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68  nes return.** th
2fe30 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c  e database name,
2fe40 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75   the _table_ rou
2fe50 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
2fe60 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64   table name, and
2fe70 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20  .** the origin_ 
2fe80 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
2fe90 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e  the column name.
2fea0 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65  .** ^The returne
2feb0 64 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69  d string is vali
2fec0 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65  d until the [pre
2fed0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2fee0 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a   is destroyed.**
2fef0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
2ff00 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75  finalize()] or u
2ff10 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65  ntil the stateme
2ff20 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61  nt is automatica
2ff30 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65  lly.** reprepare
2ff40 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63  d by the first c
2ff50 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2ff60 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61  step()] for a pa
2ff70 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20  rticular run.** 
2ff80 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d  or until the sam
2ff90 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  e information is
2ffa0 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67   requested.** ag
2ffb0 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65  ain in a differe
2ffc0 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a  nt encoding..**.
2ffd0 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 65  ** ^The names re
2ffe0 74 75 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f  turned are the o
2fff0 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73  riginal un-alias
30000 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a  ed names of the.
30010 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  ** database, tab
30020 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a  le, and column..
30030 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
30040 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
30050 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 69 73  se interfaces is
30060 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
30070 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65  tement]..** ^The
30080 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74  se functions ret
30090 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  urn information 
300a0 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72 65  about the Nth re
300b0 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75  sult column retu
300c0 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73  rned by.** the s
300d0 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20  tatement, where 
300e0 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20  N is the second 
300f0 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e  function argumen
30100 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d  t..** ^The left-
30110 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63  most column is c
30120 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 73  olumn 0 for thes
30130 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  e routines..**.*
30140 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f  * ^If the Nth co
30150 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79  lumn returned by
30160 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
30170 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20  s an expression 
30180 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61  or.** subquery a
30190 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75  nd is not a colu
301a0 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61  mn value, then a
301b0 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63  ll of these func
301c0 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20  tions return.** 
301d0 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f  NULL.  ^These ro
301e0 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f  utine might also
301f0 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20   return NULL if 
30200 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
30210 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63  ion error.** occ
30220 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 65  urs.  ^Otherwise
30230 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 68  , they return th
30240 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74  e name of the at
30250 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 2c  tached database,
30260 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f   table,.** or co
30270 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20  lumn that query 
30280 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61  result column wa
30290 73 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d  s extracted from
302a0 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68  ..**.** ^As with
302b0 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74   all other SQLit
302c0 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 77 68  e APIs, those wh
302d0 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 69  ose names end wi
302e0 74 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a  th "16" return.*
302f0 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  * UTF-16 encoded
30300 20 73 74 72 69 6e 67 73 20 61 6e 64 20 74 68 65   strings and the
30310 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73   other functions
30320 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a   return UTF-8..*
30330 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 73  *.** ^These APIs
30340 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61   are only availa
30350 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61  ble if the libra
30360 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  ry was compiled 
30370 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  with the.** [SQL
30380 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d  ITE_ENABLE_COLUM
30390 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72  N_METADATA] C-pr
303a0 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f  eprocessor symbo
303b0 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20  l..**.** If two 
303c0 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  or more threads 
303d0 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  call one or more
303e0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
303f0 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 73  es against the s
30400 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20  ame.** prepared 
30410 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f  statement and co
30420 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65  lumn at the same
30430 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72   time then the r
30440 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e  esults are.** un
30450 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  defined..**.** I
30460 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68  f two or more th
30470 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f  reads call one o
30480 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74  r more.** [sqlit
30490 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
304a0 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e  se_name | column
304b0 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 66   metadata interf
304c0 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65  aces].** for the
304d0 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20   same [prepared 
304e0 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72  statement] and r
304f0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  esult column.** 
30500 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
30510 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
30520 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
30530 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  .*/.SQLITE_API c
30540 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
30550 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
30560 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  se_name(sqlite3_
30570 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49  stmt*,int);.SQLI
30580 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69  TE_API const voi
30590 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
305a0 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31  n_database_name1
305b0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
305c0 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
305d0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
305e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c  ite3_column_tabl
305f0 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  e_name(sqlite3_s
30600 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54  tmt*,int);.SQLIT
30610 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64  E_API const void
30620 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
30630 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71  _table_name16(sq
30640 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
30650 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
30660 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
30670 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e  _column_origin_n
30680 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
30690 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  *,int);.SQLITE_A
306a0 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  PI const void *s
306b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72  qlite3_column_or
306c0 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69  igin_name16(sqli
306d0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
306e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
306f0 20 44 65 63 6c 61 72 65 64 20 44 61 74 61 74 79   Declared Dataty
30700 70 65 20 4f 66 20 41 20 51 75 65 72 79 20 52 65  pe Of A Query Re
30710 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  sult.** METHOD: 
30720 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
30730 2a 2a 20 5e 28 54 68 65 20 66 69 72 73 74 20 70  ** ^(The first p
30740 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70  arameter is a [p
30750 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
30760 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73  t]..** If this s
30770 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53  tatement is a [S
30780 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
30790 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c   and the Nth col
307a0 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65  umn of the.** re
307b0 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65  turned result se
307c0 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43  t of that [SELEC
307d0 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f  T] is a table co
307e0 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20  lumn (not an.** 
307f0 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75  expression or su
30800 62 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 65  bquery) then the
30810 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f   declared type o
30820 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63  f the table.** c
30830 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65  olumn is returne
30840 64 2e 29 5e 20 20 5e 49 66 20 74 68 65 20 4e 74  d.)^  ^If the Nt
30850 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  h column of the 
30860 72 65 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e  result set is an
30870 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f  .** expression o
30880 72 20 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e  r subquery, then
30890 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
308a0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
308b0 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
308c0 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55  ring is always U
308d0 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a  TF-8 encoded..**
308e0 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c  .** ^(For exampl
308f0 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61 74  e, given the dat
30900 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a  abase schema:.**
30910 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45  .** CREATE TABLE
30920 20 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b   t1(c1 VARIANT);
30930 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66  .**.** and the f
30940 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65  ollowing stateme
30950 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65  nt to be compile
30960 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20  d:.**.** SELECT 
30970 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20  c1 + 1, c1 FROM 
30980 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72  t1;.**.** this r
30990 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74  outine would ret
309a0 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22  urn the string "
309b0 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65  VARIANT" for the
309c0 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a   second result.*
309d0 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c  * column (i==1),
309e0 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e   and a NULL poin
309f0 74 65 72 20 66 6f 72 20 74 68 65 20 66 69 72 73  ter for the firs
30a00 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  t result column 
30a10 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20  (i==0).)^.**.** 
30a20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e  ^SQLite uses dyn
30a30 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79  amic run-time ty
30a40 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20  ping.  ^So just 
30a50 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e  because a column
30a60 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20  .** is declared 
30a70 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72  to contain a par
30a80 74 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65  ticular type doe
30a90 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20  s not mean that 
30aa0 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72  the.** data stor
30ab0 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d  ed in that colum
30ac0 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c  n is of the decl
30ad0 61 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69  ared type.  SQLi
30ae0 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c  te is.** strongl
30af0 79 20 74 79 70 65 64 2c 20 62 75 74 20 74 68 65  y typed, but the
30b00 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d   typing is dynam
30b10 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20  ic not static.  
30b20 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f  ^Type.** is asso
30b30 63 69 61 74 65 64 20 77 69 74 68 20 69 6e 64 69  ciated with indi
30b40 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e  vidual values, n
30b50 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74  ot with the cont
30b60 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74  ainers.** used t
30b70 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c  o hold those val
30b80 75 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ues..*/.SQLITE_A
30b90 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  PI const char *s
30ba0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
30bb0 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73  cltype(sqlite3_s
30bc0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54  tmt*,int);.SQLIT
30bd0 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64  E_API const void
30be0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
30bf0 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69  _decltype16(sqli
30c00 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
30c10 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
30c20 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c   Evaluate An SQL
30c30 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45   Statement.** ME
30c40 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
30c50 6d 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61  mt.**.** After a
30c60 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
30c70 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70  ment] has been p
30c80 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 65 69  repared using ei
30c90 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ther.** [sqlite3
30ca0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
30cb0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
30cc0 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e  re16_v2()] or on
30cd0 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a  e of the legacy.
30ce0 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73  ** interfaces [s
30cf0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
30d00 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
30d10 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73  epare16()], this
30d20 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73   function.** mus
30d30 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20  t be called one 
30d40 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f  or more times to
30d50 20 65 76 61 6c 75 61 74 65 20 74 68 65 20 73 74   evaluate the st
30d60 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54  atement..**.** T
30d70 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68  he details of th
30d80 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68  e behavior of th
30d90 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  e sqlite3_step()
30da0 20 69 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e   interface depen
30db0 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20  d.** on whether 
30dc0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61  the statement wa
30dd0 73 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67  s prepared using
30de0 20 74 68 65 20 6e 65 77 65 72 20 22 76 32 22 20   the newer "v2" 
30df0 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71  interface.** [sq
30e00 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
30e10 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
30e20 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
30e30 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65   or the older le
30e40 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
30e50 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
30e60 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  re()] and [sqlit
30e70 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e  e3_prepare16()].
30e80 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65    The use of the
30e90 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74  .** new "v2" int
30ea0 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d  erface is recomm
30eb0 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70  ended for new ap
30ec0 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74  plications but t
30ed0 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  he legacy.** int
30ee0 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74  erface will cont
30ef0 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f  inue to be suppo
30f00 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20  rted..**.** ^In 
30f10 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
30f20 66 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e  face, the return
30f30 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65   value will be e
30f40 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55  ither [SQLITE_BU
30f50 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  SY],.** [SQLITE_
30f60 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52  DONE], [SQLITE_R
30f70 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52  OW], [SQLITE_ERR
30f80 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OR], or [SQLITE_
30f90 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74  MISUSE]..** ^Wit
30fa0 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  h the "v2" inter
30fb0 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65  face, any of the
30fc0 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63   other [result c
30fd0 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74  odes] or.** [ext
30fe0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
30ff0 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74  es] might be ret
31000 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a  urned as well..*
31010 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55  *.** ^[SQLITE_BU
31020 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  SY] means that t
31030 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69  he database engi
31040 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f  ne was unable to
31050 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20   acquire the.** 
31060 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69  database locks i
31070 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74  t needs to do it
31080 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20  s job.  ^If the 
31090 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b  statement is a [
310a0 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63  COMMIT].** or oc
310b0 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20  curs outside of 
310c0 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  an explicit tran
310d0 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f  saction, then yo
310e0 75 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a  u can retry the.
310f0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49  ** statement.  I
31100 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
31110 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54  is not a [COMMIT
31120 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74  ] and occurs wit
31130 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63  hin an.** explic
31140 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74  it transaction t
31150 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72  hen you should r
31160 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e  ollback the tran
31170 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a  saction before.*
31180 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a  * continuing..**
31190 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e  .** ^[SQLITE_DON
311a0 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  E] means that th
311b0 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20  e statement has 
311c0 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69  finished executi
311d0 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c  ng.** successful
311e0 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65  ly.  sqlite3_ste
311f0 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  p() should not b
31200 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f  e called again o
31210 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a  n this virtual.*
31220 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75  * machine withou
31230 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20  t first calling 
31240 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
31250 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76  ] to reset the v
31260 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e  irtual.** machin
31270 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e  e back to its in
31280 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a  itial state..**.
31290 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73  ** ^If the SQL s
312a0 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65  tatement being e
312b0 78 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20  xecuted returns 
312c0 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b  any data, then [
312d0 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69  SQLITE_ROW].** i
312e0 73 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20  s returned each 
312f0 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f  time a new row o
31300 66 20 64 61 74 61 20 69 73 20 72 65 61 64 79 20  f data is ready 
31310 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62  for processing b
31320 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e  y the.** caller.
31330 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20   The values may 
31340 62 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e  be accessed usin
31350 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63  g the [column ac
31360 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e  cess functions].
31370 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .** sqlite3_step
31380 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61  () is called aga
31390 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74  in to retrieve t
313a0 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64  he next row of d
313b0 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c  ata..**.** ^[SQL
313c0 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73  ITE_ERROR] means
313d0 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65   that a run-time
313e0 20 65 72 72 6f 72 20 28 73 75 63 68 20 61 73 20   error (such as 
313f0 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20  a constraint.** 
31400 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f  violation) has o
31410 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65  ccurred.  sqlite
31420 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20  3_step() should 
31430 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67  not be called ag
31440 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d  ain on.** the VM
31450 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69  . More informati
31460 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20  on may be found 
31470 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
31480 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a  te3_errmsg()]..*
31490 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61  * ^With the lega
314a0 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20  cy interface, a 
314b0 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72  more specific er
314c0 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78  ror code (for ex
314d0 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54  ample,.** [SQLIT
314e0 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53  E_INTERRUPT], [S
314f0 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b  QLITE_SCHEMA], [
31500 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c  SQLITE_CORRUPT],
31510 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a   and so forth).*
31520 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65  * can be obtaine
31530 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  d by calling [sq
31540 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
31550 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  n the.** [prepar
31560 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20  ed statement].  
31570 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74  ^In the "v2" int
31580 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d  erface,.** the m
31590 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72  ore specific err
315a0 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72  or code is retur
315b0 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62 79 20  ned directly by 
315c0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a  sqlite3_step()..
315d0 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49  **.** [SQLITE_MI
315e0 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74  SUSE] means that
315f0 20 74 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e   the this routin
31600 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61  e was called ina
31610 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a  ppropriately..**
31620 20 50 65 72 68 61 70 73 20 69 74 20 77 61 73 20   Perhaps it was 
31630 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65  called on a [pre
31640 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
31650 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72   that has.** alr
31660 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74  eady been [sqlit
31670 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69  e3_finalize | fi
31680 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f  nalized] or on o
31690 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70  ne that had.** p
316a0 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e  reviously return
316b0 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ed [SQLITE_ERROR
316c0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ] or [SQLITE_DON
316d0 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64  E].  Or it could
316e0 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65 20  .** be the case 
316f0 74 68 61 74 20 74 68 65 20 73 61 6d 65 20 64 61  that the same da
31700 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
31710 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20  n is being used 
31720 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72  by two or.** mor
31730 65 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65  e threads at the
31740 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20   same moment in 
31750 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20  time..**.** For 
31760 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  all versions of 
31770 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64  SQLite up to and
31780 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32   including 3.6.2
31790 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a  3.1, a call to.*
317a0 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
317b0 28 29 5d 20 77 61 73 20 72 65 71 75 69 72 65 64  ()] was required
317c0 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73   after sqlite3_s
317d0 74 65 70 28 29 20 72 65 74 75 72 6e 65 64 20 61  tep() returned a
317e0 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72  nything.** other
317f0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f   than [SQLITE_RO
31800 57 5d 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75  W] before any su
31810 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74  bsequent invocat
31820 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65  ion of.** sqlite
31830 33 5f 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75  3_step().  Failu
31840 72 65 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  re to reset the 
31850 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
31860 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71  nt using .** [sq
31870 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77  lite3_reset()] w
31880 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61  ould result in a
31890 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  n [SQLITE_MISUSE
318a0 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a  ] return from.**
318b0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
318c0 20 20 42 75 74 20 61 66 74 65 72 20 5b 76 65 72    But after [ver
318d0 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 5d 20 28  sion 3.6.23.1] (
318e0 5b 64 61 74 65 6f 66 3a 33 2e 36 2e 32 33 2e 31  [dateof:3.6.23.1
318f0 5d 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  ],.** sqlite3_st
31900 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61  ep() began.** ca
31910 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  lling [sqlite3_r
31920 65 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 74 69  eset()] automati
31930 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63 69  cally in this ci
31940 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68 65  rcumstance rathe
31950 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 72 6e  r.** than return
31960 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  ing [SQLITE_MISU
31970 53 45 5d 2e 20 20 54 68 69 73 20 69 73 20 6e 6f  SE].  This is no
31980 74 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20 63  t considered a c
31990 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20  ompatibility.** 
319a0 62 72 65 61 6b 20 62 65 63 61 75 73 65 20 61 6e  break because an
319b0 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 68  y application th
319c0 61 74 20 65 76 65 72 20 72 65 63 65 69 76 65 73  at ever receives
319d0 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53   an SQLITE_MISUS
319e0 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72  E error.** is br
319f0 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 74 69  oken by definiti
31a00 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45  on.  The [SQLITE
31a10 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 54 5d  _OMIT_AUTORESET]
31a20 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
31a30 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75  tion.** can be u
31a40 73 65 64 20 74 6f 20 72 65 73 74 6f 72 65 20 74  sed to restore t
31a50 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69  he legacy behavi
31a60 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f  or..**.** <b>Goo
31a70 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65  fy Interface Ale
31a80 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c  rt:</b> In the l
31a90 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
31aa0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65   the sqlite3_ste
31ab0 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79  p().** API alway
31ac0 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65  s returns a gene
31ad0 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20  ric error code, 
31ae0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20  [SQLITE_ERROR], 
31af0 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a  following any.**
31b00 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61   error other tha
31b10 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  n [SQLITE_BUSY] 
31b20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  and [SQLITE_MISU
31b30 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63  SE].  You must c
31b40 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  all.** [sqlite3_
31b50 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
31b60 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
31b70 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e   in order to fin
31b80 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20  d one of the.** 
31b90 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20  specific [error 
31ba0 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74 74  codes] that bett
31bb0 65 72 20 64 65 73 63 72 69 62 65 73 20 74 68 65  er describes the
31bc0 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64   error..** We ad
31bd0 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 69 73  mit that this is
31be0 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e   a goofy design.
31bf0 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61    The problem ha
31c00 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20  s been fixed.** 
31c10 77 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e  with the "v2" in
31c20 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75  terface.  If you
31c30 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20   prepare all of 
31c40 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65  your SQL stateme
31c50 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74  nts.** using eit
31c60 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  her [sqlite3_pre
31c70 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73  pare_v2()] or [s
31c80 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
31c90 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a  _v2()] instead.*
31ca0 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20  * of the legacy 
31cb0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
31cc0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
31cd0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e  _prepare16()] in
31ce0 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65  terfaces,.** the
31cf0 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69  n the more speci
31d00 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  fic [error codes
31d10 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 20 64  ] are returned d
31d20 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71  irectly.** by sq
31d30 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54  lite3_step().  T
31d40 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 22 76  he use of the "v
31d50 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  2" interface is 
31d60 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a  recommended..*/.
31d70 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
31d80 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69  qlite3_step(sqli
31d90 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
31da0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
31db0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
31dc0 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74 0a 2a  n a result set.*
31dd0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
31de0 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  3_stmt.**.** ^Th
31df0 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  e sqlite3_data_c
31e00 6f 75 6e 74 28 50 29 20 69 6e 74 65 72 66 61 63  ount(P) interfac
31e10 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
31e20 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
31e30 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  in the.** curren
31e40 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73  t row of the res
31e50 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70  ult set of [prep
31e60 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
31e70 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61 72  P..** ^If prepar
31e80 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20 64  ed statement P d
31e90 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 72 65 73  oes not have res
31ea0 75 6c 74 73 20 72 65 61 64 79 20 74 6f 20 72 65  ults ready to re
31eb0 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c  turn.** (via cal
31ec0 6c 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  ls to the [sqlit
31ed0 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20  e3_column_int | 
31ee0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a  sqlite3_column_*
31ef0 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66  ()] of.** interf
31f00 61 63 65 73 29 20 74 68 65 6e 20 73 71 6c 69 74  aces) then sqlit
31f10 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
31f20 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e   returns 0..** ^
31f30 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
31f40 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e  _count(P) routin
31f50 65 20 61 6c 73 6f 20 72 65 74 75 72 6e 73 20 30  e also returns 0
31f60 20 69 66 20 50 20 69 73 20 61 20 4e 55 4c 4c 20   if P is a NULL 
31f70 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65  pointer..** ^The
31f80 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
31f90 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 72  unt(P) routine r
31fa0 65 74 75 72 6e 73 20 30 20 69 66 20 74 68 65 20  eturns 0 if the 
31fb0 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
31fc0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
31fd0 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 20 5b  p](P) returned [
31fe0 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e  SQLITE_DONE].  ^
31ff0 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
32000 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c  _count(P).** wil
32010 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72  l return non-zer
32020 6f 20 69 66 20 70 72 65 76 69 6f 75 73 20 63 61  o if previous ca
32030 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
32040 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64  tep](P) returned
32050 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  .** [SQLITE_ROW]
32060 2c 20 65 78 63 65 70 74 20 69 6e 20 74 68 65 20  , except in the 
32070 63 61 73 65 20 6f 66 20 74 68 65 20 5b 50 52 41  case of the [PRA
32080 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f  GMA incremental_
32090 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65  vacuum].** where
320a0 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72   it always retur
320b0 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65 20 65 61  ns zero since ea
320c0 63 68 20 73 74 65 70 20 6f 66 20 74 68 61 74 20  ch step of that 
320d0 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72  multi-step.** pr
320e0 61 67 6d 61 20 72 65 74 75 72 6e 73 20 30 20 63  agma returns 0 c
320f0 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a  olumns of data..
32100 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
32110 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
32120 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49  count()].*/.SQLI
32130 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
32140 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71  e3_data_count(sq
32150 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
32160 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
32170 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c  REF: Fundamental
32180 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45   Datatypes.** KE
32190 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54  YWORDS: SQLITE_T
321a0 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72  EXT.**.** ^(Ever
321b0 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74  y value in SQLit
321c0 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76  e has one of fiv
321d0 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61  e fundamental da
321e0 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c  tatypes:.**.** <
321f0 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62  ul>.** <li> 64-b
32200 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
32210 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74  r.** <li> 64-bit
32220 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70   IEEE floating p
32230 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c  oint number.** <
32240 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c  li> string.** <l
32250 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20  i> BLOB.** <li> 
32260 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a  NULL.** </ul>)^.
32270 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
32280 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20  tants are codes 
32290 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73  for each of thos
322a0 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e  e types..**.** N
322b0 6f 74 65 20 74 68 61 74 20 74 68 65 20 53 51 4c  ote that the SQL
322c0 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e  ITE_TEXT constan
322d0 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20  t was also used 
322e0 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  in SQLite versio
322f0 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d  n 2.** for a com
32300 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e  pletely differen
32310 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74  t meaning.  Soft
32320 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20  ware that links 
32330 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20  against both.** 
32340 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32  SQLite version 2
32350 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73   and SQLite vers
32360 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65  ion 3 should use
32370 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e   SQLITE3_TEXT, n
32380 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58  ot.** SQLITE_TEX
32390 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  T..*/.#define SQ
323a0 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a  LITE_INTEGER  1.
323b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
323c0 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e  LOAT    2.#defin
323d0 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20  e SQLITE_BLOB   
323e0 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
323f0 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69  TE_NULL     5.#i
32400 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54  fdef SQLITE_TEXT
32410 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f  .# undef SQLITE_
32420 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66  TEXT.#else.# def
32430 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20  ine SQLITE_TEXT 
32440 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65      3.#endif.#de
32450 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58  fine SQLITE3_TEX
32460 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43  T     3../*.** C
32470 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20  API3REF: Result 
32480 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75  Values From A Qu
32490 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ery.** KEYWORDS:
324a0 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20   {column access 
324b0 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45  functions}.** ME
324c0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
324d0 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  mt.**.** ^These 
324e0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
324f0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75  information abou
32500 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d  t a single colum
32510 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  n of the current
32520 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f  .** result row o
32530 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20  f a query.  ^In 
32540 65 76 65 72 79 20 63 61 73 65 20 74 68 65 20 66  every case the f
32550 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
32560 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
32570 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
32580 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69  tatement] that i
32590 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65  s being evaluate
325a0 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  d (the [sqlite3_
325b0 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77  stmt*].** that w
325c0 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  as returned from
325d0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
325e0 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f  e_v2()] or one o
325f0 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a  f its variants).
32600 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  ** and the secon
32610 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
32620 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63  e index of the c
32630 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20  olumn for which 
32640 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73  information.** s
32650 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  hould be returne
32660 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74  d. ^The leftmost
32670 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72   column of the r
32680 65 73 75 6c 74 20 73 65 74 20 68 61 73 20 74 68  esult set has th
32690 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54  e index 0..** ^T
326a0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
326b0 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75  umns in the resu
326c0 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d  lt can be determ
326d0 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  ined using.** [s
326e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
326f0 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  unt()]..**.** If
32700 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
32710 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72  nt does not curr
32720 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61  ently point to a
32730 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69   valid row, or i
32740 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  f the.** column 
32750 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20  index is out of 
32760 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c  range, the resul
32770 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  t is undefined..
32780 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
32790 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61  s may only be ca
327a0 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f  lled when the mo
327b0 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
327c0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  o.** [sqlite3_st
327d0 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e  ep()] has return
327e0 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  ed [SQLITE_ROW] 
327f0 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b  and neither.** [
32800 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
32810 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69   nor [sqlite3_fi
32820 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62  nalize()] have b
32830 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65  een called subse
32840 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61  quently..** If a
32850 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ny of these rout
32860 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
32870 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72  after [sqlite3_r
32880 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  eset()] or.** [s
32890 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
328a0 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c  )] or after [sql
328b0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
328c0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d   returned.** som
328d0 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61  ething other tha
328e0 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  n [SQLITE_ROW], 
328f0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
32900 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66  undefined..** If
32910 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
32920 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
32930 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
32940 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a  e3_finalize()].*
32950 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f  * are called fro
32960 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 68  m a different th
32970 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f  read while any o
32980 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
32990 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c  .** are pending,
329a0 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
329b0 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
329c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
329d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
329e0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
329f0 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  s the.** [SQLITE
32a00 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74  _INTEGER | datat
32a10 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68  ype code] for th
32a20 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74  e initial data t
32a30 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65  ype.** of the re
32a40 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54  sult column.  ^T
32a50 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75  he returned valu
32a60 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  e is one of [SQL
32a70 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a  ITE_INTEGER],.**
32a80 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c   [SQLITE_FLOAT],
32a90 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20   [SQLITE_TEXT], 
32aa0 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f  [SQLITE_BLOB], o
32ab0 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e  r [SQLITE_NULL].
32ac0 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72    The value.** r
32ad0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
32ae0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
32af0 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67   is only meaning
32b00 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a  ful if no type.*
32b10 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61  * conversions ha
32b20 76 65 20 6f 63 63 75 72 72 65 64 20 61 73 20 64  ve occurred as d
32b30 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20  escribed below. 
32b40 20 41 66 74 65 72 20 61 20 74 79 70 65 20 63 6f   After a type co
32b50 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65  nversion,.** the
32b60 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
32b70 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
32b80 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64 65  n_type() is unde
32b90 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a  fined.  Future.*
32ba0 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  * versions of SQ
32bb0 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20  Lite may change 
32bc0 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
32bd0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
32be0 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  ype().** followi
32bf0 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  ng a type conver
32c00 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  sion..**.** ^If 
32c10 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
32c20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74  BLOB or UTF-8 st
32c30 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71  ring then the sq
32c40 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
32c50 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  es().** routine 
32c60 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
32c70 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
32c80 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  hat BLOB or stri
32c90 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
32ca0 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31  esult is a UTF-1
32cb0 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73  6 string, then s
32cc0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
32cd0 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a  tes() converts.*
32ce0 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20  * the string to 
32cf0 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72  UTF-8 and then r
32d00 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
32d10 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e  r of bytes..** ^
32d20 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
32d30 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65   a numeric value
32d40 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
32d50 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65  lumn_bytes() use
32d60 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e  s.** [sqlite3_sn
32d70 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e  printf()] to con
32d80 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20  vert that value 
32d90 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  to a UTF-8 strin
32da0 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a  g and returns.**
32db0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
32dc0 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72  ytes in that str
32dd0 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
32de0 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20  result is NULL, 
32df0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
32e00 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75  umn_bytes() retu
32e10 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20  rns zero..**.** 
32e20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
32e30 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d  s a BLOB or UTF-
32e40 31 36 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74  16 string then t
32e50 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
32e60 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72  n_bytes16().** r
32e70 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
32e80 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
32e90 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20  es in that BLOB 
32ea0 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  or string..** ^I
32eb0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
32ec0 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20  a UTF-8 string, 
32ed0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
32ee0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f  umn_bytes16() co
32ef0 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74  nverts.** the st
32f00 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61  ring to UTF-16 a
32f10 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20  nd then returns 
32f20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
32f30 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  tes..** ^If the 
32f40 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65  result is a nume
32f50 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73  ric value then s
32f60 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
32f70 74 65 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20  tes16() uses.** 
32f80 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
32f90 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20  f()] to convert 
32fa0 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20  that value to a 
32fb0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e  UTF-16 string an
32fc0 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65  d returns.** the
32fd0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
32fe0 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e   in that string.
32ff0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
33000 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  lt is NULL, then
33010 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
33020 62 79 74 65 73 31 36 28 29 20 72 65 74 75 72 6e  bytes16() return
33030 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54  s zero..**.** ^T
33040 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
33050 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
33060 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61  olumn_bytes()] a
33070 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nd .** [sqlite3_
33080 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
33090 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65  ] do not include
330a0 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e   the zero termin
330b0 61 74 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64  ators at the end
330c0 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e  .** of the strin
330d0 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79  g.  ^For clarity
330e0 3a 20 74 68 65 20 76 61 6c 75 65 73 20 72 65 74  : the values ret
330f0 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
33100 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
33110 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  s()] and [sqlite
33120 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
33130 28 29 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62  ()] are the numb
33140 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69  er of.** bytes i
33150 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f  n the string, no
33160 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
33170 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a  characters..**.*
33180 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72  * ^Strings retur
33190 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
331a0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64  olumn_text() and
331b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
331c0 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65  text16(),.** eve
331d0 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c  n empty strings,
331e0 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f   are always zero
331f0 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54  -terminated.  ^T
33200 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c  he return.** val
33210 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
33220 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f  column_blob() fo
33230 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20  r a zero-length 
33240 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70  BLOB is a NULL p
33250 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62  ointer..**.** <b
33260 3e 57 61 72 6e 69 6e 67 3a 3c 2f 62 3e 20 5e 54  >Warning:</b> ^T
33270 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  he object return
33280 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
33290 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
332a0 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65  s an.** [unprote
332b0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
332c0 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 49 6e 20  ue] object.  In 
332d0 61 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 20  a multithreaded 
332e0 65 6e 76 69 72 6f 6e 6d 65 6e 74 2c 0a 2a 2a 20  environment,.** 
332f0 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73  an unprotected s
33300 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
33310 65 63 74 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  ect may only be 
33320 75 73 65 64 20 73 61 66 65 6c 79 20 77 69 74 68  used safely with
33330 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
33340 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b  d_value()] and [
33350 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
33360 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74  alue()]..** If t
33370 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  he [unprotected 
33380 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
33390 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
333a0 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  y.** [sqlite3_co
333b0 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73  lumn_value()] is
333c0 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68   used in any oth
333d0 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e  er way, includin
333e0 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f  g calls.** to ro
333f0 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c  utines like [sql
33400 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29  ite3_value_int()
33410 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
33420 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72  e_text()],.** or
33430 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
33440 62 79 74 65 73 28 29 5d 2c 20 74 68 65 20 62 65  bytes()], the be
33450 68 61 76 69 6f 72 20 69 73 20 6e 6f 74 20 74 68  havior is not th
33460 72 65 61 64 73 61 66 65 2e 0a 2a 2a 0a 2a 2a 20  readsafe..**.** 
33470 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
33480 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72  ttempt to conver
33490 74 20 74 68 65 20 76 61 6c 75 65 20 77 68 65 72  t the value wher
334a0 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20  e appropriate.  
334b0 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c  ^For.** example,
334c0 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   if the internal
334d0 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20   representation 
334e0 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74  is FLOAT and a t
334f0 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73  ext result.** is
33500 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c   requested, [sql
33510 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
33520 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61   is used interna
33530 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74  lly to perform t
33540 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e  he.** conversion
33550 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
33560 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67   ^(The following
33570 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74   table details t
33580 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a  he conversions.*
33590 2a 20 74 68 61 74 20 61 72 65 20 61 70 70 6c 69  * that are appli
335a0 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ed:.**.** <block
335b0 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65  quote>.** <table
335c0 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20   border="1">.** 
335d0 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61  <tr><th> Interna
335e0 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52  l<br>Type <th> R
335f0 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65  equested<br>Type
33600 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f   <th>  Conversio
33610 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  n.**.** <tr><td>
33620 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49    NULL    <td> I
33630 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65  NTEGER   <td> Re
33640 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72  sult is 0.** <tr
33650 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
33660 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
33670 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30  d> Result is 0.0
33680 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
33690 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58  LL    <td>   TEX
336a0 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  T    <td> Result
336b0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
336c0 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  er.** <tr><td>  
336d0 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42  NULL    <td>   B
336e0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75  LOB    <td> Resu
336f0 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  lt is a NULL poi
33700 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  nter.** <tr><td>
33710 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
33720 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f  FLOAT    <td> Co
33730 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67  nvert from integ
33740 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c  er to float.** <
33750 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
33760 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
33770 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65  <td> ASCII rende
33780 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65  ring of the inte
33790 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ger.** <tr><td> 
337a0 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20  INTEGER  <td>   
337b0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d  BLOB    <td> Sam
337c0 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45  e as INTEGER->TE
337d0 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  XT.** <tr><td>  
337e0 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54  FLOAT   <td> INT
337f0 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53  EGER   <td> [CAS
33800 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a  T] to INTEGER.**
33810 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54   <tr><td>  FLOAT
33820 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
33830 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e    <td> ASCII ren
33840 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c  dering of the fl
33850 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  oat.** <tr><td> 
33860 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20   FLOAT   <td>   
33870 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 5b 43 41  BLOB    <td> [CA
33880 53 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a 20 3c  ST] to BLOB.** <
33890 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20  tr><td>  TEXT   
338a0 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
338b0 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49  <td> [CAST] to I
338c0 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74  NTEGER.** <tr><t
338d0 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
338e0 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
338f0 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a  [CAST] to REAL.*
33900 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
33910 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20      <td>   BLOB 
33920 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67     <td> No chang
33930 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  e.** <tr><td>  B
33940 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  LOB    <td> INTE
33950 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54  GER   <td> [CAST
33960 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20  ] to INTEGER.** 
33970 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
33980 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
33990 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20   <td> [CAST] to 
339a0 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  REAL.** <tr><td>
339b0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20    BLOB    <td>  
339c0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64   TEXT    <td> Ad
339d0 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  d a zero termina
339e0 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a  tor if needed.**
339f0 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62   </table>.** </b
33a00 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a  lockquote>)^.**.
33a10 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65  ** Note that whe
33a20 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  n type conversio
33a30 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65  ns occur, pointe
33a40 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 70  rs returned by p
33a50 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f  rior.** calls to
33a60 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
33a70 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f  blob(), sqlite3_
33a80 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61  column_text(), a
33a90 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  nd/or.** sqlite3
33aa0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
33ab0 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61   may be invalida
33ac0 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e  ted..** Type con
33ad0 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69  versions and poi
33ae0 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f  nter invalidatio
33af0 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a  ns might occur.*
33b00 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69  * in the followi
33b10 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20  ng cases:.**.** 
33b20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
33b30 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
33b40 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73   is a BLOB and s
33b50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
33b60 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20  xt() or.**      
33b70 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
33b80 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65  ext16() is calle
33b90 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69  d.  A zero-termi
33ba0 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20  nator might.**  
33bb0 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61      need to be a
33bc0 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 69  dded to the stri
33bd0 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e  ng.</li>.** <li>
33be0 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
33bf0 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65  tent is UTF-8 te
33c00 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  xt and sqlite3_c
33c10 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
33c20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74  or.**      sqlit
33c30 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
33c40 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54  () is called.  T
33c50 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20  he content must 
33c60 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20  be converted.** 
33c70 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c       to UTF-16.<
33c80 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  /li>.** <li> The
33c90 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
33ca0 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 20   is UTF-16 text 
33cb0 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
33cc0 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a  mn_bytes() or.**
33cd0 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
33ce0 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63  lumn_text() is c
33cf0 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74  alled.  The cont
33d00 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ent must be conv
33d10 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f  erted.**      to
33d20 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20   UTF-8.</li>.** 
33d30 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e  </ul>.**.** ^Con
33d40 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e  versions between
33d50 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54   UTF-16be and UT
33d60 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79  F-16le are alway
33d70 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20  s done in place 
33d80 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e  and do.** not in
33d90 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72  validate a prior
33da0 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68   pointer, though
33db0 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63   of course the c
33dc0 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75  ontent of the bu
33dd0 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65  ffer.** that the
33de0 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72   prior pointer r
33df0 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68  eferences will h
33e00 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65  ave been modifie
33e10 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a  d.  Other kinds.
33e20 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e  ** of conversion
33e30 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61   are done in pla
33e40 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f  ce when it is po
33e50 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65  ssible, but some
33e60 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72  times they.** ar
33e70 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61  e not possible a
33e80 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65  nd in those case
33e90 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73  s prior pointers
33ea0 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64   are invalidated
33eb0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65  ..**.** The safe
33ec0 73 74 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20  st policy is to 
33ed0 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75  invoke these rou
33ee0 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20  tines.** in one 
33ef0 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
33f00 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c   ways:.**.** <ul
33f10 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65  >.**  <li>sqlite
33f20 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
33f30 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
33f40 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
33f50 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e  ()</li>.**  <li>
33f60 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
33f70 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  lob() followed b
33f80 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
33f90 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a  _bytes()</li>.**
33fa0 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
33fb0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f  lumn_text16() fo
33fc0 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
33fd0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
33fe0 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e  ()</li>.** </ul>
33ff0 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20  .**.** In other 
34000 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c  words, you shoul
34010 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63  d call sqlite3_c
34020 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a  olumn_text(),.**
34030 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
34040 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74  blob(), or sqlit
34050 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
34060 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63  () first to forc
34070 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20  e the result.** 
34080 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65 64  into the desired
34090 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e   format, then in
340a0 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  voke sqlite3_col
340b0 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a  umn_bytes() or.*
340c0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
340d0 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20 66 69  _bytes16() to fi
340e0 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  nd the size of t
340f0 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e  he result.  Do n
34100 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20  ot mix calls.** 
34110 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
34120 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69  n_text() or sqli
34130 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
34140 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a  ) with calls to.
34150 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
34160 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64  n_bytes16(), and
34170 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c   do not mix call
34180 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
34190 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20  umn_text16().** 
341a0 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71  with calls to sq
341b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
341c0 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  es()..**.** ^The
341d0 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
341e0 65 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74  ed are valid unt
341f0 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  il a type conver
34200 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a  sion occurs as.*
34210 2a 20 64 65 73 63 72 69 62 65 64 20 61 62 6f 76  * described abov
34220 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c  e, or until [sql
34230 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20  ite3_step()] or 
34240 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
34250 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
34260 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20  _finalize()] is 
34270 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65  called.  ^The me
34280 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65 64 20  mory space used 
34290 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a  to hold strings.
342a0 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20  ** and BLOBs is 
342b0 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61  freed automatica
342c0 6c 6c 79 2e 20 20 44 6f 20 3c 65 6d 3e 6e 6f 74  lly.  Do <em>not
342d0 3c 2f 65 6d 3e 20 70 61 73 73 20 74 68 65 20 70  </em> pass the p
342e0 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
342f0 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
34300 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d  3_column_blob()]
34310 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  , [sqlite3_colum
34320 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20  n_text()], etc. 
34330 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  into.** [sqlite3
34340 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _free()]..**.** 
34350 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  ^(If a memory al
34360 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f  location error o
34370 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 65  ccurs during the
34380 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61   evaluation of a
34390 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72  ny.** of these r
343a0 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75  outines, a defau
343b0 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65 74 75  lt value is retu
343c0 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61 75  rned.  The defau
343d0 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65  lt value.** is e
343e0 69 74 68 65 72 20 74 68 65 20 69 6e 74 65 67 65  ither the intege
343f0 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e  r 0, the floatin
34400 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30  g point number 0
34410 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a  .0, or a NULL.**
34420 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65   pointer.  Subse
34430 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b  quent calls to [
34440 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
34450 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a  )] will return.*
34460 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  * [SQLITE_NOMEM]
34470 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  .)^.*/.SQLITE_AP
34480 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  I const void *sq
34490 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
344a0 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
344b0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49   int iCol);.SQLI
344c0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
344d0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
344e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
344f0 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45  nt iCol);.SQLITE
34500 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
34510 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
34520 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
34530 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45  nt iCol);.SQLITE
34540 5f 41 50 49 20 64 6f 75 62 6c 65 20 73 71 6c 69  _API double sqli
34550 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c  te3_column_doubl
34560 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
34570 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49   int iCol);.SQLI
34580 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
34590 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71  e3_column_int(sq
345a0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
345b0 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   iCol);.SQLITE_A
345c0 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  PI sqlite3_int64
345d0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
345e0 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  int64(sqlite3_st
345f0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
34600 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
34610 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a   unsigned char *
34620 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
34630 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ext(sqlite3_stmt
34640 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51  *, int iCol);.SQ
34650 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
34660 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
34670 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74  umn_text16(sqlit
34680 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
34690 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ol);.SQLITE_API 
346a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
346b0 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  mn_type(sqlite3_
346c0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
346d0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c  ;.SQLITE_API sql
346e0 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69  ite3_value *sqli
346f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
34700 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
34710 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a  int iCol);../*.*
34720 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 73 74  * CAPI3REF: Dest
34730 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 20 53  roy A Prepared S
34740 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
34750 2a 2a 20 44 45 53 54 52 55 43 54 4f 52 3a 20 73  ** DESTRUCTOR: s
34760 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
34770 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66  * ^The sqlite3_f
34780 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69  inalize() functi
34790 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20  on is called to 
347a0 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72  delete a [prepar
347b0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
347c0 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72  * ^If the most r
347d0 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e  ecent evaluation
347e0 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   of the statemen
347f0 74 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f  t encountered no
34800 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 66   errors.** or if
34810 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
34820 73 20 6e 65 76 65 72 20 62 65 65 6e 20 65 76 61  s never been eva
34830 6c 75 61 74 65 64 2c 20 74 68 65 6e 20 73 71 6c  luated, then sql
34840 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20  ite3_finalize() 
34850 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54  returns.** SQLIT
34860 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d  E_OK.  ^If the m
34870 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75  ost recent evalu
34880 61 74 69 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65  ation of stateme
34890 6e 74 20 53 20 66 61 69 6c 65 64 2c 20 74 68 65  nt S failed, the
348a0 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e  n.** sqlite3_fin
348b0 61 6c 69 7a 65 28 53 29 20 72 65 74 75 72 6e 73  alize(S) returns
348c0 20 74 68 65 20 61 70 70 72 6f 70 72 69 61 74 65   the appropriate
348d0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72   [error code] or
348e0 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 65 72  .** [extended er
348f0 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a  ror code]..**.**
34900 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69   ^The sqlite3_fi
34910 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75 74 69 6e  nalize(S) routin
34920 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  e can be called 
34930 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72  at any point dur
34940 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20  ing.** the life 
34950 63 79 63 6c 65 20 6f 66 20 5b 70 72 65 70 61 72  cycle of [prepar
34960 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a  ed statement] S:
34970 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74 61 74 65  .** before state
34980 6d 65 6e 74 20 53 20 69 73 20 65 76 65 72 20 65  ment S is ever e
34990 76 61 6c 75 61 74 65 64 2c 20 61 66 74 65 72 0a  valuated, after.
349a0 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63  ** one or more c
349b0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
349c0 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72 20 61 66  _reset()], or af
349d0 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20  ter any call.** 
349e0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
349f0 28 29 5d 20 72 65 67 61 72 64 6c 65 73 73 20 6f  ()] regardless o
34a00 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
34a10 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
34a20 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20  as.** completed 
34a30 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  execution..**.**
34a40 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74   ^Invoking sqlit
34a50 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e  e3_finalize() on
34a60 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
34a70 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f  is a harmless no
34a80 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  -op..**.** The a
34a90 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
34aa0 66 69 6e 61 6c 69 7a 65 20 65 76 65 72 79 20 5b  finalize every [
34ab0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
34ac0 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  nt] in order to 
34ad0 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63  avoid.** resourc
34ae0 65 20 6c 65 61 6b 73 2e 20 20 49 74 20 69 73 20  e leaks.  It is 
34af0 61 20 67 72 69 65 76 6f 75 73 20 65 72 72 6f 72  a grievous error
34b00 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61   for the applica
34b10 74 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f 20 75  tion to try to u
34b20 73 65 0a 2a 2a 20 61 20 70 72 65 70 61 72 65 64  se.** a prepared
34b30 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72   statement after
34b40 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e   it has been fin
34b50 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75 73 65  alized.  Any use
34b60 20 6f 66 20 61 20 70 72 65 70 61 72 65 64 0a 2a   of a prepared.*
34b70 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65  * statement afte
34b80 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69  r it has been fi
34b90 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72 65 73 75  nalized can resu
34ba0 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  lt in undefined 
34bb0 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62  and.** undesirab
34bc0 6c 65 20 62 65 68 61 76 69 6f 72 20 73 75 63 68  le behavior such
34bd0 20 61 73 20 73 65 67 66 61 75 6c 74 73 20 61 6e   as segfaults an
34be0 64 20 68 65 61 70 20 63 6f 72 72 75 70 74 69 6f  d heap corruptio
34bf0 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  n..*/.SQLITE_API
34c00 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e   int sqlite3_fin
34c10 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74  alize(sqlite3_st
34c20 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
34c30 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
34c40 65 74 20 41 20 50 72 65 70 61 72 65 64 20 53 74  et A Prepared St
34c50 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a  atement Object.*
34c60 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
34c70 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 68 65  3_stmt.**.** The
34c80 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29   sqlite3_reset()
34c90 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c   function is cal
34ca0 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b  led to reset a [
34cb0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
34cc0 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61  nt].** object ba
34cd0 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61  ck to its initia
34ce0 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 74  l state, ready t
34cf0 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 64  o be re-executed
34d00 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74  ..** ^Any SQL st
34d10 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65  atement variable
34d20 73 20 74 68 61 74 20 68 61 64 20 76 61 6c 75 65  s that had value
34d30 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20  s bound to them 
34d40 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71  using.** the [sq
34d50 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
34d60 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  | sqlite3_bind_*
34d70 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74  () API] retain t
34d80 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20  heir values..** 
34d90 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65  Use [sqlite3_cle
34da0 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74  ar_bindings()] t
34db0 6f 20 72 65 73 65 74 20 74 68 65 20 62 69 6e 64  o reset the bind
34dc0 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ings..**.** ^The
34dd0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
34de0 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  S)] interface re
34df0 73 65 74 73 20 74 68 65 20 5b 70 72 65 70 61 72  sets the [prepar
34e00 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a  ed statement] S.
34e10 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62  ** back to the b
34e20 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20  eginning of its 
34e30 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e  program..**.** ^
34e40 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
34e50 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nt call to [sqli
34e60 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72  te3_step(S)] for
34e70 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
34e80 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72  d statement] S r
34e90 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
34ea0 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ROW] or [SQLITE_
34eb0 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20  DONE],.** or if 
34ec0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
34ed0 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f  ] has never befo
34ee0 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f  re been called o
34ef0 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71  n S,.** then [sq
34f00 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
34f10 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
34f20 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  OK]..**.** ^If t
34f30 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
34f40 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
34f50 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65  step(S)] for the
34f60 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
34f70 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63  atement] S indic
34f80 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74  ated an error, t
34f90 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  hen.** [sqlite3_
34fa0 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e  reset(S)] return
34fb0 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  s an appropriate
34fc0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a   [error code]..*
34fd0 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  *.** ^The [sqlit
34fe0 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74  e3_reset(S)] int
34ff0 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20  erface does not 
35000 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
35010 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c  s.** of any [sql
35020 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62  ite3_bind_blob|b
35030 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20  indings] on the 
35040 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
35050 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 53 51 4c 49 54  ent] S..*/.SQLIT
35060 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
35070 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f  3_reset(sqlite3_
35080 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
35090 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
350a0 72 65 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e  reate Or Redefin
350b0 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a  e SQL Functions.
350c0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75  ** KEYWORDS: {fu
350d0 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20  nction creation 
350e0 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59  routines}.** KEY
350f0 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74  WORDS: {applicat
35100 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
35110 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59  function}.** KEY
35120 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74  WORDS: {applicat
35130 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
35140 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45  functions}.** ME
35150 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
35160 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74  .** ^These funct
35170 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76 65  ions (collective
35180 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e  ly known as "fun
35190 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72  ction creation r
351a0 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65  outines").** are
351b0 20 75 73 65 64 20 74 6f 20 61 64 64 20 53 51 4c   used to add SQL
351c0 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67   functions or ag
351d0 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f 20 72  gregates or to r
351e0 65 64 65 66 69 6e 65 20 74 68 65 20 62 65 68 61  edefine the beha
351f0 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74  vior.** of exist
35200 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ing SQL function
35210 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 2e  s or aggregates.
35220 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 65    The only diffe
35230 72 65 6e 63 65 73 20 62 65 74 77 65 65 6e 0a 2a  rences between.*
35240 2a 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * these routines
35250 20 61 72 65 20 74 68 65 20 74 65 78 74 20 65 6e   are the text en
35260 63 6f 64 69 6e 67 20 65 78 70 65 63 74 65 64 20  coding expected 
35270 66 6f 72 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e  for.** the secon
35280 64 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65  d parameter (the
35290 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 66 75 6e   name of the fun
352a0 63 74 69 6f 6e 20 62 65 69 6e 67 20 63 72 65 61  ction being crea
352b0 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20  ted).** and the 
352c0 70 72 65 73 65 6e 63 65 20 6f 72 20 61 62 73 65  presence or abse
352d0 6e 63 65 20 6f 66 20 61 20 64 65 73 74 72 75 63  nce of a destruc
352e0 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66 6f 72  tor callback for
352f0 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
35300 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72  ion data pointer
35310 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
35320 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
35330 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
35340 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69  nnection] to whi
35350 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75  ch the SQL.** fu
35360 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20  nction is to be 
35370 61 64 64 65 64 2e 20 20 5e 49 66 20 61 6e 20 61  added.  ^If an a
35380 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 65 73 20  pplication uses 
35390 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61  more than one da
353a0 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
353b0 74 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69 63  tion then applic
353c0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
353d0 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74  L functions must
353e0 20 62 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f 20   be added.** to 
353f0 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f  each database co
35400 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61 72 61 74  nnection separat
35410 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ely..**.** ^The 
35420 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
35430 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
35440 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
35450 20 74 6f 20 62 65 20 63 72 65 61 74 65 64 20 6f   to be created o
35460 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e 20  r.** redefined. 
35470 20 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20   ^The length of 
35480 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69  the name is limi
35490 74 65 64 20 74 6f 20 32 35 35 20 62 79 74 65 73  ted to 255 bytes
354a0 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a 20 72   in a UTF-8.** r
354b0 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c 20 65  epresentation, e
354c0 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20  xclusive of the 
354d0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e  zero-terminator.
354e0 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65    ^Note that the
354f0 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68 20   name.** length 
35500 6c 69 6d 69 74 20 69 73 20 69 6e 20 55 54 46 2d  limit is in UTF-
35510 38 20 62 79 74 65 73 2c 20 6e 6f 74 20 63 68 61  8 bytes, not cha
35520 72 61 63 74 65 72 73 20 6e 6f 72 20 55 54 46 2d  racters nor UTF-
35530 31 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a 20 5e  16 bytes.  .** ^
35540 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63  Any attempt to c
35550 72 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f 6e  reate a function
35560 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e   with a longer n
35570 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75  ame.** will resu
35580 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f 4d 49  lt in [SQLITE_MI
35590 53 55 53 45 5d 20 62 65 69 6e 67 20 72 65 74 75  SUSE] being retu
355a0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rned..**.** ^The
355b0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
355c0 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74 68   (nArg).** is th
355d0 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  e number of argu
355e0 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65 20 53  ments that the S
355f0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a  QL function or.*
35600 2a 20 61 67 67 72 65 67 61 74 65 20 74 61 6b 65  * aggregate take
35610 73 2e 20 5e 49 66 20 74 68 69 73 20 70 61 72 61  s. ^If this para
35620 6d 65 74 65 72 20 69 73 20 2d 31 2c 20 74 68 65  meter is -1, the
35630 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  n the SQL functi
35640 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61  on or.** aggrega
35650 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e 79 20  te may take any 
35660 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
35670 6e 74 73 20 62 65 74 77 65 65 6e 20 30 20 61 6e  nts between 0 an
35680 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20 73  d the limit.** s
35690 65 74 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c  et by [sqlite3_l
356a0 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49  imit]([SQLITE_LI
356b0 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
356c0 5d 29 2e 20 20 49 66 20 74 68 65 20 74 68 69 72  ]).  If the thir
356d0 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69  d.** parameter i
356e0 73 20 6c 65 73 73 20 74 68 61 6e 20 2d 31 20 6f  s less than -1 o
356f0 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31  r greater than 1
35700 32 37 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  27 then the beha
35710 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66  vior is.** undef
35720 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ined..**.** ^The
35730 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
35740 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70 65  r, eTextRep, spe
35750 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b  cifies what.** [
35760 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74 65  SQLITE_UTF8 | te
35770 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69  xt encoding] thi
35780 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70  s SQL function p
35790 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74  refers for.** it
357a0 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 54  s parameters.  T
357b0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
357c0 68 6f 75 6c 64 20 73 65 74 20 74 68 69 73 20 70  hould set this p
357d0 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b  arameter to.** [
357e0 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 20  SQLITE_UTF16LE] 
357f0 69 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  if the function 
35800 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
35810 6e 76 6f 6b 65 73 20 0a 2a 2a 20 5b 73 71 6c 69  nvokes .** [sqli
35820 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
35830 6c 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70 75  le()] on an inpu
35840 74 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54  t, or [SQLITE_UT
35850 46 31 36 42 45 5d 20 69 66 20 74 68 65 0a 2a 2a  F16BE] if the.**
35860 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
35870 69 6e 76 6f 6b 65 73 20 5b 73 71 6c 69 74 65 33  invokes [sqlite3
35880 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28  _value_text16be(
35890 29 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20  )] on an input, 
358a0 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54  or.** [SQLITE_UT
358b0 46 31 36 5d 20 69 66 20 5b 73 71 6c 69 74 65 33  F16] if [sqlite3
358c0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d  _value_text16()]
358d0 20 69 73 20 75 73 65 64 2c 20 6f 72 20 5b 53 51   is used, or [SQ
358e0 4c 49 54 45 5f 55 54 46 38 5d 0a 2a 2a 20 6f 74  LITE_UTF8].** ot
358f0 68 65 72 77 69 73 65 2e 20 20 5e 54 68 65 20 73  herwise.  ^The s
35900 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ame SQL function
35910 20 6d 61 79 20 62 65 20 72 65 67 69 73 74 65 72   may be register
35920 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65  ed multiple time
35930 73 20 75 73 69 6e 67 0a 2a 2a 20 64 69 66 66 65  s using.** diffe
35940 72 65 6e 74 20 70 72 65 66 65 72 72 65 64 20 74  rent preferred t
35950 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2c 20 77  ext encodings, w
35960 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 69 6d  ith different im
35970 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f  plementations fo
35980 72 0a 2a 2a 20 65 61 63 68 20 65 6e 63 6f 64 69  r.** each encodi
35990 6e 67 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c  ng..** ^When mul
359a0 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  tiple implementa
359b0 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
359c0 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61  e function are a
359d0 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65  vailable, SQLite
359e0 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68  .** will pick th
359f0 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c  e one that invol
35a00 76 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d  ves the least am
35a10 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e  ount of data con
35a20 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  version..**.** ^
35a30 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
35a40 65 74 65 72 20 6d 61 79 20 6f 70 74 69 6f 6e 61  eter may optiona
35a50 6c 6c 79 20 62 65 20 4f 52 65 64 20 77 69 74 68  lly be ORed with
35a60 20 5b 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49   [SQLITE_DETERMI
35a70 4e 49 53 54 49 43 5d 0a 2a 2a 20 74 6f 20 73 69  NISTIC].** to si
35a80 67 6e 61 6c 20 74 68 61 74 20 74 68 65 20 66 75  gnal that the fu
35a90 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 61 6c 77 61  nction will alwa
35aa0 79 73 20 72 65 74 75 72 6e 20 74 68 65 20 73 61  ys return the sa
35ab0 6d 65 20 72 65 73 75 6c 74 20 67 69 76 65 6e 0a  me result given.
35ac0 2a 2a 20 74 68 65 20 73 61 6d 65 20 69 6e 70 75  ** the same inpu
35ad0 74 73 20 77 69 74 68 69 6e 20 61 20 73 69 6e 67  ts within a sing
35ae0 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  le SQL statement
35af0 2e 20 20 4d 6f 73 74 20 53 51 4c 20 66 75 6e 63  .  Most SQL func
35b00 74 69 6f 6e 73 20 61 72 65 0a 2a 2a 20 64 65 74  tions are.** det
35b10 65 72 6d 69 6e 69 73 74 69 63 2e 20 20 54 68 65  erministic.  The
35b20 20 62 75 69 6c 74 2d 69 6e 20 5b 72 61 6e 64 6f   built-in [rando
35b30 6d 28 29 5d 20 53 51 4c 20 66 75 6e 63 74 69 6f  m()] SQL functio
35b40 6e 20 69 73 20 61 6e 20 65 78 61 6d 70 6c 65 20  n is an example 
35b50 6f 66 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  of a.** function
35b60 20 74 68 61 74 20 69 73 20 6e 6f 74 20 64 65 74   that is not det
35b70 65 72 6d 69 6e 69 73 74 69 63 2e 20 20 54 68 65  erministic.  The
35b80 20 53 51 4c 69 74 65 20 71 75 65 72 79 20 70 6c   SQLite query pl
35b90 61 6e 6e 65 72 20 69 73 20 61 62 6c 65 20 74 6f  anner is able to
35ba0 0a 2a 2a 20 70 65 72 66 6f 72 6d 20 61 64 64 69  .** perform addi
35bb0 74 69 6f 6e 61 6c 20 6f 70 74 69 6d 69 7a 61 74  tional optimizat
35bc0 69 6f 6e 73 20 6f 6e 20 64 65 74 65 72 6d 69 6e  ions on determin
35bd0 69 73 74 69 63 20 66 75 6e 63 74 69 6f 6e 73 2c  istic functions,
35be0 20 73 6f 20 75 73 65 0a 2a 2a 20 6f 66 20 74 68   so use.** of th
35bf0 65 20 5b 53 51 4c 49 54 45 5f 44 45 54 45 52 4d  e [SQLITE_DETERM
35c00 49 4e 49 53 54 49 43 5d 20 66 6c 61 67 20 69 73  INISTIC] flag is
35c10 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 77 68 65   recommended whe
35c20 72 65 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 0a  re possible..**.
35c30 2a 2a 20 5e 28 54 68 65 20 66 69 66 74 68 20 70  ** ^(The fifth p
35c40 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61  arameter is an a
35c50 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72  rbitrary pointer
35c60 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74  .  The implement
35c70 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20  ation of the.** 
35c80 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69  function can gai
35c90 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68 69 73  n access to this
35ca0 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 5b   pointer using [
35cb0 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
35cc0 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  a()].)^.**.** ^T
35cd0 68 65 20 73 69 78 74 68 2c 20 73 65 76 65 6e 74  he sixth, sevent
35ce0 68 20 61 6e 64 20 65 69 67 68 74 68 20 70 61 72  h and eighth par
35cf0 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20  ameters, xFunc, 
35d00 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c  xStep and xFinal
35d10 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72  , are.** pointer
35d20 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20  s to C-language 
35d30 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69  functions that i
35d40 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c  mplement the SQL
35d50 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
35d60 61 67 67 72 65 67 61 74 65 2e 20 5e 41 20 73 63  aggregate. ^A sc
35d70 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f  alar SQL functio
35d80 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d  n requires an im
35d90 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
35da0 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c  the xFunc.** cal
35db0 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c  lback only; NULL
35dc0 20 70 6f 69 6e 74 65 72 73 20 6d 75 73 74 20 62   pointers must b
35dd0 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
35de0 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c  xStep and xFinal
35df0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20  .** parameters. 
35e00 5e 41 6e 20 61 67 67 72 65 67 61 74 65 20 53 51  ^An aggregate SQ
35e10 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69  L function requi
35e20 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74  res an implement
35e30 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a  ation of xStep.*
35e40 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64  * and xFinal and
35e50 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d 75   NULL pointer mu
35e60 73 74 20 62 65 20 70 61 73 73 65 64 20 66 6f 72  st be passed for
35e70 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c 65   xFunc. ^To dele
35e80 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a  te an existing.*
35e90 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  * SQL function o
35ea0 72 20 61 67 67 72 65 67 61 74 65 2c 20 70 61 73  r aggregate, pas
35eb0 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20  s NULL pointers 
35ec0 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75  for all three fu
35ed0 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61  nction.** callba
35ee0 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  cks..**.** ^(If 
35ef0 74 68 65 20 6e 69 6e 74 68 20 70 61 72 61 6d 65  the ninth parame
35f00 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ter to sqlite3_c
35f10 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76  reate_function_v
35f20 32 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  2() is not NULL,
35f30 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 64  .** then it is d
35f40 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68  estructor for th
35f50 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  e application da
35f60 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20  ta pointer. .** 
35f70 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69  The destructor i
35f80 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74  s invoked when t
35f90 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64  he function is d
35fa0 65 6c 65 74 65 64 2c 20 65 69 74 68 65 72 20 62  eleted, either b
35fb0 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c  y being.** overl
35fc0 6f 61 64 65 64 20 6f 72 20 77 68 65 6e 20 74 68  oaded or when th
35fd0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
35fe0 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a  ction closes.)^.
35ff0 2a 2a 20 5e 54 68 65 20 64 65 73 74 72 75 63 74  ** ^The destruct
36000 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f 6b  or is also invok
36010 65 64 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74  ed if the call t
36020 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65  o.** sqlite3_cre
36030 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28  ate_function_v2(
36040 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65  ) fails..** ^Whe
36050 6e 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  n the destructor
36060 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65   callback of the
36070 20 74 65 6e 74 68 20 70 61 72 61 6d 65 74 65 72   tenth parameter
36080 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 0a   is invoked, it.
36090 2a 2a 20 69 73 20 70 61 73 73 65 64 20 61 20 73  ** is passed a s
360a0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
360b0 68 69 63 68 20 69 73 20 61 20 63 6f 70 79 20 6f  hich is a copy o
360c0 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
360d0 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e 74  n data .** point
360e0 65 72 20 77 68 69 63 68 20 77 61 73 20 74 68 65  er which was the
360f0 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72   fifth parameter
36100 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61   to sqlite3_crea
36110 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29  te_function_v2()
36120 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 70  ..**.** ^It is p
36130 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69  ermitted to regi
36140 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d  ster multiple im
36150 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
36160 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e   the same.** fun
36170 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20  ctions with the 
36180 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69  same name but wi
36190 74 68 20 65 69 74 68 65 72 20 64 69 66 66 65 72  th either differ
361a0 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a  ing numbers of.*
361b0 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64  * arguments or d
361c0 69 66 66 65 72 69 6e 67 20 70 72 65 66 65 72 72  iffering preferr
361d0 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ed text encoding
361e0 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  s.  ^SQLite will
361f0 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c   use.** the impl
36200 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20  ementation that 
36210 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74  most closely mat
36220 63 68 65 73 20 74 68 65 20 77 61 79 20 69 6e 20  ches the way in 
36230 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c  which the.** SQL
36240 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65   function is use
36250 64 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20  d.  ^A function 
36260 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
36270 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69  ith a non-negati
36280 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d  ve.** nArg param
36290 65 74 65 72 20 69 73 20 61 20 62 65 74 74 65 72  eter is a better
362a0 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75   match than a fu
362b0 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
362c0 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20  ation with.** a 
362d0 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20 20  negative nArg.  
362e0 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72  ^A function wher
362f0 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20  e the preferred 
36300 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a  text encoding.**
36310 20 6d 61 74 63 68 65 73 20 74 68 65 20 64 61 74   matches the dat
36320 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69  abase encoding i
36330 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61  s a better.** ma
36340 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74  tch than a funct
36350 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e  ion where the en
36360 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65 72  coding is differ
36370 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 6e  ent.  .** ^A fun
36380 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
36390 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65  encoding differe
363a0 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e 20 55  nce is between U
363b0 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31 36  TF16le and UTF16
363c0 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65  be.** is a close
363d0 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66  r match than a f
363e0 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
363f0 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65  e encoding diffe
36400 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74 77  rence is.** betw
36410 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54 46  een UTF8 and UTF
36420 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74  16..**.** ^Built
36430 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61  -in functions ma
36440 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 20  y be overloaded 
36450 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69  by new applicati
36460 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
36470 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20  ions..**.** ^An 
36480 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
36490 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ned function is 
364a0 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63 61 6c  permitted to cal
364b0 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74  l other.** SQLit
364c0 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20 48  e interfaces.  H
364d0 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63 61 6c  owever, such cal
364e0 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 63  ls must not.** c
364f0 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73  lose the databas
36500 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72  e connection nor
36510 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65 73   finalize or res
36520 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64 0a  et the prepared.
36530 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  ** statement in 
36540 77 68 69 63 68 20 74 68 65 20 66 75 6e 63 74 69  which the functi
36550 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
36560 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
36570 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
36580 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69  function(.  sqli
36590 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74  te3 *db,.  const
365a0 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e   char *zFunction
365b0 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67  Name,.  int nArg
365c0 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
365d0 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a  ,.  void *pApp,.
365e0 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28    void (*xFunc)(
365f0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
36600 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
36610 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
36620 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63  xStep)(sqlite3_c
36630 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
36640 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
36650 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73  void (*xFinal)(s
36660 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
36670 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .);.SQLITE_API i
36680 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
36690 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20  e_function16(.  
366a0 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63  sqlite3 *db,.  c
366b0 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63  onst void *zFunc
366c0 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  tionName,.  int 
366d0 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78  nArg,.  int eTex
366e0 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41  tRep,.  void *pA
366f0 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75  pp,.  void (*xFu
36700 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
36710 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
36720 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
36730 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74  d (*xStep)(sqlit
36740 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
36750 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
36760 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61  ,.  void (*xFina
36770 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  l)(sqlite3_conte
36780 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41  xt*).);.SQLITE_A
36790 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
367a0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76  reate_function_v
367b0 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
367c0 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ,.  const char *
367d0 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20  zFunctionName,. 
367e0 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74   int nArg,.  int
367f0 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69   eTextRep,.  voi
36800 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20  d *pApp,.  void 
36810 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33  (*xFunc)(sqlite3
36820 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
36830 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
36840 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28    void (*xStep)(
36850 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
36860 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
36870 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
36880 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f  xFinal)(sqlite3_
36890 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f 69  context*),.  voi
368a0 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69  d(*xDestroy)(voi
368b0 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  d*).);../*.** CA
368c0 50 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63  PI3REF: Text Enc
368d0 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65  odings.**.** The
368e0 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69  se constant defi
368f0 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73  ne integer codes
36900 20 74 68 61 74 20 72 65 70 72 65 73 65 6e 74 20   that represent 
36910 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74  the various.** t
36920 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75  ext encodings su
36930 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74  pported by SQLit
36940 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e..*/.#define SQ
36950 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20 20 20  LITE_UTF8       
36960 20 20 20 20 31 20 20 20 20 2f 2a 20 49 4d 50 3a      1    /* IMP:
36970 20 52 2d 33 37 35 31 34 2d 33 35 35 36 36 20 2a   R-37514-35566 *
36980 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
36990 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20 20 20  _UTF16LE        
369a0 32 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 30  2    /* IMP: R-0
369b0 33 33 37 31 2d 33 37 36 33 37 20 2a 2f 0a 23 64  3371-37637 */.#d
369c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
369d0 31 36 42 45 20 20 20 20 20 20 20 20 33 20 20 20  16BE        3   
369e0 20 2f 2a 20 49 4d 50 3a 20 52 2d 35 31 39 37 31   /* IMP: R-51971
369f0 2d 33 34 31 35 34 20 2a 2f 0a 23 64 65 66 69 6e  -34154 */.#defin
36a00 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20  e SQLITE_UTF16  
36a10 20 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20          4    /* 
36a20 55 73 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  Use native byte 
36a30 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65  order */.#define
36a40 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20   SQLITE_ANY     
36a50 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20 44         5    /* D
36a60 65 70 72 65 63 61 74 65 64 20 2a 2f 0a 23 64 65  eprecated */.#de
36a70 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
36a80 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20  6_ALIGNED  8    
36a90 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  /* sqlite3_creat
36aa0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79  e_collation only
36ab0 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
36ac0 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 46 6c  REF: Function Fl
36ad0 61 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ags.**.** These 
36ae0 63 6f 6e 73 74 61 6e 74 73 20 6d 61 79 20 62 65  constants may be
36af0 20 4f 52 65 64 20 74 6f 67 65 74 68 65 72 20 77   ORed together w
36b00 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ith the .** [SQL
36b10 49 54 45 5f 55 54 46 38 20 7c 20 70 72 65 66 65  ITE_UTF8 | prefe
36b20 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69  rred text encodi
36b30 6e 67 5d 20 61 73 20 74 68 65 20 66 6f 75 72 74  ng] as the fourt
36b40 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  h argument.** to
36b50 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
36b60 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 5b 73  _function()], [s
36b70 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
36b80 6e 63 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a  nction16()], or.
36b90 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ** [sqlite3_crea
36ba0 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29  te_function_v2()
36bb0 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ]..*/.#define SQ
36bc0 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54  LITE_DETERMINIST
36bd0 49 43 20 20 20 20 30 78 38 30 30 0a 0a 2f 2a 0a  IC    0x800../*.
36be0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 70  ** CAPI3REF: Dep
36bf0 72 65 63 61 74 65 64 20 46 75 6e 63 74 69 6f 6e  recated Function
36c00 73 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44 0a  s.** DEPRECATED.
36c10 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63  **.** These func
36c20 74 69 6f 6e 73 20 61 72 65 20 5b 64 65 70 72 65  tions are [depre
36c30 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65  cated].  In orde
36c40 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a  r to maintain.**
36c50 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
36c60 74 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c  tibility with ol
36c70 64 65 72 20 63 6f 64 65 2c 20 74 68 65 73 65 20  der code, these 
36c80 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e  functions contin
36c90 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70  ue .** to be sup
36ca0 70 6f 72 74 65 64 2e 20 20 48 6f 77 65 76 65 72  ported.  However
36cb0 2c 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f  , new applicatio
36cc0 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a  ns should avoid.
36cd0 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74 68  ** the use of th
36ce0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20  ese functions.  
36cf0 54 6f 20 65 6e 63 6f 75 72 61 67 65 20 70 72 6f  To encourage pro
36d00 67 72 61 6d 6d 65 72 73 20 74 6f 20 61 76 6f 69  grammers to avoi
36d10 64 0a 2a 2a 20 74 68 65 73 65 20 66 75 6e 63 74  d.** these funct
36d20 69 6f 6e 73 2c 20 77 65 20 77 69 6c 6c 20 6e 6f  ions, we will no
36d30 74 20 65 78 70 6c 61 69 6e 20 77 68 61 74 20 74  t explain what t
36d40 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64  hey do..*/.#ifnd
36d50 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44  ef SQLITE_OMIT_D
36d60 45 50 52 45 43 41 54 45 44 0a 53 51 4c 49 54 45  EPRECATED.SQLITE
36d70 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52  _API SQLITE_DEPR
36d80 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
36d90 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75  e3_aggregate_cou
36da0 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  nt(sqlite3_conte
36db0 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  xt*);.SQLITE_API
36dc0 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54   SQLITE_DEPRECAT
36dd0 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  ED int sqlite3_e
36de0 78 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73  xpired(sqlite3_s
36df0 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  tmt*);.SQLITE_AP
36e00 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  I SQLITE_DEPRECA
36e10 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
36e20 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67  transfer_binding
36e30 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  s(sqlite3_stmt*,
36e40 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b   sqlite3_stmt*);
36e50 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49  .SQLITE_API SQLI
36e60 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
36e70 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c  t sqlite3_global
36e80 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a  _recover(void);.
36e90 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54  SQLITE_API SQLIT
36ea0 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69  E_DEPRECATED voi
36eb0 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64  d sqlite3_thread
36ec0 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a  _cleanup(void);.
36ed0 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54  SQLITE_API SQLIT
36ee0 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
36ef0 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
36f00 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f  alarm(void(*)(vo
36f10 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36  id*,sqlite3_int6
36f20 34 2c 69 6e 74 29 2c 0a 20 20 20 20 20 20 20 20  4,int),.        
36f30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f                vo
36f40 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36  id*,sqlite3_int6
36f50 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  4);.#endif../*.*
36f60 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61  * CAPI3REF: Obta
36f70 69 6e 69 6e 67 20 53 51 4c 20 56 61 6c 75 65 73  ining SQL Values
36f80 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
36f90 74 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20  te3_value.**.** 
36fa0 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69  The C-language i
36fb0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
36fc0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61   SQL functions a
36fd0 6e 64 20 61 67 67 72 65 67 61 74 65 73 20 75 73  nd aggregates us
36fe0 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f  es.** this set o
36ff0 66 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74  f interface rout
37000 69 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20 74  ines to access t
37010 68 65 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c  he parameter val
37020 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75  ues on.** the fu
37030 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67  nction or aggreg
37040 61 74 65 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65  ate.  .**.** The
37050 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61 6c   xFunc (for scal
37060 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72  ar functions) or
37070 20 78 53 74 65 70 20 28 66 6f 72 20 61 67 67 72   xStep (for aggr
37080 65 67 61 74 65 73 29 20 70 61 72 61 6d 65 74 65  egates) paramete
37090 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65  rs.** to [sqlite
370a0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
370b0 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
370c0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
370d0 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65  n16()].** define
370e0 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20   callbacks that 
370f0 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51  implement the SQ
37100 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20  L functions and 
37110 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54  aggregates..** T
37120 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
37130 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 61   to these callba
37140 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79 20  cks is an array 
37150 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a  of pointers to.*
37160 2a 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  * [protected sql
37170 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
37180 63 74 73 2e 20 20 54 68 65 72 65 20 69 73 20 6f  cts.  There is o
37190 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ne [sqlite3_valu
371a0 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a  e] object for.**
371b0 20 65 61 63 68 20 70 61 72 61 6d 65 74 65 72 20   each parameter 
371c0 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  to the SQL funct
371d0 69 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 74  ion.  These rout
371e0 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 74 6f  ines are used to
371f0 0a 2a 2a 20 65 78 74 72 61 63 74 20 76 61 6c 75  .** extract valu
37200 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c  es from the [sql
37210 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
37220 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  cts..**.** These
37230 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f   routines work o
37240 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f 74 65 63  nly with [protec
37250 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
37260 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41  e] objects..** A
37270 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73  ny attempt to us
37280 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  e these routines
37290 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63   on an [unprotec
372a0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
372b0 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73  e].** object res
372c0 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65  ults in undefine
372d0 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a  d behavior..**.*
372e0 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
372f0 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65  s work just like
37300 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
37310 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73  ng [column acces
37320 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20  s functions].** 
37330 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65 73  except that thes
37340 65 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20  e routines take 
37350 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63  a single [protec
37360 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
37370 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69  e] object.** poi
37380 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20  nter instead of 
37390 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  a [sqlite3_stmt*
373a0 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e  ] pointer and an
373b0 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20   integer column 
373c0 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  number..**.** ^T
373d0 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
373e0 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65 72 66  _text16() interf
373f0 61 63 65 20 65 78 74 72 61 63 74 73 20 61 20 55  ace extracts a U
37400 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20  TF-16 string.** 
37410 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
37420 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20  te-order of the 
37430 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e  host machine.  ^
37440 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  The.** sqlite3_v
37450 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29 20  alue_text16be() 
37460 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  and sqlite3_valu
37470 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e 74  e_text16le() int
37480 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 61  erfaces.** extra
37490 63 74 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  ct UTF-16 string
374a0 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e 20  s as big-endian 
374b0 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61  and little-endia
374c0 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  n respectively..
374d0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69  **.** ^(The sqli
374e0 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69  te3_value_numeri
374f0 63 5f 74 79 70 65 28 29 20 69 6e 74 65 72 66 61  c_type() interfa
37500 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61  ce attempts to a
37510 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20  pply.** numeric 
37520 61 66 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20  affinity to the 
37530 76 61 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61  value.  This mea
37540 6e 73 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d  ns that an attem
37550 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f  pt is.** made to
37560 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c   convert the val
37570 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  ue to an integer
37580 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69   or floating poi
37590 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20  nt.  If.** such 
375a0 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20  a conversion is 
375b0 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74  possible without
375c0 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61   loss of informa
375d0 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a  tion (in other.*
375e0 2a 20 77 6f 72 64 73 2c 20 69 66 20 74 68 65 20  * words, if the 
375f0 76 61 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e  value is a strin
37600 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b  g that looks lik
37610 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74  e a number).** t
37620 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69  hen the conversi
37630 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e  on is performed.
37640 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63    Otherwise no c
37650 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73  onversion occurs
37660 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ..** The [SQLITE
37670 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74  _INTEGER | datat
37680 79 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65  ype] after conve
37690 72 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65  rsion is returne
376a0 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73  d.)^.**.** Pleas
376b0 65 20 70 61 79 20 70 61 72 74 69 63 75 6c 61 72  e pay particular
376c0 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68   attention to th
376d0 65 20 66 61 63 74 20 74 68 61 74 20 74 68 65 20  e fact that the 
376e0 70 6f 69 6e 74 65 72 20 72 65 74 75 72 6e 65 64  pointer returned
376f0 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
37700 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c  3_value_blob()],
37710 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
37720 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b  text()], or.** [
37730 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
37740 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69  xt16()] can be i
37750 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20 61 20  nvalidated by a 
37760 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20  subsequent call 
37770 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  to.** [sqlite3_v
37780 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b  alue_bytes()], [
37790 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
377a0 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74  tes16()], [sqlit
377b0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d  e3_value_text()]
377c0 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ,.** or [sqlite3
377d0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d  _value_text16()]
377e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
377f0 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63  utines must be c
37800 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
37810 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a  ame thread as.**
37820 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
37830 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65 64 20  n that supplied 
37840 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
37850 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 2e  ue*] parameters.
37860 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  .*/.SQLITE_API c
37870 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
37880 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71  e3_value_blob(sq
37890 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53  lite3_value*);.S
378a0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
378b0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
378c0 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  s(sqlite3_value*
378d0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
378e0 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
378f0 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f  bytes16(sqlite3_
37900 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f  value*);.SQLITE_
37910 41 50 49 20 64 6f 75 62 6c 65 20 73 71 6c 69 74  API double sqlit
37920 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28  e3_value_double(
37930 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
37940 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
37950 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
37960 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t(sqlite3_value*
37970 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71  );.SQLITE_API sq
37980 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
37990 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28  te3_value_int64(
379a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
379b0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
379c0 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20  t unsigned char 
379d0 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
379e0 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ext(sqlite3_valu
379f0 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  e*);.SQLITE_API 
37a00 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
37a10 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
37a20 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
37a30 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
37a40 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
37a50 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28  _value_text16le(
37a60 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
37a70 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
37a80 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
37a90 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73  value_text16be(s
37aa0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
37ab0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
37ac0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70  qlite3_value_typ
37ad0 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
37ae0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
37af0 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
37b00 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c  numeric_type(sql
37b10 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f  ite3_value*);../
37b20 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
37b30 69 6e 64 69 6e 67 20 54 68 65 20 53 75 62 74 79  inding The Subty
37b40 70 65 20 4f 66 20 53 51 4c 20 56 61 6c 75 65 73  pe Of SQL Values
37b50 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
37b60 74 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20  te3_value.**.** 
37b70 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
37b80 65 5f 73 75 62 74 79 70 65 28 56 29 20 66 75 6e  e_subtype(V) fun
37b90 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
37ba0 65 20 73 75 62 74 79 70 65 20 66 6f 72 0a 2a 2a  e subtype for.**
37bb0 20 61 6e 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e   an [application
37bc0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
37bd0 63 74 69 6f 6e 5d 20 61 72 67 75 6d 65 6e 74 20  ction] argument 
37be0 56 2e 20 20 54 68 65 20 73 75 62 74 79 70 65 0a  V.  The subtype.
37bf0 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 63  ** information c
37c00 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 70 61  an be used to pa
37c10 73 73 20 61 20 6c 69 6d 69 74 65 64 20 61 6d 6f  ss a limited amo
37c20 75 6e 74 20 6f 66 20 63 6f 6e 74 65 78 74 20 66  unt of context f
37c30 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 53 51 4c 20 66  rom.** one SQL f
37c40 75 6e 63 74 69 6f 6e 20 74 6f 20 61 6e 6f 74 68  unction to anoth
37c50 65 72 2e 20 20 55 73 65 20 74 68 65 20 5b 73 71  er.  Use the [sq
37c60 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 73 75 62  lite3_result_sub
37c70 74 79 70 65 28 29 5d 0a 2a 2a 20 72 6f 75 74 69  type()].** routi
37c80 6e 65 20 74 6f 20 73 65 74 20 74 68 65 20 73 75  ne to set the su
37c90 62 74 79 70 65 20 66 6f 72 20 74 68 65 20 72 65  btype for the re
37ca0 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 61 6e  turn value of an
37cb0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a   SQL function..*
37cc0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65  *.** SQLite make
37cd0 73 20 6e 6f 20 75 73 65 20 6f 66 20 73 75 62 74  s no use of subt
37ce0 79 70 65 20 69 74 73 65 6c 66 2e 20 20 49 74 20  ype itself.  It 
37cf0 6d 65 72 65 6c 79 20 70 61 73 73 65 73 20 74 68  merely passes th
37d00 65 20 73 75 62 74 79 70 65 0a 2a 2a 20 66 72 6f  e subtype.** fro
37d10 6d 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20  m the result of 
37d20 6f 6e 65 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e  one [application
37d30 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
37d40 63 74 69 6f 6e 5d 20 69 6e 74 6f 20 74 68 65 0a  ction] into the.
37d50 2a 2a 20 69 6e 70 75 74 20 6f 66 20 61 6e 6f 74  ** input of anot
37d60 68 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  her..*/.SQLITE_A
37d70 50 49 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 20  PI unsigned int 
37d80 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 73 75  sqlite3_value_su
37d90 62 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61  btype(sqlite3_va
37da0 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  lue*);../*.** CA
37db0 50 49 33 52 45 46 3a 20 43 6f 70 79 20 41 6e 64  PI3REF: Copy And
37dc0 20 46 72 65 65 20 53 51 4c 20 56 61 6c 75 65 73   Free SQL Values
37dd0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
37de0 74 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20  te3_value.**.** 
37df0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  ^The sqlite3_val
37e00 75 65 5f 64 75 70 28 56 29 20 69 6e 74 65 72 66  ue_dup(V) interf
37e10 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ace makes a copy
37e20 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
37e30 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63  _value].** objec
37e40 74 20 44 20 61 6e 64 20 72 65 74 75 72 6e 73 20  t D and returns 
37e50 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61  a pointer to tha
37e60 74 20 63 6f 70 79 2e 20 20 5e 54 68 65 20 5b 73  t copy.  ^The [s
37e70 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 72 65  qlite3_value] re
37e80 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 61 20 5b  turned.** is a [
37e90 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
37ea0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
37eb0 65 76 65 6e 20 69 66 20 74 68 65 20 69 6e 70 75  even if the inpu
37ec0 74 20 69 73 20 6e 6f 74 2e 0a 2a 2a 20 5e 54 68  t is not..** ^Th
37ed0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
37ee0 64 75 70 28 56 29 20 69 6e 74 65 72 66 61 63 65  dup(V) interface
37ef0 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69 66   returns NULL if
37f00 20 56 20 69 73 20 4e 55 4c 4c 20 6f 72 20 69 66   V is NULL or if
37f10 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c   a.** memory all
37f20 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2e 0a 2a  ocation fails..*
37f30 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
37f40 33 5f 76 61 6c 75 65 5f 66 72 65 65 28 56 29 20  3_value_free(V) 
37f50 69 6e 74 65 72 66 61 63 65 20 66 72 65 65 73 20  interface frees 
37f60 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  an [sqlite3_valu
37f70 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 72 65  e] object.** pre
37f80 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64  viously obtained
37f90 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76   from [sqlite3_v
37fa0 61 6c 75 65 5f 64 75 70 28 29 5d 2e 20 20 5e 49  alue_dup()].  ^I
37fb0 66 20 56 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  f V is a NULL po
37fc0 69 6e 74 65 72 0a 2a 2a 20 74 68 65 6e 20 73 71  inter.** then sq
37fd0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 66 72 65 65  lite3_value_free
37fe0 28 56 29 20 69 73 20 61 20 68 61 72 6d 6c 65 73  (V) is a harmles
37ff0 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 53 51 4c 49  s no-op..*/.SQLI
38000 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 76  TE_API sqlite3_v
38010 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 76 61  alue *sqlite3_va
38020 6c 75 65 5f 64 75 70 28 63 6f 6e 73 74 20 73 71  lue_dup(const sq
38030 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53  lite3_value*);.S
38040 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
38050 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 66 72 65  qlite3_value_fre
38060 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
38070 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
38080 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65  EF: Obtain Aggre
38090 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f  gate Function Co
380a0 6e 74 65 78 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  ntext.** METHOD:
380b0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
380c0 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74  .**.** Implement
380d0 61 74 69 6f 6e 73 20 6f 66 20 61 67 67 72 65 67  ations of aggreg
380e0 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ate SQL function
380f0 73 20 75 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f  s use this.** ro
38100 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74  utine to allocat
38110 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f  e memory for sto
38120 72 69 6e 67 20 74 68 65 69 72 20 73 74 61 74 65  ring their state
38130 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
38140 73 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69  st time the sqli
38150 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
38160 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69  ntext(C,N) routi
38170 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a  ne is called .**
38180 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
38190 72 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  r aggregate func
381a0 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20  tion, SQLite.** 
381b0 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d  allocates N of m
381c0 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75  emory, zeroes ou
381d0 74 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61  t that memory, a
381e0 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  nd returns a poi
381f0 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e  nter.** to the n
38200 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73  ew memory. ^On s
38210 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71  econd and subseq
38220 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  uent calls to.**
38230 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
38240 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f 72  te_context() for
38250 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67   the same aggreg
38260 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73  ate function ins
38270 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61  tance,.** the sa
38280 6d 65 20 62 75 66 66 65 72 20 69 73 20 72 65 74  me buffer is ret
38290 75 72 6e 65 64 2e 20 20 53 71 6c 69 74 65 33 5f  urned.  Sqlite3_
382a0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
382b0 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a  t() is normally.
382c0 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66  ** called once f
382d0 6f 72 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69  or each invocati
382e0 6f 6e 20 6f 66 20 74 68 65 20 78 53 74 65 70 20  on of the xStep 
382f0 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68 65  callback and the
38300 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69  n one.** last ti
38310 6d 65 20 77 68 65 6e 20 74 68 65 20 78 46 69 6e  me when the xFin
38320 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  al callback is i
38330 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20  nvoked.  ^(When 
38340 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a  no rows match.**
38350 20 61 6e 20 61 67 67 72 65 67 61 74 65 20 71 75   an aggregate qu
38360 65 72 79 2c 20 74 68 65 20 78 53 74 65 70 28 29  ery, the xStep()
38370 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65   callback of the
38380 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
38390 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ion.** implement
383a0 61 74 69 6f 6e 20 69 73 20 6e 65 76 65 72 20 63  ation is never c
383b0 61 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e 61 6c  alled and xFinal
383c0 28 29 20 69 73 20 63 61 6c 6c 65 64 20 65 78 61  () is called exa
383d0 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e  ctly once..** In
383e0 20 74 68 6f 73 65 20 63 61 73 65 73 2c 20 73 71   those cases, sq
383f0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
38400 63 6f 6e 74 65 78 74 28 29 20 6d 69 67 68 74 20  context() might 
38410 62 65 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68  be called for th
38420 65 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d 65 20  e.** first time 
38430 66 72 6f 6d 20 77 69 74 68 69 6e 20 78 46 69 6e  from within xFin
38440 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  al().)^.**.** ^T
38450 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  he sqlite3_aggre
38460 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e  gate_context(C,N
38470 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
38480 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
38490 20 0a 2a 2a 20 77 68 65 6e 20 66 69 72 73 74 20   .** when first 
384a0 63 61 6c 6c 65 64 20 69 66 20 4e 20 69 73 20 6c  called if N is l
384b0 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61  ess than or equa
384c0 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20  l to zero or if 
384d0 61 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  a memory.** allo
384e0 63 61 74 65 20 65 72 72 6f 72 20 6f 63 63 75 72  cate error occur
384f0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61  s..**.** ^(The a
38500 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63 65 20 61  mount of space a
38510 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69  llocated by sqli
38520 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
38530 6e 74 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a  ntext(C,N) is.**
38540 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74   determined by t
38550 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 6f  he N parameter o
38560 6e 20 66 69 72 73 74 20 73 75 63 63 65 73 73 66  n first successf
38570 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69  ul call.  Changi
38580 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20  ng the.** value 
38590 6f 66 20 4e 20 69 6e 20 73 75 62 73 65 71 75 65  of N in subseque
385a0 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  nt call to sqlit
385b0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
385c0 74 65 78 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a  text() within.**
385d0 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67   the same aggreg
385e0 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73  ate function ins
385f0 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72  tance will not r
38600 65 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79  esize the memory
38610 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29  .** allocation.)
38620 5e 20 20 57 69 74 68 69 6e 20 74 68 65 20 78 46  ^  Within the xF
38630 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 2c 20 69  inal callback, i
38640 74 20 69 73 20 63 75 73 74 6f 6d 61 72 79 20 74  t is customary t
38650 6f 20 73 65 74 0a 2a 2a 20 4e 3d 30 20 69 6e 20  o set.** N=0 in 
38660 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
38670 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
38680 78 74 28 43 2c 4e 29 20 73 6f 20 74 68 61 74 20  xt(C,N) so that 
38690 6e 6f 20 0a 2a 2a 20 70 6f 69 6e 74 6c 65 73 73  no .** pointless
386a0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
386b0 6f 6e 73 20 6f 63 63 75 72 2e 0a 2a 2a 0a 2a 2a  ons occur..**.**
386c0 20 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74   ^SQLite automat
386d0 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65  ically frees the
386e0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65   memory allocate
386f0 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33  d by .** sqlite3
38700 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
38710 78 74 28 29 20 77 68 65 6e 20 74 68 65 20 61 67  xt() when the ag
38720 67 72 65 67 61 74 65 20 71 75 65 72 79 20 63 6f  gregate query co
38730 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  ncludes..**.** T
38740 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
38750 65 72 20 6d 75 73 74 20 62 65 20 61 20 63 6f 70  er must be a cop
38760 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  y of the.** [sql
38770 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53  ite3_context | S
38780 51 4c 20 66 75 6e 63 7